---
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.