Skill Writing

Skill Writing

Skills are bundled instruction modules that load into an agent's context when activated. They are the highest-leverage mechanism for controlling agent behavior because they deliver focused instructions at the moment of relevance.

The Iron Law

No skill without a failing test first. Before writing a skill, run a subagent on the target task WITHOUT the skill. Document what it gets wrong — the exact rationalizations, shortcuts, and skipped steps. Then write the skill addressing those specific failures. This is TDD applied to documentation.

When to Create a Skill

Create when: the technique wasn't obvious, you'd reference it across projects, others would benefit, or the agent repeatedly fails without it.

Don't create for: one-off solutions, standard practices documented elsewhere, project-specific conventions (use CLAUDE.md), or mechanical constraints (enforce with linters/hooks instead).

Core Principles

Instructions are a finite budget. Models reliably follow ~150 instructions. The system prompt burns ~50. Every instruction you add degrades compliance across ALL instructions. Be ruthless about what earns a slot.

Peripheral positions get more attention. First and last sections receive disproportionate attention. Bury a critical rule in the middle and it gets skipped.

Specificity drives compliance. "Consider running audits" gets ignored. "Call accessibility_audit before emitting RUN_COMPLETED" gets followed.

Unconditional beats conditional. "You MUST call X" works. "When appropriate, consider X" does not.

Description Optimization

The description field controls when the skill activates. The agent reads it to decide: "Should I load this right now?" Describe triggering conditions, not workflow.

Bad: description: A skill for TDD - write test first, watch it fail, write code Good: description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently. Covers flaky tests, hanging tests, zombie processes.

Checklist for descriptions:

• Start with "Use when..." focusing on triggering conditions
• Include specific symptoms and error messages the user would mention
• Include synonyms (timeout/hang/freeze, cleanup/teardown/afterEach)
• Name tools, commands, file types that signal relevance
• Max 500 characters. Under 200 for frequently-loaded skills
• Never summarize the skill's process — this causes agents to follow the description instead of loading the full skill

Skill Structure

.agents/skills/<skill-name>/
  SKILL.md          # Required. Under 200 lines.
  references/       # Optional. Heavy reference docs (100+ lines).

Frontmatter

---
name: kebab-case-name
description: Use when [triggering conditions]. Covers [symptoms, tools, keywords].
---

Use verb-first active naming: creating-skills not skill-creation, condition-based-waiting not async-helpers.

Writing Instructions That Get Followed

Lead with identity, then constraints

One-line role statement, then hard constraints immediately. Do not build up to them.

# Browser Test Executor

You are executing adversarial browser tests against code changes.

REQUIRED for every test run:
1. Call accessibility_audit before completing
2. Call performance_metrics before completing
3. Call close to flush the session

Use numbered checklists gated on completion

Numbered lists signal sequence and completeness. Tie them to whatever marks the task "done."

Before marking the task complete, you MUST:
1. Run the linter
2. Run the type checker
3. Run the test suite
Do not skip any step. A skipped step is a failed task.

The trailing "do not skip" is not redundant — it closes the escape hatch.

Name tools and commands exactly

Never "run the appropriate checks." Always call accessibility_audit or run pnpm typecheck.

Put mandatory behaviors at the end

The last section is the last thing read before acting. Put the non-negotiable checklist there.

One good example, one bad example

Examples are worth more than explanations.

**Bad:** `test the login page`
**Good:** `Submit login with empty fields, invalid email, wrong password, valid credentials. Verify errors and redirect.`

Bulletproofing Against Rationalization

Agents invent reasons to skip rules. Anticipate and close every loophole explicitly.

Close escape hatches: After every mandatory rule, add: "No exceptions for 'just this once', 'it's simple enough', or 'I'll do it next time'."

Build a rationalization table from your RED phase testing. Every excuse the agent made becomes an explicit counter in the skill:

Create a red flags list: "If you catch yourself thinking any of these, stop and follow the checklist."

Anti-Patterns

Checklist: Before Shipping

• Tested without the skill first (RED phase) and documented failures
• Skill addresses those specific failures, not hypothetical ones
• Description starts with "Use when..." and lists triggering conditions, not workflow
• Under 200 lines total
• Mandatory behaviors in a numbered checklist at top or bottom
• Every tool/command named exactly — no "appropriate" or "relevant"
• No hedging ("consider", "when appropriate", "if needed")
• At least one good/bad example pair
• No duplication with CLAUDE.md or other skills
• Escape hatches closed with explicit "no exceptions" language
• Re-tested with the skill (GREEN phase) and agent now complies