writing-skills

Overview

Skills are behavioral shaping code — they change how agents act, not just what agents know. Writing a good skill requires the discipline of writing good code: clear structure, testable outputs, and defense against misuse.

When to Use

When creating a new skill for CodeHands
When improving an existing skill
When reviewing skill contributions
NOT for skill usage (see codehands:using-codehands)

Process

1. Start from the Template

Copy skills/_template/SKILL.md and fill in all sections. Never write a skill from scratch — the template ensures you don't miss required sections.

2. Write the Description First

The description in YAML frontmatter is the most important text in the skill. Agents decide whether to activate a skill based on this text. Rules:

Start with what the skill does (third person)
Include trigger conditions: "Use when [X]"
Maximum 1024 characters
Do NOT summarize the process — agents may follow the summary instead of the full skill

3. Design the Process

The Process section is the heart of the skill. Each step must be:

Actionable — "Run npm test" not "make sure tests work"
Verifiable — Each step produces evidence of completion
Sequential — Steps build on each other with clear gates

4. Write Anti-Rationalizations

For EVERY step an agent might want to skip, add an entry:

Think: "What would a lazy agent say to skip this step?"
Write the excuse in the Rationalization column
Write a factual rebuttal in the Reality column

This is the MOST IMPORTANT section. Skills without anti-rationalizations are requests, not rules.

5. Add Model Variants

Different models respond to different enforcement styles:

Claude: Collaborative framing ("your human partner")
Gemini: Structured checklists with clear gates
GPT: Direct imperatives with MUST/SHALL language

Add model_variants to frontmatter with appropriate phrasing.

6. Test the Skill

Validate your skill:

bash tests/skill-format.test.sh skills/your-skill/
bash tests/frontmatter.test.sh skills/your-skill/SKILL.md

7. Keep Token Budget

SKILL.md body < 2,000 tokens
If a section exceeds 100 lines, move it to a supporting file
Every section must justify its inclusion — if removing it wouldn't change agent behavior, remove it

Writing Principles

Process over knowledge. Steps, not facts.
Specific over general. Commands, not advice.
Evidence over assumption. Every gate requires proof.
Anti-rationalization as first-class. Every skip-worthy step needs a counter.
Progressive disclosure. Entry point first, details on demand.
Token-conscious. Justify every section's inclusion.

Common Rationalizations

Rationalization	Reality
"My skill doesn't need anti-rationalizations"	Every skill has skip-worthy steps. If you can't think of any, you haven't thought hard enough. Ask: "What would a time-pressured agent skip?"
"The process is obvious, I don't need detailed steps"	What's obvious to you is ambiguous to an agent. "Write good tests" is useless. "Run `npm test` and verify 0 failures" is actionable.
"Model variants are overkill"	Models are your users. Different users respond to different communication styles. 3 extra lines of YAML is not overkill.

Red Flags

Skills without Common Rationalizations table
Skills with vague process steps ("ensure quality")
Skills that exceed 2,000 tokens without supporting files
Description that summarizes the process (agents won't read the full skill)
No Verification section

Verification

All required sections present (Overview, When to Use, Process, Rationalizations, Red Flags, Verification)
YAML frontmatter valid with all required fields
Description < 1024 chars, starts with what (not how)
Every process step is actionable and verifiable
Anti-rationalization table has 3+ entries
Model variants specified
SKILL.md < 2,000 tokens
Cross-references use codehands: namespace
Format tests pass