> ## Documentation Index
> Fetch the complete documentation index at: https://sidenet.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Named blocks of instructions an agent loads on demand instead of carrying them in every prompt — versioned, shared across agents, published independently.

A skill is a named block of instructions an agent reads **when it needs it**.
The agent's prompt carries one line per skill — its name and when to load it —
and the agent fetches the full text with a tool call the first time a
conversation calls for it. The text then stays in the conversation.

Use a skill for guidance that is long, that only some conversations need, or
that several agents share: a refund policy, a reporting format, a procedure
for a rare case, the house rules for a particular customer. Keep in the
prompt what every turn needs: who the agent is, its tone, the two or three
rules that always apply.

## A skill has three parts

| Field | What it is for |
| - | - |
| `name` | What the agent passes to its `skill` tool. 1–64 characters: lowercase letters, digits and hyphens. `refund-policy`, `weekly-report-format`. |
| `description` | **When to load it.** This line is in the agent's prompt on every turn, so write it as a rule: *"Load before answering any refund or cancellation question."* |
| `instructions` | Markdown the agent receives when it loads the skill. Up to 60 000 characters. |

The description does the real work: an agent that never loads a skill was
not told when to. Say what the skill covers and the moment to reach for it.
Write the instructions themselves as positive, imperative rules — what to
do, in what order — rather than examples of mistakes to avoid; smaller models
copy whatever they read.

## Creating and publishing

```json theme={null}
POST /v1/skills
{
  "name": "refund-policy",
  "description": "How refunds are decided and worded. Load before answering any refund or cancellation question.",
  "instructions": "## Refunds\n\n1. Full refund within 14 days of purchase.\n2. …"
}
```

A skill is versioned, but not quite like an agent or a prompt block: there is
no separate draft. **Every save that changes the text creates a new version**,
and the newest version is the working copy. Agents get the **active** version,
the one `publish` points them at:

* `PATCH /v1/skills/{id}` saves `name`, `description` or `instructions`. A
  change becomes a new version; agents keep getting the active one.
* `POST /v1/skills/{id}/publish` makes the latest version active. Every agent
  referencing the skill gets it on its next turn — no agent republish.
* `POST /v1/skills/{id}/activate` with a `version_id` points agents at an
  earlier version: that is how you roll back.
* `GET /v1/skills/{id}` returns the record with `latest` (the working copy),
  `active` (what agents get) and `dirty`, which is true when the two differ.

A skill that has never been published is skipped by the agents that reference
it, and the skip is reported in the agent's rebuild summary.

## Attaching skills to an agent

On the agent draft, `skills` lists the skills by id:

```json theme={null}
PATCH /v1/agents/{id}/draft
{ "skills": [{ "skill_id": "9a4e2c71-…" }] }
```

The reference is by id, not pinned to a version. That is deliberate: a skill
is reference material the model asks for, and when you publish a correction
every agent should see it. (Prompt blocks pin a version at publish time
because they are part of the authored prompt; skills are not.)

Every id must be one of your organization's skills, or the save is refused.
Two skills on one agent may not share a name.

`GET /v1/skills/{id}/references` lists the agents using a skill, and
`DELETE /v1/skills/{id}` is refused with a `409` while an agent draft or
active version still references it (`?force=true` overrides; those agents
then skip the skill until the reference is removed).

## What the agent sees

The agent's prompt gains one block:

```
## Skills

Detailed rules are packaged as skills. Load one by calling the `skill` tool
with its `name`, then follow the instructions it returns; …
- `refund-policy`: How refunds are decided and worded. Load before answering
  any refund or cancellation question.
```

and three tools: `skill` (load one by name), `skill_search` (search across the
skills' text) and `skill_read` (read a skill's reference files, none today).
The loaded instructions arrive as that tool call's result and stay in the
conversation, so a skill is loaded once per conversation, and again only if
it has fallen out of the context window. The chat widget shows the call like
any other tool call.

## Reference

| Endpoint | Purpose |
| - | - |
| `POST /v1/skills` | Create a skill with its first version |
| `GET /v1/skills` | List the organization's skills |
| `GET /v1/skills/{id}` | Record, working copy, active version, `dirty` |
| `PATCH /v1/skills/{id}` | Save `name`, `description`, `instructions` (a change = a new version) |
| `POST /v1/skills/{id}/publish` | Make the latest version the one agents get |
| `POST /v1/skills/{id}/activate` | Point agents at a specific version |
| `GET /v1/skills/{id}/versions` | Every version, newest first |
| `GET /v1/skills/{id}/references` | Which agents use this skill |
| `DELETE /v1/skills/{id}` | Delete (guarded) |
| `PATCH /v1/agents/{id}/draft` | `skills: [{ skill_id }]` attaches skills to an agent |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.