Writing skills

Overview

Skill development connects drafting (this skill) with evaluation (slow-powers:evaluating-skills). Start with the problem the skill should solve and the outcomes that would make it useful. Draft the guidance and design its eval coverage against those same goals. This skill covers structure, building blocks, description writing, and rationalization-proofing; evaluating-skills owns measurement.

A behavioral draft you didn't measure is a claim you didn't verify. Build a reusable suite with a new skill, and reuse it when revising the prose. Define new cases when goals change or evidence reveals a coverage gap or defective grader. Deterministic edits can skip behavioral measurement with a stated reason; see "When to run" in slow-powers:evaluating-skills. Mark draft or exploratory work as such until measured.

Validation checklist

Use your persistent task tracker — one task per item. Works for authoring a new skill or auditing an existing one — copy it into your tracker before you start, then work through the rest of this skill against it.

Draft:

• State the motivating problem, intended goals, and observable success before drafting prose
• Name uses only lowercase letters, numbers, hyphens
• Frontmatter has name and description (under 1024 chars total)
• Description starts with "Use when…", is third person, includes triggers/symptoms, and contains NO workflow summary
• Body keeps to one excellent example per concept; no narrative-of-one-session content
• Companion files use the correct directory from "Skill directory layout"; principles stay inline
• Flowcharts only for non-obvious decisions/loops/branches; semantic labels, no code
• Any checklist sits near the top of the body, before the procedural sections it gates
• Body is lean (≤200 lines preferred, 500 max)

Validate (handoff to slow-powers:evaluating-skills):

• Decide whether the change is behavior-shaping or deterministic, and announce the decision and reasoning (see "When to run"). Default to behavior-shaping when unsure.
• Reuse a trustworthy suite; for an uncovered goal, explore realistic work and author cases in evals/evals.json, with a goal-based COVERAGE.md beside it
• For discipline-enforcing skills, include realistic pressure and at least one seeded case (embeds a prior transcript) alongside a cold contrast case
• Calibrate new or revised graders, then measure the frozen suite across fresh sessions; report regressions, benefits, cost, and uncertainty against the goals

Deploy:

• Commit the skill (and its evals/evals.json, when authored) together
• In the PR, include before/after eval evidence and its limitations — or, for a deterministic change, the stated decision and reasoning to skip; label unfinished measurement explicitly

What is a skill?

A skill is a reusable reference guide for a proven technique, pattern, or tool — not a narrative about how you solved a problem once ("In session 2025-10-03 we found…" is too tied to a moment to reuse).

Create a skill when: the technique wasn't intuitively obvious, you'd reference it again across projects, and the pattern applies broadly.

Don't create one for: one-off solutions, standard practices documented elsewhere, project-specific conventions (put those in CLAUDE.md / AGENTS.md), or mechanical constraints a regex or validation could enforce — automate those instead.

Skill types

• Technique — concrete method with steps (condition-based-waiting, root-cause-tracing).
• Pattern — a way of thinking about problems (flatten-with-flags, test-invariants).
• Reference — API docs, syntax guides, tool documentation.

Cross-harness vocabulary

Skills may ship across harnesses, so they should describe capabilities, not platform tool names. Use these terms as the canonical vocabulary reference.

SKILL.md structure

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Skill name

## Overview        — what is this? Core principle in 1-2 sentences.
## When to use     — symptoms and use cases; when not to use.
## Core pattern    — before/after comparison (techniques/patterns).
## Quick reference — table or bullets for scanning common operations.
## Implementation  — inline code for simple patterns; link a file for heavy reference.
## Common mistakes — what goes wrong + fixes.

Frontmatter rules:

• Two required fields, name and description, max 1024 characters total. See agentskills.io/specification for the full schema.
• name: lowercase letters, numbers, hyphens only.
• description: third person, triggering conditions only — see "Writing the description".

Building blocks

The blocks below help structure a SKILL.md file. Use the ones that fit — not every skill needs all of them. These aren't limiters, and your skill should contain the content it needs.

Each block does one job:

