Skill Writing Guide
This is a strict guideline. Follow these rules exactly when creating or modifying skills.
Skill Types
Every skill has a type that tells the agent how to treat it:
type: guideline
Strict rules. The agent must follow these exactly.
Opening line after the heading:
**This is a strict guideline.** Follow these rules exactly.Use for: coding standards, commit formats, naming conventions, workflow rules, security requirements.
type: pattern
Reference implementations. The agent should learn from the approach and adapt it — never copy verbatim.
Opening line after the heading:
**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 SKILL.md must start with YAML frontmatter:
---
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:
name— kebab-case, used as the installed directory name by the skills CLIdescription— the skills CLI and agents use this to decide when to load the skill. Make the first sentence a clear trigger.type— must beguidelineorpattern
File Structure
Skills live in the authoring repo under categorized directories:
skills/
guidelines/
{skill-name}/SKILL.md
patterns/
{skill-name}/SKILL.mdThe directory categorization is for human browsing only. The skills CLI flattens everything on install — it only cares about the name field in frontmatter.
Precedence
When a skill needs to override conflicting advice from third-party skills, state it explicitly:
**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 (PROJECT_ID, environment). 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
- Frontmatter has
name,description,type - Behavioral instruction line immediately after first heading
- Description's first sentence works as a trigger for when to load this skill
- No project-specific details (names, tables, endpoints)
- Code examples are minimal and use placeholders
- Document is scannable (headers, bullets, bold)
- Ends with Progressive Improvement section
Progressive Improvement
Every skill must end with this section:
---
## 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.