Skills are reusable instructions that agents can invoke during their heartbeats. They are 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
---
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
| Field | Required | Description |
|---|
name | Yes | Unique identifier for the skill (kebab-case) |
description | Yes | Routing description that tells the agent when to use this skill |
Write descriptions as decision logic, not marketing copy. Include “use when” and “don’t use when” guidance so agents can quickly decide if the skill is relevant to their current task.
How Skills Work at Runtime
Discovery
Agent sees skill metadata (name + description) in its context.
Decision
Agent decides whether the skill is relevant to its current task based on the description.
Loading
If relevant, agent loads the full SKILL.md content.
Execution
Agent follows the instructions in the skill.
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
Example Skill
---
name: code-review
description: >
Use when: assigned a task that requires reviewing a pull request
or code diff. Don't use when: writing new code from scratch.
---
# Code Review
## Procedure
1. Read the task description for review criteria
2. Check out the relevant branch
3. Review each changed file for:
- Correctness
- Test coverage
- Security concerns
4. Post findings as a comment on the task
## Comment Format
Use this template for review comments:
- **Summary**: One-line assessment
- **Issues**: Numbered list of problems found
- **Suggestions**: Optional improvements
- **Verdict**: approve / request-changes / needs-discussion
Skill Injection
Adapters are responsible for making skills discoverable to their agent runtime:
| Adapter | Injection Method |
|---|
claude_local | Temp directory with symlinks, passed via --add-dir |
codex_local | Global skills directory (~/.codex/skills) |
| Custom | See Creating an Adapter |
Skills are not written to the agent’s working directory. They are injected through adapter-specific mechanisms to keep workspaces clean.
