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>
2.2 KiB
2.2 KiB
title, summary
| title | summary |
|---|---|
| Writing a Skill | 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
---
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
- Agent sees skill metadata (name + description) in its context
- Agent decides whether the skill is relevant to its current task
- If relevant, agent loads the full SKILL.md content
- 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 guide for details.