# Skills

> Give an agent reusable instructions by selecting skills, which the model lists and loads on demand.

A skill is a folder with a `SKILL.md` file. It holds instructions the agent can read when a task calls for them. Raw does not add skills to the system prompt. The model reads a skill only when it calls the skill tools.

## How skills reach the model

An agent with skills follows a two-step pattern:

1. `builtin/list_skills` returns the names and descriptions of the skills the agent selected.
2. `builtin/load_skill` returns the Markdown body of one skill, placed at the end of the conversation.

The first request contains no skill catalog. The model discovers skills by calling these tools.

> **Note:**
>
> An agent that selects skills must also select both `builtin/list_skills` and `builtin/load_skill` in `tools.use`. Raw rejects the config otherwise.

## Select skills

`skills.use` takes these ID forms:

| Prefix                        | Where Raw loads it from                                               |
| ----------------------------- | --------------------------------------------------------------------- |
| `builtin/<id>`                | The installed Raw package. Includes seven setup skills.               |
| `local/<id>`                  | `$XDG_CONFIG_HOME/raw/skills/<id>/`, or `~/.config/raw/skills/<id>/`. |
| `agent/<id>`                  | `skills/<id>/` beside the selected config file.                       |
| `pkg/<alias>/skills/<export>` | A skill from an installed package.                                    |

```json
{
  "agents": {
    "reviewer": {
      "model": "local",
      "tools": {
        "use": [
          "builtin/read_file",
          "builtin/list_skills",
          "builtin/load_skill"
        ]
      },
      "skills": {
        "use": ["local/review"]
      }
    }
  }
}
```

Raw reads only the folders an agent selects. Unselected skills are not read, so a broken unrelated skill does not affect the agent.

## Write a skill

```text
~/.config/raw/skills/
  review/
    SKILL.md
    references/
      checklist.md
```

`SKILL.md` starts with YAML frontmatter, followed by the Markdown body.

```markdown
---
name: review
description: Review a code change for correctness. Use when asked for a review.
---
# Review


Inspect the changed behavior and report actionable findings.
```

| Frontmatter field | Rule                                                                                                                                                  |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | Matches the folder name. Use lowercase kebab-case for portable skills.                                                                                |
| `description`     | Required and nonempty, up to 1024 characters. The model uses it to decide whether to load the skill, so state what the skill does and when to use it. |

Optional standard fields are `license`, `compatibility`, and string-valued `metadata`.

Skill folders may also contain `scripts/`, `references/`, and `assets/`. The body does not load those files automatically. Mention each file’s relative path in the body, and the agent can read it with `builtin/read_file`.

### Size limits

`load_skill` returns the body of one skill, and the body must fit the agent’s `max_output_bytes` (8192 bytes by default). The catalog from `list_skills` must fit too. A skill that exceeds the limit fails to load instead of being cut off. Keep each skill focused, and move long reference material into a file the agent reads only when needed.

## Fork a shipped skill

Raw ships seven setup skills under `builtin/`. Each has an editable copy in [examples/skills/](https://github.com/lploc94/raw-cli/tree/main/examples/skills).

1. Copy the example folder into your config directory.

   ```sh
   mkdir -p ~/.config/raw/skills
   cp -R examples/skills/configure_raw ~/.config/raw/skills/my-config-guide
   ```

2. Change the `name` in the copied `SKILL.md` to match the folder, `my-config-guide`.

3. Select the copy in your agent.

   ```json
   "skills": { "use": ["local/my-config-guide"] }
   ```

## Changes in a resumed session

Raw takes a snapshot of each selected skill when a session attaches. When you edit a skill, the change applies on the next attachment or turn. If a session was resumed and the model had already seen the old version of a skill, Raw adds one notice at the end of the conversation asking the model to list or load the skill again. The earlier results are not rewritten.

## Related

- [Skill authoring](https://raw.tlelabs.com/docs/extend/skill-authoring/) covers how to write skills that agents use well.
- [Tools](https://raw.tlelabs.com/docs/extend/tools/) covers the skill tools and other built-in tools.
- [Packages](https://raw.tlelabs.com/docs/extend/packages/) covers sharing skills as part of a package.