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

# Skills

> Create reusable agent procedures and install skills from the catalog.

Skills are tenant-owned procedures written in Markdown. Attach them to agents to provide reusable instructions without duplicating those instructions across agent configurations.

<Note>
  All endpoints are **\[User+Key]**. Reads require `skills:read`; writes require `skills:write`. For user sessions, write operations are available to `owner`, `billing_admin`, and `developer`.
</Note>

## Endpoints

| Method   | Path                                      | Description                 | Auth                       |
| -------- | ----------------------------------------- | --------------------------- | -------------------------- |
| `GET`    | `/skills?tenant_id=`                      | List tenant-authored skills | \[User+Key] `skills:read`  |
| `POST`   | `/skills`                                 | Create a skill              | \[User+Key] `skills:write` |
| `GET`    | `/skills/catalog?tenant_id=`              | List catalog templates      | \[User+Key] `skills:read`  |
| `POST`   | `/skills/catalog/:id/favorite`            | Favorite a catalog template | \[User+Key] `skills:write` |
| `DELETE` | `/skills/catalog/:id/favorite?tenant_id=` | Remove a favorite           | \[User+Key] `skills:write` |
| `POST`   | `/skills/catalog/:id/install`             | Install a catalog template  | \[User+Key] `skills:write` |
| `GET`    | `/skills/:id?tenant_id=`                  | Get a skill                 | \[User+Key] `skills:read`  |
| `PATCH`  | `/skills/:id?tenant_id=`                  | Update a skill              | \[User+Key] `skills:write` |
| `DELETE` | `/skills/:id?tenant_id=`                  | Archive a skill             | \[User+Key] `skills:write` |

## Attachment modes

Agents reference skills by ID and resolve the current skill content each time they run. Editing a skill therefore affects later runs without creating a new agent version.

| Mode     | Behavior                                                                                                                                                                         |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `always` | The full skill instructions are included in every run. Use this for procedures the agent must follow consistently.                                                               |
| `auto`   | The agent sees the skill's name and description, then loads the full instructions only when the current task matches. Use this to keep unrelated instructions out of the prompt. |

See [Configuring agents](/agents/configuring) for the `attached_skills` shape and runtime behavior.

***

### List skills

`GET /skills`

<ParamField query="tenant_id" type="string" required>
  Tenant whose active skills to list.
</ParamField>

```bash theme={null}
curl "https://api.autosage.ai/api/v1/skills?tenant_id=TENANT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

***

### Create a skill

`POST /skills`

<ParamField body="tenant_id" type="string" required>
  Tenant that will own the skill.
</ParamField>

<ParamField body="name" type="string" required>
  Skill name, up to 255 characters.
</ParamField>

<ParamField body="description" type="string" required>
  Short matching description, up to 280 characters. Make it specific enough for an agent to decide when an `auto` skill applies.
</ParamField>

<ParamField body="body" type="string" required>
  Markdown instructions the agent follows when the skill is loaded.
</ParamField>

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/skills" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "TENANT_ID",
    "name": "Escalate urgent tickets",
    "description": "Classify urgent support requests and prepare an escalation summary.",
    "body": "## Procedure\n1. Confirm the impact.\n2. Collect reproduction details.\n3. Produce an escalation summary."
  }'
```

***

### Get a skill

`GET /skills/:id`

<ParamField path="id" type="string" required>
  Skill ID.
</ParamField>

<ParamField query="tenant_id" type="string" required>
  Tenant that owns the skill.
</ParamField>

***

### Update a skill

`PATCH /skills/:id`

Updates any supplied `name`, `description`, or `body` field.

<ParamField path="id" type="string" required>
  Skill ID.
</ParamField>

<ParamField query="tenant_id" type="string" required>
  Tenant that owns the skill.
</ParamField>

<Tip>
  Attached agents use the latest saved content on their next run. Review high-impact edits carefully because no separate agent update is required.
</Tip>

***

### Archive a skill

`DELETE /skills/:id`

Archives the skill rather than returning it in the active library.

<ParamField path="id" type="string" required>
  Skill ID.
</ParamField>

<ParamField query="tenant_id" type="string" required>
  Tenant that owns the skill.
</ParamField>

## Skill catalog

### List catalog templates

`GET /skills/catalog`

Returns active templates together with their version, favorite state, and installed skill ID for the tenant.

<ParamField query="tenant_id" type="string" required>
  Tenant context used for favorite and installation state.
</ParamField>

### Favorite a template

`POST /skills/catalog/:id/favorite`

<ParamField path="id" type="string" required>
  Catalog template ID.
</ParamField>

<ParamField body="tenant_id" type="string" required>
  Tenant that will favorite the template.
</ParamField>

### Remove a favorite

`DELETE /skills/catalog/:id/favorite`

<ParamField path="id" type="string" required>
  Catalog template ID.
</ParamField>

<ParamField query="tenant_id" type="string" required>
  Tenant whose favorite to remove.
</ParamField>

### Install a template

`POST /skills/catalog/:id/install`

Creates an editable tenant skill from the catalog template. Reinstalling an already-installed template returns the existing skill; reinstalling an archived template reactivates it.

<ParamField path="id" type="string" required>
  Catalog template ID.
</ParamField>

<ParamField body="tenant_id" type="string" required>
  Tenant that will own the installed skill.
</ParamField>

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/skills/catalog/TEMPLATE_ID/install" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tenant_id": "TENANT_ID" }'
```

## Next steps

<CardGroup cols={2}>
  <Card title="Configure agents" icon="robot" href="/agents/configuring">
    Attach skills in `always` or `auto` mode.
  </Card>

  <Card title="API keys" icon="key" href="/developers/api/api-keys">
    Grant `skills:read` and `skills:write` safely.
  </Card>

  <Card title="Tenants" icon="box" href="/developers/api/tenants">
    Understand the ownership boundary for skills.
  </Card>
</CardGroup>