Skills

Skills are reusable workflow packages installed under /skills. They extend the agent’s capabilities without changing its code. A skill is a directory containing instructions, scripts, and references that the agent reads and follows.

What a skill is

A skill is a directory containing:

• A SKILL.md file with YAML frontmatter (name, description) and markdown instructions
• Supporting scripts, references, and assets

Skills are not code that runs automatically. They are instructions and context that the agent reads when the skill is relevant to the current task. The agent follows the procedures defined in the skill’s markdown, running scripts and referencing documentation as directed.

How skills work

When a skill is relevant, the agent reads the SKILL.md and follows its instructions. This might mean:

• Running a script from the skill directory
• Following a step-by-step procedure defined in markdown
• Referencing documentation bundled with the skill
• Using the skill’s declared tools (if any)

Skills are discovered from the filesystem at runtime. The agent scans /skills for directories containing SKILL.md files and builds a catalog of available skills. There is no separate registry to maintain — the directory structure is the source of truth.

Built-in vs. shared skills

Skills come from two roots:

Root	Location	Persistence	Examples
Built-in	/skills/@builtin/ (read-only)	Shipped with the runtime	skill-creator, skill-discovery
Shared	/skills/<name>/ (read-write)	Persistent volume	technical-writing, browser-use, youtube-transcript

Built-in skills are embedded in the agent binary and available on every deployment. They are read-only — the agent cannot modify them.

Shared skills are installed by the operator or by the agent itself during normal work. They persist across restarts and upgrades because /skills is a persistent volume.

Skill catalog

The agent maintains an in-memory catalog of all available skills. Each entry includes:

• Name — the directory name (e.g., technical-writing)
• Description — from the SKILL.md frontmatter
• Source — builtin or shared
• Path — filesystem location

The catalog is rebuilt at startup and can be refreshed during a session. The agent uses the catalog to decide which skills are relevant to the current task.

Skill injection

Skills can be injected into subagents. When you delegate work to a subagent, you can specify which skills it should have access to:

subagent(
  model: "deepseek-v4-flash",
  task: "Write a concept page...",
  skills: ["technical-writing"],
  tools: ["read_file", "write_file"]
)

The subagent receives the skill’s SKILL.md in its system prompt and can use the skill’s declared tools. This lets you compose capabilities: a subagent with the technical-writing skill writes documentation, while the parent agent orchestrates.

Skill validation

The validate_skill tool checks that a skill directory is well-formed:

• SKILL.md exists and is valid markdown
• YAML frontmatter has required fields (name, description)
• Name matches the ^[a-z0-9]+(?:-[a-z0-9]+)*$ pattern
• Description is under 1024 characters
• Directory structure follows conventions

Use validation after creating or editing a skill to catch metadata or structure issues before the agent tries to use it.

Installing skills

Skills can be installed through normal agent work — the agent fetches and places them under /skills. They can also be installed manually by the operator.

The directory structure under /skills is the source of truth:

/skills/
├── @builtin/
│   ├── skill-creator/
│   │   └── SKILL.md
│   └── skill-discovery/
│       └── SKILL.md
├── technical-writing/
│   ├── SKILL.md
│   └── references/
│       ├── style-guide.md
│       ├── documentation-patterns.md
│       ├── anti-patterns.md
│       └── diagram-guide.md
└── browser-use/
    ├── SKILL.md
    └── scripts/
        └── chrome-wrapper.sh

Persistence

/skills is a persistent volume. Skills survive restarts and upgrades. In local development, skills may be reset, but persistence avoids repeated skill bootstrap in production deployments.

Relationship to tools

Skills are not tools — they are workflow packages. The validate_skill tool is the mechanism for checking that a skill is well-formed, but the skill itself is content the agent reads and follows, not a function it calls.

See Tools for the full list of agent capabilities.