| name | authoring-skills |
| description | Use when creating, editing, validating, or codifying reusable lessons into strict agent skills. |
| license | MIT |
| metadata | {"author":"h3y6e","version":"2026.5.5"} |
Authoring Skills
Skill authoring is TDD for process docs: scenario, failure, SKILL.md, verify, refactor. A skill is reusable technique, pattern, tool, or reference, not session history.
Create Or Skip
Create/edit only for reusable, non-obvious, broad, judgment-based lessons or paired failure/success evidence. Dedup first; skip one-offs, local conventions, generic hygiene, and obvious advice inferable from the trigger, repo instructions, or tool docs. Automate enforceable rules.
Structure
Use skill-name/SKILL.md; frontmatter needs matching name/description; keep under 1024 chars. Names use lowercase letters, numbers, and hyphens only. Name by action/core insight; gerunds fit process skills. Use scripts/ for reusable tools and references/ for heavy reference.
Description
Description: trigger, not workflow. Start with Use when...; name symptoms/situations; stay tech-agnostic unless needed; avoid first person; stay under 500 chars; include searchable keywords.
Strict Loop
Mapping: test case = pressure/application scenario; production code = SKILL.md; RED = baseline violation or rationalization; GREEN = compliant use; refactor = close loopholes.
Do not deploy or mark a behavior-changing skill valid without a failing scenario first.
- RED: write pressure scenarios; for discipline skills, combine time, sunk cost, authority, and exhaustion. Record baseline rationalizations.
- GREEN: write the smallest
SKILL.md that blocks those failures.
- VERIFY: test the same scenarios, preferably with a fresh subagent.
- REFACTOR: plug rationalizations, remove excess text, and re-test.
Validate by type: discipline skills need pressure compliance; techniques need application/variation; patterns need recognition/counter-examples; references need retrieval, application, and gap tests.
References: use empirical-validation.md for empirical review or major behavior changes; retrospective-codification.md for reusable lessons; description-tuning.md for trigger misses; skill-structure.md for placement.
Quality Rules
- Keep frequently loaded skills very short; keep others under 500 words. This is an upper bound, not a target. A skill can be much shorter; never pad toward 500 words.
- Write only non-obvious guidance: traps, judgment calls, failure modes, and exceptions. Delete generic checklists that do not change agent behavior.
- Move heavy examples, APIs, syntax into references.
- Add scripts only for deterministic repeated operations.
- Prefer one excellent example; avoid multi-language dilution.
- Use flowcharts only for non-obvious decisions or loops.
- Cross-reference skills by name with explicit requirement markers; avoid path or
@ links.
- Add counters or red flags only for real rationalizations.
- Avoid narrative session history and hidden dependencies.
- When improving from feedback, fix the observed behavior and re-verify instead of rewriting unrelated sections.
Evidence
Before claiming a skill works, record:
- scenarios used
- critical requirements
- baseline failure or reason baseline was skipped
- result:
untested, structurally reviewed, or scenario-tested
- unclear points or discretionary fill-ins
If validation was skipped, say untested; do not imply it passed.
Final Check
Trigger-only description; concise actionable body; necessary supporting files; RED scenario; recorded validation status.
