skill-crafting

Files (9)

• SKILL.md
• CLAUDE_MD_TESTING.md · examples/
• anthropic-best-practices.md · references/
• graphviz-conventions.dot · references/
• persuasion-principles.md · references/
• search-optimization.md · references/
• thariq-skill-categories.md · references/
• render-graphs.js
• testing-skills-with-subagents.md

SKILL.md (first lines)

# 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

```yaml
---
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

```markdown
# 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.

From renathoaz/arsyn, MIT.

More from renathoaz/arsyn