write-skill

name	write-skill
description	Use when authoring a new skill, editing an existing skill, upgrading a flexible skill to rigid, or the user says "/write-skill", "create a skill", "new skill for X", or "make this a skill". Fires before any new `SKILL.md` is committed.
user-invocable	true
tier	rigid
kind	process

Run: `bash "$(git rev-parse --show-toplevel)/bin/harness-update-check"` - `UPGRADE_AVAILABLE ` → tell the user: "agent-harness is available (you have ). Run `/harness-update` to pull it in." Then continue. - `JUST_UPGRADED ` → tell the user: "agent-harness upgraded → ." Then continue. - No output → continue silently.

Write Skill

Override: see CLAUDE.md § Instruction precedence. The user is principal; this skill is advisory.

Writing a skill IS test-driven development applied to process documentation. If you didn't watch a subagent fail without the skill, you don't know what the skill is for. Merges superpowers' writing-skills with .claude/docs/harness-principles.md and skills/CONVENTIONS.md. Violating the letter is violating the spirit.

The Iron Law

NO RIGID SKILL SHIPS WITHOUT (1) A NAMED FAILURE MODE FROM A SUBAGENT
BASELINE, (2) A RATIONALIZATION TABLE QUOTING VERBATIM EXCUSES, (3) A
TRIGGERS-ONLY DESCRIPTION, (4) A DECLARED TERMINAL STATE, AND (5) AN
`eval.yaml` DECLARING AT LEAST ONE TRAJECTORY EVAL (OR ONE INVOCATION
EVAL FOR SUBAGENT-ONLY SKILLS).

Flexible/util skills are exempt from (1), (2), (5) — never from (3). Wrote the body before baselining? Delete the rationalization table; don't keep imagined rows "as reference." (§3, §11.) Missing eval.yaml? bin/skill-eval --validate-strict fails.

The cycle

1. Decide. Skill at all? Most candidates belong in CLAUDE.md or a hook (checklist.md).
2. RED. /skill-baseline against a subagent without the skill. Capture verbatim excuses.
3. GREEN. Copy _template-rigid/{TEMPLATE.md,eval.yaml}. Counter the baseline rationalizations verbatim → rationalizations.md. Translate GREEN trajectory → eval.yaml. Re-run with the skill; subagent should cite the section that prevented the failure.
4. REFACTOR. New rationalization under stacked pressure? Add a row. Iterate until compliance holds.
5. Validate. bin/test-frontmatter and bin/skill-eval --validate both pass. Then run /skill-eval <new-skill> to execute the first trajectory eval against a fresh subagent — confirms the eval contract is satisfiable, not just well-formed.
6. Ship. Bump VERSION, commit, push, open a draft PR.

References: skill-md-template.md, checklist.md, .claude/docs/skill-eval-spec.md.

Red Flags — STOP and Start Over

• Description summarizes workflow instead of triggers (model follows the summary, skips the body).
• Rationalization rows or eval.yaml trajectories from imagination — no docs/skill-baselines/ source link.
• Rigid skill missing eval.yaml (bin/skill-eval --validate-strict fails).
• Body > 700 words with content that belongs in a sibling.
• Multi-language examples. One excellent example beats five mediocre ones.
• @-loading a sibling (force-loads context) — use **REQUIRED SUB-FILE:** Read foo.md.
• Missing <update-check> block, missing override pointer, frontmatter omits tier or kind.
• "I'll baseline it later." "Just a small edit, no baseline needed."

All of these mean: stop. Move the work back into RED. Expanded list: red-flags.md.

Common Rationalizations

REQUIRED SUB-FILE: Read rationalizations.md if you find yourself making excuses. The verbatim-excuse-to-reality table is seeded from superpowers' writing-skills baseline and flagged for re-baseline in this harness.

Self-Review Checklist

Before committing:

• Folder name == frontmatter name. bin/test-frontmatter passes.
• Description starts with Use when, lists concrete triggers, contains zero workflow summary.
• <update-check> block present immediately after frontmatter.
• If rigid: Iron Law, Red Flags, rationalizations.md, Self-Review Checklist, Terminal State all present. Every rationalization row traces to a file under docs/skill-baselines/.
• If rigid: eval.yaml present with at least one trajectory eval (or one invocation eval for subagent-only skills). bin/skill-eval --validate passes.
• Body word count: wc -w SKILL.md < 500 (target) / < 700 (hard ceiling). Overflow → siblings.
• One excellent example, not five mediocre ones.
• VERSION bumped.

Cannot check all boxes? You skipped this skill. Restart from the top.

What this skill does NOT cover

Hooks (different contract), commands (thin wrappers), memory entries (see CLAUDE.md § Learnings), and doc-only edits (no baseline; still bump VERSION patch if user-visible).

Terminal State

Terminal state is a draft PR to agent-harness containing the new/edited skill, baseline transcripts under docs/skill-baselines/, the populated eval.yaml, and a VERSION bump. bin/test-frontmatter and bin/skill-eval --validate must pass. Do NOT invoke /ship — the draft is on purpose. Do NOT use the new skill on real work until the user reviews the rationalization table and the PR merges.