Writing skills

Overview

Design skills that route predictably, disclose only the relevant detail, and make completion observable. The description is the routing signal available before the skill loads: it states what the skill does and when it applies. The entrypoint owns steps shared by every run; precise pointers lead to branch-specific references.

When to Use

• Creating a new skill
• Refactoring an oversized or overlapping skill
• Rewriting descriptions for clearer routing
• Demoting router-like skills into reference docs

When Not to Use

• Ordinary code changes that do not alter skill behavior
• One-off repo conventions better placed in AGENTS.md
• Pure implementation work with no routing or progressive-disclosure question