• Gotchas (any skill) — environment-specific facts that defy reasonable assumptions, so the agent reads them before hitting the trap. These correct factual mistakes, not motivation:

  • The users table uses soft deletes — queries need WHERE deleted_at IS NULL.
  • The ID is user_id in the DB, uid in auth, accountId in billing — same value.

  Keep gotchas inline; when an agent makes a mistake you have to correct, add it here.

• Red flags / rationalization table (discipline skills only) — these look like gotchas but are not the same: gotchas correct facts, red flags counter motivated reasoning under pressure, and they come from observed failures in real work or eval pressure-testing. See "Rationalization-proofing" below for how to build them.
• Quick-reference table — for scanning common operations. Tables and lists, not prose.
• Checklist (multi-step skills) — when steps have dependencies or validation gates, give a checklist the agent copies into its task tracker and ticks off, so it can't skip a gate. Place the checklist near the top of the body: the agent must adopt it into its tracker before following the rest of the skill, and a checklist buried below the procedural prose is met mid-flow — after the agent has already started executing the steps it was meant to gate.
• Code examples — one excellent example beats many mediocre ones. Pick the language that fits the domain (testing → TS/JS, system debugging → shell/Python). A good example is complete, runnable, commented on the WHY, from a real scenario, ready to adapt. Don't reimplement it in five languages — agents port well, and multi-language dilution means mediocre quality everywhere plus maintenance burden on every change.

Flowchart usage

Use a small inline flowchart only when the decision is non-obvious, there's a process loop where you might stop too early, or it's an "A vs B" branch where the wrong choice has consequences. Don't use flowcharts for reference material (use tables/lists), code (use code blocks — step1[import fs] can't be copy-pasted), linear instructions (use numbered lists), or labels without semantic meaning (step1, helper2 — labels should carry meaning).

