skill-development

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

The description should use third person and include specific trigger phrases users would say, such as "create a hook" or "configure settings". Avoid vague descriptions like "provides guidance" since they fail to trigger the skill reliably.

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

Progressive disclosure is a three-level loading system: metadata 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.

Add scripts when the same code is repeatedly rewritten or deterministic reliability is needed. Add references for documentation Claude should consult while working, such as schemas, API docs, or detailed workflow guides.

Skills fail to trigger when the description lacks specific user phrases or uses second person instead of third person. Rewrite the description with concrete trigger phrases like "create X" and "configure Y" that match actual user requests.