skill-development

Create a directory under your plugin's skills/ folder containing a SKILL.md file with YAML frontmatter defining name and description, followed by Markdown instructions. Add optional references/, examples/, and scripts/ subdirectories for supporting resources.

A good skill description uses third person ("This skill should be used when...") and includes specific trigger phrases users would actually say, such as "create a hook" or "configure settings". Vague descriptions without concrete phrases cause skills to never activate.

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

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.

Skills fail to trigger when the description lacks specific trigger phrases, uses second person instead of third person, or is too generic. Rewrite the description to list exact phrases users would say that should activate the skill.