skill_md_authoring v1.0.0

name: "skill_md_authoring" description: "Writes and audits SKILL.md files that actually get used: trigger-driven descriptions, progressive disclosure layout, and validation checklists. Use when creating a new agent skill, reviewing an existing one, or fixing a skill that never fires."

SKILL.md Authoring

Purpose

Build or repair agent skills whose SKILL.md files are discoverable (triggered when they should be), cheap to load (progressive disclosure), and verified (validated before shipping).

Workflow

1. Scope one job. If the job splits into two different trigger contexts, build two skills. A skill that covers everything triggers on nothing.
2. Design the trigger first. Draft the description in third person: what the skill does AND when it should fire. Put concrete trigger words near the front. Models under-trigger by default, so be specific and a little pushy. Read references/trigger-design.md before drafting.
3. Plan the layout. Keep only the operational core in SKILL.md. Bulky docs, schemas, and long examples go in references/; fixed output artifacts in assets/; deterministic repeated work in scripts/ or bin/ with the body pointing to them. Read references/progressive-disclosure.md.
4. Draft frontmatter. name in snake_case matching the kebab-case directory (my-skill/ -> my_skill). description <= 1024 chars. These two fields are the whole trigger surface.
5. Draft the body in the right template. Tool-backed skill: Purpose / Tooling / Auth / Operating Rules. Workflow-only skill: Purpose / Workflow / Output Contract / Operating Rules. The body tells the model what to do next, not the whole domain.
6. Trim aggressively. Anything not needed on every trigger moves to references/. Target under ~500 lines for the body. Chains of references (a file that only links to another file) are banned: one level deep, direct links.
7. Validate. Run python3 scripts/validate_skill.py <skill-dir> and work references/validation-checklist.md. Compile any Python helpers with python3 -m py_compile and dry-run them for real.

Output Contract

A finished package looks like this:

<skill-name>/
├── SKILL.md          # valid frontmatter, body in template, < ~500 lines
├── references/       # one-level-deep docs, TOCs on files over 100 lines
├── scripts/          # compiled, dry-run-tested helpers
└── assets/           # only if the output needs them

The validator report passes: name matches directory, description states capability and trigger, required sections present, all referenced files exist.

Operating Rules

1. Never invent commands, paths, binaries, or auth flows. Match the real runtime.
2. One skill, one job. No Swiss-army skills.
3. Descriptions in third person: what it does plus when to use it.
4. Keep attribution, credits, and licenses out of SKILL.md; they go in README.md or the catalog.
5. No time-sensitive wording. For migrations use "Current Workflow" and "Old Patterns" sections, not dates.
6. Avoid Windows-style paths; use portable conventions.
7. Each skill is self-contained and completes its task. There is no supported pattern of one skill invoking another mid-turn.
8. Keep mutually exclusive contexts in separate files so unrelated tokens are never paid for together.