skill-engineering

What this skill does

# Skill Engineering

Skills are prompt templates that extend Claude with domain expertise. A skill lives in `skill-name/SKILL.md` with an
optional `references/` directory for deepening material. SKILL.md must be **behaviorally self-sufficient** — an agent
reading only SKILL.md, without loading any references, must be able to do the job correctly. References provide depth,
not breadth. Description triggers activation; instructions shape behavior. 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

- **SKILL.md format, frontmatter rules, directory layout** — [`${CLAUDE_SKILL_DIR}/references/spec.md`] All frontmatter
  fields (open standard + Claude Code extensions), name rules, string substitutions, progressive disclosure mechanics
  (1%/8K budget, 250-char cap), discovery/precedence, instruction budget, SDK behavior differences
- **Creating a skill from scratch** — [`${CLAUDE_SKILL_DIR}/references/creation.md`] Step-by-step creation workflow,
  scope sizing, description writing formula with examples, evaluation-driven development, archetype deep dives with
  structural patterns, pre-delivery checklist
- **Evaluating skill quality (review, audit)** — [`${CLAUDE_SKILL_DIR}/references/evaluation.md`] Scoring rubric (5
  dimensions × 20pts), activation rate benchmarks, trigger keyword density, testing protocol, common issues by score
  range
- **Skill not triggering, wrong output, refinement** — [`${CLAUDE_SKILL_DIR}/references/iteration.md`] Activation
  reliability research (20%→100%), commitment mechanisms, description optimization tiers, output fixes, restructuring
  and splitting guidance
- **Multi-file skills, scripts, subagents, hooks** — [`${CLAUDE_SKILL_DIR}/references/advanced-patterns.md`] Fork
  pattern, workflow skills, composable skills, dynamic context injection, permission scoping, plugin packaging, Agent
  SDK integration, agent teams, skill-scoped hooks, model/effort overrides
- **Debugging activation failures, script errors** — [`${CLAUDE_SKILL_DIR}/references/troubleshooting.md`] Diagnostic
  steps for structure, activation, output, script, reference, token budget, and plugin cache issues. YAML multiline bug
  documentation.
- **Writing persuasive instructions, reasoning** — [`${CLAUDE_SKILL_DIR}/references/prompt-techniques.md`] Instruction
  budget research, prompt interference detection (Arbiter), CoT trade-offs in persistent context, instruction
  strengthening escalation, format control, debugging instruction failures
- **Skill security — authoring and vetting** — [`${CLAUDE_SKILL_DIR}/references/security.md`] Vulnerability taxonomy
  (26.1% of skills affected), consent gap, enterprise vetting checklist, secure authoring rules, red flags quick
  reference

Read the relevant reference before proceeding.

## Description Formula

The description determines when Claude activates your skill — the highest-leverage field; poor descriptions cause missed
activations.

```
[What it does] + [When to invoke — broad domain claim with trigger examples]
```

- **What it does** — functional description of the skill's purpose. State what the skill covers concretely, not a slogan
  or tagline.
- **When to invoke** — "Invoke whenever task involves any interaction with X." Claims the domain broadly, then lists
  specific triggers as examples under the broad claim.

**Good — functional description + broad claim:**

```yaml
description: >-
  Go language conventions, idioms, and toolchain. Invoke when task
  involves any interaction with Go code — writing, reviewing,
  refactoring, debugging, or understanding Go projects.
```

**Bad — vague, no trigger surface:**

```yaml
description: Helps with documents
```

### Principles

- **Lead with function, not slogans.** The first sentence must describe what the skill covers concretely. Slogans waste
  description tokens on zero activation value.
- **Claim broadly, then list specifics.** "Invoke whenever task involves any interaction with X — creating, editing,
  debugging" beats "Invoke when creating, editing, or debugging X."
- **Aggressive triggering, graceful de-escalation.** Better to trigger and de-escalate inside the skill than to miss
  activations. Native activation is unreliable (20-50% without enforcement hooks). Design skills to be useful when
  loaded, not to depend on perfect auto-activation.
- **Skill dependencies belong in SKILL.md body, not descriptions.** Prerequisites like "load prompt-engineering first"
  are handled by the skill body — putting them in descriptions wastes trigger space.
- **Philosophy belongs in SKILL.md body.** Guiding principles shape behavior inside the skill — not in the description
  where they have zero activation value.

### Activation Reliability

Native skill activation is unreliable. Measured rates across 250+ sandboxed evaluations:

- No hook / simple instruction hook: ~20-50% activation
- LLM pre-eval hook (API pre-screening): ~80% (can fail on multi-skill prompts)
- Forced-eval hook (explicit YES/NO per skill): ~84-100% (most consistent, zero false positives)
- Manual `/skill-name` invocation: 100%

The forced-eval hook works via a **commitment mechanism**: Claude must evaluate each skill, state YES/NO with reason,
then follow through. Simple passive suggestions are ignored. Description optimization alone cannot break the ~50%
systemic ceiling — hooks are the path to consistent activation.

Description optimization tiers, hook implementation details: see [`${CLAUDE_SKILL_DIR}/references/iteration.md`].

## Content Architecture

SKILL.md must be behaviorally self-sufficient. An agent reading only SKILL.md — without loading any references — must be
able to do the job correctly. References provide depth, not breadth.

### What Goes Where

- **Behavioral rules** → SKILL.md body — agent must follow these during work; can't afford a missed reference read
- **Catalog/lookup content** → references/ — agent reads on-demand for specific lookups
- **Situational content** → references/ — only needed in specific phases
- **Voluminous structural content** → references/ — too large to inline, inherently lookup-oriented

If an agent skipping a reference would produce wrong output, that content is behavioral and belongs in SKILL.md.

### Working-Resolution / High-Resolution

When a reference contains both rules and depth, use a two-resolution split:

- **SKILL.md** — working-resolution: the thesis, core rules, summary that enables correct behavior
- **references/** — high-resolution: detailed rubrics, extended examples, full catalogs, edge case coverage

The agent works correctly at working resolution. References let it zoom in.

### Structured Data Formats

Format choice affects LLM accuracy by up to 16pp on identical content. Apply these rules when creating or reviewing any
skill content:

**Use KV lists** for independent-entry data — route tables, tool references, scoring rubrics, configuration mappings,
hook events, permission modes, model aliases. Each entry stands alone; no cross-row scanning is needed.

**Use markdown tables** only for genuinely 2D comparisons where cross-criteria scanning IS the point — decision
matrices, feature comparisons across two or more alternatives.

**Use numbered lists** only for sequential steps where order matters — "1. Read input → 2. Validate → 3. Output."

**Use bullet lists** for rules, directives, and conventions with no ordering — if items can be reordered without
changing meaning, use bullets.

**The table test:** if removing a column would lose comparative meaning → table. Otherwise → KV list.

**Audit format choices** when creating or reviewing a skill. Converting misused tables to KV lists is a mechanic