Skills

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:

builtin/list_skills returns the names and descriptions of the skills the agent selected.
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.

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.

{
  "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

Directory~/.config/raw/skills/
- Directoryreview/
  - SKILL.md
  - Directoryreferences/
    checklist.md

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

---
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/.

Copy the example folder into your config directory.

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

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

Select the copy in your agent.

"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.

Skill authoring covers how to write skills that agents use well.
Tools covers the skill tools and other built-in tools.
Packages covers sharing skills as part of a package.