write-procedure

Writing a Procedure

Does this deserve a file?

A procedure earns a file when it is a repeatable process the team must get right every time:

• A recurring deliverable with a strict format (weekly report, review doc, status update)
• A compliance or safety requirement that must be followed without deviation
• A multi-step workflow crossing more than one agent
• A process where a mistake is costly to undo

If it only runs once, or the team gets it right from context alone, do not write it — every standing rule costs attention forever.

Skill or policy?

• Skill (.claude/skills/<name>/SKILL.md) — loads only when a task matches. This is the default. The description frontmatter must contain the concrete trigger phrases that should activate it.
• Policy (policies/<name>.md) — applies to every task, always (security constraints, workspace boundaries). Policies are expensive: keep each under one page, and keep the folder small. If you hesitate, it's a skill.

Skill format

---
name: <kebab-case>
description: <What it covers + explicit "Use when ..." trigger phrases.>
---

# <Procedure name>

## When this applies
## Steps            (numbered, checkable)
## Output           (what is produced, where it lands)
## Failure modes    (the known ways this goes wrong)

Quality bar

• Steps are checkable: someone else can verify each was done.
• Name the failure modes the procedure exists to prevent — a procedure that prevents nothing is decoration.
• One procedure per file; link related ones instead of merging them.
• Log the new file with one CHANGELOG.md line.