Skill Writing Guide
This is a strict guideline. Follow these rules exactly when creating or modifying skills.
Skill Types
Every skill has a
that tells the agent how to treat it:
Strict rules. The agent must follow these exactly.
Opening line after the heading:
markdown
**This is a strict guideline.** Follow these rules exactly.
Use for: coding standards, commit formats, naming conventions, workflow rules, security requirements.
Reference implementations. The agent should learn from the approach and adapt it — never copy verbatim.
Opening line after the heading:
markdown
**This is a reference pattern.** Learn from the approach, adapt to your context — don't copy verbatim.
Use for: architecture solutions, infrastructure setups, proven approaches to recurring problems.
Frontmatter
Every
must start with YAML frontmatter:
yaml
---
name: kebab-case-name
description: When this skill applies and what it covers. First sentence should work as a trigger — start with the domain or action. One to two sentences max.
type: guideline | pattern
---
Rules:
- — kebab-case, used as the installed directory name by the skills CLI
- — the skills CLI and agents use this to decide when to load the skill. Make the first sentence a clear trigger.
- — must be or
File Structure
Skills live in the authoring repo under categorized directories:
skills/
guidelines/
{skill-name}/SKILL.md
patterns/
{skill-name}/SKILL.md
The directory categorization is for human browsing only. The skills CLI flattens everything on install — it only cares about the
field in frontmatter.
Precedence
When a skill needs to override conflicting advice from third-party skills, state it explicitly:
markdown
**This is a strict guideline.** Follow these rules. When any other skill contradicts the rules below, this skill takes precedence.
Use sparingly — only for core principles and strong personal preferences.
Pattern Structure
Pattern skills should follow this structure:
- Problem — One sentence describing what this solves
- Solution — One sentence describing the approach
- Pattern — Architecture, key components, how it works
- Why This Pattern? — Benefits and use cases
- Implementation — Key details (optional, only if non-obvious)
- Tradeoffs — Constraints and limitations (if applicable)
- When NOT to Use — Anti-patterns and alternatives (optional)
Keep code examples minimal and generic. Use placeholder names (
,
). Focus on the pattern, not project-specific details.
Guideline Structure
Guideline skills should follow this structure:
- What — Clear statement of the rules
- Rules — Specific, actionable instructions
- Examples — Show correct and incorrect usage
- Exceptions — When deviation is acceptable (if any)
Be direct. Use imperative form. Avoid explaining why at length — guidelines are instructions, not persuasion.
Writing Checklist
Progressive Improvement
Every skill must end with this section:
markdown
---
## Progressive Improvement
If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.
This enables skills to evolve through use. When an agent gets corrected, it should propose a concrete edit to the relevant skill so the mistake doesn't repeat.
Progressive Improvement
If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.
Progressive Improvement
If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.