Skill Development

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

Write the description in third person starting with "This skill should be used when..." and include specific trigger phrases users would say, such as "create a hook" or "configure settings". Avoid vague or second-person phrasing.

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

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

Add scripts/ when the same code is rewritten repeatedly or deterministic execution is needed. Add references/ for documentation Claude should consult while working, such as schemas or policies, to keep SKILL.md lean.

Weak trigger descriptions are the most common cause. Ensure the description uses third person, lists concrete phrases users would actually say, and covers the specific scenarios the skill handles rather than generic statements.