skill-authoring-governance

Keep the description under 1024 characters with three parts: what the skill does, when to use it, and 3-5 explicit trigger phrases. The description is the only text an agent sees when deciding which skill to load, so vague summaries like 'helps with documents' fail the standard.

Run the eight-area audit framework: YAML frontmatter, file structure, progressive disclosure, instructions quality, patterns, testing and validation, technical correctness, and distribution readiness. Produce a per-area PASS, FAIL, or PARTIAL verdict with an overall count of items to fix before merge.

SKILL.md has a hard limit of 100 lines. Core rules and workflow stay in SKILL.md while detailed examples, checklists, and reference material move into a references/ directory linked with relative paths.

Missing trigger phrases in the frontmatter description is the most common cause. Add 3-5 short phrases that naturally precede loading the skill, plus concrete scenarios in a 'When to use this skill' section.

Add scripts when the operation is deterministic, the same code would be generated repeatedly, or errors need explicit handling. Scripts save tokens and improve reliability compared to regenerated code, and must be referenced from SKILL.md with relative paths.