Write flowcharts as mermaid (```mermaid blocks) — it renders natively in GitHub and most editors, so no tooling or dependency is needed to preview. Shape carries meaning:

Quote any label containing [ ] : ( ) / or ' with "...", e.g. done(["Respond (including clarifications)"]).

Writing the description

The description is how agents (and the skill mechanism) decide whether to load your skill. Make it answer one question: should I read this skill right now?

Description = WHEN, not WHAT. Do not summarize the skill's workflow. Testing has repeatedly shown that when the description summarizes the process, agents follow the description instead of reading the skill. A description saying "code review between tasks" caused an agent to do ONE review even though the skill body described TWO; changing it to "Use when executing implementation plans with independent tasks" — no workflow summary — produced the correct two-stage behavior. The trap: workflow summaries create a shortcut, and the skill body becomes documentation the agent skips.

# ❌ Summarizes workflow — agent may follow this instead of reading the skill
description: Use when executing plans — dispatches subagent per task with code review between tasks

# ✅ Triggering conditions only
description: Use when executing implementation plans with independent tasks in the current session

Other rules:

• Start with "Use when…" and write in third person — descriptions are injected into the system prompt.
• Describe the problem (race conditions, timing dependencies), not language-specific symptoms (setTimeout, sleep) unless the skill is technology-specific.
• Keyword coverage: use words an agent would actually search for — error messages ("Hook timed out", "ENOTEMPTY"), symptoms ("flaky", "hanging"), synonyms ("timeout / hang / freeze").

Note — this is a deliberate house stance. External sources disagree on descriptions: Anthropic says include what the skill does plus when; agentskills favors imperative, user-intent phrasing. Because there's no shared standard, we maintain our WHEN-not-WHAT rule. The load-bearing part is no workflow summary.

Naming

Active voice, verb-first; gerunds (-ing) work well for processes. Name by what you DO or the core insight, not the surface category.

• ✅ creating-skills, condition-based-waiting, root-cause-tracing
• ❌ skill-creation, async-test-helpers, debugging-techniques

Cross-referencing other skills

Use the skill's qualified name with an explicit requirement marker:

• ✅ **REQUIRED BACKGROUND:** You must understand slow-powers:working-with-tdd
• ✅ **REQUIRED PREREQUISITE:** You must have already completed slow-powers:investigating-bugs
• ✅ **REQUIRED NEXT SKILL:** You must complete slow-powers:investigating-bugs next
• ❌ See skills/testing/working-with-tdd — unclear if required, harness-specific path
• ❌ @skills/testing/working-with-tdd/SKILL.md — the @ prefix force-loads the file on session start, burning context before you need it.

Don't repeat what another skill says — link to it.

Conciseness and file organization

Once a skill loads, every token competes with conversation history. Keep the body lean: aim for ≤200 lines for frequently-loaded internal skills, and treat 500 lines / 5,000 tokens as the hard ceiling for any skill. Move details to tool help ("Run <tool> --help for flags" beats listing every flag), cross-reference instead of repeating, and compress examples to one good pair.

Use progressive disclosure for anything heavy: the SKILL.md file is the always-loaded overview; bulky material lives in separate files the agent loads on demand. Tell the agent when to load each ("Read references/api-errors.md if the API returns non-200") rather than a generic "see references/".

Skill directory layout

A skill always has a SKILL.md file. Add any of these peer directories when their contents are needed:

Make every companion file reachable from SKILL.md through local links. A link in SKILL.md is relative to the skill root (references/guide.md, scripts/check.sh, assets/template.md, evals/evals.json); links inside companion files are relative to the file containing the link. Keep primary resources one level below the skill root. A secondary resource may be one more hop away when it is useful only after reading the primary resource; avoid deeper discovery chains.

skill-name/
├── SKILL.md
├── references/
├── scripts/
├── assets/
└── evals/

Create companion files when they serve one of the roles above, not merely to shorten SKILL.md. Principles, concepts, and short code patterns stay inline.

Rationalization-proofing for discipline skills

Skills that enforce discipline (TDD, verifying-development-work, hardening-plans) must survive pressure — agents find loopholes under time, sunk-cost, or authority pressure. Drafting an enforceable rule differs from drafting a guideline. In one controlled study, persuasion cues more than doubled compliance for the tested model and prompts. See the persuasion principles for the seven principles, when each applies, the study's limits, and citations (Cialdini, 2021; Meincke et al., 2026).

Close the loopholes behind observed failures. State the rule and counter the workarounds that evidence connects to a failed goal. Ordinary mechanical instructions, such as naming a next skill verbatim, do not merit red flags, repeated enforcement, or performance eval cases merely because the skill requires them. If real work or eval evidence shows an apparently mechanical step actually fails, targeted coverage and stronger guidance can be warranted.

✅ Write code before test? Delete it. Start over.
   No exceptions: don't keep it as "reference", don't "adapt" it while writing tests.
   Delete means delete.

Address "spirit vs letter" early, before the agent reaches for it:

Violating the letter of the rules is violating the spirit of the rules.

Build the rationalization table and red-flags list from failure evidence — they aren't an inventory of instructions to reinforce up front. Capture relevant excuses verbatim from real work or evals, then check them against the agent's actions. Add a counter when the evidence points to a gap in the guidance, and measure the revision on the same cases:

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |

## Red flags — STOP and start over
- Code before test
- "I already manually tested it"
- "This is different because…"

Use seeded eval cases to investigate mid-session rationalizations: embed a short prior transcript so the agent meets the decision already committed to an approach. Check explanations against actions and outcomes before adding a counter. See the pressure-scenarios reference for realistic context and the limits of text seeds.

Evaluation can also reveal guidance the base agent or intended harness already supplies. When the evidence supports that conclusion, simplify or narrow the skill for that population and remeasure. Do not demand a harder case or stronger enforcement just to produce a benefit; slow-powers:evaluating-skills owns that interpretation.

Further reading

• slow-powers:evaluating-skills — goal coverage, suite authoring, and measurement
• slow-powers:writing-technical-docs — the general technical-writing skill (comments, PR descriptions, READMEs, design docs). This skill is the doc-type authority for skills: it owns skill structure, frontmatter, and skill-specific prose conventions. Where this skill is silent about the prose itself — clarity, concision, sentence construction — writing-technical-docs' style principles apply. On any conflict, this skill wins.
• Persuasion principles — research foundation for discipline language
• agentskills.io best-practices and optimizing-descriptions — harness-agnostic depth on patterns and description testing
• Anthropic Agent Skills best practices — degrees-of-freedom, progressive disclosure, and script-bundling depth