Skill Development

Create a directory under your plugin's skills/ folder containing a SKILL.md file with YAML frontmatter (name and description) plus markdown instructions. Follow the six-step process: understand use cases, plan reusable resources, create structure, edit content, validate, and iterate.

A good description uses third person ("This skill should be used when...") and includes specific trigger phrases users would actually say, like "create a hook" or "validate tool use". Avoid vague descriptions like "provides guidance" without concrete scenarios.

Progressive disclosure is a three-level loading system: metadata (name and description) stays always in context, the SKILL.md body loads when the skill triggers, and bundled resources like references/ and scripts/ load only as needed. This keeps context usage efficient.

Keep the SKILL.md body between 1,500 and 2,000 words, with a hard maximum around 5,000 words. Move detailed patterns, API documentation, and advanced techniques into references/ files that load only when needed.

Add scripts/ when the same code is rewritten repeatedly or deterministic execution is needed, such as validation utilities. Add references/ for detailed documentation like schemas or API specs that would bloat SKILL.md but should be available on demand.

Skills fail to trigger when the description lacks specific trigger phrases or uses second person instead of third person. Rewrite the description to include exact phrases users would say, such as "create X" or "configure Y", and test with realistic queries.