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

# Skills

> Add versioned Markdown instructions and procedures to an agent through the Agents API.

Skills give an agent reusable instructions, procedures, and domain knowledge.
Configured skills are sent inline when you create or update an agent; there is
no separate Skills resource endpoint.

## Configure skills

Add each skill to the agent's `skills` array with a stable `name` and the
complete Markdown file in `content`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.herm.run/v1/agents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "name": "Support agent",
    "modelName": "anthropic/claude-sonnet-4.5",
    "systemPrompt": "Help customers resolve support questions.",
    "skills": [
      {
        "name": "support-playbook",
        "content": "---\nname: support-playbook\ndescription: Resolve common support requests.\n---\n\n# Support playbook\n\nVerify the customer account before making changes."
      }
    ],
    "tools": []
  }'
```

| Field     | Type   | Required | Description                                                    |
| --------- | ------ | -------- | -------------------------------------------------------------- |
| `name`    | string | Yes      | Stable skill identifier, from 1 to 200 characters.             |
| `content` | string | Yes      | Complete non-empty Markdown content, up to 100,000 characters. |

Use `skills: []` when the agent has no configured skills.

## Version behavior

Skills are part of an immutable agent version. Every update publishes a new
version.

```
PATCH /v1/agents/{agentId}
```

Use `PATCH` to upsert only the supplied skills by `name`; skills you omit are
preserved. Use the full-replacement `POST /v1/agents/{agentId}` when you need to
remove a skill or replace the complete array. Include `expectedVersion` with
either method to reject the update if another caller published a version first.

See [Partially update an agent](/api-reference/agents#partially-update-an-agent)
for collection merge semantics.

## Response behavior

Agent and session responses expose configured skill names, not their Markdown
content:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "skills": ["support-playbook"]
}
```

Keep the source Markdown in your own configuration repository so you can include
it in later agent updates.

## Learned skills

An agent can learn procedures while working in its persistent workspace. Learned
skills are scoped to the agent and stable subject. Public APIs to list, read,
update, and delete learned skills are coming soon.

The API described on this page only manages configured skills attached to agent
versions.