Skill Development

Guide for writing effective SKILL.md files with proper structure and triggers.

Skill Structure

skill-name/
├── SKILL.md           # Required: main instructions
├── references/        # Detailed docs (loaded as needed)
├── examples/          # Working code samples
└── scripts/           # Utility scripts

SKILL.md Format

---
name: skill-name
description: This skill should be used when the user asks to "action X",
  "do Y", "configure Z", or needs guidance on [topic].
version: 1.0.0
---

# Skill Title

Skill body content here (markdown).

Frontmatter Fields

Description Format (Critical)

Always use third-person with specific trigger phrases:

Good:

description: This skill should be used when the user asks to "create a hook",
  "add a PreToolUse hook", "validate tool use", or mentions hook events
  (PreToolUse, PostToolUse, Stop).

Bad:

description: Use this skill for hooks.  # Not third person
description: Helps with hook development.  # No triggers

Progressive Disclosure

Best practice: Keep SKILL.md concise. Move details to references/.

Quality Review

After creating a skill, use the skill-reviewer agent:

Review my skill at ./skills/my-skill

It checks:

• •Description quality and triggers
• •Word count and progressive disclosure
• •Writing style and structure
• •Reference file existence

String Substitutions

Writing Style

• •Imperative: "Create the hook" not "You should create"
• •Third-person in description
• •Specific trigger phrases
• •Concrete examples

Linking Skills

For related topics:
- **/plugin-name:other-skill** - Description

Checklist

• • Description is third-person
• • Description has trigger phrases
• • SKILL.md < 1,500 words
• • Details in references/
• • Imperative writing style
• • Name matches directory