Skills are: Reusable techniques, patterns, tools, reference guides, runbooks. Skills are NOT: Narratives, one-off solutions, standard practices already in training data, project-specific conventions (those belong in CLAUDE.md).

See references/thariq-skill-categories.md for the nine skill categories.

Skill Structure

Skills are folders, not files. Use the filesystem for progressive disclosure:

skill-name/
  SKILL.md              # Main reference (required, <300 lines target, 500 hard max)
  references/           # Detailed docs, API schemas, examples
  scripts/              # Bash scripts for deterministic operations
  config.json           # User-specific setup (if needed)

SKILL.md stays focused. Heavy reference material goes in references/. Tell Claude what files exist — it reads them when needed.

Frontmatter

---
name: gerund-style-name
description: "Use when [specific triggering conditions and symptoms]"
---

name: letters, numbers, hyphens only. Gerund preferred (orchestrating, debugging).
description: max 1024 chars. Third person. Trigger conditions only — never summarize workflow. See references/search-optimization.md for why descriptions must avoid workflow summaries.

SKILL.md Sections

# Skill Name

[1-2 sentence overview with core principle]

## When to Use
[Symptoms, triggers. When NOT to use. Flowchart only if decision is non-obvious.]

## Process / Core Pattern
[Steps, before/after, or decision tree. Inline code if <50 lines.]

## Quick Reference
[Table or bullets for scanning]

## Integration
[Cross-references to related skills]

## Gotchas
[Mandatory. Built from real failure patterns. Highest-signal section.]

Evaluation-Driven Development

Follow RED-GREEN-REFACTOR adapted from arsyn:tdd:

RED: Establish Baseline

Run pressure scenarios with a subagent WITHOUT the skill. Document:

What choices did the agent make?
What rationalizations did it use (capture verbatim)?
Which combined pressures triggered failures?

This is the eval. You must see failure before writing the fix.

GREEN: Write Minimal Skill

Address the specific failures from baseline. Do not add content for hypothetical cases. Run same scenarios WITH the skill. Agent should now comply.

REFACTOR: Close Loopholes

Agent found new rationalizations? Add explicit counters. Re-test. Iterate with Claude A/B pattern: Agent A writes skill, Agent B tests it blind.

See testing-skills-with-subagents.md for pressure scenario methodology.

Writing Principles

Conciseness — Challenge Every Token

Every token in a frequently-loaded skill burns context in every conversation.

One excellent example beats three mediocre ones
Reference --help instead of documenting all flags
Cross-reference skills instead of repeating content

Degrees of Freedom

Match constraint level to task fragility:

High freedom (creative tasks): provide info, let agent decide approach
Medium freedom (standard tasks): provide patterns with room to adapt
Low freedom (safety-critical): strict sequences, explicit prohibitions

Do Not State the Obvious

Focus on what breaks default assumptions: project-specific patterns, unconventional choices, edge cases that cause failures. Standard programming knowledge is already in training data.

Do Not Over-Constrain

Provide necessary information but allow adaptation. Skills are reused across different contexts — rigidity prevents that.

Gotchas Section is Mandatory

Most information-dense part of any skill. Built from real agent failure points.

Format:

## Gotchas
- **[Short name]** -- What goes wrong and how to avoid it.

One Level Deep References

SKILL.md references files in references/. Those files do not reference further files. Keeps the dependency graph flat.

Feedback Loops

Effective skills encode run-validate-fix-repeat cycles. Tell the agent how to verify its own work at each step, not just what to do.

Config and Setup

If a skill needs user-specific context, store in config.json. If config is missing or incomplete, use AskUserQuestion for structured input.

Deterministic Operations as Scripts

When a skill includes steps that must execute exactly (no judgment), put them in scripts/ as bash. Claude orchestrates; scripts execute deterministically.

Anti-Patterns

Narrative storytelling — "In session 2025-10-03, we found..." Too specific, not reusable.
Multi-language examples — One well-chosen language. Claude ports easily.
Code in flowcharts — Cannot copy-paste. Use code blocks.
Generic labels — "step1", "helper2". Labels need semantic meaning.
Batch skill creation — Test each skill individually before moving to the next.
Skipping baseline — Writing a skill without seeing agents fail first guarantees the skill addresses the wrong problems.
Description as workflow summary — Causes Claude to shortcut past the actual skill content. See references/search-optimization.md.

Flowcharts

Use only for non-obvious decision points, process loops where stopping too early is likely, or A-vs-B decisions. Never for reference material, code examples, or linear instructions.

See references/graphviz-conventions.dot for style rules.

Skill Testing by Type

Skill type	Test with	Success =
Discipline (rules)	Pressure scenarios, combined pressures, rationalization probes	Follows rule under max pressure
Technique (how-to)	Application scenarios, edge cases, missing-info tests	Applies technique to new scenario
Pattern (mental model)	Recognition, application, counter-examples	Correctly identifies when/how to apply
Reference (docs/APIs)	Retrieval, application, gap testing	Finds and correctly uses information

Bulletproofing Discipline Skills

When skills enforce rules (like TDD), agents rationalize under pressure. Counter this:

Close every loophole explicitly — Do not just state the rule. Forbid specific workarounds.
Build rationalization tables — Capture every excuse from baseline testing; add counters.
Create red flags lists — Self-check triggers for when the agent is about to rationalize.
"Letter = spirit" principle — State early: "Violating the letter of the rules is violating the spirit."

See references/persuasion-principles.md for research foundation on authority, commitment, and social proof.

Creation Checklist

RED:

Design pressure scenarios (3+ combined pressures for discipline skills)
Run baseline WITHOUT skill — capture failures verbatim
Identify patterns in rationalizations

GREEN:

Write SKILL.md addressing specific baseline failures
Frontmatter: gerund name, trigger-only description, <1024 chars
Run scenarios WITH skill — verify compliance

REFACTOR:

Identify new rationalizations, add counters
Re-test until stable
Verify Gotchas section covers all discovered failures

Quality:

Under 300 lines (hard max 500)
Heavy reference in references/, not inline
No redundancy with cross-referenced skills

Integration

arsyn:tdd — the RED-GREEN-REFACTOR foundation this skill adapts
references/anthropic-best-practices.md — official skill authoring guidance
references/search-optimization.md — description field and discovery optimization
references/thariq-skill-categories.md — nine skill categories for classification
references/persuasion-principles.md — research on bulletproofing discipline skills
testing-skills-with-subagents.md — pressure scenario methodology

Gotchas

Writing before measuring — Creating a skill without baseline eval means addressing imagined problems. Always see agents fail first.
Description summarizes workflow — Claude shortcuts past skill body. Descriptions must contain only trigger conditions.
Skill too long — Over 300 lines signals insufficient progressive disclosure. Move detail to references/.
Testing only happy path — Discipline skills need adversarial pressure: time constraints + sunk cost + authority pressure combined.
Batch deployment — Test each skill individually. Deploying untested skills is deploying untested code.
Hypothetical content — Adding sections for "what if" scenarios not seen in baseline. Address observed failures only; add more as discovered.
Force-loading with @ links — @ syntax loads files immediately, burning context. Use skill name references instead.