skill-engineering

# Skill Engineering

Skills are prompt templates that extend Claude with domain expertise.
They load on-demand: Claude sees only `name` and `description` at startup,
then loads full SKILL.md content when triggered.

<prerequisite>
**Skills are prompts.** Before writing or improving a skill, invoke
`prompt-engineering` to load instruction design techniques.

```
Skill(ai-helpers:prompt-engineering)
```

Skip only for trivial edits (typos, formatting).
</prerequisite>

## Route to Reference

| Situation | Reference |
|-----------|-----------|
| SKILL.md format, frontmatter rules, directory structure | [spec.md](references/spec.md) |
| Creating a skill from scratch | [creation.md](references/creation.md) |
| Evaluating skill quality (review, audit) | [evaluation.md](references/evaluation.md) |
| Skill not triggering, wrong output, needs refinement | [iteration.md](references/iteration.md) |
| Multi-file skills, scripts, subagents, hooks | [advanced-patterns.md](references/advanced-patterns.md) |
| Debugging activation failures, script errors | [troubleshooting.md](references/troubleshooting.md) |
| Writing persuasive instructions, reasoning patterns | [prompt-techniques.md](references/prompt-techniques.md) |

Read the relevant reference before proceeding.

## Description Formula

The description determines when Claude activates your skill.

```
[What it does] + [When to use it]
```

**Good:**
```yaml
description: >-
  Extract text from PDFs, fill forms, merge documents.
  Use when working with .pdf files or document extraction.
```

**Bad:**
```yaml
description: Helps with documents
```

Include: specific capabilities, trigger keywords, file types.
Avoid: vague verbs ("helps", "assists"), marketing speak.

## Skill Structure

```
skill-name/
├── SKILL.md              # Required: frontmatter + instructions
└── references/           # Optional: detailed docs loaded as needed
    └── *.md
```

**Locations:**
- Personal: `~/.claude/skills/<name>/SKILL.md`
- Project: `.clau