Skills: Writing Guide

The core principle: the model is already smart

The context window is shared with the conversation, other skills, tool schemas, and files. Every line of your skill competes for that space, so ask of each one:

• Would the agent get this wrong without it?
• Is this specific to us, or is it general knowledge?
• Would one example replace this whole paragraph?

Writing the description

Rule	✅ Good	❌ Bad
Third person	“Generates SQL migrations…”	“I can help you…” / “You can use this to…”
What and when	“…Use when the user asks for a migration or edits db/schema.sql.”	“Database helper.”
Real trigger words	“release notes, changelog, what shipped”	“documentation artefacts”
Specific scope	“Customer-facing release notes”	“Writing”
Distinct from neighbours	Mentions what it’s not for when there’s overlap	Two skills with near-identical descriptions

Formula: <Verb>s <object> <qualifier>. Use when <trigger 1>, <trigger 2>, or <trigger 3>.

Degrees of freedom

Match how prescriptive you are to how fragile the task is:

Freedom	When	Form	Example
High	Many valid approaches; judgement needed	Principles and heuristics in prose	Code review priorities
Medium	A preferred pattern, with some variation OK	A template or pseudocode with parameters	Report structure
Low	Fragile, must be exact, errors are costly	An exact script or command: “run exactly this”	DB migration, form filling, deploy

A useful picture: a narrow bridge with cliffs on both sides needs guard rails (low freedom). An open field needs only a direction (high freedom).

Proven patterns

Workflow with checklist

For multi-step tasks, give the agent a checklist to copy and track:

## Release notes workflow

Copy this checklist and update it as you go:

```
- [ ] 1. Gather merged PRs since the last tag
- [ ] 2. Classify each as New / Improved / Fixed / Internal (drop Internal)
- [ ] 3. Rewrite titles in customer language (see references/voice.md)
- [ ] 4. Fill assets/release-notes-template.md
- [ ] 5. Run scripts/check_notes.py and fix every warning
```

Template

Supply the exact output shape in assets/ or inline:

## Output format
```markdown
# <Product> <version>, <date>
## New
- **<Feature>**: <one-sentence customer benefit>
## Improved
## Fixed
```

Examples (input → output)

Two or three concrete pairs beat a page of rules:

**Input:** `fix(auth): handle null refresh token on SSO callback (#482)`
**Output:** `- Fixed an issue where some single sign-on users were logged out unexpectedly.`

Conditional workflow

1. Determine the task:
   - **Creating a new document?** → follow "Create" below
   - **Editing an existing one?** → follow "Edit" below

Feedback loop (validate → fix → repeat)

1. Make the change.
2. Run `python scripts/validate.py output/`
3. If it reports errors: fix them and go back to step 2.
4. Only continue when validation prints `OK`.

Plan → validate → execute (for high-stakes operations)

Have the agent write its intended changes to a plan file (for example changes.json), validate that file with a script, and only then apply it. This catches mistakes before they touch anything real.

Writing reference files

• Give each file one topic, and name it after that topic (references/schema.md, not references/doc2.md).
• Link it from SKILL.md with a when to read cue: “If the table isn’t in the quick list, read [references/schema.md]…”
• Add a table of contents to files over ~100 lines, because agents sometimes read only the top of a file.
• For very large references, tell the agent to grep for a keyword rather than read the whole file.

Writing scripts

• Solve, don’t punt. Handle missing files and bad input inside the script, and print what to do next.
• No magic numbers. Explain constants (TIMEOUT = 30 # the API p99 is ~12s).
• Say execute vs read. “Run scripts/x.py” is not the same instruction as “See scripts/x.py for the algorithm.”
• Declare dependencies. Don’t assume a package is installed. Hosted environments (such as the Claude API or Claude.ai) may have no network access for installs.
• Forward slashes only, and paths relative to the skill folder.
• Machine-readable output where the agent parses it (JSON, or OK/ERROR: …).

Anti-patterns

Anti-pattern	Fix
Walls of explanation about general concepts	Delete; the model knows them
“You can use A, or B, or C, or D…”	Give one default plus one escape hatch
Time-sensitive statements (“before Aug 2025 use v1”)	Describe the current method; put legacy material in a collapsed “Old patterns” section
Inconsistent terms (“endpoint” / “route” / “URL”)	Pick one term and use it everywhere
Deeply nested references	Link everything from SKILL.md
Secrets or tokens in any file	Environment variables; document the variable name only
Windows paths (scripts\run.py)	scripts/run.py
Huge SKILL.md (> 500 lines)	Split it into references/

Style conventions (recommended)

• Imperative voice: “Run…”, “Check…”, “Never…”.
• Bold the words never, always, and must sparingly, so they keep their force.
• Headings that match the order of the workflow.
• Put code blocks right before the step that uses them.