writing-skills

name	writing-skills
description	House guide for creating or editing agent skills in this repo (.claude/skills/). Use when writing a new skill, restructuring an existing one, or reviewing skills for quality. Covers the frontmatter contract, the install wiring, the house template, and the weak-executor writing rules every Carbon skill follows.

writing-skills — how Carbon skills are written

Source of truth is .claude/skills/{name}/SKILL.md (tracked in git). The installer (.ai/scripts/install-skills.sh, run automatically by pnpm prepare or manually via pnpm install-skills) copies each skill directory into .codex/skills/ for the Codex harness. Never edit under .codex/ — edit .claude/skills/ only.

The prime directive: write for the weakest executor

Assume the model executing a skill is much less capable than you and has zero context. It will not infer intent, fill gaps, or exercise judgment. So:

1. One canonical path per task. Never offer options without declaring a default. "Choose what fits" is a gap; a weak model fills gaps badly.
2. Exact commands with expected output. Every verification is a command plus what its output must contain. "Verify it works" is not an instruction.
3. Exact paths. Never "the appropriate directory". Never a path you didn't confirm exists.
4. STOP rules inline. State explicitly when to stop and report instead of improvising ("2 failed attempts → STOP", "open question unresolved → STOP").
5. Decision tables over prose. Situation → action. A weak model can match a row; it cannot weigh an essay.
6. Verified references only. Every file, command, and skill a skill mentions must exist — run the command, ls the path, before writing it down. This includes claims inherited from an earlier version of the skill: re-verify them; the previous author may have been wrong. A reference to something that doesn't exist sends the executor into a loop.
7. Close loopholes explicitly. For discipline rules, list the specific workarounds that are forbidden and the red-flag phrases that mean "stop" ("just this once", "I'll test after", "keep it as reference").
8. Announce at start. Workflow skills open with one line naming the skill and its target. It locks the executor into the procedure and tells the supervising human which playbook is running.
9. Non-interactive only. Never instruct git rebase -i, git add -i, git restore -p, or anything that opens an editor/prompt — interactive commands hang in agent harnesses. Give the non-interactive equivalent.
10. Bundle assets for generative output. When a skill produces a styled artifact (HTML page, document scaffold), ship a filled-in template under assets/ and have the executor copy + fill <!-- FILL --> markers — weak models fill templates far better than they invent structure.

Frontmatter contract (hard requirements)

• The file starts with --- on line 1. Nothing above it — an HTML comment above the frontmatter breaks description parsing and the comment leaks into the skill list. Attribution comments go below the closing ---.
• name: must equal the directory name exactly (letters, numbers, hyphens). The installer symlinks by directory name; a mismatch disconnects the skill.
• description: ≤1024 chars, third person. Formula: what it does and produces
  • "Use when …" concrete triggers + when NOT to use, pointing at the sibling skill that applies. The description is the only thing the model sees before deciding to load the skill — triggers matter more than elegance.

House template

---
name: {dir-name}
description: {what it does/produces}. Use when {triggers}. Do not use for {adjacent case} — use /{other-skill}.
---

# {name} — {one-line purpose}

{2–3 sentences: input → output contract.}

**Announce at start:** "Using the {name} skill — {purpose}."

## Step 1: {imperative}
{exact commands, expected output}
...

## Output
{exact template the skill must produce, in a fenced block}

## Done when
- [ ] {verifiable item — a command result or an artifact at an exact path}

## Failure → action        {when the skill can fail mid-run}
| Symptom | Action |

Sizing: most skills 60–180 lines. Move heavy reference material (100+ lines) to references/*.md inside the skill dir and say exactly when to read each file. One excellent example beats three mediocre ones.

Formatting trap: when a template block in your skill must itself contain fenced commands, use a four-backtick outer fence (````markdown) — a three-backtick fence inside a three-backtick fence closes the outer block early and garbles everything after it.

Canonical artifact paths (use these; never invent new ones)

Artifact	Path
Research findings	.ai/research/{slug}.md
Specs	.ai/specs/{YYYY-MM-DD}-{slug}.md
Implementation plans + progress	.ai/plans/{YYYY-MM-DD}-{slug}.md
Run logs (multi-step operation records)	.ai/runs/{YYYY-MM-DD}-{slug}.md
Browser playbooks	.ai/playbooks/{slug}.md
Improve handoff plans	.ai/plans/improve/
Ephemeral runtime output (screenshots, debug logs)	.ai/scratch/ (gitignored)

Command conventions every skill must respect: scoped typecheck only (pnpm exec turbo run typecheck --filter=<pkg> — whole-repo OOMs), pnpm never npm, pnpm run generate:types after migrations before typechecking, commits go through /check-and-commit.

Workflow for a new or edited skill

1. Check overlap first. Read .claude/skills/README.md. If an existing skill covers 70% of the job, extend it — two overlapping skills with different instructions is worse than one imperfect skill.
2. Write the skill per the template. Verify every reference (rule 6).
3. Cold-read test. Dispatch a subagent with only the skill text and a realistic task; watch where it stalls, improvises, or misreads. Every stall is a gap in the skill, not a flaw in the executor. Fix and repeat.
4. Re-run the installer and confirm the skill registers:

   pnpm install-skills && bash .ai/scripts/install-skills.sh --list
   

5. Update .claude/skills/README.md (the index) and, if the skill belongs in a pipeline, the root AGENTS.md Workflows table.

Editing rules

• A skill that names a file, command, or flag that no longer exists is stale — fix it the moment you notice (.claude/rules/keep-sources-in-sync.md).
• Never weaken a STOP rule or a gate to make a run pass.
• When you change a skill's contract (inputs, outputs, artifact paths), grep .ai/ and AGENTS.md files for inbound references and update them in the same change.