skill-crafting

name	skill-crafting
description	Create and refine agent skills.

Skill Crafting

Build skills through evaluation-driven development: create evals first, measure baseline behavior, write the skill, verify improvement, iterate.

Core principle: If you did not watch an agent fail without the skill, you do not know what the skill needs to teach.

Personal skills: ~/.claude/skills (Claude Code), ~/.agents/skills/ (Codex).

What Skills Are

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future agent instances find and apply effective approaches.

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:

1. Close every loophole explicitly — Do not just state the rule. Forbid specific workarounds.
2. Build rationalization tables — Capture every excuse from baseline testing; add counters.
3. Create red flags lists — Self-check triggers for when the agent is about to rationalize.
4. "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.