09d2ef1a37
- Restored docs/ directory that was accidentally deleted by `git add -A` in the v0.2.3 release script - Replaced generic "P" favicon with actual paperclip icon using brand primary color (#2563EB) - Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark) - Updated docs.json with logo configuration for dark/light mode - Fixed release.sh to stage only release-related files instead of `git add -A` to prevent sweeping unrelated changes into release commits Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
---
|
|
title: Writing a Skill
|
|
summary: SKILL.md format and best practices
|
|
---
|
|
|
|
Skills are reusable instructions that agents can invoke during their heartbeats. They're markdown files that teach agents how to perform specific tasks.
|
|
|
|
## Skill Structure
|
|
|
|
A skill is a directory containing a `SKILL.md` file with YAML frontmatter:
|
|
|
|
```
|
|
skills/
|
|
└── my-skill/
|
|
├── SKILL.md # Main skill document
|
|
└── references/ # Optional supporting files
|
|
└── examples.md
|
|
```
|
|
|
|
## SKILL.md Format
|
|
|
|
```markdown
|
|
---
|
|
name: my-skill
|
|
description: >
|
|
Short description of what this skill does and when to use it.
|
|
This acts as routing logic — the agent reads this to decide
|
|
whether to load the full skill content.
|
|
---
|
|
|
|
# My Skill
|
|
|
|
Detailed instructions for the agent...
|
|
```
|
|
|
|
### Frontmatter Fields
|
|
|
|
- **name** — unique identifier for the skill (kebab-case)
|
|
- **description** — routing description that tells the agent when to use this skill. Write it as decision logic, not marketing copy.
|
|
|
|
## How Skills Work at Runtime
|
|
|
|
1. Agent sees skill metadata (name + description) in its context
|
|
2. Agent decides whether the skill is relevant to its current task
|
|
3. If relevant, agent loads the full SKILL.md content
|
|
4. Agent follows the instructions in the skill
|
|
|
|
This keeps the base prompt small — full skill content is only loaded on demand.
|
|
|
|
## Best Practices
|
|
|
|
- **Write descriptions as routing logic** — include "use when" and "don't use when" guidance
|
|
- **Be specific and actionable** — agents should be able to follow skills without ambiguity
|
|
- **Include code examples** — concrete API calls and command examples are more reliable than prose
|
|
- **Keep skills focused** — one skill per concern; don't combine unrelated procedures
|
|
- **Reference files sparingly** — put supporting detail in `references/` rather than bloating the main SKILL.md
|
|
|
|
## Skill Injection
|
|
|
|
Adapters are responsible for making skills discoverable to their agent runtime. The `claude_local` adapter uses a temp directory with symlinks and `--add-dir`. The `codex_local` adapter uses the global skills directory. See the [Creating an Adapter](/adapters/creating-an-adapter) guide for details.
|