Agent Skills: Skill Authoring

Skill Authoring

Critical rules

• Put all activation guidance in frontmatter description. The body loads only after activation.
• Description formula: [Third-person capability]. Use this skill when [triggers]. Do not use when/for [near misses].
• Keep description under 1024 characters. No ellipsis (... / …) or placeholders.
• Keep SKILL.md roughly under 150 lines. Move conditional detail into references/.
• Cross-skill references use skill names only (fn-args-deps). Never relative paths to another skill's SKILL.md.
• Add a resource pointer only after its file exists. Keep references one level deep.
• Before finalizing, read references/quality-checklist.md and run the validators below.

Workflow

1. Record two or three realistic tasks (inputs, outputs, success criteria) and two or three strong near misses.
2. Inspect nearby skills so you reuse boundaries instead of duplicating policy.
3. Write the description before the body. Include realistic phrasing and material near misses.
4. Build the post-activation body: Critical rules → Workflow → Resources → Validation → Constraints.
5. Before drafting long examples or type-specific shapes, read references/skill-types.md and references/examples.md.
6. Create references/, assets/, or scripts/ when detail is reusable or would crowd the main file.
7. Compress: shorten wording, split overloaded bullets, delete duplicated When-to-Use from the body.
8. Validate (see Validation). Revise only evidence-backed gaps.

Resources

• references/quality-checklist.md — evidence checklist before publish. Read before finalizing.
• references/skill-types.md — reference / technique / discipline / pattern shapes. Read when choosing structure.
• references/examples.md — WRONG vs CORRECT descriptions, progressive disclosure, anti-patterns. Read when drafting or reviewing.

Validation

node scripts/validate-skill-metadata.mjs path/to/skill
node scripts/validate-skill-links.mjs path/to/skill

• Expect 0 metadata policy violations and 0 broken local links.
• Confirm no body ## When to Use and no ](../.*/SKILL.md) cross-skill paths.
• Confirm name matches directory; bump version on change.

Constraints

• One coherent job per skill. Do not broaden scope because related guidance exists.
• Do not encode one-off preferences. Prefer the smallest durable correction.
• Pair with documentation-standards for prose quality and testing-strategy for evaluation approaches.
• Discipline skills should still use Iron Law / red-flags / rationalization counters (see skill-types).