---

name: skill-writing-guide description: Use when writing a new SKILL.md from scratch or improving an existing one. Covers the four sections every skill needs, how to write a trigger an agent will actually match, what the pitfalls section is really for, and the signs that a skill is complete vs still a draft.

How to Write a Great Skill

A skill is a SKILL.md file that turns a general-purpose agent into a trained teammate for one specific job.

Before writing a skill for this repo, read AGENTS.md once - specifically CRITICAL RULES, Local Commands, and Deployment + Tooling Gotchas. Those sections are the ground truth; this skill teaches structure and craft, not project rules.

For verified commands, design rules, and the ship workflow, see reference/project-conventions.md (this skill's companion file).

When to trigger

You are writing a new skill, improving an existing one, or a skill is not loading at the right moment or being followed correctly.

The four sections every skill needs

1. Frontmatter description - the only thing the model reads before deciding to load the skill

Write it as "Use when [specific condition]". A condition, not a topic.

• Bad: Covers database work.
• Good: Use when applying a Drizzle migration to a live Neon database. Covers generate/migrate, why db:push destroys data, and safe additive changes.

2. When to trigger

Plain-language expansion. Name exact actions, errors, or user requests. Be specific enough that the wrong kind of request clearly does not match.

3. Procedure

Numbered steps with exact commands and real file paths - nothing approximated. Rules:

• Every command must exist in AGENTS.md > Local Commands. Do not invent variants.
• git add steps must only list paths confirmed to exist. A single nonexistent path aborts the entire staging operation silently (see AGENTS.md > Deployment + Tooling Gotchas).
• If the procedure ends with shipping, say "Run the ship-pipeline skill." Do not reproduce the pipeline.

4. Pitfalls

Real failure modes only - not theoretical cautions. Each entry: one concrete wrong action + exact consequence + exact fix. "Be careful about X" is not a pitfall.

What to leave out

• Rules already in AGENTS.md - reference them, do not copy them. A copied rule drifts silently when AGENTS.md changes.
• Generic best practices.
• Directory listings the agent can ls itself.
• Multiple concerns. Two procedures = two skills.

Skill locations in this repo

Both must be created and kept in sync. A skill that only exists in one location is invisible to the other runtime.

Public library: single-file skills in lib/library/skills.ts; multi-file flagship skills in skills-source/ + generator. See AGENTS.md > Repo Skills > Flagship skill authoring.

Signs a skill is complete

• Trigger is specific enough you can name a request that would NOT match.
• Every command is in AGENTS.md > Local Commands.
• Every pitfall has a named failure, not a caution.
• Reading it takes under 3 minutes.
• No content duplicated from AGENTS.md.

Signs a skill is still a draft

• Trigger is a topic: "Use for database work."
• Procedure contains "appropriately" or "as needed."
• Pitfalls say "make sure to..." instead of "this will fail because..."
• Skill restates rules already in AGENTS.md.

Pitfalls

• A topic-based trigger loads the skill for every question in that domain, burning context on irrelevant jobs. Make it a condition.
• Duplicating AGENTS.md rules in a skill creates drift. When AGENTS.md is updated, the skill goes stale silently. Point there instead.
• A git add step that might include a nonexistent path will silently abort the entire staging operation. Guard with [ -e path ] && git add path or only list confirmed-present paths.
• Skills only exist in .claude/skills/ will not load for Codex agents, and vice versa.