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 content, 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 references, and advanced techniques into references/ files that load only when needed.

Use references/ for documentation Codex should read while working, such as schemas or detailed patterns. Use scripts/ for executable code that needs deterministic reliability or is repeatedly rewritten, like validation utilities.

Skills fail to trigger when the description lacks specific trigger phrases or uses vague language. Rewrite the description in third person with exact phrases users would say, listing concrete scenarios like "create X" or "configure Y".