guidance

---
paths:
  - "**/agents/**/*.md"
---

# Agent Description Length

## Contents

- The target: keep every agent description under 1024 characters
- Why agents drifted long, and why it matters
- What belongs in the description, and what moves to the body
- The priority cutting ladder
- How to measure a description
- Common Pitfalls
- Summary Checklist
- Cross-References

Every installed agent's frontmatter `description` is loaded into context in every conversation, the same way skill
descriptions are. Claude reads the whole roster of agent descriptions to decide which agent to dispatch, so each one is
paid for in every session whether or not the agent runs. Run `/context` in a session with agents installed and you will
see a `Custom agents` line counting those always-loaded tokens before any prompt is sent. This doc sets the length
target for an agent description and explains what belongs in it versus in the agent body.

For _what_ an agent description is for (triggering metadata, not the persona), see
[Domain Focus in Agent Definitions](./agent-domain-focus.md). That doc governs the Role Identity (the body's "You are
a..." paragraph, under 50 tokens) and the `## Domain Vocabulary` and `## Anti-Patterns` body sections. This doc is only
about _how long_ the always-loaded `description` may be, and which content has to move into those body sections to keep
it short.

## The target: keep every agent description under 1024 characters

**Write every agent `description` to fit within 1024 characters**, the same target skills use (see
[Skill Description Length](../skill-building-guidance/skill-description-length.md)). Count the rendered description
string, not the YAML around it.

Some agents legitimately run longer. An orchestrator that names every specialist it coordinates, or a specialist that
has to draw a boundary against five near-sibling agents, carries more required boundary clauses than a single-purpose
skill does. Treat 1024 as the target you aim for and **anything past roughly 1500 characters as a strong signal that the
description is carrying body-grade content** — domain vocabulary, methodology name-drops, an anti-pattern checklist, or
process detail — that belongs in the body instead. The fix is almost never to keep that content and hope it survives; it
is to move it where it already lives.

## Why agents drifted long, and why it matters

Agent descriptions were exempted from the 50-token Role Identity budget (correctly: the description is triggering
metadata, not persona) but were never given a length budget of their own. With no ceiling, the largest agents
accumulated their full domain vocabulary, their named-framework citations, and their anti-pattern lists directly in the
always-loaded description, where every token is paid in every session and competes for the model's attention against
every other instruction (see [Context Hygiene](../skill-building-guidance/context-hygiene.md)). The routing-relevant
signal in those descriptions is a small fraction of the text; the rest is duplicated in the agent body, which loads only
when the agent is dispatched.

That duplication is the lever. The vocabulary an agent lists in the description almost always also appears in its
`## Domain Vocabulary` body section; the anti-pattern checklist also appears in its `## Anti-Patterns` body section.
Moving those out of the description loses nothing operationally — the agent still has them when it runs — and reclaims
always-loaded budget for every session.

## What belongs in the description, and what moves to the body

An agent description answers the same four questions a skill description does: **what** the agent does, **when** to
invoke it, its **boundary** (the "Does not X — use Y" clauses that route to sibling agents), and **trigger breadth**
(the vocabulary a real request would use). Everything else is body-grade.

| Content                                                         | Where it goes                                        |
| --------------------------------------------------------------- | ---------------------------------------------------- |
| What the agent does; primary "Use when" trigger                 | Description (never cut)                              |
| "Does not X — use Y" boundary against a near-sibling agent      | Description (the routing signal is the agent name)   |
| The output contract (what it produces, its adversarial posture) | Description, kept tight                              |
| A unique trigger term no other agent's description carries      | Description (it is the only anchor for that request) |
| Domain vocabulary, named frameworks, author citations           | Body `## Domain Vocabulary`                          |
| Anti-pattern checklists, detection signals                      | Body `## Anti-Patterns`                              |
| Protocols, step lists, methodology expansions                   | Body                                                 |

A useful test for the boundary clauses: the load-bearing unit of a "Does not X — use Y" redirect is the **agent name**,
not the prose describing what that sibling does. A reader who does not already know what `devops-engineer` covers will
look it up; thirty words restating its scope inside this agent's description do not help them route and are not worth
the always-loaded cost. Name the sibling, keep the clause to roughly eight to twelve words, and let the sibling's own
description carry its scope.

Two cautions when trimming, both of which can turn a safe-looking cut into a routing regression:

- **Keep unique anchors.** Before deleting a domain term, check that it is not the _only_ always-loaded place a real
  request would land. If `data-engineer` is the only agent whose description says "event sourcing and CQRS," a user
  asking to "audit this event-sourced projection for CQRS problems" has nowhere else to route once it is gone. A term
  that lives in several descriptions is a name-drop; a term that lives in exactly one is an anchor. Keep the anchor.
- **Boundaries are bidirectional.** If this agent points to a sibling, the sibling should point back (see the
  bidirectional-disambiguation rule in
  [Skill Description Frontmatter](../skill-building-guidance/skill-description-frontmatter.md)). Before deleting one
  side of a pair, confirm the other side; deleting only one half opens a gap Claude can fall through. If you find a
  one-way boundary while trimming, repair it rather than preserve the gap.

## The priority cutting ladder

When a description is over the target, cut in the same fixed order skills use. The full ladder lives in
[Skill Description Length](../skill-building-guidance/skill-description-length.md); applied to agents it reads:

1. **Domain vocabulary, methodology name-drops, and anti-pattern checklists (cut first).** These are body-grade and
   almost always already in the agent body. Move them to `## Domain Vocabulary` / `## Anti-Patterns` and delete them
   from the description. This is the largest and safest reclaim.
2. **Restated capability and process prose.** Mode elaborations, "how it works" sentences, and exhaustive rosters that
   re-list what the body already explains.
3. **Boundary clauses against agents no one would confuse this with.** Drop a "Does not X — use Y" only when a real
   request could not plausibly hit the wrong agent.
4. **Boundary clauses against near siblings (cut last, and reluctantly).** Tighten the wording before deleting; the
   agent name is the part that must survive.
5. **What the agent does and its primary triggers (never cut).** The irreducible core. If what plus primary triggers
   will not fit, the agent is doing too much.

## How to measure a description

Count the rendered description string, resolving a folded (`>`) or quoted scalar. The measuring snippet is in
[Skill Description Length](../skill-building-guidance/skill-description-length.md#how-to-measure-a-description);
point it at the agent file instead of a `SKILL.md`. If the count is well over 1024, find the vocabulary or
anti-pattern content and move it to the body.

## Common Pitfalls

| Anti-pattern                              | Problem                                                                    | Fix                                                                       |
| ----------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Full domain vocabulary in the description | Always-loaded cost paid every session for content the body already carries | Move it to `## Domain Vocabulary`; keep only unique trigger anchors       |
| Anti-pattern checklist in the description | Same; the checklist is in `## Anti-Patterns` already                       | Move it to the body                                                       |
| Thirty-word prose per "Does not" redirect | Burns budget restating sibling scope that adds no routing signal           | Keep the agent name and a short clause; drop the prose                    |
| Deleting a unique trigger term            | Removes the only always-loaded anchor for a real request                   | Grep every agent description first; keep terms owned by exactly one agent |
| Trimming one side of a boundary pair      | Opens a one-way routing gap                                                | Check the sibling's reverse clause; repair, do not preserve, a gap        |

## Summary Checklist

1. The rendered `description` is at or near **1024 characters**, and not past ~1500 unless every clause is a required
   boundary.
2. Domain vocabulary, named frameworks, and anti-pattern checklists live in the agent body, not the description.
3. Each "Does not X — use Y" boundary keeps the sibling name and drops the scope prose.
4. No deleted term was the only always-loaded anchor for a real request (grep to confirm).
5. Every boundary the description draws is matched by a reverse clause in the sibling.
6. The length was measured against the rendered string, not the YAML.

## Cross-References

- [Domain Focus in Agent Definitions](./agent-domain-focus.md) — What the description is for, the 50-token Role Identity
  budget, and the `## Domain Vocabulary` / `## Anti-Patterns` body sections content moves into.
- [Skill Description Length](../skill-building-guidance/skill-description-length.md) — The sibling 1024-character budget
  for skills, the platform limits behind it, and the full priority cutting ladder.
- [Skill Description Frontmatter](../skill-building-guidance/skill-description-frontmatter.md) — The four description
  components and the bidirectional-disambiguation rule that makes boundary trimming safe.
- [Context Hygiene](../skill-building-guidance/context-hygiene.md) — Why every always-loaded token competes for
  attention, so a shorter description helps routing for the whole roster.
- [Progressive Disclosure](../skill-building-guidance/progressive-disclosure.md) — The always-loaded-versus-on-demand
  split that justifies moving vocabulary out of the description and into the body.

---
paths:
  - "**/agents/**/*.md"
---

# Domain Focus in Agent Definitions

## Contents

- Why Domain Focus Matters
- Implementation
- Summary Checklist
- Cross-References

Agents perform better when they target a narrow domain with precise vocabulary. A focused agent activates deep expertise
in the model. A broad generalist activates shallow, averaged knowledge across competing domains.

## Why Domain Focus Matters

### Vocabulary Routing

LLMs organize knowledge in embedding clusters activated by specific terminology. When an agent definition uses precise
domain vocabulary (the terms a 15-year practitioner would use with peers) the model routes to expert-level training
data. Generic language (_"review this code for issues"_) routes to introductory material and blog posts.

This is the **15-year practitioner test**: for every key term in the agent definition, ask whether a senior domain
expert would use that exact term in conversation with another expert. If not, the term is too generic and the model will
activate shallow knowledge.

### Persona Length and Attention

Research indicates that accuracy degrades with elaborate persona descriptions. The optimal range for the Role Identity
(the "You are a..." opening paragraph in the agent body) is **under 50 tokens**. This is enough context to route to the
right domain without wasting attention on self-description rather than task performance.

The frontmatter `description` field is separate from the Role Identity. It is triggering metadata that tells Claude when
to spawn the agent, and is not subject to the 50-token budget. It has its own length budget, because it is always-loaded
for routing: see [Agent Description Length](./agent-description-length.md).

Detailed protocols, checklists, anti-patterns, and procedures that follow the Role Identity do not count toward this
budget. They provide operational depth, not identity framing.

### Self-Evaluation Bias

Agents cannot reliably evaluate their own work. Generator biases replicate in evaluation, creating systematic blind
spots. This means a single agent should not both generate output and evaluate it. Separate agents with fresh
perspectives catch what originators miss.

An agent should have a single role: generate **or** evaluate, not both.

## Implementation

### 1. Write a Clear Frontmatter Description

The `description` field in frontmatter is triggering metadata. It tells Claude when to spawn the agent. It is **not**
the agent's persona and is **not** subject to the 50-token budget. It does, however, have its own length budget, because
every agent description is loaded into context in every session for routing: target 1024 characters and keep domain
vocabulary and anti-pattern lists in the body, not the description. See
[Agent Description Length](./agent-description-length.md). The description should clearly state what the agent does and
when to invoke it.

**Example:**

```yaml
description:
  "Research analyst for gathering, evaluating, and synthesizing information from multiple sources into evidence-based
  research briefs. Invoke when a task requires systematic information gathering, source credibility assessment, or
  triangulation of findings."
```

This description is well over 50 tokens, and that is fine. Its job is to help Claude decide when to use the agent, not
to set the model's persona. It is still bound by the description length budget, though: keep it near 1024 characters and
push domain vocabulary and anti-pattern detail into the body sections below. See
[Agent Description Length](./agent-description-length.md).

### 2. Write a Concise Role Identity (Under 50 Tokens)

The Role Identity is the opening "You are a..." paragraph in the agent body. This is the persona statement that routes
the model to expert-level knowledge. Keep it **under 50 tokens**. State the domain, the task, and the perspective,
nothing more.

Some agents use a formal `## Role Identity` heading for this section. Others place it as the opening paragraph of the
body. Both patterns work.

**Before (78 tokens):**

```markdown
You are an incredibly talented and experienced senior security engineer who has spent decades reviewing code for
vulnerabilities. You have deep expertise in OWASP, penetration testing, and secure coding practices. Your reviews are
thorough, precise, and always actionable.
```

**After (22 tokens):**

```markdown
You are a senior application security engineer. Your job is to identify exploitable vulnerabilities in code changes.
```

The "after" version uses precise domain vocabulary ("application security engineer," "exploitable vulnerabilities") that
routes to expert knowledge, without flattery or filler.

### 3. Include a Domain Vocabulary Section

Agent definitions should include an explicit section listing 15-30 domain-specific terms. These terms activate
expert-level embedding clusters and make the agent's domain scope explicit and auditable.

**Example for a security review agent:**

```markdown
## Domain Vocabulary

injection (SQL, XSS, command), authentication bypass, authorization escalation, CSRF, SSRF, insecure deserialization,
path traversal, secrets exposure, timing side-channel, input validation boundary, trust boundary crossing, defense in
depth, least privilege violation, cryptographic misuse, session fixation, open redirect, IDOR
```

**Example for a performance analysis agent:**

```markdown
## Domain Vocabulary

hot path, allocation pressure, cache miss ratio, flame graph, tail latency (p99/p999), throughput saturation, lock
contention, GC pause, memory leak, connection pool exhaustion, query plan regression, N+1 query, index scan vs.
sequential scan, event loop blocking, thread starvation, backpressure, circuit breaker
```

Apply the 15-year practitioner test to each term: would a senior expert use this exact term with peers?

### 4. List Named Anti-Patterns with Detection Signals

Each specialist agent should list 5-10 named anti-patterns relevant to its domain. Each anti-pattern needs a name and
detection signals: what to look for in the code or output.

**Example for a test engineering agent:**

```markdown
## Anti-Patterns

- **Test-the-mock**: Tests that verify mock behavior instead of real system behavior. Detection: assertions on mock call
  counts with no integration path.
- **Assertion-free test**: Test runs code but never asserts outcomes. Detection: test functions with no `expect`,
  `assert`, or equivalent.
- **Flaky time dependency**: Tests that depend on wall-clock time. Detection: `Date.now()`, `setTimeout`, or sleep-based
  synchronization in test code.
- **Shotgun coverage**: Many low-value tests on trivial paths, none on complex paths. Detection: high line coverage but
  untested error branches.
```

Anti-patterns make the agent's expertise concrete and auditable. They also prime the model to look for specific failure
modes rather than generic "issues."

### 5. Avoid Flattery and Motivational Framing

Flattery and superlatives (_"you are the world's best," "your expertise is unmatched"_) activate motivational and
inspirational content in the model's embeddings rather than technical expertise. They consume tokens without improving
(and often degrading) output quality.

**Avoid:**

- _"You are an expert..."_ / _"You are the best..."_
- _"Your analysis is always thorough and insightful"_
- _"You take pride in finding every issue"_

**Instead:** Let domain vocabulary and precise task framing do the routing work. A concise role statement with the right
terminology outperforms an elaborate motivational preamble.

### 6. One Role per Agent: Generate or Evaluate

Do not ask a single agent to both produce output and judge its quality. Self-evaluation bias means the same reasoning
patterns that created a blind spot will also evaluate it as correct.

**Instead:**

- Use one agent to generate (investigate, explore, draft)
- Use a separate agent to evaluate (validate, audit, challenge)

Pair a generator with a separate evaluator. For example, a generator agent that gathers evidence produces the findings,
and a separate evaluator agent that challenges those findings audits them. They are separate agents with separate
perspectives.

## Summary Checklist

1. Write a clear frontmatter `description` that states what the agent does and when to invoke it.
2. Keep the Role Identity under 50 tokens. State domain, task, and perspective only.
3. Include a domain vocabulary section with 15-30 precise terms that pass the 15-year practitioner test.
4. List 5-10 named anti-patterns with detection signals relevant to the agent's domain.
5. No flattery, superlatives, or motivational framing. Let vocabulary do the routing.
6. Assign a single role per agent. Generate or evaluate, not both.
7. Inline all vocabulary, anti-patterns, and protocols in the agent file (see
   [External File References](./agent-external-files.md)).

## Cross-References

- [Agent Description Length](./agent-description-length.md). The 1024-character budget for the always-loaded
  `description`, and which content has to move into the body to hit it.
- [External File References](./agent-external-files.md). All content must be inlined in the agent file. Vocabulary and
  anti-pattern sections are no exception.
- [Model Selection](./agent-model-selection.md). A well-specialized agent with precise vocabulary may perform well with
  a faster model, because domain terms activate expert knowledge even in smaller models.
- [Specialization and Model Selection](../specialization-and-model-selection.md). Evidence base for why specialization
  shifts work from inference-time compute to prompt-time design.
- Source: [The Specialized Review Principle](https://jdforsythe.github.io/10-principles/principles/specialized-review/).
  Research-backed principle on vocabulary routing, persona length, and self-evaluation bias.

---
paths:
  - "**/agents/**/*.md"
---

# External File References in Agent Definitions

## Contents

- The Rule
- Why: Structural Evidence
- Comparison: Skills vs. Agents
- Agent Frontmatter Fields
- The Pattern in Practice
- What to Do Instead
- Summary Checklist
- Cross-References

Agent definitions are self-contained markdown files. Unlike skills, agents do not support external file references. No
`references/` folders, no `scripts/` folders, and no context injection commands. All content must be inlined directly in
the agent `.md` file.

## The Rule

Agent `.md` files must be entirely self-contained. Do not create subdirectories, companion folders, or use
`` !`command` `` syntax in agent definitions.

## Why: Structural Evidence

Four independent pieces of evidence confirm this limitation:

### 1. Directory structure: flat vs. nested

Agents live as flat files in a shared directory:

```
agents/
  generator-agent.md
  evaluator-agent.md
```

Skills each get their own directory with room for sibling folders:

```
skills/
  {skill-name}/
    SKILL.md
    references/        # Optional: reference documents
    scripts/           # Optional: shell scripts
```

There is no per-agent subdirectory to house companion files.

### 2. Plugin structure in CLAUDE.md

The documented plugin structure shows `references/` and `scripts/` only under skills:

```
{plugin-name}/
  agents/
    {agent-name}.md          # Agent definition (frontmatter + prompt body)
  skills/
    {skill-name}/
      SKILL.md               # Skill definition (frontmatter + prompt body)
      references/            # Optional: reference documents injected into context
      scripts/               # Optional: shell scripts used by the skill
```

No equivalent optional folders appear under `agents/`.

### 3. Entity taxonomy

The [Entity Taxonomy](../plugin-entity-taxonomy.md) defines skills as the "Process Engine" that "can have companion
reference folders." The agent definition ("Thinking Layer") makes no mention of companion folders or external file
support.

### 4. Context injection docs

The [Context Injection Commands](../skill-building-guidance/context-injection-commands.md) documentation describes
`` !`command` `` syntax exclusively for SKILL.md files. Agent definitions are not mentioned as supporting this syntax.

## Comparison: Skills vs. Agents

| Capability                           | Skills                              | Agents                         |
| ------------------------------------ | ----------------------------------- | ------------------------------ |
| `references/` folder                 | Yes                                 | No                             |
| `scripts/` folder                    | Yes                                 | No                             |
| Context injection (`` !`command` ``) | Yes                                 | No                             |
| Frontmatter: `allowed-tools`         | Yes                                 | No (uses `tools`)              |
| Frontmatter: `argument-hint`         | Yes                                 | No                             |
| Frontmatter: `model`                 | No                                  | Yes                            |
| Directory structure                  | Own subdirectory (`skills/{name}/`) | Flat file (`agents/{name}.md`) |

## Agent Frontmatter Fields

Many agents set only `name`, `description`, `tools`, and `model`, but the
[Subagents documentation](https://code.claude.com/docs/en/sub-agents) supports more. Only `name` and `description` are
required. The others, briefly:

| Field             | What it does                                                                                 |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `tools`           | Allowlist of tools the agent may use. Inherits all tools if omitted.                         |
| `disallowedTools` | Denylist applied on top of `tools`. A tool in both is removed.                               |
| `model`           | Model alias, full model ID, or `inherit`. See [Model Selection](./agent-model-selection.md). |
| `permissionMode`  | Permission posture (`default`, `acceptEdits`, `plan`, and so on).                            |
| `maxTurns`        | Cap on agentic turns before the agent stops.                                                 |
| `skills`          | Skills to preload at startup (full content injected).                                        |
| `mcpServers`      | MCP servers available to the agent.                                                          |
| `hooks`           | Lifecycle hooks scoped to the agent.                                                         |
| `memory`          | `user`, `project`, or `local` to enable cross-session persistent memory.                     |
| `background`      | `true` to always run the agent as a background task.                                         |
| `effort`          | `low`/`medium`/`high`/`xhigh`/`max` effort override.                                         |
| `isolation`       | `worktree` to run the agent in a temporary git worktree.                                     |
| `color`           | Display color for the agent in the UI.                                                       |
| `initialPrompt`   | First user turn auto-submitted when the agent runs as a main session via `--agent`.          |

### Plugin agents ignore three of these (security boundary)

When an agent is loaded **from a plugin** (which is how every plugin agent ships), Claude Code ignores its `hooks`,
`mcpServers`, and `permissionMode` frontmatter. This is a documented security boundary, not a bug: a plugin cannot
silently grant itself hooks, MCP access, or a looser permission mode on the operator's machine. Do not rely on any of
these three fields in a plugin agent definition; they will be dropped. Source:
[Subagents documentation](https://code.claude.com/docs/en/sub-agents).

### Default to no `Agent` tool: prefer dispatch from skills to agents

Prefer dispatch to flow from skills to agents. By default, an agent does not carry the `Agent` tool, so it never
dispatches another agent directly; the skills do the dispatching and the agents apply judgment. This default keeps
dispatch boundaries clean, keeps every dispatch namespaced through a skill, and keeps the orchestrating context
economical, since a dispatched agent's deliberation stays out of the caller's window (see
[Agent Dispatch Namespacing](../skill-building-guidance/agent-dispatch-namespacing.md)).

Break the default only when the agent's own protocol dispatches sub-agents. When it does, the `Agent` tool earns its
place the way every tool does, by being used in the body, so the dispatching steps are themselves the justification and
there is nothing separate to record. The shape that earns it is a coordinator that dispatches a dedicated worker agent
for a self-contained sub-task, so the worker gets fresh context and its back-and-forth stays out of the coordinator's
window. For example, a review coordinator that dispatches a review agent which runs a code-review skill and fans out its
own specialist panel: the deviation is deliberate, the reviewers get clean context, and the panel's deliberation never
crowds the coordinator.

## The Pattern in Practice

Well-built agents are fully self-contained with all content inlined. For example:

- An investigation agent defines its investigation protocols entirely inline (search for direct evidence, trace code
  paths, check git history, examine test coverage, map dependencies). No external references.
- An exploration agent defines its exploration strategy, universal checklist, and feature-type-specific checklists
  entirely inline. No external references.

A well-built agent does not reference external files or scripts, and does not use context injection commands.

## What to Do Instead

When building agents that need substantial reference content:

1. **Inline the content.** Write protocols, strategies, and reference material directly in the agent `.md` file.
2. **Keep agents focused.** Agents should orchestrate and make judgment calls. If an agent needs complex procedural
   steps or reference data, that work likely belongs in a skill.
3. **Delegate to skills.** Agents can dispatch skills for operations that need `references/`, `scripts/`, or context
   injection. This follows the composition rule: _"agents orchestrate, skills execute."_

## Summary Checklist

1. Agent `.md` files are self-contained. No companion folders or subdirectories.
2. Do not use `` !`command` `` context injection syntax in agent definitions.
3. Do not create `references/` or `scripts/` folders under `agents/`.
4. Inline all protocols, strategies, and reference material directly in the agent file.
5. Delegate complex file-dependent operations to skills.

## Cross-References

- [Entity Taxonomy](../plugin-entity-taxonomy.md). Defines agents as the "Thinking Layer" with no mention of companion
  folders.
- [Context Injection Commands](../skill-building-guidance/context-injection-commands.md). Documents `` !`command` ``
  syntax for SKILL.md files only.

---
paths:
  - "**/agents/**/*.md"
---

# Choosing the Right Model for Agent Definitions

## Contents

- The `model` Field
- Model Characteristics
- Decision Criteria
- A Note on Cost
- Evidence from Agent Archetypes
- Summary Checklist
- Cross-References
- Sources

Agents support a `model` frontmatter field that skills do not. Choosing the right model is about matching capability and
speed to the task the agent performs. **Cost is not a factor in model selection.** Choose based on what the task
demands, not price.

## The `model` Field

The `model` field in agent frontmatter controls which AI model the agent uses.

**Valid values:**

| Value     | Behavior                                         |
| --------- | ------------------------------------------------ |
| `opus`    | Most capable model. Deep reasoning and judgment. |
| `sonnet`  | Balanced capability and speed.                   |
| `haiku`   | Fastest model. Low-latency, lightweight tasks.   |
| `inherit` | Uses the same model as the user's main session.  |

**Default behavior:** If `model` is omitted, the agent defaults to `inherit`. A full model ID (for example
`claude-opus-5`) is also accepted in place of an alias. Prefer the alias: it keeps tracking the current model in that
tier, where a pinned ID goes stale as new models ship.

**Syntax example:**

```yaml
---
name: my-agent
description: "Does a specific thing"
tools: Read, Glob, Grep
model: sonnet
---
```

**Resolution order.** When an agent runs, Claude Code resolves the model from the first source that is set:

1. The `CLAUDE_CODE_SUBAGENT_MODEL` environment variable.
2. The model chosen at dispatch time (Claude's own decision when it delegates).
3. The agent definition's `model` frontmatter (the value this doc is about).
4. The main conversation's model (the `inherit` default).

The frontmatter `model` is the level you control as an agent author, but an operator's env var or a dispatch-time choice
can override it.

**Scope: this rule governs agent definition files only, not skill dispatch.** "Always set model explicitly" applies to
the `model:` frontmatter of an agent definition (`**/agents/**/*.md`). It does NOT mean a skill should pass a `model`
override on its Agent tool calls. A skill that hard-codes a tier name at dispatch (`pass model: "sonnet"`) sends a
Claude-specific identifier across the host boundary, which fails on non-Claude hosts that have their own model
namespace, and it silently supersedes each dispatched agent's own frontmatter tier. Skills should pass no model
override; let each agent's frontmatter tier govern on Claude Code, and let the host default govern elsewhere.

## Model Characteristics

| Model    | Capability | Speed   | Best For                                                                           |
| -------- | ---------- | ------- | ---------------------------------------------------------------------------------- |
| `opus`   | Highest    | Slowest | Complex reasoning, nuanced judgment, multi-dimensional analysis, advanced coding   |
| `sonnet` | High       | Fast    | Code generation, data analysis, agentic tool use, structured workflows             |
| `haiku`  | Moderate   | Fastest | Real-time lookups, high-volume processing, simple pattern matching, quick searches |

## Decision Criteria

Walk through these questions in order to select the right model for an agent:

### 1. Does the agent need to match the user's session model?

Use `inherit` (or omit the field). This is rare. Only appropriate when the agent's task is generic enough that the
user's own model choice should carry through. Most agents have a specific cognitive profile that warrants an explicit
model.

### 2. Does the agent require complex reasoning, nuanced judgment, or multi-dimensional analysis?

Use `opus`. Signs that an agent needs opus:

- Synthesizing findings across many files and drawing non-obvious conclusions
- Auditing for subtle omissions or inconsistencies
- Exploring large codebases where judgment calls determine search direction
- Making qualitative assessments that require weighing competing factors

### 3. Does the agent perform focused, targeted work with clear procedures?

Use `sonnet`. Signs that an agent fits sonnet:

- Following defined protocols or checklists
- Gathering evidence along well-defined paths
- Validating against known criteria
- Executing structured investigation steps

### 4. Does the agent perform simple, fast lookups or high-volume processing?

Use `haiku`. Signs that an agent fits haiku:

- Quick file searches or pattern matching
- Straightforward Q&A about code
- Simple, repetitive operations at high volume
- Tasks where latency matters more than depth

### Summary Decision Table

| Task Characteristic                                      | Model     |
| -------------------------------------------------------- | --------- |
| Must match user's session model                          | `inherit` |
| Complex reasoning, nuanced judgment, synthesis           | `opus`    |
| Focused procedures, structured investigation, checklists | `sonnet`  |
| Fast lookups, simple patterns, high volume               | `haiku`   |

## A Note on Cost

Cost should not influence model selection. The goal is to pick the model that best fits the task's cognitive demands.
Optimizing for cost leads to under-powered agents that produce poor results. A false economy that wastes developer time
reviewing bad output and re-running tasks.

## Evidence from Agent Archetypes

### Mapping Archetypes to Tiers

These archetypes illustrate the decision criteria. Match the agent you are building to the closest archetype:

| Agent Archetype                                  | Model    | Rationale                                                                                          |
| ------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------- |
| Structure-and-config explorer                    | `haiku`  | Fast lookups across config and structure; speed over depth.                                        |
| Fact extractor / classifier against a fixed list | `haiku`  | Fact extraction and classification against a list. Pattern matching.                               |
| Open-ended edge-case explorer                    | `sonnet` | Open-ended exploration across several dimensions; qualitative judgment on likelihood and severity. |
| Test planner across many files                   | `sonnet` | Synthesizes findings across many files; weighs value vs brittleness tradeoffs for test planning.   |
| Protocol-following investigator                  | `sonnet` | Follows defined investigation protocols; gathers evidence along structured paths.                  |
| Rubric-based validator                           | `sonnet` | Validates against known criteria; executes structured challenge strategies.                        |
| Facilitator synthesizing many specialists        | `opus`   | Facilitation and synthesis across specialist input; high-judgment.                                 |
| Architect synthesizing cross-cutting findings    | `opus`   | Synthesizes structural/behavioral/concurrency findings into SOLID recommendations.                 |

The shape: fast lookup and classification agents fit haiku; structured-protocol agents working against fixed rubrics fit
sonnet; open-ended synthesis agents weighing competing factors over unbounded input fit opus.

### Claude Code Built-in Agents

| Agent             | Model     | Rationale                                                |
| ----------------- | --------- | -------------------------------------------------------- |
| Explore           | `haiku`   | Fast, read-only codebase searches. Speed over depth.     |
| Plan              | `inherit` | Research for planning matches user's session model.      |
| General-purpose   | `inherit` | Generic delegation. User's model choice carries through. |
| statusline-setup  | `sonnet`  | Focused configuration task with a clear procedure.       |
| claude-code-guide | `haiku`   | Fast Q&A lookups against Claude Code documentation.      |

These examples reinforce the decision criteria: opus for synthesis and judgment, sonnet for structured procedures, haiku
for fast lookups, inherit for generic tasks.

## Summary Checklist

1. Always set `model` explicitly. Do not rely on the `inherit` default unless `inherit` is the intentional choice.
2. Follow the decision criteria flow: inherit → opus → sonnet → haiku.
3. Never choose a model based on cost.
4. When unsure, prefer `sonnet` as the default. It balances capability and speed well.

## Cross-References

- [Domain Focus](./agent-domain-focus.md). A well-specialized agent with precise domain vocabulary may perform well with
  a faster model (sonnet or haiku), because domain-specific terms activate expert knowledge even in smaller models.
- [Specialization and Model Selection](../specialization-and-model-selection.md). Evidence and mechanism behind why
  tightly-specified agents can run on smaller models without loss of quality, and where that breaks down.

## Sources

- [Claude Code Sub-agents Documentation](https://code.claude.com/docs/en/sub-agents). Documents the `model` field, valid
  values, defaults, and built-in agent configurations.
- [Choosing the Right Model](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model). Model comparison
  covering capabilities, speed, and selection criteria.

---
paths:
  - "**/agents/**/*.md"
---

# Graceful Degradation

Agent definitions are self-contained and dispatched by skills. When a skill operates in degraded mode (for example, no
git), the agents it dispatches may include steps that depend on git history, branch context, or other tools that may be
absent. Without this guidance, agents that fail or produce errors when a tool is missing force the orchestrating skill
to add defensive guards around every agent dispatch. An agent that checks tool availability inline and skips gracefully
self-adapts to degraded environments.

## The Rules

### Rule: Conditionally skip steps that depend on unavailable tools

Without this rule, an agent always attempts tool-dependent steps, receives empty or error output, and either fails or
silently produces incomplete analysis. With no indication to the calling skill or user about what was omitted.

For any step that depends on a tool (git, a CLI, an external API), check availability inline before attempting the step.
If the tool is not available, skip the step and note the limitation explicitly in the agent's output.

**Pattern:**

> _"If {tool/data} is not available, skip this step and note this limitation."_

**Before (unconditional):**

```markdown
## Recency Analysis

Run `git log --since="30 days ago" --name-only` to identify recently modified files. Prioritize test coverage for files
changed in the last 30 days.
```

When git is absent, the agent receives an error. The analysis is silently incomplete and no explanation appears in
output.

**After (conditional skip):**

```markdown
## Recency Analysis

If git is not available, skip recency analysis and note this limitation.

Run `git log --since="30 days ago" --name-only` to identify recently modified files. Prioritize test coverage for files
changed in the last 30 days.
```

**Noting the limitation** means including a line in the agent's output such as:

> _"Note: git was not available. Recency analysis was skipped."_

This helps the calling skill and user understand why certain analysis was omitted without treating it as a failure.

---

## Summary Checklist

1. Check tool availability inline before tool-dependent steps. Do not assume tools are present.
2. Use the pattern _"If X is not available, skip this step and note this limitation."_
3. Include an explicit note in agent output when a step is skipped due to tool absence.

---

Cross-references:

- [Graceful Degradation (skills)](../skill-building-guidance/graceful-degradation.md). Skill-level multi-mode branching
  that determines what data is available when the agent is dispatched.

---
paths:
  - "**/agents/**/*.md"
---

# Multi-Agent Economics

## Contents

- Say what warrants delegation, because the model's default is eager
- The Escalation Cascade
- The 45% Threshold
- Scaling Reality
- Practical Implications for Skills
- Summary Checklist
- Sources

When a skill dispatches agents via the `Agent` tool, each agent adds latency and token cost. This doc provides the
decision framework for when adding agents is justified and when it's wasteful.

This doc is about **whether to add more agents**. For choosing which model tier (opus/sonnet/haiku) a given agent should
use, see [Model Selection](./agent-model-selection.md). That decision is about matching capability to task complexity,
and cost is not a factor there. Here, cost is a factor: multiplying agents multiplies token spend, and each additional
agent must clear a quality bar to justify that spend.

**What "multi-agent" means here.** A skill can dispatch sub-agents in parallel through the `Agent` tool, and each
agent's result is summarized back into the dispatching skill's context. This is _not_ the experimental Claude Code
[agent-teams](https://code.claude.com/docs/en/agent-teams) feature, in which each teammate is a separate Claude session
with its own context window and teammates talk to each other. Agent teams cost significantly more (token usage scales
linearly per teammate) and are gated behind `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`. The economics below apply to
parallel sub-agent dispatch; agent teams cost strictly more for the same head count.

## Say what warrants delegation, because the model's default is eager

Newer models reach for subagents readily. Anthropic's Opus 5 guidance is explicit that the model delegates more than
earlier ones, and that delegation pays off on genuinely independent, sizeable tracks of work while multiplying cost and
time on small ones. Left unstated, that eagerness pushes a skill up the cascade below without any of the measurement
the cascade asks for.

So a skill that dispatches agents should state its delegation policy rather than rely on the default. Three rules,
which hold regardless of the model:

- **Do not delegate work the skill can finish in a handful of tool calls.** The dispatch overhead exceeds the work.
- **Do not dispatch an agent to verify or double-check the dispatching skill's own work.** This is a self-check, and
  current models already perform it unprompted. It is distinct from Level 1 below, where a specialist reviewer
  evaluates the output from a genuinely different perspective. That pattern still earns its cost; a self-check does
  not.
- **Prefer one agent to several.** If a single agent can complete the track, dispatch one and keep spawn counts low.

Where the policy needs to be deterministic rather than advisory, cap the count in the skill body instead of describing
when delegation is appropriate.

## The Escalation Cascade

Start with the simplest architecture that could work. Advance only when measured quality justifies moving up.

### Level 0: Single Agent

A single well-prompted agent with access to the right tools handles roughly 70% of tasks. Before designing a multi-agent
system, verify that one agent with good instructions, domain vocabulary, and tool access cannot achieve acceptable
quality.

**When this is enough:** The task is coherent (one domain, one perspective), the output is straightforward to evaluate,
and the quality bar can be met by improving instructions rather than adding reviewers.

### Level 1: Worker + Specialist Reviewer

Add a second agent when a single agent cannot reliably self-validate. The worker generates output. The reviewer
evaluates it from a different perspective. This is motivated by [self-evaluation bias](./agent-domain-focus.md): agents
cannot reliably evaluate their own work because generator biases replicate in evaluation.

**When to escalate here:** The single agent's output consistently fails a specific quality dimension (security,
accessibility, domain accuracy) that requires specialist knowledge the worker agent doesn't activate.

### Level 2: Agent Team (3-5 Agents)

Add a team only when the review problem is genuinely multi-dimensional. The output needs evaluation from multiple
independent specialist perspectives that cannot be combined into one reviewer without diluting each domain's vocabulary
activation.

**When to escalate here:** The worker + reviewer pattern produces good results on one dimension but misses others, and
combining review domains into one agent degrades each (the generalist trap described in
[Domain Focus](./agent-domain-focus.md)).

**Hard cap (practical heuristic):** Cap teams at about 5 agents. Beyond this, coordination costs consistently exceed
production benefits. This is a practical operating limit, not a platform rule, but it sits in the same range as the
official agent-teams guidance, which recommends 3-5 teammates
([Agent Teams](https://code.claude.com/docs/en/agent-teams)).

## The 45% Threshold

Before adding another agent, ask: does the current architecture achieve more than 45% of optimal quality on the
dimension you're trying to improve? If yes, improve the existing agent's instructions, vocabulary, or tool access first.
Adding an agent is justified only when a single agent has been optimized and still falls short.

This threshold tracks a finding from _Towards a Science of Scaling Agent Systems_ (Google Research, Google DeepMind, and
MIT, 2025): when a single agent already solves a task at roughly 45% accuracy, adding agents yields diminishing or
negative returns. See [Sources](#sources).

Multi-agent teams only outperform single agents when:

- Tasks decompose into **independent subtasks** with clear interfaces.
- Each subtask activates a **distinct domain** that benefits from separate vocabulary routing.
- The coordination overhead is **less than** the quality improvement.

Sequential reasoning tasks (where each step depends on the previous step's full context) can degrade sharply in
multi-agent setups because handoffs lose context. The same 2025 study reports 39-70% performance degradation for
multi-agent variants on strict sequential-reasoning tasks: each handoff is a lossy compression of state, transferring
explicit message content but losing the tacit understanding built up during reasoning. See [Sources](#sources).

## Scaling Reality

Multi-agent scaling shows diminishing returns. The 2025 study ran 180 controlled experiments across five architectures
and three model families (GPT, Gemini, Claude) and found performance swinging from an 81% boost to a 70% drop depending
on the task: parallelizable work benefits from more agents, sequential work degrades. The consistent shape is that the
efficiency ratio (quality gained per token spent) falls as agents are added.

The table below is an **illustrative model of that shape**, not data lifted from the study. Use it to reason about the
trade-off, not as measured constants:

| Team Size | Token Cost | Output Quality          | Efficiency |
| --------- | ---------- | ----------------------- | ---------- |
| 1 agent   | 1x         | 1x (baseline)           | 1.0        |
| 3 agents  | ~4x        | ~2x                     | 0.5        |
| 5 agents  | ~7x        | ~3.1x                   | 0.44       |
| 7+ agents | ~12x+      | Often less than 4-agent | < 0.3      |

Each additional agent must produce a measurable quality improvement to justify its cost. The efficiency ratio drops with
every agent added. Team effectiveness plateaus around 4 agents. Beyond this, coordination costs actively harm output.

## Practical Implications for Skills

When designing a skill that dispatches agents:

1. **Start at Level 0.** Build and test with a single agent first. Measure quality.
2. **Add a reviewer only for a measured gap.** If the single agent misses security issues 60% of the time, add a
   security reviewer. Don't add reviewers speculatively.
3. **Use parallel dispatch for independent perspectives.** When multiple agents evaluate the same artifact from
   different angles, dispatch them in parallel (multiple `Agent` tool calls in one message) to avoid sequential latency.
4. **Avoid sequential chains longer than 3 agents.** Each handoff loses context. If you need more than 3 sequential
   steps, consider whether intermediate results can be written to files (artifact-based handoffs) rather than passed
   through agent context.
5. **Match team composition to the task.** Not every invocation needs every agent. If a skill dispatches a security
   reviewer, accessibility reviewer, and performance reviewer, but the current change only affects API endpoints, skip
   the accessibility reviewer for that run.

## Summary Checklist

1. Start with one well-prompted agent. It handles most tasks.
2. State the delegation policy in the skill body. The model's default eagerness is not the policy you want.
3. Never dispatch an agent to verify the dispatching skill's own work.
4. Add a reviewer only when a single agent consistently fails a specific quality dimension.
5. Escalate to a team only when review is genuinely multi-dimensional.
6. Cap teams at 5 agents. Beyond this, coordination costs exceed benefits.
7. Apply the 45% threshold: optimize existing agents before adding new ones.
8. Dispatch independent agents in parallel. Avoid long sequential chains.

## Sources

- [Towards a Science of Scaling Agent Systems (Google Research / Google DeepMind / MIT, 2025)](https://research.google/blog/towards-a-science-of-scaling-agent-systems-when-and-why-agent-systems-work/).
  Source for the ~45% capability-saturation threshold, the 39-70% sequential-reasoning degradation range, and the
  diminishing-returns direction (180 experiments, five architectures, three model families).
- [Building effective agents (Anthropic)](https://www.anthropic.com/engineering/building-effective-agents). "Agentic
  systems often trade latency and cost for better task performance"; start simple and add agent complexity only when
  measurement justifies it.
- [Agent Teams (Claude Code docs)](https://code.claude.com/docs/en/agent-teams). The experimental multi-session feature
  distinct from parallel `Agent`-tool dispatch; token cost scales linearly per teammate; recommends 3-5 teammates.
- [Prompting Claude Opus 5 (Anthropic)](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5).
  Source for readier default delegation, the rule against delegating self-verification, and the advice to prefer one
  agent over several and keep spawn counts low.

Cross-references:

- [Model Selection](./agent-model-selection.md). Choosing which model tier for a given agent (separate from whether to
  add agents).
- [Domain Focus](./agent-domain-focus.md). Vocabulary routing, self-evaluation bias, and the generalist trap.
- [Skill Decomposition](../skill-building-guidance/skill-decomposition.md). When to split skills vs. when to add agents
  within a skill.
- [Per-Model Authoring Guidance](../per-model-authoring.md). The wider set of author-time adjustments the current models
  call for, including the verification instructions to leave out.

# marketplace.json Schema Reference

## Contents

- Root Object
- Plugin Entry Object
- Source Variants
- Strict Mode
- Version Resolution
- Reserved Marketplace Names
- Official Reference
- JSON example

The `.claude-plugin/marketplace.json` file is the registry that Claude Code reads to discover and install plugins from a
marketplace.

## Root Object

| Field                                 | Required | Type   | Description                                                             |
| ------------------------------------- | -------- | ------ | ----------------------------------------------------------------------- |
| `name`                                | Yes      | string | Marketplace identifier in kebab-case                                    |
| `owner`                               | Yes      | object | Maintainer info — `name` (required) and `email` (optional)              |
| `plugins`                             | Yes      | array  | Array of plugin entry objects (see below)                               |
| `description`                         | No       | string | Human-readable marketplace description                                  |
| `version`                             | No       | string | Marketplace manifest version                                            |
| `metadata`                            | No       | object | Additional metadata — `pluginRoot`, `description`, `version` sub-fields |
| `allowCrossMarketplaceDependenciesOn` | No       | array  | Other marketplace names this one may declare dependencies on            |

### metadata sub-fields

| Field         | Description                                              |
| ------------- | -------------------------------------------------------- |
| `pluginRoot`  | Base directory prepended to relative plugin source paths |
| `description` | Alternate location for marketplace description           |
| `version`     | Alternate location for marketplace version               |

## Plugin Entry Object

Each item in the `plugins` array:

| Field            | Required | Type             | Description                                                                                                                                          |
| ---------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | Yes      | string           | Plugin identifier in kebab-case. Never use a `.`; see [Plugin Naming](./plugin-naming.md).                                                           |
| `source`         | Yes      | string \| object | Where to fetch the plugin (see Source Variants below)                                                                                                |
| `displayName`    | No       | string           | Human-readable name shown in the UI; falls back to `name`. Not used for namespacing. Requires Claude Code v2.1.143+.                                 |
| `description`    | No       | string           | Plugin description                                                                                                                                   |
| `version`        | No       | string           | Plugin version (overridden by `plugin.json` if both specify)                                                                                         |
| `defaultEnabled` | No       | boolean          | Whether the plugin is enabled after install (default `true`). Takes precedence over the same field in `plugin.json`. Requires Claude Code v2.1.154+. |
| `author`         | No       | object           | `name` (required if present) and `email` (optional)                                                                                                  |
| `homepage`       | No       | string           | Plugin documentation URL                                                                                                                             |
| `repository`     | No       | string           | Source code URL                                                                                                                                      |
| `license`        | No       | string           | SPDX license identifier                                                                                                                              |
| `keywords`       | No       | array            | Discovery tags (strings)                                                                                                                             |
| `category`       | No       | string           | Plugin category                                                                                                                                      |
| `tags`           | No       | array            | Additional searchability tags (strings)                                                                                                              |
| `strict`         | No       | boolean          | Default `true`. Controls `plugin.json` authority (see Strict Mode below)                                                                             |
| `skills`         | No       | string \| array  | Custom paths to skill directories                                                                                                                    |
| `commands`       | No       | string \| array  | Custom paths to flat skill files                                                                                                                     |
| `agents`         | No       | string \| array  | Custom paths to agent files                                                                                                                          |
| `hooks`          | No       | string \| object | Hooks config path or inline object                                                                                                                   |
| `mcpServers`     | No       | string \| object | MCP server config path or inline object                                                                                                              |
| `lspServers`     | No       | string \| object | LSP server config path or inline object                                                                                                              |

## Source Variants

### 1. Relative Path (string)

```json
{ "source": "./plugins/my-plugin" }
```

- Must start with `./`
- Resolved relative to marketplace root
- Only works with git-based marketplaces, not URL distributions
- Do not use `../` outside the marketplace root

### 2. GitHub Repository

```json
{
  "source": {
    "source": "github",
    "repo": "owner/repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
  }
}
```

| Sub-field | Required | Description                                       |
| --------- | -------- | ------------------------------------------------- |
| `repo`    | Yes      | GitHub repo in `owner/repo` format                |
| `ref`     | No       | Branch or tag (defaults to repo default branch)   |
| `sha`     | No       | Full 40-character commit SHA to pin exact version |

### 3. URL / Non-GitHub Git

```json
{
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
  }
}
```

| Sub-field | Required | Description                                                 |
| --------- | -------- | ----------------------------------------------------------- |
| `url`     | Yes      | Full git URL (`https://` or `git@`); `.git` suffix optional |
| `ref`     | No       | Branch or tag (defaults to default branch)                  |
| `sha`     | No       | Full 40-character commit SHA                                |

### 4. Git Subdirectory (Monorepo)

```json
{
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
  }
}
```

| Sub-field | Required | Description                                        |
| --------- | -------- | -------------------------------------------------- |
| `url`     | Yes      | Git URL, `owner/repo` GitHub shorthand, or SSH URL |
| `path`    | Yes      | Subdirectory path within the repo                  |
| `ref`     | No       | Branch or tag                                      |
| `sha`     | No       | Full 40-character commit SHA                       |

Uses sparse/partial clone to minimize bandwidth.

### 5. npm Package

```json
{
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}
```

| Sub-field  | Required | Description                                                |
| ---------- | -------- | ---------------------------------------------------------- |
| `package`  | Yes      | Package name or scoped package (e.g. `@acme/plugin`)       |
| `version`  | No       | Version or semver range (e.g. `2.1.0`, `^2.0.0`, `~1.5.0`) |
| `registry` | No       | Custom npm registry URL (defaults to npmjs.org)            |

## Strict Mode

The `strict` field on a plugin entry controls the relationship between `plugin.json` and the marketplace entry:

| Value            | Behavior                                                                                                                                     |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `true` (default) | `plugin.json` is the authority. Marketplace entry may supplement with additional components. Both are merged.                                |
| `false`          | Marketplace entry is the entire definition. Plugin's own `plugin.json` component declarations cause a conflict and the plugin fails to load. |

## Version Resolution

Versions resolve in this order:

1. `version` in the plugin's own `plugin.json`
2. `version` in the marketplace plugin entry
3. Git commit SHA of the plugin's source (for git-based sources)

If both `plugin.json` and the marketplace entry specify a version, `plugin.json` silently wins. Omit version entirely to
auto-update on every commit via the commit SHA.

## Reserved Marketplace Names

These names are reserved for official Anthropic use and cannot be used by third-party marketplaces:

- `claude-code-marketplace`
- `claude-code-plugins`
- `claude-plugins-official`
- `anthropic-marketplace`
- `anthropic-plugins`
- `agent-skills`
- `anthropic-agent-skills`
- `knowledge-work-plugins`
- `life-sciences`
- `claude-for-legal`
- `claude-for-financial-services`
- `financial-services-plugins`

Names that impersonate official marketplaces (e.g. `official-claude-plugins` or `anthropic-tools-v2`) are also blocked.

## Official Reference

https://code.claude.com/docs/en/plugin-marketplaces.md

## JSON example

available at ../templates/marketplace-example.json

# monitors.json Schema Reference

The monitors configuration file defines persistent background processes that deliver notifications to Claude during a
session. It is a JSON **array** of monitor entry objects.

> **Experimental.** Monitors are an experimental plugin component. In `plugin.json` the preferred placement is under the
> `experimental` key (`"experimental": { "monitors": "..." }`). The bare top-level `monitors` key still works but
> `claude plugin validate` warns against it, and `--strict` treats that warning as an error. The schema may change.

## File Location

- Default: `monitors/monitors.json` in the plugin root
- Custom path: set the `monitors` field in `plugin.json` (e.g. `"monitors": "./config/monitors.json"`); the preferred
  form is `"experimental": { "monitors": "./config/monitors.json" }`
- Inline: declare the array directly in `plugin.json` under the `experimental.monitors` key

Requires Claude Code v2.1.105 or later.

## Monitor Entry Object

| Field         | Required | Type   | Description                                                                                                |
| ------------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `name`        | Yes      | string | Unique identifier within the plugin. Prevents duplicate processes on plugin reload or skill re-invocation. |
| `command`     | Yes      | string | Shell command run as a persistent background process in the session working directory.                     |
| `description` | Yes      | string | Short summary of what is being watched. Shown in the task panel and in notification summaries.             |
| `when`        | No       | string | Controls when the monitor starts (see When Values below). Defaults to `"always"`.                          |

## `when` Values

| Value                            | Description                                                        |
| -------------------------------- | ------------------------------------------------------------------ |
| `"always"`                       | (default) Starts at session start and on plugin reload             |
| `"on-skill-invoke:<skill-name>"` | Starts the first time the named skill in this plugin is dispatched |

## Variable Substitution in `command`

The `command` field supports these substitution variables:

| Variable                | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `${CLAUDE_PLUGIN_ROOT}` | Absolute path to the plugin install directory                 |
| `${CLAUDE_PLUGIN_DATA}` | Persistent data directory at `~/.claude/plugins/data/{id}/`   |
| `${user_config.KEY}`    | User config values defined in the plugin's `userConfig` field |
| `${ENV_VAR}`            | Any environment variable                                      |

To run the command from the plugin's own directory, prefix with `cd "${CLAUDE_PLUGIN_ROOT}" && `.

## Behavior

- Each stdout line from the monitor is delivered to Claude as a notification
- Claude can react to log entries, status changes, or polled events automatically
- Monitors run only in interactive CLI sessions — skipped where the Monitor tool is unavailable
- Monitors run unsandboxed at the same trust level as hooks
- Disabling a plugin mid-session does not stop already-running monitors; they stop when the session ends

## Official Reference

https://code.claude.com/docs/en/plugins-reference.md#monitors

## JSON example

available at ../templates/monitors-example.json

# plugin.json Schema Reference

## Contents

- Required Fields
- Metadata Fields (Optional)
- Component Path Fields (Optional)
- userConfig
- channels
- dependencies
- Environment Variables
- Complete Example
- Official Reference
- JSON example

The `.claude-plugin/plugin.json` manifest file defines a Claude Code plugin's metadata and component paths.

## Required Fields

| Field  | Type   | Description                                                                                           |
| ------ | ------ | ----------------------------------------------------------------------------------------------------- |
| `name` | string | Unique identifier in kebab-case, no spaces. Never use a `.`; see [Plugin Naming](./plugin-naming.md). |

## Metadata Fields (Optional)

| Field            | Type    | Description                                                                                                  | Example                                                           |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| `$schema`        | string  | JSON Schema URL for editor validation (ignored by Claude Code at load time)                                  | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
| `version`        | string  | Semver version. If omitted, falls back to git commit SHA.                                                    | `"2.1.0"`                                                         |
| `displayName`    | string  | Human-readable name shown in the UI. Not used for namespacing. Requires Claude Code v2.1.143+.               | `"Deployment Tools"`                                              |
| `description`    | string  | Brief explanation of plugin purpose                                                                          | `"Deployment automation tools"`                                   |
| `defaultEnabled` | boolean | Whether the plugin is enabled by default when installed. Defaults to `true`. Requires Claude Code v2.1.154+. | `false`                                                           |
| `author`         | object  | Author info with optional `name`, `email`, `url` sub-fields                                                  | `{"name": "Dev Team", "email": "dev@company.com"}`                |
| `homepage`       | string  | Documentation URL                                                                                            | `"https://docs.example.com"`                                      |
| `repository`     | string  | Source code URL                                                                                              | `"https://github.com/user/plugin"`                                |
| `license`        | string  | License identifier                                                                                           | `"MIT"`, `"Apache-2.0"`                                           |
| `keywords`       | array   | Discovery tags (strings)                                                                                     | `["deployment", "ci-cd"]`                                         |

## Component Path Fields (Optional)

All paths must be relative to the plugin root and start with `./`. Specifying a custom path **replaces** the default. To
keep the default and add more, use an array (e.g. `["./skills/", "./extras/"]`).

| Field          | Type                      | Default scanned path     | Description                                               |
| -------------- | ------------------------- | ------------------------ | --------------------------------------------------------- |
| `skills`       | string \| array           | `skills/`                | Directories containing `<name>/SKILL.md` files            |
| `commands`     | string \| array           | `commands/`              | Flat `.md` skill files or directories                     |
| `agents`       | string \| array           | `agents/`                | Agent definition `.md` files                              |
| `hooks`        | string \| array \| object | —                        | Hook config paths or inline hook object                   |
| `mcpServers`   | string \| array \| object | —                        | MCP config paths or inline MCP object                     |
| `lspServers`   | string \| array \| object | `.lsp.json`              | Language Server Protocol configs                          |
| `monitors`     | string \| array           | `monitors/monitors.json` | Background monitor configurations                         |
| `outputStyles` | string \| array           | `output-styles/`         | Custom output style files/directories                     |
| `themes`       | string \| array           | `themes/`                | Color theme files (JSON with `name`, `base`, `overrides`) |

For `hooks`, `mcpServers`, and `lspServers`, multiple sources are **merged** rather than replaced.

**`monitors` and `themes` are experimental.** The current preferred placement for both is under an `experimental` key,
not at the top level:

```json
"experimental": {
  "monitors": "./monitors/monitors.json",
  "themes": "./themes/"
}
```

The bare top-level `monitors` and `themes` keys still load, but `claude plugin validate` warns against them, and
`claude plugin validate --strict` (used in CI) treats that warning as an error. Prefer the `experimental.*` form for new
plugins. See [monitors](./monitors-json-options.md) and [themes](./themes-json-options.md).

## userConfig

User-configurable values prompted at enable time. Each key is a config option:

| Sub-field     | Required | Type    | Description                                                          |
| ------------- | -------- | ------- | -------------------------------------------------------------------- |
| `type`        | Yes      | string  | One of: `"string"`, `"number"`, `"boolean"`, `"directory"`, `"file"` |
| `title`       | Yes      | string  | Label shown in config dialog                                         |
| `description` | Yes      | string  | Help text shown beneath field                                        |
| `sensitive`   | No       | boolean | Masks input and stores in secure storage instead of `settings.json`  |
| `required`    | No       | boolean | Validation fails when field is empty                                 |
| `default`     | No       | any     | Value used when user provides nothing                                |
| `multiple`    | No       | boolean | `string` type only — allow array of strings                          |
| `min` / `max` | No       | number  | `number` type only — value bounds                                    |

Values are available as `${user_config.KEY}` in MCP/LSP/hook/monitor configs and as `CLAUDE_PLUGIN_OPTION_<KEY>`
environment variables in subprocesses. Non-sensitive values are also available in skill/agent content.

## channels

Array of message injection channel declarations (Telegram, Slack, Discord).

| Sub-field    | Required | Type   | Description                                                     |
| ------------ | -------- | ------ | --------------------------------------------------------------- |
| `server`     | Yes      | string | Must match a key in the plugin's `mcpServers`                   |
| `userConfig` | No       | object | Per-channel user config (same schema as top-level `userConfig`) |

## dependencies

Other plugins this plugin requires. Each entry is either a plain plugin name or an object:

```json
"dependencies": [
  "helper-lib",
  { "name": "secrets-vault", "version": "~2.1.0" },
  { "name": "shared-lib", "marketplace": "other-marketplace" }
]
```

| Sub-field     | Required | Type   | Description                                                                                    |
| ------------- | -------- | ------ | ---------------------------------------------------------------------------------------------- |
| `name`        | Yes      | string | The dependency's plugin name. Resolved in the same marketplace as this plugin by default.      |
| `version`     | No       | string | Semver range (e.g. `~2.1.0`). When omitted, floats to whatever version the marketplace serves. |
| `marketplace` | No       | string | A different marketplace to resolve from. Blocked unless the installing marketplace allows it.  |

Behavior, in brief: installing a plugin auto-installs its dependencies and reports what it added; enabling a plugin
enables its dependencies at the same scope, and a plugin cannot be disabled while another enabled plugin still depends
on it. A dependency in another marketplace is refused unless that marketplace appears in the installing marketplace's
`allowCrossMarketplaceDependenciesOn` list (see [marketplace.json reference](./marketplace-json-options.md)), and a
dependency from a marketplace the user has not added stays unresolved. The full resolution, versioning, and
error-handling rules are in the
[canonical Claude Code documentation](https://code.claude.com/docs/en/plugin-dependencies).

See also: the
[canonical Claude Code plugin-dependencies documentation](https://code.claude.com/docs/en/plugin-dependencies) for a
full worked walkthrough of declaring and resolving dependencies, and the
[marketplace.json reference](./marketplace-json-options.md) for the cross-marketplace allow-list that governs
dependencies declared against another marketplace.

## Environment Variables

Available for substitution in skill/agent content, hook commands, monitor commands, and MCP/LSP server configs:

| Variable                | Description                                                               |
| ----------------------- | ------------------------------------------------------------------------- |
| `${CLAUDE_PLUGIN_ROOT}` | Absolute path to plugin install directory. Changes on plugin update.      |
| `${CLAUDE_PLUGIN_DATA}` | Persistent state dir at `~/.claude/plugins/data/{id}/`. Survives updates. |
| `${CLAUDE_PROJECT_DIR}` | Absolute path to the project root of the current session.                 |

Both are also exported as environment variables to hook processes and MCP/LSP server subprocesses.

## Complete Example

```json
{
  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
  "name": "deployment-tools",
  "version": "1.2.0",
  "description": "Deployment automation and monitoring tools",
  "author": {
    "name": "Dev Team",
    "email": "dev@company.com",
    "url": "https://github.com/company"
  },
  "homepage": "https://docs.example.com/deployment",
  "repository": "https://github.com/company/deployment-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci-cd", "monitoring"],
  "skills": "./custom/skills/",
  "agents": "./agents/",
  "hooks": "./hooks/hooks.json",
  "mcpServers": {
    "deployment": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/deploy-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "lspServers": "./.lsp.json",
  "monitors": "./monitors.json",
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API Endpoint",
      "description": "Your deployment API endpoint",
      "required": true
    },
    "api_token": {
      "type": "string",
      "title": "API Token",
      "description": "Authentication token",
      "sensitive": true
    },
    "timeout": {
      "type": "number",
      "title": "Timeout (seconds)",
      "description": "Request timeout",
      "min": 1,
      "max": 3600,
      "default": 30
    }
  },
  "dependencies": ["helper-lib", { "name": "secrets-vault", "version": "~2.1.0" }]
}
```

## Official Reference

https://code.claude.com/docs/en/plugins-reference.md#plugin-manifest-schema

## JSON example

available at ../templates/plugin-example.json

# Plugin Naming

A plugin's `name` is an identifier, not prose. It appears in the `plugin.json` manifest, in every marketplace entry, in
the install command (`/plugin install <name>@<marketplace>`), and as the namespace prefix on every skill and agent the
plugin ships (`<name>:skill`, `subagent_type: "<name>:agent"`). Pick a name that survives all of those uses unchanged.

## Rule: Never put a `.` in a plugin name

Plugin names must be kebab-case: lowercase letters, numbers, and hyphens only. Do not use a dot (`.`) as a separator,
even though it reads naturally as a namespace (`acme.core`, `acme.github`).

A dot in a plugin name breaks tooling:

- **Codex is incompatible with it.** The Codex marketplace format does not accept a dot in a plugin name, so a dotted
  plugin cannot be packaged for or installed through Codex at all.
- **Claude Code is partially incompatible with it.** A dotted name loads in some paths and fails in others. Because the
  plugin name is also the namespace prefix for the plugin's skills and agents, a dot collides with the `name:component`
  separator and with slash-command and dispatch resolution, so behavior is inconsistent across surfaces.

Use a hyphen wherever you would reach for a dot. The hyphen carries the same "this belongs to the `acme` family" reading
without the incompatibility.

**Before (dotted, which breaks Codex and partially breaks Claude Code):**

```
acme.core/
  .claude-plugin/
    plugin.json    # { "name": "acme.core", ... }
```

```json
// dependent plugin.json
"dependencies": ["acme.core"]
```

```
// dispatch and invocation
subagent_type: "acme.core:my-agent"
/acme.core:my-skill
```

**After (hyphenated, which works everywhere):**

```
acme-core/
  .claude-plugin/
    plugin.json    # { "name": "acme-core", ... }
```

```json
// dependent plugin.json
"dependencies": ["acme-core"]
```

```
// dispatch and invocation
subagent_type: "acme-core:my-agent"
/acme-core:my-skill
```

## When renaming an existing plugin off a dotted name

The name is referenced in more places than the manifest. Change all of them together so nothing dangles:

1. The plugin directory name (it must match the `name` field; see
   [Naming Conventions](../skill-building-guidance/naming-conventions.md)).
2. The `name` and `source` in every marketplace entry (`.claude-plugin/marketplace.json`, and any Codex marketplace).
3. The `name` in the plugin's own `plugin.json` (both `.claude-plugin/` and `.codex-plugin/` if present).
4. Every `dependencies` entry in other plugins that depend on it, including the meta-plugin's `dependencies` array.
5. Every namespace prefix in prose and config: `name:skill` invocations, `subagent_type: "name:agent"` dispatches, and
   any `name-*` wildcard references to the plugin family.
6. Doc folders, indexes, and cross-references that mirror the plugin name.

## Summary

1. Plugin names are kebab-case identifiers: lowercase letters, numbers, hyphens. No dots, no spaces, no other
   punctuation.
2. A dot breaks Codex entirely and Claude Code partially, because the name doubles as the skill and agent namespace
   prefix.
3. Renaming off a dotted name is a coordinated change across the directory, every manifest, every dependency array, and
   every namespace reference.

# Theme File Schema Reference

## Contents

- Fields
- `base` Valid Values
- Color Value Formats
- Color Tokens
- Behavior
- Official Reference
- JSON example

Plugin theme files are JSON files placed in the `themes/` directory (or a custom path set via the `themes` field in
`plugin.json`). The filename without `.json` becomes the theme's slug.

> **Experimental.** Themes are an experimental plugin component. In `plugin.json` the preferred placement is under the
> `experimental` key (`"experimental": { "themes": "./themes/" }`). The bare top-level `themes` key still works but
> `claude plugin validate` warns against it, and `--strict` treats that warning as an error. The manifest schema may
> change.

## Fields

All three fields are optional.

| Field       | Required | Type   | Default       | Description                                 |
| ----------- | -------- | ------ | ------------- | ------------------------------------------- |
| `name`      | No       | string | Filename slug | Display label shown in the `/theme` command |
| `base`      | No       | string | `"dark"`      | Built-in preset to inherit from             |
| `overrides` | No       | object | `{}`          | Color token → value mappings                |

## `base` Valid Values

| Value                | Description                                  |
| -------------------- | -------------------------------------------- |
| `"dark"`             | Default dark theme                           |
| `"light"`            | Default light theme                          |
| `"dark-daltonized"`  | Dark theme with colorblind-friendly palette  |
| `"light-daltonized"` | Light theme with colorblind-friendly palette |
| `"dark-ansi"`        | Dark theme using terminal ANSI colors        |
| `"light-ansi"`       | Light theme using terminal ANSI colors       |

## Color Value Formats

Any `overrides` token accepts these formats:

| Format       | Example                      |
| ------------ | ---------------------------- |
| Hex 6-digit  | `"#bd93f9"`                  |
| Hex 3-digit  | `"#f0f"`                     |
| RGB function | `"rgb(189, 147, 249)"`       |
| ANSI 256     | `"ansi256(141)"` (n = 0–255) |
| ANSI 16 name | `"ansi:magentaBright"`       |

ANSI 16 names: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, and their `Bright` variants
(`blackBright`, `redBright`, etc.).

## Color Tokens

### Text and Accent

| Token         | Controls                                           |
| ------------- | -------------------------------------------------- |
| `claude`      | Primary brand accent, spinner, and assistant label |
| `text`        | Default foreground text                            |
| `inverseText` | Text on colored backgrounds (e.g. status badges)   |
| `inactive`    | Secondary text — hints, timestamps, disabled items |
| `subtle`      | Faint borders and de-emphasized text               |
| `permission`  | Dialog borders and permission prompts              |
| `remember`    | Memory and `CLAUDE.md` indicators                  |

### Status

| Token     | Controls                            |
| --------- | ----------------------------------- |
| `success` | Success messages and passing checks |
| `error`   | Error messages and failures         |
| `warning` | Warnings and caution messages       |
| `merged`  | Merged pull request status          |

### Input Box and Mode Indicators

| Token          | Controls                                |
| -------------- | --------------------------------------- |
| `promptBorder` | Input box border in default mode        |
| `planMode`     | Plan mode accent and border             |
| `autoAccept`   | Accept-edits mode accent and border     |
| `bashBorder`   | Input box border for `!` shell commands |
| `ide`          | IDE connection indicator                |
| `fastMode`     | Fast mode indicator                     |

### Diff Rendering

| Token               | Controls                              |
| ------------------- | ------------------------------------- |
| `diffAdded`         | Background of added lines             |
| `diffRemoved`       | Background of removed lines           |
| `diffAddedDimmed`   | Context background near added lines   |
| `diffRemovedDimmed` | Context background near removed lines |
| `diffAddedWord`     | Word-level highlight in added lines   |
| `diffRemovedWord`   | Word-level highlight in removed lines |

### Fullscreen Mode

| Token                   | Controls                          |
| ----------------------- | --------------------------------- |
| `userMessageBackground` | Background behind user messages   |
| `selectionBg`           | Background of mouse-selected text |

### Shimmer Variants

Animated gradient counterparts for select tokens:

`claudeShimmer`, `successShimmer`, `errorShimmer`, `warningShimmer`, `mergedShimmer`, `planModeShimmer`,
`autoAcceptShimmer`, `bashBorderShimmer`, `ideShimmer`, `fastModeShimmer`

### Subagent Colors

Eight colors for distinguishing subagents visually. Suffix `_FOR_SUBAGENTS_ONLY` is required:

`red_FOR_SUBAGENTS_ONLY`, `blue_FOR_SUBAGENTS_ONLY`, `green_FOR_SUBAGENTS_ONLY`, `yellow_FOR_SUBAGENTS_ONLY`,
`purple_FOR_SUBAGENTS_ONLY`, `orange_FOR_SUBAGENTS_ONLY`, `pink_FOR_SUBAGENTS_ONLY`, `cyan_FOR_SUBAGENTS_ONLY`

## Behavior

- Unknown tokens and invalid color values are silently ignored
- Tokens absent from `overrides` inherit from the `base` preset
- Claude Code auto-reloads themes from `~/.claude/themes/` when files change
- Selecting a plugin theme stores `custom:<plugin-name>:<slug>` in user config
- Pressing Ctrl+E on a plugin theme copies it to `~/.claude/themes/` for local editing

## Official Reference

https://code.claude.com/docs/en/terminal-config.md https://code.claude.com/docs/en/plugins-reference.md

## JSON example

available at ../templates/themes-example.json

---
paths:
  - "**/skills/**/*.md"
  - "**/agents/**/*.md"
---

# Agent Dispatch Namespacing

When a skill dispatches a sub-agent, it must name the agent by the namespace of the plugin that **defines** the agent.
If a plugin named `example-plugin` defines the agent, every dispatch uses `example-plugin:agent-name`. A bare name and a
meta-plugin prefix that has no agents are both wrong.

## The Rules

### Rule: Dispatch agents by `your-plugin:agent-name`

In every `Agent` tool call, set `subagent_type` to the fully-qualified name:

```
subagent_type: "example-plugin:structural-analyst"
```

The same applies to dispatch-instruction prose inside a skill. Write "Launch `example-plugin:adversarial-validator`",
not "Launch `adversarial-validator`". The model reads the skill top to bottom and carries whatever name it finds to the
dispatch, so the roster tables, the per-agent prompt lists, and the prose all use the qualified name. Mixing qualified
and bare names in one skill is the inconsistency that produces a dispatch bug.

### Rule: Never use a meta-plugin prefix for an agent

A meta-plugin is a plugin with no components of its own. Picture a plugin named `example` that has no agents, skills, or
commands; it only declares `example.core` and `example.github` as dependencies so installing it pulls them in. A
dependency is installed as its own plugin and keeps its own namespace. Depending on `example.core` does not re-export
`example.core`'s agents under `example:`. So `example:plan-synthesizer` resolves to nothing, because the `example` plugin
contains no `plan-synthesizer`.

### Rule: Qualify skill cross-references the same way

A skill that tells the reader to run another skill uses the same defining plugin's namespace. Write
`example.core:iterative-plan-review`, not `example:iterative-plan-review`. Provenance metadata in generated artifacts
follows the same rule: `generated_by: "example.core:gap-analysis"`.

## Why

Claude Code namespaces a plugin's components under that plugin's `name` field. The plugin reference states it directly:
the `name` "is used for namespacing components", so an agent `agent-creator` in a plugin named `plugin-dev` registers as
`plugin-dev:agent-creator`. If your agents are defined in a plugin whose `plugin.json` has `"name": "example.core"`,
they register as `example.core:agent-name`.

A bare name resolves only when it is unique across every installed plugin plus the user and project agent scopes.
Generic names like `data-engineer`, `test-engineer`, or `software-architect` can collide with an agent from another
installed plugin or a user's own `~/.claude/agents`, and the resolver returns whichever it reaches first. Qualifying the
name removes that ambiguity.

## Correct and incorrect

```
# correct
subagent_type: "example.core:risk-analyst"
Launch `example.core:junior-developer` in artifact-review mode.
run `example.core:plan-implementation`

# incorrect
subagent_type: "risk-analyst"             # bare: may resolve to the wrong agent
subagent_type: "example:risk-analyst"     # example has no agents; resolves to nothing
run `example:plan-implementation`         # example has no skills; same failure
```

## Scope note

By convention, an agent does not carry the `Agent` tool, so it never dispatches another agent directly. Dispatch flows
from skills to agents: a routing table inside a coordinator agent can name the specialists a facilitating skill should
bring in, and the skill performs the qualified dispatch. The rules above govern the skills and any documented invocation
example.

When an agent does need the `Agent` tool, that is a deliberate exception (see
[External File References in Agent Definitions](../agent-building-guidelines/agent-external-files.md)), and its
dispatches still follow the `your-plugin:agent-name` namespacing rules above.

Cross-references:

- [Skill Decomposition](./skill-decomposition.md). When a step's judgment belongs in a dispatched agent.
- [Workflow Patterns](./workflow-patterns.md). Common dispatch-and-verify shapes.
- [Entity Taxonomy](../plugin-entity-taxonomy.md). Skills dispatch agents; agents apply judgment.

---
paths:
  - "**/skills/**/*.md"
---

# `AskUserQuestion` in Skill `allowed-tools`

The `allowed-tools` frontmatter in a SKILL.md file defines which tools are auto-approved without user permission prompts
when the skill is active. Due to a bug in Claude Code's permission evaluator, `AskUserQuestion` must not be listed in
`allowed-tools` — doing so silently breaks the tool's interactive prompt.

## The Rule

Do not add `AskUserQuestion` to the `allowed-tools` frontmatter in any skill file.

**Before (broken):**

```
allowed-tools: Bash(gh *), Bash(git *), Read, Grep, Glob, AskUserQuestion
```

**After (correct):**

```
allowed-tools: Bash(gh *), Bash(git *), Read, Grep, Glob, EnterPlanMode, Skill
```

## Why It Fails

`allowed-tools` is an auto-approve list, not an allowlist. Tools not listed can still be called — they just require a
one-time user permission prompt. When `AskUserQuestion` is in `allowed-tools`, the permission evaluator (`Xv9`) has an
early return path that auto-approves the tool without rendering the interactive prompt UI:

```
Step 1: Check alwaysAllowRules (includes skill allowed-tools)
  └─ AskUserQuestion matches → RETURN { behavior: "allow", answers: {} }
  └─ Steps 4-5 (requiresUserInteraction check) NEVER REACHED
```

The tool returns immediately with empty answers. The user never sees the question. Both AskUserQuestion calls return
`"User has answered your questions: ."` with empty answers.

This also affects skills that delegate via the `Skill` tool — the parent skill's `alwaysAllowRules` persist and stack.
If a parent skill has `AskUserQuestion` in its `allowed-tools`, every child skill's AskUserQuestion calls will also
silently fail.

**Upstream bug reports:**

- GitHub Issue #29547 — "AskUserQuestion silently returns empty answers when called inside plugin skills" (closed March
  2, 2026; fix noted as "upcoming release" but still reproducing as of March 4)
- GitHub Issue #9846 — same symptom in an earlier version (v2.0.22). Fixed in v2.0.28 by adding a
  `requiresUserInteraction()` guard, but that guard only covers the non-allowed-tools path — the `alwaysAllowRules`
  early return bypasses it entirely.

## Which Skills This Affects

Any skill that calls `AskUserQuestion` to ask the user something interactively. If such a skill lists `AskUserQuestion`
in `allowed-tools`, the prompt silently returns empty answers. Audit every skill that asks the user a question and
confirm `AskUserQuestion` is absent from its `allowed-tools` line.

## What Happens Without It

Removing `AskUserQuestion` from `allowed-tools` does not break it. `AskUserQuestion` still works — the user just sees a
one-time permission prompt ("Allow AskUserQuestion?") before the actual question is displayed. The interactive prompt
then renders correctly and the user can respond.

Once Anthropic ships the upstream fix (#29547), `AskUserQuestion` can optionally be re-added to `allowed-tools` for
cleaner UX (auto-approved permission with the interactive prompt still shown).

## Related Tools

`EnterPlanMode` and other mode-toggle tools do NOT have this issue. They don't use `requiresUserInteraction()` and don't
require interactive user input — they are mode toggles called by the agent. No GitHub issues exist for `EnterPlanMode` +
`allowed-tools`.

## Summary Checklist

1. Never add `AskUserQuestion` to `allowed-tools` frontmatter
2. If found in an existing skill, remove it
3. `AskUserQuestion` will still work — it just won't be auto-approved
4. This is a workaround for Claude Code bug #29547; revisit when the fix ships

Cross-reference: [Context Injection Commands](./context-injection-commands.md) for related `allowed-tools` formatting
guidance (separate `Bash()` entries).

---
paths:
  - "**/skills/**/*.md"
---

# Bash Permission Patterns in `allowed-tools`

## Contents

- Syntax Rules
- Granularity Rules
- Common Patterns
- Summary Checklist

The `allowed-tools` frontmatter in a SKILL.md file declares which Bash commands are auto-approved without user
permission prompts. Bash permissions use a glob pattern syntax: `Bash(command prefix *)`. Getting the syntax or
granularity wrong causes skills to either stall on permission prompts or silently auto-approve unintended commands.

## Syntax Rules

### Rule: Each command prefix gets its own `Bash()` entry

Every distinct command prefix must be a separate `Bash()` declaration, comma-separated in the `allowed-tools` line.

**Correct:**

```yaml
allowed-tools: Bash(date *), Bash(git config *), Bash(whoami), Bash(mkdir *), Bash(find *)
```

**Wrong — colon-separated syntax (doesn't exist):**

```yaml
allowed-tools: Bash(gh:*), Bash(git:*)
```

Colon-separated syntax is invented and matches nothing. Use a space before the wildcard.

**Wrong — multiple commands in one `Bash()` declaration:**

```yaml
allowed-tools: Bash(date *, git config *, whoami, ls *, mkdir *, find *)
```

The glob matcher treats the entire contents as a single pattern. Individual commands after the first won't match
correctly.

**Fixed:**

```yaml
allowed-tools: Bash(date *), Bash(git config *), Bash(whoami), Bash(mkdir *), Bash(find *)
```

Each command prefix gets its own `Bash()` entry.

## Granularity Rules

### Rule: Match the prefix to what the skill actually uses

Use the narrowest prefix that covers the skill's actual Bash usage. Overly broad patterns auto-approve commands the
skill doesn't need; overly narrow patterns cause permission prompt interruptions.

**Narrower is better when practical:**

```yaml
# If the skill only uses git branch and git diff:
allowed-tools: Bash(git branch *), Bash(git diff *)
```

Narrower prefixes prevent auto-approving commands the skill doesn't need (like `git push` or `git reset --hard`).

However, skills that use many git subcommands across their steps (branch, diff, log, config, symbolic-ref, and so on)
may use `Bash(git *)` to avoid an unwieldy list of narrow prefixes. A review skill or a PR-description skill that
touches most of git is a typical case. The tradeoff is acceptable when the skill's workflow genuinely requires broad git
access.

**Too narrow / missing:**

```yaml
allowed-tools: Bash(gh *), Bash(git *)
```

A skill that also uses `find` for file discovery will stall on permission prompts when it tries to run `find`, because
no listed prefix covers it.

### Rule: Remove permissions for commands the skill doesn't use

If a skill doesn't actually call a command, don't include it in `allowed-tools`. A stale `Bash(ls *)` entry left over
from an earlier draft, for instance, grants approval the skill never needs and should be removed.

### Rule: Prefer `find` over `ls` — and match `allowed-tools` accordingly

Skills should use `find` for file/directory detection (see
[Context Injection Commands](./context-injection-commands.md#rule-use-find-instead-of-ls-for-file-detection)). If a
skill uses `find` in context injection or step logic, include `Bash(find *)` in `allowed-tools` — not `Bash(ls *)`.

## Common Patterns

Common `allowed-tools` patterns:

| Pattern              | What it covers                                   |
| -------------------- | ------------------------------------------------ |
| `Bash(git branch *)` | Branch listing                                   |
| `Bash(git diff *)`   | Diff operations                                  |
| `Bash(git log *)`    | Log queries                                      |
| `Bash(git config *)` | Config reads                                     |
| `Bash(gh *)`         | All GitHub CLI operations                        |
| `Bash(find *)`       | File/directory discovery                         |
| `Bash(jq *)`         | JSON processing                                  |
| `Bash(which *)`      | Tool availability checks                         |
| `Bash(whoami)`       | OS username (no wildcard needed — exact command) |

## Summary Checklist

1. Each command prefix gets its own `Bash()` entry — never combine multiple commands in one declaration
2. No colon syntax (`Bash(gh:*)`) — use space: `Bash(gh *)`
3. Use the narrowest prefix that covers actual usage
4. Remove `Bash()` entries for commands the skill doesn't use
5. Use `Bash(find *)` not `Bash(ls *)` — skills should use `find` for file detection

Cross-reference: [Context Injection Commands](./context-injection-commands.md) for the relationship between context
injection commands and `allowed-tools` entries.

---
paths:
  - "**/skills/**/*.md"
---

# Context Hygiene

## Contents

- The Rules
- Anti-Patterns
- Summary Checklist

Context hygiene is the discipline of keeping a skill's context footprint minimal, well-positioned, and free of stale or
irrelevant tokens. Several other guidance docs contain rules that serve this goal — progressive disclosure, frontmatter
conciseness, extracting to references/, position-aware ordering, stale-doc audits. This doc explains the mechanisms
behind those rules: why they work and what happens when they're violated. It is based on the
[Context Hygiene principle](https://jdforsythe.github.io/10-principles/principles/context-hygiene/), adapted for
skill-building concerns.

Research on transformer attention shows that every token in context competes for attention weight. Irrelevant tokens
don't just waste space — they actively dilute the model's ability to attend to the tokens that matter. Adding a
paragraph of boilerplate to a SKILL.md doesn't cost "a few tokens of overhead." It degrades the model's attention on
every other instruction in that skill. This is the mechanism behind progressive-disclosure's three-level architecture,
frontmatter conciseness in skill-description-frontmatter.md, and extracting domain knowledge to `references/`.

Research on context position shows that information at the beginning and end of the context window receives
disproportionate attention weight, while information in the middle receives less — a pattern sometimes called "lost in
the middle." Additionally, focused context outperforms accumulated context: performance peaks at roughly 15-40% context
window utilization — enough grounding to prevent hallucination, not so much that relevant tokens get buried in noise.
These effects are the mechanism behind the recency bias rule in workflow-patterns.md and the "don't bury critical
instructions" rule in writing-effective-instructions.md.

## The Rules

### Rule: Every token must earn its place

Before adding content to a SKILL.md, its frontmatter, or its references, ask: does this token improve the skill's
output? Content that doesn't improve output — filler prose, redundant explanations, restated context that the model
already has — doesn't just take up space. It competes for attention with the tokens that do matter.

This is the unifying principle behind several rules in other docs:

- Frontmatter descriptions must earn every word ([Skill Description Frontmatter](./skill-description-frontmatter.md))
- Domain knowledge belongs in `references/`, loaded only when needed
  ([Progressive Disclosure](./progressive-disclosure.md))
- Deterministic operations belong in `scripts/`, whose code never enters context
  ([Progressive Disclosure](./progressive-disclosure.md))
- Rules enforced by linters and formatters should be removed entirely
  ([Progressive Disclosure](./progressive-disclosure.md))

**Before (tokens that don't earn their place):**

```markdown
## Step 2: Analyze the Code

You are now going to analyze the code changes. This is an important step because code quality matters and we want to
make sure everything is good. Take your time and be thorough. Look at the changes carefully and consider all aspects of
the code including readability, maintainability, and correctness. Make sure to check for any issues that might cause
problems.

For each file, review the changes and note any findings.
```

Six sentences of filler before the one actionable instruction. Every filler token competes for attention with "For each
file, review the changes and note any findings."

**After (every token earns its place):**

```markdown
## Step 2: Analyze the Code

For each changed file:

1. Read the full file for context, not just the diff
2. Check against `references/review-checklist.md`
3. Classify each finding as critical, warning, or suggestion
4. Record the file path and line number for each finding
```

### Rule: Build a self-sufficient region at the point of use

The previous rule cuts redundant tokens. This one keeps the tokens a step needs together. Both protect the model's
limited attention.

When a step acts, give it a region that already carries what the step needs — so the model isn't left reconstructing
which reference applies where. A single instruction applied to the data in front of it is cheap; the model does that
constantly and well. What's costly is a step that makes it hold several references at once and route each to a
different, overlapping set of targets — "run the items from [A], but apply [B] to items 2 and 3 and [C] to items 1 and
4." Every extra binding the model has to track and route in one pass is another chance to mis-route. That routing is
work you can do for it.

A region is **self-sufficient** when the routing is already resolved: the step names what applies to what, with nothing
left for the model to reconstruct. That is stronger than merely moving the references next to the step — it removes the
bookkeeping rather than shortening the reach. A step that Reads one `references/checklist.md` and applies it is fine (a
**loadable pointer**: one thing, in focus, applied uniformly). A step that hands the model three references and a
mapping of which applies where is an **in-head reference** — collapse that mapping before the model sees it.

This is the idea progressive disclosure already runs on: a `references/` file is a self-sufficient region, Read into
focus only when a step needs it. Keep the source normalized, and build the region a step acts from at the point of use.
See [Resolve variation at the point of use](./writing-effective-instructions.md) for the form this takes when a step
drives many similar items.

### Rule: Position critical content at the edges, not the middle

Front-load constraints, prerequisites, and context that shapes the entire skill execution. Back-load checklists,
validation criteria, and summary structures. Avoid placing the skill's most important instructions in the middle steps,
where they receive the least attention weight.

This extends the within-step recency bias guidance in [Workflow Patterns](./workflow-patterns.md) to the overall
SKILL.md structure. The same principle applies at both levels: the model weights the beginning and end more heavily than
the middle.

**Before (critical constraint buried in Step 4 of 6):**

```markdown
## Project Context

- Branch: !`git branch --show-current`

## Step 1: Gather Changes

Read the diff between the current branch and the default branch.

## Step 2: Categorize Files

Group changed files by type: source, test, config, docs.

## Step 3: Review Source Files

For each source file, check for issues.

## Step 4: Security Constraint

IMPORTANT: This project handles PII. All findings must be evaluated for data exposure risk. Flag any change that touches
user data fields.

## Step 5: Generate Report

Write the review report.

## Step 6: Summary Checklist

Verify all sections are complete.
```

The security constraint — the single most important instruction — sits in the middle where it gets the least attention.

**After (critical constraint front-loaded):**

```markdown
## Project Context

- Branch: !`git branch --show-current`

## Constraints

This project handles PII. Evaluate every finding for data exposure risk. Flag any change that touches user data fields.

## Step 1: Gather Changes

Read the diff between the current branch and the default branch.

## Step 2: Categorize Files

Group changed files by type: source, test, config, docs.

## Step 3: Review Source Files

For each source file, check for issues.

## Step 4: Generate Report

Write the review report.

## Step 5: Summary Checklist

Verify all sections are complete.
```

The constraint now appears at the top, in a dedicated section that shapes every subsequent step.

### Rule: Do not restate what the toolchain or platform already provides

Content that duplicates what the model already sees — linter rules, CLAUDE.md project context that the platform
auto-loads, MCP tool documentation from tool schemas, or Claude Code's built-in behaviors — wastes attention budget and
creates drift risk when the source changes. This extends the "when to remove entirely" guidance in
[Progressive Disclosure](./progressive-disclosure.md) beyond linters to include all platform-provided context. See that
doc for full examples and rationale.

### Rule: Remember that loaded skill content persists under a compaction budget

Once a skill is invoked, its SKILL.md content stays in context for the rest of the session. When Claude Code
auto-compacts, it carries skills forward within a shared budget of roughly 25,000 tokens, re-attaching the most recently
invoked skills first and capping each at about 5,000 tokens. A bloated SKILL.md does not just dilute attention while it
runs; it crowds the post-compaction budget, and in a session that invoked many skills, the oldest or largest can be
dropped entirely. Keeping the body lean (see [Progressive Disclosure](./progressive-disclosure.md)) is what keeps a
skill present and intact after compaction. Source:
[Claude Code Skills documentation](https://code.claude.com/docs/en/skills).

### Rule: Treat stale context as a bug, not tech debt

Stale tokens are worse than absent tokens. When a reference file describes a convention that was abandoned or a script
path that was renamed, the model follows the stale instruction faithfully — producing confidently wrong output. The
attention mechanism doesn't distinguish "current" from "outdated." Stale tokens compete for attention on equal footing
with current ones, but they point the model in the wrong direction. See
[Documentation Maintenance](./documentation-maintenance.md) for the full audit process, triggers, and examples.

## Anti-Patterns

| Anti-pattern                                         | Why it hurts                                              | Where to fix it                                                       |
| ---------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------- |
| Kitchen sink SKILL.md                                | Token competition dilutes attention on every instruction  | [Progressive Disclosure](./progressive-disclosure.md)                 |
| Restating toolchain rules                            | Wastes attention budget; drifts when config changes       | [Progressive Disclosure](./progressive-disclosure.md)                 |
| In-head join (matrix joined against a separate list) | Attention fragments across the blocks the model must join | [Writing Effective Instructions](./writing-effective-instructions.md) |
| Stale references                                     | Model faithfully follows outdated instructions            | [Documentation Maintenance](./documentation-maintenance.md)           |
| Critical instruction buried in middle steps          | Lost-in-the-middle reduces attention weight               | [Workflow Patterns](./workflow-patterns.md)                           |
| Verbose frontmatter descriptions                     | Token cost paid in every conversation                     | [Skill Description Frontmatter](./skill-description-frontmatter.md)   |

## Summary Checklist

1. Every token in SKILL.md, frontmatter, and references must improve the skill's output — cut filler
2. Front-load constraints and prerequisites; back-load checklists and validation
3. Do not restate rules enforced by linters, formatters, or the platform
4. Treat stale documentation as a functional bug — audit when dependencies change
5. Extract domain knowledge to `references/` to keep the SKILL.md body lean
6. Place the most important instruction or example last within any list (recency bias)
7. Give each step a self-sufficient region to act from — reachable when it runs, with nothing to join from elsewhere

Cross-references:

- [Progressive Disclosure](./progressive-disclosure.md) — The three-level architecture that controls context loading
- [Workflow Patterns](./workflow-patterns.md) — Recency bias and lost-in-the-middle within step design
- [Writing Effective Instructions](./writing-effective-instructions.md) — Conciseness and structure rules for SKILL.md
  body
- [Multi-Agent Economics](../agent-building-guidelines/multi-agent-economics.md) — Self-contained briefs across the
  sub-agent boundary
- [Skill Description Frontmatter](./skill-description-frontmatter.md) — Frontmatter token efficiency and trigger
  accuracy
- [Documentation Maintenance](./documentation-maintenance.md) — Audit process for stale context

---
paths:
  - "**/skills/**/*.md"
---

# Context Injection Commands in Skill Files

## Contents

- Syntax
- When to Use
- Section Placement
- Command Guidelines
- What NOT to Use in Context Injection
- Referencing Injected Context in Steps
- Relationship to `allowed-tools`
- Command Categories Quick Reference
- Summary Checklist

Context injection commands use the `` !`command` `` syntax to execute a shell command at skill load time and inject its
stdout into the skill as runtime context. The command runs **once when the skill loads**, not during each step. This
gives skill steps access to dynamic information about the current environment without hardcoding values.

## Syntax

Format: `` - label: !`command` ``

Multiple commands per line: ``- Git user: !`git config user.name` (!`git config user.email`)``

Many skills use this pattern: code-review skills, documentation skills, PR-description skills, investigation skills,
project-discovery skills, and any skill whose steps need to know the current git state or project layout.

## When to Use

**Use when:** skill steps need runtime information — git state, user identity, project structure, tool availability.

**Don't use when:** the skill is procedural or content-focused and doesn't need environment-specific context. A skill
whose steps are pure instructions (a writing-style guide, a content checklist, a procedural walkthrough) has no need for
context injection commands because its steps don't depend on runtime environment details.

## Section Placement

Context injection commands belong in one of two sections:

1. **`## Pre-requisites`** — tool availability checks that gate execution. If a required tool is missing, the skill
   should inform the user and stop immediately.
2. **`## Project Context`** — runtime information used by step logic (git state, file structure, user identity).

Do not duplicate commands across both sections. A tool availability check belongs in Pre-requisites only; repeating the
same check in Project Context runs the command twice and adds nothing.

## Command Guidelines

### Rule: Keep every command an auto-approvable read-only form

Context injection runs at skill load, and it never prompts. If a command is not auto-approvable, the loader hard-rejects
it and stops loading the skill. You see the error for the first failing command only; every command after it is masked,
so one bad command takes the whole skill down. There is no prompt to fall back on, so keeping commands simple is not a
style preference here. It is what keeps the skill loadable.

A command auto-approves only when every command in it, and every stage of a pipe or part of a chain, is one of:

1. A built-in **read-only** command in an allowed form. The loader ships a fixed allowlist that already covers most
   inspection tools, including `cat`, `ls`, `head`, `tail`, `wc`, `grep`, `find` (without the dangerous predicates
   below), `which`, `echo`, `date`, and the read-only `git` and `gh` subcommands such as `git status`, `git log`,
   `git diff`, `git rev-parse`, and `git config --get`. Commands on this list need no `allowed-tools` entry.
2. Matched by an explicit `Bash()` rule in the skill's `allowed-tools`.

Read the allowlist as a claim about the command, not about its arguments. A probe using an allowlisted command has
still been refused in the field over what it was pointed at, with an error naming a permission classifier this guidance
does not describe. Treat the two rules above as necessary rather than sufficient, and pair them with the path rule
below.

Pipes and `&&` / `;` / `||` chains are not forbidden. The loader splits them and checks each part against the two rules
above, so `git log --oneline | head` and `git rev-parse HEAD && git branch --show-current` load fine because every part
is an allowlisted read-only form. What breaks a skill is a part that is neither allowlisted nor declared, or one of the
constructs the classifier refuses outright.

**Four constructs are refused every time, and declaring a `Bash()` rule does not rescue them:**

- **Command substitution** `$(...)` injects the error `Contains command_substitution`.
- **Process substitution** `<(...)` or `>(...)` injects `Contains process_substitution`.
- **Subshells** `( ... )` and **background** `&`, reported as "not a simple read-only command".
- **Dangerous sub-forms of otherwise-safe tools**: `find` with `-exec`, `-execdir`, `-delete`, `-ok`, or `-fprint*`;
  `sed` with in-place editing; and similar. These stay blocked even when a matching prefix rule such as `Bash(find *)`
  is present. The danger check overrides the grant, so a broad `Bash(find *)` cannot re-enable `find -exec`.

Even though a pipe of read-only commands loads, prefer one flag-driven command when it exists. Not because pipes fail,
but because every extra stage is one more part that has to stay on the allowlist, and one part that slips off aborts the
whole skill load with an error that names only that part. A flag on the primary command usually replaces the pipe
outright. Instead of piping `git symbolic-ref` through `sed` to strip a prefix, use the `--short` flag.

**Prefer (one allowlisted command, nothing to slip off):**

```
!`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown`
!`find . -maxdepth 3 -name "project-discovery.md" -type f`
!`find . -maxdepth 1 -name "Makefile" -type f`
```

**Avoid:**

```
!`export DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | cut -d '/' -f4-) && echo $DEFAULT_BRANCH`
!`test -f Makefile && echo "yes" || echo "no"`
```

The first line is refused outright because of the `$(...)`. The second loads, but a single `find` with `-name` returns
the same answer with nothing to slip off the allowlist.

**Keep each injected value small.** Injected output is inserted once at load and stays in context for the whole skill
run, so a large blob is a standing cost that can bury the signal. Bound it at the source rather than after the fact:
prefer a command that returns only what the step needs, such as `git log -n 10 --oneline` over piping a full log into
`head`, `git diff --stat` or `--name-only` over a full diff, and `find` with `-maxdepth` and `-name` over listing a
whole tree. A native limit cuts at a meaningful boundary and stays a single command.

`| head -N` is a last resort, not a ban. It loads, because `head` is allowlisted, so when a command has no native limit
and you only need a capped preview, `cmd | head -20` is fine. Two cautions. Never `| head` a result the step logic then
checks for completeness, because it can drop the very line you were looking for; use a bounded query or gather it in a
step instead. And if you are capping a flood, that is usually a sign the data should be gathered in a step during the
run, not injected at load.

One compound form is not only allowed but recommended: the trailing `2>/dev/null || echo <sentinel>` guard. It is a `||`
chain, and it loads because both parts qualify. The sentinel side is a bare `echo`, which is allowlisted, and the
primary side is an allowlisted read-only command or one your `allowed-tools` declares. Use it on any command that exits
non-zero when its subject is absent, so the command exits 0 and injects a value the step logic can check.
`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown` keeps its guard because `origin/HEAD`
may be unset.

One edge is worth knowing. The read-only `git config` form on the allowlist is `git config --get`, so write
`git config --get user.name`, not the bare `git config user.name`. The bare form is accepted as a lone command but not
as a part of a `&&` / `;` / `||` chain, where it then needs an explicit `Bash(git config *)` rule. Using `--get` keeps
the guarded form self-sufficient: `git config --get user.name || echo unset` loads on the allowlist alone.

This reflects the loader's current behavior. The exact allowlist can shift between Claude Code versions, so when a
command is not clearly a plain read-only form, prefer the simplest single-command version or move the logic into a
script (next rule).

### Rule: Keep every probe reading inside the project working directory

A probe reads files in the directory the skill runs from. When a step needs the content of a file somewhere else, gather
it during the run with the Read tool instead.

The reason is the no-prompt, no-fallback behavior from the rule above. A probe stakes the whole skill on a permission
decision it cannot recover from, and a read reaching outside the project into a home directory, a configuration
directory, or anywhere holding credentials is the read most likely to draw a refusal. A Read-tool call during the run
carries no such risk to the skill: the step handles a read that returns nothing and carries on.

Han shipped this mistake once. Forty skills read an optional personal config through a probe pointed at the Claude Code
configuration directory, and the refusal that followed took whole skills down before they did any work:

```
Error: Shell command permission check failed for pattern
"!`cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.han/config.md" 2>/dev/null || echo ""`":
Permission for this action was denied by the Claude Code auto mode classifier.
Reason: Blocked by classifier.
```

Resolving a path in a probe stays fine, because `echo` opens no file. Reading through it does not.

**Prefer (probe resolves the location, a step reads the file):**

```
- personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
```

That line reads an environment variable inside a script rather than in the probe text, which is the only measured way
to reach one. See "Rule: Reach an environment variable through a script, not through probe text" below.

**Avoid (probe reads outside the project):**

```
!`cat "$HOME/.someconfig" 2>/dev/null || echo ""`
!`cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.han/config.md" 2>/dev/null || echo ""`
```

### Rule: Reach an environment variable through a script, not through probe text

The loader inspects the probe's text before anything runs. A variable named there is refused, and the refusal is
narrower than the error message suggests. These results are measured on Claude Code `2.1.234`, each form written into a
scratch skill and invoked from a fresh session:

| Probe form                                         | Result |
| -------------------------------------------------- | ------ |
| `echo hello`                                       | loads  |
| `echo "$HOME"`                                     | loads  |
| `echo "$HOME/.claude"`                             | loads  |
| `echo ~/.claude`                                   | loads  |
| `echo "${HOME}"`                                   | aborts |
| `echo "${HOME:-/tmp}"`                             | aborts |
| `echo "$CLAUDE_CONFIG_DIR"`                        | aborts |
| `echo "$FOOBAR_NOT_REAL"`                          | aborts |
| `echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"`       | aborts |
| `printenv HOME`                                    | aborts |
| `printenv CLAUDE_CONFIG_DIR \|\| echo "~/.claude"` | aborts |

Three rules explain every row. A bare `$HOME` is permitted. Brace syntax is refused even for `$HOME`, so the form
matters as much as the name. Every variable other than `HOME` is refused, including one that does not exist, so the
loader is not resolving values and reacting to them.

An `allowed-tools` grant does not help here. The refusal happens on the text, before any permission question is asked.

To reach a variable, put it in a script and run the script from the probe:

```
- personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
```

```yaml
allowed-tools: Read, Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")
```

Four things make that work, and leaving any of them out aborts the skill:

1. **Grant the exact command.** A script probe is refused without a grant, even with no variable anywhere in it. This
   is the second route to auto-approval described in the first rule on this page, and it is the one a script needs.
2. **Use the braced `${CLAUDE_PLUGIN_ROOT}`.** It is a harness substitution, replaced before the permission check runs,
   so the check never sees a variable reference. The unbraced `$CLAUDE_PLUGIN_ROOT` is not substituted and is refused.
3. **Stay inside a plugin.** Both spellings abort in a skill under `.claude/skills/`, where nothing defines the
   substitution. Verify a script probe as an installed plugin, never as a local skill.
4. **Guard the command.** A missing or failing script aborts the skill exactly as a refused probe does. The
   `2>/dev/null || echo <fallback>` tail degrades instead. The grant needs to name only the `bash ...` half, because the
   `echo` half is separately auto-approvable.

Keep the script itself trivial and read-only. A probe cannot prompt, so anything the script does that could fail takes
the skill down with it.

### Rule: Use shell scripts for complex operations

When a task requires command substitution, process substitution, heredocs, JSON construction, or multi-step logic,
extract it into a shell script and call the script from skill steps (not from context injection).

A common case is posting structured data to an API. Building a JSON payload inline with a heredoc, then piping it to a
CLI, mixes a heredoc and command substitution into one command. The heredoc and the substitution are both refused at
load, so none of it runs. Put it in a script instead.

**Before (inline in SKILL.md, fails):**

```
some-cli api repos/{owner}/{repo}/reviews --method POST --input - <<'REVIEW_JSON'
{
  "commit_id": "{head_sha}",
  "event": "{event_type}",
  "body": "{review_body}"
}
REVIEW_JSON
```

**After (extracted to shell scripts):**

- A `scripts/gather-metadata.sh` that collects what it needs using the CLI, `jq`, pipes, and subcommands
- A `scripts/post-review.sh` that builds the JSON payload with `jq` and posts it via the CLI

The SKILL.md then references the scripts using `${CLAUDE_SKILL_DIR}` paths:

```
${CLAUDE_SKILL_DIR}/scripts/gather-metadata.sh
${CLAUDE_SKILL_DIR}/scripts/post-review.sh {owner/repo} {id} {head_sha} {event_type} {temp_file_path}
```

See also: [Script Execution Instructions](./script-execution-instructions.md) for the full pattern on how to write
script invocation steps in SKILL.md.

Shell scripts can safely use pipes, redirects, subcommands, and complex logic because they run as normal bash processes,
not through the skill context injection system.

### Rule: Use `which` (guarded) to check if a tool is installed

Use `which {command} 2>/dev/null || echo "not installed"` to check whether a tool is installed:

```
- gh CLI: !`which gh 2>/dev/null || echo "not installed"`
- jq: !`which jq 2>/dev/null || echo "not installed"`
```

When the tool is missing, `which` exits non-zero and may print to stderr — either can abort the skill or dirty the
injected value. `2>/dev/null` drops the stderr and `|| echo "not installed"` forces a clean exit plus a sentinel the
Pre-requisites gate checks. Prefer this over `{command} --version`, which fails the same way. The same guard fits any
command that fails when its subject is absent — e.g.
`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown` when `origin/HEAD` may be unset.

### Rule: Use `find` instead of `ls` for file detection

Use `find` with specific flags for file and directory detection. Do not use `ls`.

**Before (avoid):**

```
- has Makefile: !`ls Makefile`
- has package.json: !`ls package.json`
- doc directories: !`ls -d docs/ documentation/ doc/`
- CLAUDE.md exists: !`ls CLAUDE.md`
- Project language indicators: !`ls *.go go/ src/ package.json ...`
```

**After (current, working):**

```
- has Makefile: !`find . -maxdepth 1 -name "Makefile" -type f`
- has package.json: !`find . -maxdepth 1 -name "package.json" -type f`
- doc directories: !`find . -maxdepth 1 -type d \( -name "docs" -o -name "documentation" -o -name "doc" \)`
- CLAUDE.md exists: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
- Project language indicators: !`find . -maxdepth 1 \( -type f \( -name "*.go" -o -name "package.json" ... \) -o -type d \( -name "go" -o -name "src" \) \)`
```

`find` is more reliable because:

- It doesn't fail with exit code 2 when files don't exist (unlike `ls`)
- `-maxdepth` controls search scope explicitly
- `-type f` and `-type d` distinguish files from directories
- `-name` with `-o` handles multiple patterns cleanly

### Rule: Never use the literal bang-backtick syntax in SKILL.md prose

The skill loader scans the **raw text** of the SKILL.md body for context injection patterns. Markdown escaping — double
backticks, inline code spans, fenced code blocks — does **not** prevent parsing. If the literal pattern appears anywhere
in the SKILL.md body, even as a documentation example or description, the loader will extract it and attempt to execute
the command inside.

This bites skills that document or analyze other skills. A skill whose SKILL.md contained the literal pattern in a
bullet describing the syntax had the loader parse it as an actual command and fail with:
`Shell command permission check failed for pattern "!`command`": This command requires approval`.

**When you need to reference context injection syntax in a SKILL.md body** (e.g., when a skill analyzes other skills),
describe the concept without the literal pattern:

**Before (broken — loader executes `command`):**

```markdown
- A context injection command (`` !`command` `` syntax)
```

**After (correct — describes the concept safely):**

```markdown
- A context injection command (bang-backtick syntax for runtime context)
```

**Reference files are safe.** Files in `references/` are not parsed by the skill loader, so they can contain the literal
pattern for documentation purposes.

## What NOT to Use in Context Injection

| Pattern                                          | Example                                                 | What happens                                                                                                                                                   |
| ------------------------------------------------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Command substitution                             | `$(command)`                                            | Refused every time (`Contains command_substitution`), even when declared                                                                                       |
| Process substitution                             | `<(command)`, `>(command)`                              | Refused every time (`Contains process_substitution`), even when declared                                                                                       |
| Subshell or background                           | `( cmd )`, `cmd &`                                      | Refused as "not a simple read-only command"                                                                                                                    |
| Dangerous tool flags                             | `find ... -exec`, `find ... -delete`, `sed -i`          | Refused even with a matching `Bash()` prefix rule                                                                                                              |
| An environment variable named in probe text      | `echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"`            | Refused (`Contains expansion`) for every variable except a bare `$HOME`, and refused for `$HOME` itself in brace form. No `allowed-tools` grant changes this   |
| `printenv` anywhere in a probe                   | `printenv HOME`                                         | Refused whatever variable it names, so it is not a way around the rule above                                                                                   |
| A script probe with no matching grant            | `bash ./scripts/thing.sh`                               | Aborts the skill load even with no variable in the command. Grant the exact command in `allowed-tools`                                                         |
| An unguarded script probe                        | `bash "${CLAUDE_PLUGIN_ROOT}/scripts/thing.sh"`         | Aborts the skill if the script is missing or exits non-zero. Append `2>/dev/null \|\| echo <fallback>`                                                         |
| A stage that is neither allowlisted nor declared | `command \| custom-bin`                                 | Aborts the whole skill load; the error names only the offending stage                                                                                          |
| Large injected output                            | full `git diff`, unbounded `git log`, whole-tree `find` | Bound at the source (`-n`, `--stat`, `--name-only`, `-maxdepth`); a big value persists in context for the whole run. `\| head -N` is a last resort, not broken |
| A read reaching outside the project              | `cat "$HOME/.config/thing"`                             | Stakes the skill load on a permission decision with no fallback; resolve the path in a probe and read the file with the Read tool during the run               |
| `ls` for detection                               | `ls filename`                                           | Use `find` instead; `ls` fails on missing files                                                                                                                |
| Heredocs                                         | `<<'EOF' ... EOF`                                       | Extract to shell scripts                                                                                                                                       |
| Literal bang-backtick syntax in prose            | Showing the pattern as an example                       | Loader parses raw text; use "bang-backtick syntax" instead                                                                                                     |

## Referencing Injected Context in Steps

1. **Refer to the label** — "If `default branch` is empty"
2. **Handle empty output** — check for emptiness, then ask the user or skip (for example, "If git user or email is
   **empty**")
3. **Pre-requisite gates** — if a tool is not found, inform the user and stop immediately

## Relationship to `allowed-tools`

Each Bash command pattern must be a separate `Bash()` entry in the `allowed-tools` frontmatter.

```
# Before (broken: one Bash() with several commands inside):
allowed-tools: Bash(date *, git config *, whoami, ls *, mkdir *)

# After (correct: one Bash() per command prefix):
allowed-tools: Bash(date *), Bash(git config *), Bash(whoami), Bash(mkdir *), Bash(find *)
```

See also: [allowed-tools: AskUserQuestion](./allowed-tools-AskUserQuestion.md) for another `allowed-tools` constraint.

## Command Categories Quick Reference

Examples organized by purpose:

**Git state** (each exits non-zero outside a repo or with `origin/HEAD` unset, so each is guarded):

- `` !`git branch --show-current 2>/dev/null || echo unknown` `` — current branch
- `` !`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown` `` — default branch
- `` !`git log origin/HEAD..HEAD --oneline 2>/dev/null || echo unknown` `` — branch summary
- `` !`git diff origin/HEAD...HEAD --stat 2>/dev/null || echo unknown` `` — branch stats
- `` !`git diff origin/HEAD...HEAD 2>/dev/null || echo unknown` `` — branch changes

**Git diffs/logs (via gh CLI):**

- `` !`gh pr diff --name-only 2>/dev/null || echo "no pr"` `` — PR changed files (fails when no PR exists)

**User identity:**

- `` !`git config --get user.name || echo unset` `` — git user name (exits 1 when identity is unset)
- `` !`git config --get user.email || echo unset` `` — git user email
- `` !`whoami` `` — OS username

**File/directory discovery:**

- `` !`find . -maxdepth 1 -name "CLAUDE.md" -type f` `` — check for a file
- `` !`find . -maxdepth 1 -name "AGENTS.md" -type f` `` — check for a file
- `` !`find . -maxdepth 1 -name "README*" -type f` `` — check for a file
- `` !`find . -maxdepth 3 -name "project-discovery.md" -type f` `` — find a known output file written by another skill
- `` !`find . -maxdepth 4 -type d -path "*/.claude/rules/coding-standards"` `` — check for a path-scoped rules directory

**Tool availability:**

- `` !`which gh 2>/dev/null || echo "not installed"` `` — check for the gh CLI
- `` !`which jq 2>/dev/null || echo "not installed"` `` — check for jq
- `` !`which git 2>/dev/null || echo "not installed"` `` — check for git

## Summary Checklist

1. Use `` !`command` `` in `## Pre-requisites` or `## Project Context`
2. Every command, and every pipe stage or chain part, must be an allowlisted read-only form or explicitly declared in
   `allowed-tools`; a part that is neither aborts the whole skill load. Never use command substitution `$(...)`, process
   substitution `<(...)`, subshells, or `&`, which are refused even when declared. Pipes and `&&` / `;` / `||` chains
   are fine when every part qualifies, but prefer one flag-driven command; the trailing `2>/dev/null || echo <sentinel>`
   guard is the recommended compound (items 3-4)
3. Use `which {command} 2>/dev/null || echo "not installed"` for tool availability checks
4. Guard any read that exits non-zero when its subject is absent (`git symbolic-ref … origin/HEAD`,
   `git log/diff origin/HEAD…`, `gh pr diff`, `git config user.name/email`) with a trailing
   `2>/dev/null || echo <sentinel>`, and gate its consumer on that sentinel
5. Keep every probe reading inside the project working directory; resolve an outside path with `echo` and read the file
   with the Read tool during the run
6. Use `find` for file/directory detection, not `ls`
7. Extract complex operations into shell scripts
8. Handle empty output in step logic; keep injected values small by bounding at the source (`git log -n`, `--stat`,
   `find -maxdepth`), and never trim a result you then check for completeness
9. Do not duplicate commands across sections
10. Use separate `Bash()` entries in `allowed-tools`
11. Never use the literal bang-backtick pattern in SKILL.md prose — the loader parses raw text regardless of markdown
    escaping

---
paths:
  - "**/skills/**/*.md"
---

# Claude Cowork — Complete Reference

## Contents

- What is Cowork?
- What Cowork Can Do
- Cowork vs. Claude Code: Extension Model
- Skills in Cowork
- Skill File Format
- Skill Directory Structure
- How Skills Load (Progressive Disclosure)
- Cowork Runtime Environment
- Authoring Best Practices
- Checklist Before Uploading a Skill
- Resources

## What is Cowork?

Claude Cowork is Anthropic's agentic AI system for knowledge workers (not developers), available as a research preview
in the Claude Desktop app (Mac/Windows) and claude.ai. Unlike Claude Chat (one prompt → one response), Cowork
autonomously plans and executes multi-step tasks on your local machine.

**Target users:** Researchers, analysts, operations, legal, finance — anyone doing time-consuming document/data/file
work.

**Requirements:** Paid plan (Pro, Max, Team, Enterprise), Claude Desktop app or claude.ai, code execution enabled.

---

## What Cowork Can Do

- Direct local file access (read/write without manual uploads)
- Multi-step autonomous task execution
- Parallel subtask coordination
- Create formatted spreadsheets (with formulas), PowerPoint presentations, Word documents, PDFs
- File organization (rename, sort, deduplicate)
- Research synthesis across multiple sources
- Data extraction from unstructured documents
- Scheduled/recurring automation tasks

---

## Cowork vs. Claude Code: Extension Model

| Feature        | Claude Code                          | Claude.ai / Cowork   |
| -------------- | ------------------------------------ | -------------------- |
| Plugins        | Yes (`.claude-plugin/`, marketplace) | **No**               |
| Skills         | Yes (filesystem directories)         | **Yes** (ZIP upload) |
| Agents         | Yes (part of plugins)                | No                   |
| Hooks          | Yes (part of plugins)                | No                   |
| Slash commands | Yes (part of plugins/skills)         | No                   |

**Cowork only supports Skills** — not the full Claude Code plugin system.

---

## Skills in Cowork

Skills are the only extension mechanism. Cowork ships with four pre-built Skills:

- **PowerPoint (pptx)** — create/edit presentations
- **Excel (xlsx)** — create spreadsheets, analyze data, generate charts
- **Word (docx)** — create/edit/format documents
- **PDF (pdf)** — generate formatted PDF documents and reports

Custom Skills are uploaded as **ZIP files** via **Settings > Features**. Available on Pro, Max, Team, and Enterprise
plans.

**Sharing:** Custom Skills are per-user only. Each team member must upload separately. No org-wide or admin-managed
distribution on claude.ai.

---

## Skill File Format

Every Skill requires a `SKILL.md` file with YAML frontmatter:

````yaml
---
name: processing-pdfs
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Use pdfplumber for text extraction:

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
````

For form filling, see [FORMS.md](FORMS.md).

```

### Frontmatter field rules

**`name`**
- Max 64 characters
- Lowercase letters, numbers, and hyphens only
- No XML tags
- Cannot contain reserved words: `anthropic`, `claude`

**`description`**
- Non-empty, max 1024 characters
- No XML tags
- Must be written in **third person** ("Processes Excel files" — not "I can help you")
- Must describe both **what** the skill does and **when** to use it
- Claude uses this to auto-select the right skill from potentially 100+ installed

---

## Skill Directory Structure

```

your-skill/ ├── SKILL.md # Required: frontmatter + instructions ├── FORMS.md # Optional: referenced as-needed ├──
reference/ │ ├── finance.md # Optional: domain-specific reference │ └── sales.md └── scripts/ ├── process.py # Optional:
utility scripts (executed, not read) └── validate.py

````

ZIP the skill folder itself (not a wrapper folder) for upload to Cowork.

---

## How Skills Load (Progressive Disclosure)

Skills use a 3-level loading model to minimize context usage:

| Level | When Loaded | Token Cost | Content |
|---|---|---|---|
| **1: Metadata** | Always (at startup) | ~100 tokens/skill | `name` + `description` from frontmatter |
| **2: Instructions** | When skill is triggered | Under 5k tokens | SKILL.md body |
| **3: Resources/code** | As needed | Effectively unlimited | Bundled files, scripts |

Claude reads `SKILL.md` via bash only when your request matches the description. Additional files (FORMS.md, reference/*.md) are read only when SKILL.md references them. Scripts are **executed** — their code never enters the context window, only their output does.

---

## Cowork Runtime Environment

- **Network access:** Varies by user/admin settings (full, partial, or none)
- **Package installation:** Can install from npm and PyPI, and pull from GitHub repos
- Scripts run in a VM with filesystem access and bash

This is more permissive than the Claude API (which has no network access) but less predictable than Claude Code (which has full network access like any local program).

---

## Authoring Best Practices

### Descriptions
- Be specific; include key trigger terms
- Third person only
- Include both what it does and when to use it

**Good:**
```yaml
description: Analyzes Excel spreadsheets, creates pivot tables, generates charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
````

**Bad:**

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

### Conciseness

- Keep `SKILL.md` body under **500 lines**
- Don't explain things Claude already knows
- Put detail in separate referenced files

### Progressive disclosure patterns

**Pattern 1 — High-level guide with references:**

```markdown
## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) **API reference**: See [REFERENCE.md](REFERENCE.md)
```

**Pattern 2 — Domain-specific organization:**

```
bigquery-skill/
├── SKILL.md (overview + navigation)
└── reference/
    ├── finance.md
    ├── sales.md
    └── product.md
```

**Pattern 3 — Conditional details:**

```markdown
For tracked changes: See [REDLINING.md](REDLINING.md) For OOXML details: See [OOXML.md](OOXML.md)
```

Keep all references **one level deep** from SKILL.md, and open any reference file over roughly 100 lines with a contents
list. Neither rule is specific to cowork; both are in
[Skill Reference Files](./skill-reference-files.md#keep-reference-links-one-level-deep-from-skillmd).

### Degrees of freedom

- **High freedom** (text instructions): when multiple approaches are valid
- **Medium freedom** (pseudocode/parameterized scripts): when a preferred pattern exists
- **Low freedom** (exact scripts, specific commands): for fragile/critical operations like DB migrations

### Workflows

Break complex tasks into numbered steps. For multi-step operations, provide a checklist Claude can track:

```markdown
## Form filling workflow

Copy this checklist:

- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form
- [ ] Step 5: Verify output
```

### Scripts

- Pre-made scripts are more reliable than asking Claude to generate code on the fly
- Script code never enters context — only output does
- Be explicit: "Run `analyze_form.py`" (execute) vs "See `analyze_form.py` for the algorithm" (read)
- Handle errors in scripts explicitly; don't punt errors to Claude
- Always use forward slashes in paths (no Windows-style backslashes)
- List required packages explicitly in instructions

### Naming conventions

Use gerund form (verb + -ing):

- `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases`
- Avoid: `helper`, `utils`, `tools`, `documents`

This gerund preference is the general Anthropic convention, not Cowork-specific.
[Naming Conventions](./naming-conventions.md) is the canonical doc for skill and plugin naming; it covers the same
gerund rule plus directory-name, dependency-prefix, and case-sensitivity rules.

---

## Checklist Before Uploading a Skill

**Core quality**

- [ ] Description is specific, third-person, includes what + when
- [ ] SKILL.md body under 500 lines
- [ ] No time-sensitive information
- [ ] Consistent terminology throughout
- [ ] File references are one level deep from SKILL.md
- [ ] Reference files over roughly 100 lines open with a contents list
- [ ] Workflows have clear numbered steps

**Code and scripts**

- [ ] Scripts handle errors explicitly (don't punt to Claude)
- [ ] Required packages listed and verified available
- [ ] No Windows-style paths (all forward slashes)
- [ ] Validation/feedback loops for critical operations

**Testing**

- [ ] Tested with real usage scenarios
- [ ] Tested with multiple Claude model tiers if applicable

---

## Resources

- Product page: `anthropic.com/product/claude-cowork`
- Skills overview: `platform.claude.com/docs/en/agents-and-tools/agent-skills/overview`
- Skills best practices: `platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices`
- Skills cookbook: `platform.claude.com/cookbook/skills-notebooks-01-skills-introduction`
- Free intro course: Anthropic Academy — "Introduction to Claude Cowork"
- Open-source Skills repo: `github.com/anthropics/skills`

---
paths:
  - "**/skills/**/*.md"
---

# Documentation Maintenance

## Contents

- The Rules
- Rule: Treat doc-code contradictions as functional bugs
- Rule: Audit SKILL.md when its dependencies change
- Rule: Audit references/ against source truth
- Rule: Version documentation with the code it describes
- Summary Checklist

A skill that worked last month can silently degrade if its SKILL.md or references describe things that have changed. The
model follows stale instructions faithfully — stale documentation is active poison, not passive neglect.

A team once spent three days debugging ESLint violations where an agent consistently used `Array<T>` instead of the
enforced `T[]`. The root cause was a buried markdown file that said "Prefer `Array<T>` for readability." The agent read
and faithfully followed the stale instruction. The symptom looked like a model failure, but it was a documentation
failure.

This guide covers when and how to audit skills so their documentation matches reality.

## The Rules

### Rule: Treat doc-code contradictions as functional bugs

When SKILL.md references a file path that no longer exists, a tool flag that was renamed, or a convention that was
abandoned, the model follows the stale instruction. The symptom is structurally correct but factually wrong output — it
looks like a model failure but is actually a documentation failure. Triage these with the same severity as a broken
shell script.

**Before (stale script reference):**

```markdown
## Step 5: Post Review

Run `scripts/post-review.sh {owner/repo} {pr_number}` to post the review.
```

The script was renamed to `scripts/submit-review.sh` two months ago. The model tries to run the old name, fails, and
either halts or invents a workaround.

**After (updated reference):**

```markdown
## Step 5: Post Review

Run `scripts/submit-review.sh {owner/repo} {pr_number}` to post the review.
```

**Before (stale convention in references/):**

`references/coding-conventions.md`:

```markdown
## Date Handling

Use Moment.js for all date parsing and formatting:

- `moment(dateString).format('YYYY-MM-DD')`
- `moment().add(7, 'days')`
```

The project migrated to date-fns six months ago. The model reads this reference and generates Moment.js code.

**After (updated reference):**

`references/coding-conventions.md`:

```markdown
## Date Handling

Use date-fns for all date parsing and formatting:

- `format(parseISO(dateString), 'yyyy-MM-dd')`
- `addDays(new Date(), 7)`
```

### Rule: Audit SKILL.md when its dependencies change

The following changes should trigger a review of any skill that depends on them:

- A referenced script (`scripts/`) was modified or renamed
- A referenced file (`references/`) was updated
- An external tool the skill calls (gh CLI, jq, etc.) released a breaking change
- Project conventions the skill enforces were updated
- The skill's functional tests start failing intermittently — this is often a signal that reality has drifted from what
  the skill describes

This is a manual discipline. The triggers above tell you _when_ to look. When a trigger fires, read the SKILL.md and its
references end-to-end, checking every file path, tool flag, and convention reference against the current state.

### Rule: Audit references/ against source truth

For each reference file, identify what it describes: a codebase convention, an external standard, a tool's API, a style
guide. When that source changes, the reference must be updated or it becomes a poisoned few-shot example the model will
faithfully reproduce.

Questions to ask during an audit:

- Does the reference describe the current state of the codebase, or a past state?
- Do code examples in the reference use the same libraries, patterns, and APIs the project currently uses?
- Are file paths in the reference still valid?
- Are tool flags and CLI options still supported by the current tool version?

### Rule: Version documentation with the code it describes

When a PR changes a script in `scripts/`, renames a reference file, or updates a convention that a skill enforces, the
corresponding SKILL.md or reference update belongs in the same commit. This prevents a drift window where code has
changed but documentation has not yet caught up — exactly the gap that causes the failures described in the rules above.

This is the proactive complement to the reactive audit triggers. Audits catch drift after it happens; co-versioning
prevents it from happening.

**Before (code and docs updated separately):**

```
commit a1b2c3: Rename scripts/post-review.sh → scripts/submit-review.sh
commit d4e5f6: (three days later) Update SKILL.md to reference submit-review.sh
```

For three days, the skill references a script that doesn't exist.

**After (code and docs updated together):**

```
commit a1b2c3: Rename scripts/post-review.sh → scripts/submit-review.sh
              Update SKILL.md to reference submit-review.sh
```

No drift window. The documentation is never wrong.

## Summary Checklist

1. Treat doc-code contradictions as functional bugs — triage with the same severity as broken scripts
2. Audit SKILL.md when referenced scripts, reference files, external tools, or project conventions change
3. Audit `references/` against the current state of what they describe
4. Version documentation changes in the same commit as the code changes they describe
5. When a skill's functional tests fail intermittently, check for stale documentation before debugging the skill logic

Cross-references:

- [Troubleshooting](./troubleshooting.md) — Cause 4 under "Instructions Not Followed" covers stale documentation as a
  symptom
- [Skill Reference Files](./skill-reference-files.md) — Placement and purpose of reference documents
- [Success Criteria and Testing](./success-criteria-and-testing.md) — Functional tests that can surface documentation
  drift
- [Context Hygiene](./context-hygiene.md) — Why stale tokens actively degrade model performance

---
paths:
  - "**/skills/**/*.md"
---

# Dynamic Project Discovery

## Contents

- The Rules
- Rule: Never hardcode branch names
- Rule: Use `which` (guarded) for tool availability, not `--version`
- Rule: Discover project structure dynamically
- Rule: Handle missing tools gracefully in Pre-requisites
- Summary Checklist

Skills run in whatever repository the user invokes them from. They must discover the project's structure, branch names,
and tool availability dynamically rather than hardcoding assumptions.

## The Rules

### Rule: Never hardcode branch names

Use `origin/HEAD` or `git symbolic-ref --short refs/remotes/origin/HEAD` to discover the default branch. Do not hardcode
`main`, `master`, `develop`, or any other branch name.

**Before (broken on non-`main` repos):**

```
git log main..HEAD --oneline
git diff main...HEAD
```

Hardcoded `main` breaks immediately on repos whose default is `develop`, `master`, or any other branch name.

**After (dynamic):**

```
git log origin/HEAD..HEAD --oneline
git diff origin/HEAD...HEAD
```

Using `origin/HEAD` works regardless of the default branch name.

For context injection commands, guard the read so an unset `origin/HEAD` (which makes `git symbolic-ref` exit 128) can't
abort the skill:

```
- default branch: !`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown`
```

This injects the actual default branch name at skill load time, or the sentinel `unknown` when `origin/HEAD` isn't set —
which the skill's step logic checks the same way it checks for empty output.

### Rule: Use `which` (guarded) for tool availability, not `--version`

Check tool availability with `which {command} 2>/dev/null || echo "not installed"` in the Pre-requisites section.

**Before (problematic):**

```
- gh CLI: !`gh --version`
```

**After (correct):**

```
- gh CLI: !`which gh 2>/dev/null || echo "not installed"`
```

A missing tool makes `which` (or `--version`) exit non-zero and print to stderr, which can abort the skill.
`2>/dev/null` drops the stderr and `|| echo "not installed"` forces a clean exit plus a sentinel the Pre-requisites
logic checks.

### Rule: Discover project structure dynamically

Use `find` to detect directories, files, and language indicators. Do not assume paths like `src/`, `docs/`, or `lib/`
exist.

**Examples of dynamic discovery:**

```
- doc directories: !`find . -maxdepth 1 -type d \( -name "docs" -o -name "documentation" -o -name "doc" \)`
- has Makefile: !`find . -maxdepth 1 -name "Makefile" -type f`
- language indicators: !`find . -maxdepth 1 \( -type f \( -name "*.go" -o -name "package.json" -o -name "Cargo.toml" \) -o -type d \( -name "go" -o -name "src" \) \)`
```

These patterns detect what exists without assuming it does. Empty output means the file or directory isn't present, and
the skill's step logic can handle that gracefully.

### Rule: Handle missing tools gracefully in Pre-requisites

When a required external tool is missing, the skill should inform the user and stop — not crash with an unhandled error.

**Pattern:**

```markdown
## Pre-requisites

- gh CLI: !`which gh 2>/dev/null || echo "not installed"`
- jq: !`which jq 2>/dev/null || echo "not installed"`

If any of the above read `not installed` (or are empty), inform the user which tool is missing and stop.
```

The Pre-requisites section runs before any substantive steps. If a required tool isn't found, the skill tells the user
what to install rather than failing partway through execution.

## Summary Checklist

1. Never hardcode branch names — use `origin/HEAD`, or inject the default branch with
   `git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown`
2. Use `which {command} 2>/dev/null || echo "not installed"` for tool availability checks, not `{command} --version`
3. Discover project structure with `find` — don't assume paths exist
4. Gate execution on Pre-requisites and handle empty output gracefully

Cross-reference: [Context Injection Commands](./context-injection-commands.md) for command syntax rules and the `find`
vs `ls` guidance.

---
paths:
  - "**/skills/**/*.md"
  - "**/skills/**/scripts/**"
---

# Graceful Degradation

## Contents

- The Rules
- Rule: Detect environment state with a script, then branch to a named mode
- Rule: Apply conventional defaults for directory keys when config is absent
- Summary Checklist

**Differentiation from `dynamic-project-discovery.md`:** That doc covers hard prerequisites — tools or capabilities the
skill cannot function without at all; when they're missing, the skill stops with a message to the user. This doc covers
_partial context_ — situations where the environment is usable but some data (a git history, project config, docs
directory) is absent. Graceful degradation means detecting what is available, selecting a named execution mode, and
continuing to produce useful output.

## The Rules

### Rule: Detect environment state with a script, then branch to a named mode

Without this rule, skills that assume git is always present hard-fail when invoked on new codebases, local files, or
non-git directories. The user sees an error exit instead of a useful result.

Use a shell script to detect git availability and environment state. The script emits structured `key: value` pairs and
exits 0 in all code paths. The skill reads the output and routes to a named mode based on what is available.

**Detection script requirements:**

- Must exit 0 in all cases — not just the success path
- Use `command -v git` to check for git availability, not `git --version`
- Emit structured key-value output that the skill can parse

**Named mode pattern:**

Define modes explicitly by name so the skill body and review output can reference them clearly:

- **Mode A: Full context** — all expected tools and data are available; use the richest analysis path
- **Mode B: Partial context** — the tool is available but the expected data state is absent (e.g., git is installed but
  no branch changes exist); adapt scope accordingly
- **Mode C: Minimal context** — the tool is absent or no structured data is available; fall back to user-specified or
  discovered inputs

**Before (broken outside git):**

```markdown
## Step 1: Identify Changes

Run `git diff origin/HEAD...HEAD` to get the list of changed files.
```

This fails with an error if the skill is invoked outside a git repository, stopping the workflow entirely.

**After (mode-branching):**

```markdown
## Step 1: Identify Changes

Run `${CLAUDE_SKILL_DIR}/scripts/detect-review-context.sh` to detect the git environment. Use the output to determine
the review mode.

**Mode A: Full git context** — script reports `git-available: true` and changed files list has content.

- Use the changed files list as review scope; run `git diff {default-branch}...HEAD` for the full diff.

**Mode B: Git but no branch changes** — script reports `git-available: true` but `changed-files: none`.

- Check unstaged and staged changes; use those files as review scope.

**Mode C: No git / no changes found**

- Use user-provided file paths or discover source files with Glob.
```

The detection script (`detect-review-context.sh` here) lives in the skill's `scripts/` directory; the SKILL.md body
reads its structured output and routes to the named mode.

---

### Rule: Apply conventional defaults for directory keys when config is absent

When a skill needs project config (docs directory, ADR directory, etc.), it reads CLAUDE.md's `## Project Discovery`
section and falls back to project-discovery.md. For directory keys not found in either source, check conventional
defaults with Glob — but only use the default if the directory actually exists.

**Conventional defaults (use only if directory exists):**

- docs directory -> `docs/`
- ADR directory -> `docs/adr/`
- coding standards directory -> `docs/coding-standards/`

**Keys with no sensible default (skip if absent):**

- test command, lint command, build command
- language, framework
- non-standard paths

Skills discover config inline (context injection + Read) rather than calling a data-fetch sub-skill. This avoids the
early-exit failure mode documented in `writing-effective-instructions.md`.

---

## Summary Checklist

1. Use a shell script for environment detection — not inline shell commands in the skill body
2. Detection script exits 0 in all code paths (git not installed, not in a work tree, normal operation)
3. Name execution modes explicitly (Mode A, Mode B, Mode C) and route to them by name
4. Apply conventional defaults for well-known directory keys when the directory exists on disk
5. Skip keys with no sensible conventional default (commands, language, framework) when absent

---

Cross-references:

- [Dynamic Project Discovery](./dynamic-project-discovery.md) — Hard prerequisites: detect tool absence and stop with a
  message
- [Skill Composition](./skill-composition.md) — `context: fork` for data-fetch sub-skills
- [Script Execution Instructions](./script-execution-instructions.md) — How to invoke detection scripts from SKILL.md
- [Graceful Degradation (agents)](../agent-building-guidelines/graceful-degradation.md) — Agent-side skip patterns when
  tools are unavailable

---
paths:
  - "**/skills/**/*.md"
---

# Hardening: Fuzzy vs. Deterministic Steps

Other guidance docs tell you to extract deterministic operations to scripts
([Progressive Disclosure](./progressive-disclosure.md),
[Writing Effective Instructions](./writing-effective-instructions.md)). This doc provides the decision framework for
recognizing which steps are candidates and classifying them correctly.

The core insight: LLMs excel at fuzzy reasoning (summarization, classification, judgment calls) but introduce
unnecessary unreliability when used for mechanical operations that have one correct answer. Separating these concerns —
keeping fuzzy steps as SKILL.md instructions and extracting deterministic steps to scripts — makes skills more reliable
without reducing their capabilities.

## The Fuzzy-Deterministic Spectrum

Every step in a skill falls somewhere on this spectrum:

### Fuzzy Steps

Require judgment, context, creativity, or interpretation. The "right answer" depends on circumstances and there are
multiple acceptable outputs.

**Examples:** Analyzing code for quality issues, summarizing findings, choosing an investigation strategy, classifying
severity, writing documentation prose.

**Where they belong:** SKILL.md instructions. These are what the LLM is good at.

### Deterministic Steps

Have one correct output for a given input. Can be validated mechanically. Correctness matters more than flexibility.

**Examples:** Constructing JSON payloads, making API calls with specific parameters, validating file formats, running
git commands with exact flags, escaping strings, computing checksums.

**Where they belong:** Shell scripts in `scripts/`. See
[Script Execution Instructions](./script-execution-instructions.md) for the invocation pattern.

### Hybrid Steps

Require judgment to decide _what_ to do, then mechanical execution to _do it_. Split these into two sub-steps: the fuzzy
decision stays in SKILL.md, the mechanical execution moves to a script.

**Example:** A code review skill that decides which findings to include (fuzzy) and then constructs a structured JSON
review payload (deterministic). The decision stays in SKILL.md; the JSON construction moves to a script.

## Recognition Signals

These patterns in SKILL.md instructions suggest a step should be hardened:

- **Precise prose for mechanical work** — You're writing careful, exact language instructions for something that has an
  unambiguous correct output. If the instruction reads like pseudocode, it should probably be actual code.
- **"Make sure to" and "Don't forget to"** — These phrases in the context of a mechanical operation signal that the
  operation is error-prone when done via language instructions. Scripts don't forget.
- **String manipulation instructions** — Escaping, formatting, encoding, templating. These are classic sources of
  intermittent failures when left to language interpretation.
- **API call construction** — Specific endpoints, headers, authentication patterns, request body formats. One wrong
  field and the call fails.
- **File format requirements** — YAML frontmatter construction, JSON schema compliance, CSV formatting. Format
  correctness is binary, not fuzzy.

## The Hardening Process

1. **Identify** a step that matches the recognition signals above
2. **Classify** it as deterministic or hybrid using the spectrum
3. **Write the script** — extract the mechanical logic into a shell script in `scripts/`
4. **Update SKILL.md** — replace the prose instructions with a script invocation step (see
   [Script Execution Instructions](./script-execution-instructions.md) for the correct pattern)
5. **Test** — verify the script produces the same output that Claude was generating via language instructions,
   consistently

## When NOT to Harden

- **The workflow is still in flux** — don't build production scripts for steps that may change next iteration. Harden
  after the workflow stabilizes.
- **The step genuinely requires judgment** — summarization, analysis, classification, and creative work should stay as
  SKILL.md instructions even if you wish they were more consistent.
- **The step runs once and is trivial** — a single `git branch --show-current` call doesn't need a wrapper script. Use
  context injection (`` !`command` ``) for simple runtime data.

## Summary Checklist

1. Classify every step as fuzzy, deterministic, or hybrid
2. Keep fuzzy steps as SKILL.md instructions
3. Extract deterministic steps to `scripts/`
4. Split hybrid steps: fuzzy decision in SKILL.md, mechanical execution in script
5. Watch for recognition signals: precise prose for mechanical work, "make sure to" phrases, string manipulation, API
   construction, format requirements
6. Don't harden prematurely — wait for the workflow to stabilize

Cross-references:

- [Script Execution Instructions](./script-execution-instructions.md) — How to invoke scripts from SKILL.md
- [Progressive Disclosure](./progressive-disclosure.md) — Where scripts live in the three-level architecture (Rule: Use
  scripts/ for deterministic operations)
- [Writing Effective Instructions](./writing-effective-instructions.md) — Rule: Use scripts for deterministic validation

---
paths:
  - "**/skills/**/*.md"
---

# Naming Conventions

## Contents

- The Rules
- Rule: Plugin directory name must match the `name` field in `plugin.json`
- Rule: Never put a `.` in a plugin name
- Rule: Skill directory names should indicate external dependencies
- Rule: Avoid skill names that imply the wrong artifact type
- Rule: Skill `name` in frontmatter matches the directory name
- Rule: No README.md inside skill folders
- Rule: SKILL.md is case-sensitive
- Summary Checklist

Consistent naming across plugins, skills, and directories helps users discover and understand what a skill does from its
name alone.

## The Rules

### Rule: Plugin directory name must match the `name` field in `plugin.json`

The directory containing the plugin must match the `name` field in its `.claude-plugin/plugin.json`.

**Before (mismatched):**

```
research-and-development/
  .claude-plugin/
    plugin.json    # { "name": "example-plugin", ... }
```

The directory was `research-and-development/` but the plugin name was `example-plugin`.

**After (matched):**

```
example-plugin/
  .claude-plugin/
    plugin.json    # { "name": "example-plugin", ... }
```

Rename the directory to match the plugin name.

### Rule: Never put a `.` in a plugin name

Plugin names are kebab-case identifiers: lowercase letters, numbers, and hyphens only. Do not use a dot (`.`) as a
separator, even though it reads naturally as a family namespace (`acme.core`). A dot breaks Codex entirely and Claude
Code partially, because the plugin name doubles as the namespace prefix on its skills and agents. Use a hyphen instead
(`acme-core`). The full rationale and the rename checklist live in
[Plugin Naming](../claude-marketplace-and-plugin-configuration/plugin-naming.md).

### Rule: Skill directory names should indicate external dependencies

If a skill requires an external tool or service (GitHub CLI, Slack, Jira, etc.), prefix the skill directory name with
the tool name so users can predict the dependency from the name alone.

**Before (generic):**

```
skills/
  pr-review/       # Requires gh CLI — not obvious from name
  pr-description/  # Requires gh CLI — not obvious from name
```

**After (dependency-prefixed):**

```
skills/
  gh-pr-review/       # Clearly requires gh CLI
  update-pr-description/  # Clearly requires gh CLI
```

Rename to clarify the GitHub dependency.

### Rule: Avoid skill names that imply the wrong artifact type

Without this rule, skill names using implementation verbs create expectations about what kind of artifact the skill
produces. When the actual output differs, users avoid the skill (thinking it does something they don't want) and Claude
may generate the wrong output type.

Consider a skill named `write-tests`. That name implies the skill produces runnable test code, when it actually produces
a test plan document. Renaming it to `automated-test-planning` names the process/activity rather than an implementation
action, so users and Claude both predict the right output type.

**Before (`write-tests` — implies executable test code):**

```
skills/
  write-tests/      # Users wanting test analysis may avoid it; Claude may generate code instead of plans
```

**After (`automated-test-planning` — names the process unambiguously):**

```
skills/
  automated-test-planning/    # Names the activity; the artifact (a test plan) is implied without suggesting runnable code
```

Prefer gerund process names (`automated-test-planning`, `iterative-plan-review`) over implementation verbs (`write-tests`,
`generate-docs`) when the skill produces analysis, plans, or documentation rather than runnable artifacts. This matches
Anthropic's general naming recommendation: gerund form (`processing-pdfs`, `analyzing-spreadsheets`) is the preferred
convention, with noun phrases (`pdf-processing`) and action forms (`process-pdfs`) acceptable alternatives. Avoid vague
names like `helper`, `utils`, `tools`, or `data`. See
[Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).

**Heuristic:** "If someone reads only this directory name, could they mistake what type of artifact the skill produces?"

### Rule: Skill `name` in frontmatter matches the directory name

The `name` field in the SKILL.md frontmatter must match the skill's directory name.

```
skills/
  post-code-review-to-pr/
    SKILL.md       # name: "post-code-review-to-pr"
```

This ensures the skill is invoked with the same name the user sees in the file system.

In Claude Code the **directory name is what produces the slash command**, and the frontmatter `name` is the display
label shown in skill listings. The one exception is a plugin-root `SKILL.md` (a skill defined at the plugin root rather
than under `skills/{name}/`), where `name` does set the command because there is no directory to derive it from. Keeping
the two equal, as this rule requires, means the distinction never bites. The open standard also requires `name` to match
the parent directory: lowercase letters, numbers, and hyphens, max 64 characters, no reserved words (`claude`,
`anthropic`).

### Rule: No README.md inside skill folders

Do not include a `README.md` inside a skill directory. All skill documentation belongs in `SKILL.md` (for instructions
and process steps) or `references/` (for domain knowledge, templates, and checklists). A `README.md` in the skill folder
creates ambiguity about where documentation lives and is not loaded by the plugin system.

**Before (wrong):**

```
skills/
  code-review/
    SKILL.md
    README.md        # Not loaded by plugin system, creates confusion
    references/
      checklist.md
```

**After (correct):**

```
skills/
  code-review/
    SKILL.md           # All skill documentation here
    references/
      checklist.md     # Domain knowledge here
```

Note: Repository-level README files (at the repo root or plugin root) are fine — this rule applies only to skill
directories. When distributing via GitHub, use a repo-level README for human visitors.

### Rule: SKILL.md is case-sensitive

The skill definition file must be named exactly `SKILL.md` — uppercase `SKILL`, lowercase `.md`. No variations are
accepted. The plugin system will not recognize other casings.

**Rejected names:**

```
skill.md       # Wrong: lowercase "skill"
SKILL.MD       # Wrong: uppercase ".MD"
Skill.md       # Wrong: mixed case
skill.MD       # Wrong: both wrong
```

**Accepted:**

```
SKILL.md       # Exactly this, nothing else
```

## Summary Checklist

1. Plugin directory name matches `name` in `plugin.json`, and that name never contains a `.` (kebab-case only; a dot
   breaks Codex and Claude Code)
2. Skill directory names indicate external tool dependencies (e.g., `gh-` prefix for GitHub CLI)
3. Skill `name` in SKILL.md frontmatter matches the directory name
4. No `README.md` inside skill folders — use `SKILL.md` and `references/` instead
5. Skill definition file must be exactly `SKILL.md` (case-sensitive)
6. Avoid skill names using implementation verbs that imply the wrong output type — prefer gerund process names for
   analysis/planning skills (e.g., `automated-test-planning` not `write-tests`)

---
paths:
  - "**/skills/**/*.md"
---

# Optional Git Repositories

Skills that analyze code should treat git as optional. Hard-requiring git breaks skills in common, legitimate scenarios
— and the moments when git is _not_ fully set up are often the most valuable times to run an analysis skill.

## Why Git Should Be Optional

**Hard-requiring git breaks valid use cases:**

- Fresh checkouts with no remote configured (`origin/HEAD` does not exist)
- Detached HEAD states (CI environments, `git checkout <sha>`)
- Non-git project directories (scripts, notebooks, local experiments)
- Users who want to analyze specific files without regard to branch history

**Uncommitted changes are the most valuable analysis target.** Code exists locally before it is committed. The user most
wants guidance _now_, while they can still act on it easily, not after pushing. A skill that requires committed changes
forces the user to commit first — inverting the natural workflow.

**Untracked files are real in-progress work.** New files not yet staged are part of the same logical change. Excluding
them produces an incomplete picture of what the user is actually working on.

**Making git optional maximizes when a skill is useful** without forcing users to commit, stage, or push work before
they can benefit from it.

## Three Git Execution Modes

Every analysis skill should recognize three distinct execution modes:

| Mode                            | Condition                                                    | Scope source                                                                            |
| ------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| **Mode A: Full git**            | git available, remote exists, branch has committed changes   | `git diff {default-branch}...HEAD`                                                      |
| **Mode B: Uncommitted changes** | git available, but no committed branch diff                  | `git diff` (unstaged) + `git diff --cached` (staged) + `git status --short` (untracked) |
| **Mode C: No git / no changes** | git missing, not in a repo, or no changes found in any state | User-provided paths, or Glob discovery with confirmation                                |

### Why Mode B Specifically Matters

Without Mode B, a skill invoked in a git repo with uncommitted work falls through to Mode C and asks the user to confirm
scope — even though the changes are fully detectable. This is unnecessary friction that makes the skill feel broken in a
common workflow state.

Mode B recovers uncommitted and untracked files automatically. The user gets the same seamless experience as Mode A,
just scoped to their local working state rather than their branch history.

## Priority Rule: User-Provided Arguments Always Win

If the user supplies file paths, directories, or a description of what to analyze, use those as scope **regardless of
which git mode is active**. The git modes exist to provide automatic scope when the user does not supply it. Never
override explicit user input with git-detected scope.

## Detection Architecture

Detection happens in two layers:

**Layer 1 — Detection script** (runs first): Determines whether git is available and whether the current branch has
committed changes against the default branch. Emits structured output with `git-available`, `branch`, `default-branch`,
and either a `changed-files-start`/`changed-files-end` block or `changed-files: none`. This script only distinguishes
Mode A from non-Mode-A; it does not check for uncommitted changes.

**Layer 2 — Skill body** (runs after the script): If the script reports `git-available: true` but `changed-files: none`,
the skill body runs `git diff`, `git diff --cached`, and `git status --short` to check for uncommitted or untracked
work. If any files are found, that is Mode B. If none are found, fall through to Mode C.

See [`graceful-degradation.md`](./graceful-degradation.md) for the detection script pattern and implementation rules,
including a worked example of a detection script in a skill's `scripts/` directory.

---
paths:
  - "**/skills/**/*.md"
---

# Progressive Disclosure

## Contents

- The Rules
- Rule: Skills use three levels of information loading
- Rule: Keep SKILL.md body focused on process steps — extract domain knowledge to references/
- Rule: Frontmatter descriptions must earn every word
- Rule: Use scripts/ for deterministic operations
- Summary Checklist

Skills use a three-level information architecture that balances context availability with token efficiency. Each level
loads only when needed, keeping Claude's context window focused on what matters for the current task.

Understanding this architecture is essential for deciding where content belongs. Process steps go in the SKILL.md body.
Domain knowledge — templates, checklists, rate tables, decision matrices — goes in `references/`. Deterministic
operations go in `scripts/`. Getting this wrong means either bloating the context window with content Claude doesn't
need yet, or hiding critical instructions behind an extra file load.

This architecture matters because SKILL.md content is not passive documentation — it is operational context that
directly calibrates the model's output. Every example in a SKILL.md or reference file becomes a demonstration the model
pattern-matches against. Every instruction competes for the model's finite attention budget. The three levels are not
just an information hierarchy — they are an attention architecture.

## The Rules

### Rule: Skills use three levels of information loading

The three levels control when Claude sees each piece of a skill's content:

**Level 1 — YAML frontmatter (always loaded):** Loaded into Claude's system prompt for every conversation. Claude reads
all skill descriptions to decide which skill to invoke. This level must be concise — every token here is paid in every
conversation, whether the skill triggers or not.

```yaml
---
name: "code-review"
description: >
  Run a full code review on the current git branch's changes against the default branch. Use when reviewing, auditing,
  or checking code quality on local changes before or after pushing. Does not post to GitHub — use
  post-code-review-to-pr to post review comments to a pull request.
allowed-tools: Read, Grep, Glob, Agent, ExitPlanMode
---
```

**Level 2 — SKILL.md body (loaded on trigger):** Loaded only when Claude decides the skill is relevant. Contains the
process steps, context injection commands, and execution logic. Anthropic and the cross-tool Agent Skills standard both
recommend keeping the SKILL.md body under **500 lines**; past that, move detail into `references/`. Treat 500 lines as
the ceiling, not the target.

**The unit of a move is a whole sentence or a whole bullet, never a fragment.** A move that cuts mid-sentence leaves the
SKILL.md stating half an instruction and the reference file opening with the other half, and neither file read alone
says what the step does. This has happened twice in this repository, both times in a commit made to get a skill back
under the ceiling. After a move, read the last line before the cut and the first line after it, in both files.

```markdown
## Project Context

- Current branch: !`git branch --show-current`
- Default branch: !`git symbolic-ref --short refs/remotes/origin/HEAD`

## Step 1: Gather Changes

Read the diff between the current branch and the default branch...
```

**Level 3 — Linked files (loaded on demand):** Files in `references/` and `scripts/` that Claude loads only when a step
explicitly references them. Templates, checklists, style guides, and shell scripts live here. Level 3 is one level, not
a chain: link every reference file directly from SKILL.md, and open any reference file over roughly 100 lines with a
contents list, so a partial read still shows what the file holds. Both rules are in
[Skill Reference Files](./skill-reference-files.md).

```
skills/
  code-review/
    SKILL.md              # Level 2: process steps
    references/
      owasp-top10.md      # Level 3: loaded when review step references it
      review-checklist.md  # Level 3: loaded when checklist step references it
    scripts/
      post-review.sh       # Level 3: executed when posting step calls it
```

### Rule: Keep SKILL.md body focused on process steps — extract domain knowledge to references/

The SKILL.md body should contain the skill's execution logic: numbered steps, context injection, decision points, and
tool usage instructions. Domain knowledge that the skill consults — templates, checklists, rate tables, formulas,
decision matrices — belongs in `references/`.

**When to extract to references/:**

- Templates that define output structure (ADR templates, review templates, PR description templates)
- Checklists that guide evaluation (OWASP checklist, code review checklist, documentation checklist)
- Rate tables, formulas, or scoring matrices (pricing tables, complexity scores, risk assessments)
- Style guides or brand standards (voice guidelines, formatting rules)
- Decision matrices with multiple criteria

**When to keep in SKILL.md:**

- Step-by-step process instructions
- Context injection commands
- Conditional logic ("if X, do Y")
- Tool invocation patterns
- Error handling instructions

**When to remove entirely:**

- Rules already enforced by the toolchain (linters, formatters, CI checks). If a linter catches it, documenting it in
  SKILL.md wastes attention budget and risks contradiction when the linter config changes. Reserve SKILL.md instructions
  for judgment calls — decisions that require context, tradeoffs, or domain knowledge that no automated tool checks.

**Before (restating what the toolchain enforces):**

```markdown
## Step 3: Apply Coding Standards

Ensure all code follows these rules:

- Use single quotes for strings
- Indent with 2 spaces
- No trailing semicolons
- Maximum line length 100 characters
- Use `const` over `let` where possible
```

All five rules are enforced by ESLint and Prettier. Documenting them wastes tokens and will drift when the config
changes.

**After (focusing on judgment calls):**

```markdown
## Step 3: Apply Coding Standards

The linter and formatter handle syntax conventions. Focus on standards that require judgment:

- Error messages must include enough context for debugging (function name, relevant IDs)
- Public API functions must validate input types at the boundary
- Side effects (network calls, file writes) must be explicit in function names
```

**Before (domain knowledge mixed into SKILL.md):**

```markdown
## Step 3: Calculate Value

Use these rates for estimation:

- Junior engineer: $150/hr
- Senior engineer: $250/hr
- Principal engineer: $350/hr

Apply the complexity multiplier:

| Complexity | Multiplier |
| ---------- | ---------- |
| Low        | 1.0x       |
| Medium     | 1.5x       |
| High       | 2.5x       |

Use the formula: (hours × rate) × complexity_multiplier × risk_factor...
```

**After (domain knowledge extracted):**

`references/rate-tables.md`:

```markdown
# Rate Tables and Formulas

## Hourly Rates

- Junior engineer: $150/hr
- Senior engineer: $250/hr
- Principal engineer: $350/hr

## Complexity Multipliers

| Complexity | Multiplier |
| ---------- | ---------- |
| Low        | 1.0x       |
| Medium     | 1.5x       |
| High       | 2.5x       |

## Formula

(hours × rate) × complexity_multiplier × risk_factor
```

`SKILL.md`:

```markdown
## Step 3: Calculate Value

Consult `references/rate-tables.md` for hourly rates, complexity multipliers, and the estimation formula. Apply the
formula to the gathered data.
```

The SKILL.md step is now focused on _what to do_, while the reference file holds _what to know_.

### Rule: Frontmatter descriptions must earn every word

Level 1 content (frontmatter) is loaded into every conversation. A description that wastes tokens on filler — vague
adjectives, redundant phrasing, or information that doesn't improve trigger accuracy — costs tokens across all
conversations without benefit.

**Before (verbose, low-signal):**

```yaml
description: >
  A comprehensive and powerful skill that helps users with various aspects of code review, providing thorough analysis
  and detailed feedback on code quality and best practices.
```

**After (concise, high-signal):**

```yaml
description: >
  Run a full code review on the current git branch's changes against the default branch. Use when reviewing, auditing,
  or checking code quality on local changes before or after pushing. Does not post to GitHub — use
  post-code-review-to-pr to post review comments to a pull request.
```

Every sentence in the "after" version serves a purpose: what it does, when to use it, and what it doesn't do. See
[Skill Description Frontmatter](./skill-description-frontmatter.md) for the full description-writing rules.

### Rule: Use scripts/ for deterministic operations

When a step requires deterministic computation — validation, data transformation, JSON construction, API calls with
specific parameters — extract it to a shell script rather than relying on Claude to interpret language instructions.
Code is deterministic; language interpretation isn't.

**Before (language instruction):**

```markdown
## Step 5: Post Review

Construct a JSON payload with the review body, commit SHA, and event type. POST it to the GitHub API at the
pulls/reviews endpoint. Make sure to properly escape the review body for JSON.
```

**After (script reference):**

```markdown
## Step 5: Post Review

Run `scripts/post-pr-review.sh {owner/repo} {pr_number} {head_sha} {event_type} /tmp/pr-review-body.md` to post the
review to GitHub.
```

The script handles JSON construction, escaping, and API calls — operations where correctness matters more than
flexibility.

## Summary Checklist

1. Level 1 (frontmatter) is always loaded — keep descriptions concise and high-signal
2. Level 2 (SKILL.md body) loads on trigger — focus on process steps and execution logic
3. Level 3 (references/ and scripts/) loads on demand — store domain knowledge, templates, and deterministic operations
   here
4. Extract templates, checklists, rate tables, and decision matrices to `references/`
5. Keep step-by-step process instructions, context injection, and conditional logic in SKILL.md
6. Use `scripts/` for deterministic operations where correctness matters more than flexibility
7. Every token in frontmatter costs context in every conversation — make it count
8. Level 3 files link directly from SKILL.md, and the ones over roughly 100 lines open with a contents list

Cross-references:

- [Skill Frontmatter Fields](./skill-frontmatter-fields.md) — The full inventory of Level 1 frontmatter fields
- [Skill Reference Files](./skill-reference-files.md) — Placement rules for the `references/` directory
- [Skill Description Frontmatter](./skill-description-frontmatter.md) — Rules for writing effective Level 1 descriptions
- [Context Injection Commands](./context-injection-commands.md) — How to inject runtime data into Level 2 content
- [Context Hygiene](./context-hygiene.md) — The scientific rationale behind the three-level architecture

---
paths:
  - "**/skills/**/*.md"
  - "**/skills/**/scripts/**"
---

# Script Execution Instructions in SKILL.md

When a skill needs to run shell scripts during its steps, the SKILL.md body must describe the invocation as numbered
prose instructions — not fenced code blocks.

## The Correct Pattern

Use numbered prose steps with `${CLAUDE_SKILL_DIR}` paths and explicit action verbs:

```markdown
1. Generate a unique temp file path by running `${CLAUDE_SKILL_DIR}/scripts/create-review-tempfile.sh`. Capture the
   output — it is the temp file path.
2. Write the content to the temp file path using the Write tool. Do not use Bash for this step.
3. Post the review by running
   `${CLAUDE_SKILL_DIR}/scripts/post-pr-review.sh {owner/repo} {pr_number} {head_sha} {event_type} {temp_file_path}`.
```

Each step has three elements:

1. **Action verb** — "Generate", "Write", "Post", "Run" — tells Claude what to do
2. **`${CLAUDE_SKILL_DIR}` path** — resolves to the skill's directory at runtime
3. **Explanation of inputs/outputs** — what to capture, where values come from

## Why Fenced Code Blocks Are Wrong

Fenced code blocks with comments as pseudocode are ambiguous:

````markdown
<!-- BAD — do not do this -->

    ```
    # generate a unique temp file path
    scripts/create-review-tempfile.sh

    # write content to the temp file
    # use the Write tool, not Bash

    # post the review
    scripts/post-pr-review.sh {args}
    ```
````

Problems:

- **Ambiguous intent** — Claude may treat a fenced code block as display code (show to user) rather than executable
  instructions (run these commands). Prose with action verbs is unambiguous.
- **Bare relative paths** — `scripts/create-review-tempfile.sh` is relative to the skill directory, but Claude runs
  commands from the user's CWD. The path won't resolve.
- **No action verbs** — Comments like `# generate a temp file` describe what should happen but don't instruct Claude to
  do it. Prose like "Generate a temp file by running..." is a direct instruction.

## How `${CLAUDE_SKILL_DIR}` Works

Claude Code expands `${CLAUDE_SKILL_DIR}` to the absolute path of the skill's directory at runtime. This means
`${CLAUDE_SKILL_DIR}/scripts/my-script.sh` resolves to something like
`/Users/name/.claude/plugins/your-marketplace/your-plugin/skills/post-code-review-to-pr/scripts/my-script.sh`.

Use `${CLAUDE_SKILL_DIR}` for all script paths in the SKILL.md body. Never use bare relative paths like
`scripts/my-script.sh`.

## Why Scripts Should Not Be in `allowed-tools`

`Bash()` patterns in the `allowed-tools` frontmatter are **prefix-based matches**. The pattern
`Bash(scripts/create-review-tempfile.sh)` matches commands that start with `scripts/create-review-tempfile.sh` — but at
runtime, the actual command starts with the expanded `${CLAUDE_SKILL_DIR}` absolute path (e.g.,
`/Users/name/.claude/plugins/.../scripts/create-review-tempfile.sh`). The prefix won't match.

Since script commands can't be reliably auto-approved, omit them from `allowed-tools`. Scripts typically run once per
skill invocation, so a single user approval is acceptable.

## Each Skill Gets Its Own Scripts

Skills must be self-contained. If two skills use the same script, each skill gets its own copy in its own `scripts/`
directory. Do not reference scripts from another skill's directory — this creates a hidden dependency that breaks if the
other skill is modified or removed.

## Summary

| Rule            | Details                                                                         |
| --------------- | ------------------------------------------------------------------------------- |
| Format          | Numbered prose steps with action verbs                                          |
| Paths           | Always use `${CLAUDE_SKILL_DIR}/scripts/...`                                    |
| Code blocks     | Never use fenced code blocks for script execution steps                         |
| `allowed-tools` | Do not list scripts — prefix matching can't resolve `${CLAUDE_SKILL_DIR}` paths |
| Self-contained  | Each skill owns its own scripts; no cross-skill references                      |

---
paths:
  - "**/skills/**/*.md"
---

# Security Restrictions

## Contents

- The Rules
- Rule: No XML angle brackets in frontmatter
- Rule: No "claude" or "anthropic" in skill names
- Rule: Description field max 1024 characters
- Rule: Safe YAML parsing only
- Summary Checklist

Skill frontmatter appears in Claude's system prompt. This privileged position means malicious or malformed frontmatter
could inject instructions into the system prompt, bypass skill boundaries, or cause silent failures. These restrictions
prevent those risks.

## The Rules

### Rule: No XML angle brackets in frontmatter

Do not use `<` or `>` characters anywhere in YAML frontmatter fields. Frontmatter is injected into Claude's system
prompt, where XML tags have special meaning. Angle brackets in frontmatter could be interpreted as system prompt
directives, creating an injection vector.

**Before (dangerous):**

```yaml
---
name: "data-processor"
description: "Processes <xml> data files and converts them to <json> format"
---
```

**After (safe):**

```yaml
---
name: "data-processor"
description: "Processes XML data files and converts them to JSON format"
---
```

This restriction applies to all frontmatter fields — `name`, `description`, `argument-hint`, `allowed-tools`, and any
custom metadata. The SKILL.md body (below the closing `---`) is not affected by this restriction.

### Rule: No "claude" or "anthropic" in skill names

The prefixes "claude" and "anthropic" are reserved. Skills with these terms in their `name` field will be rejected
during upload.

**Before (rejected):**

```yaml
---
name: "claude-helper"
description: "Helps with Claude-related tasks"
---
```

```yaml
---
name: "anthropic-tools"
description: "Tools for working with Anthropic APIs"
---
```

**After (accepted):**

```yaml
---
name: "ai-helper"
description: "Helps with Claude-related tasks"
---
```

This applies to the `name` field only. The `description` field may reference Claude or Anthropic when describing what
the skill does.

### Rule: Description field max 1024 characters

The `description` field has a hard limit of 1024 characters. Descriptions beyond this limit will be truncated or cause
upload failures.

This limit reinforces the progressive disclosure principle — descriptions should be concise triggers, not documentation.
Detailed instructions belong in the SKILL.md body (Level 2) or `references/` (Level 3).

**Before (too long — 1,100+ characters):**

```yaml
description: >
  Run a full code review on the current git branch's changes against the default branch. Use when reviewing, auditing,
  or checking code quality on local changes before or after pushing. Does not post to GitHub — use
  post-code-review-to-pr to post review comments to a pull request. This skill analyzes all changed files, applies the
  OWASP top 10 security checklist, checks for common code smells, evaluates test coverage, reviews documentation
  changes, verifies naming conventions, checks for dependency updates, validates error handling patterns, reviews
  logging practices, and ensures backward compatibility. It produces a structured review document with severity ratings,
  specific line references, and actionable recommendations for each finding. The review covers both the diff itself and
  the broader context of changed files to catch issues that only appear when considering the full file. Additional
  capabilities include performance analysis, accessibility checking, and internationalization review.
```

**After (under 1024 characters):**

```yaml
description: >
  Run a full code review on the current git branch's changes against the default branch. Use when reviewing, auditing,
  or checking code quality on local changes before or after pushing. Does not post to GitHub — use
  post-code-review-to-pr to post review comments to a pull request.
```

Move the detailed capability list to the SKILL.md body where it guides execution rather than competing for system prompt
space.

### Rule: Safe YAML parsing only

Frontmatter is parsed with safe YAML parsing. Features like custom tags, anchors with aliases across documents, or
executable directives are not supported. Stick to standard YAML types: strings, numbers, booleans, lists, and objects.

**Before (unsafe YAML features):**

```yaml
---
name: "my-skill"
description: !!python/object:__main__.inject "malicious"
custom_field: !include /etc/passwd
---
```

**After (standard YAML):**

```yaml
---
name: "my-skill"
description: "Processes data files for analysis"
metadata:
  author: "Team Name"
  version: "1.0.0"
---
```

Custom metadata fields are allowed — `metadata`, `license`, `compatibility` — as long as they use standard YAML types.

## Summary Checklist

1. No `<` or `>` characters in any frontmatter field — XML injection risk
2. No "claude" or "anthropic" in the `name` field — reserved prefixes
3. Keep `description` under 1024 characters — move details to SKILL.md body
4. Use only standard YAML types — no custom tags, executable directives, or unsafe parsing features
5. The SKILL.md body is not subject to frontmatter security restrictions

Cross-references:

- [Skill Description Length](./skill-description-length.md) — The length budget behind the 1024-character target, and
  what gets cut first when a description runs long
- [Skill Description Frontmatter](./skill-description-frontmatter.md) — How to write effective descriptions within the
  1024-character limit
- [Naming Conventions](./naming-conventions.md) — Additional naming rules for skills and plugins

---
paths:
  - "**/skills/**/*.md"
---

# Skill Composition

## Contents

- Orchestration composition (supported, with care)
- Data-fetch composition (avoid)
- The `context: fork` field
- Deciding which way to go

Skills can call other skills through the Skill tool. This is a real, supported capability, and Han uses it in
production. It also has sharp edges. Treat it as a power tool: reach for it deliberately, with the safeguards below, and
only when the alternative is duplicating a whole skill's worth of work.

Two patterns hide under the word "composition," and they behave very differently:

- **Orchestration composition.** A thin calling skill hands the heavy work to a called skill that drives the rest of the
  output, and optionally chains into another skill afterward. **Supported. Use it with the discipline below.**
- **Data-fetch composition.** A skill calls another skill just to retrieve a few values (config paths, a command, a
  setting). **Avoid it. Do discovery inline instead.** The early-exit failure mode this caused is documented below and
  has not been reliably fixed by any frontmatter or instruction tuning. One narrow, separately-tested exception
  (surfacing a whole shared standard inline) is carved out at the end of that section.

Knowing which one you are reaching for is the whole decision. The rest of this document is the guidance for each.

## Orchestration composition (supported, with care)

In orchestration composition the calling skill is a thin coordinator. It validates inputs, then invokes a substantial
sub-skill that owns a whole artifact and drives the remaining output, optionally chaining that result into a second
sub-skill. The calling skill does almost no work of its own.

Han ships two live examples, and they run reliably:

- `han-atlassian:plan-a-feature-to-confluence` validates its inputs, runs `han-planning:plan-a-feature` to a temporary
  folder, gets the user's review and publish choice, then hands every file to `han-atlassian:markdown-to-confluence` to
  publish.
- `han-atlassian:project-documentation-to-confluence` does the same shape with `han-documentation:project-documentation` feeding
  `han-atlassian:markdown-to-confluence`.

These work because they follow a disciplined shape. If you compose skills, match it.

### Keep the orchestrator thin

The calling skill should validate, forward, capture, and report, and almost nothing else. The more logic the
orchestrator carries across a Skill call, the more likely it is to lose track of its own workflow after the sub-skill
returns. A thin orchestrator has little state to lose. Both Atlassian skills open by stating plainly that "the steps
below are the whole skill" and that they do not do the called skill's job themselves. Copy that framing.

### Preflight hard requirements before any expensive sub-skill work

Validate everything that can fail cheaply before you spend a long sub-skill run. The Confluence orchestrators check that
the Atlassian MCP server is reachable as their very first step, so a missing server fails in seconds rather than after a
full planning interview. Put your hard requirements (a connected MCP server, a required destination, a needed input)
ahead of the Skill call, not after it.

### Forward the user's context verbatim

When you invoke the sub-skill, pass the user's request, the `size` argument, known constraints, and the relevant
conversation context through unchanged. Do not summarize, trim, or reinterpret it. The goal is that the sub-skill runs
exactly as it would if the user had invoked it directly. `plan-a-feature-to-confluence` is explicit about this: it
forwards "all provided context verbatim" so the planning skill's interview, review team, and synthesis all run normally.

### Give the sub-skill explicit overrides, not silent assumptions

If the orchestration needs the sub-skill to behave differently in one respect, say so in the invocation. The Confluence
orchestrators tell `plan-a-feature` to write under `/tmp/` rather than into the repo, and not to prompt the user to
choose an output location, because the orchestrator owns that decision. State each override as one explicit instruction
in the Skill call. Do not assume the sub-skill will infer it.

### Capture the sub-skill's exact outputs

After the sub-skill finishes, record the precise paths or values it produced before you move on.
`plan-a-feature-to-confluence` captures the exact `/tmp/` paths of every file written, and accounts for the one
companion artifact that is created only conditionally. The next step depends on those exact outputs, so pin them down
rather than reconstructing them.

### Instruct continuation explicitly after the Skill call

A Skill call mid-workflow is the moment the calling model is most likely to stop, treating the sub-skill's output as its
own final answer. Counter it directly: end the step with an explicit instruction to proceed to the next step. Never rely
on implicit continuation. This is the single most common way an orchestration silently ends early.

### Declare the Skill tool in `allowed-tools`

A skill that invokes another skill must list `Skill` in its `allowed-tools` frontmatter (both Atlassian orchestrators
do). Without it the Skill call is not permitted.

## Data-fetch composition (avoid)

Data-fetch composition is calling a sub-skill only to retrieve a few structured values (a docs directory, a test
command, a config setting) for the calling skill to use immediately. **Do not do this.** Discover the values inline
instead.

The failure mode is concrete and has been observed repeatedly. A forked data-fetch sub-skill (`context: fork`) returns
its values, and then an `api_retry` event can fire and anchor the calling model on the sub-skill's output as if it were
the final answer, bypassing every remaining workflow step. Adding explicit "proceed immediately, do not stop here"
wording and conventional defaults reduces but does not reliably eliminate it. The same shared config-reading sub-skill
broke multiple calling skills this way. The early-exit risk is not worth the small amount of discovery logic it saves.

### Prefer inline discovery

Instead of a data-fetch sub-skill, handle discovery and retrieval inside the skill's own steps:

1. Use context injection to detect config files (CLAUDE.md, project-discovery.md).
2. Read the file directly and extract the values you need in your own step logic.
3. Fall back to conventional defaults when a value is not found.

This eliminates the forked sub-skill entirely, and with it the `api_retry` interaction and the early-exit risk. See
[Writing Effective Instructions](./writing-effective-instructions.md) for a before/after example.

### Duplicate small discovery logic rather than sharing it through a skill

If two skills both need to find the docs directory, duplicate that handful of lines in each. A small amount of
duplicated discovery logic is far more reliable than a shared data-fetch sub-skill. Reserve composition for
orchestration, where a whole substantial workflow, not a few values, is what you would otherwise be duplicating.

### The one exception: surfacing a shared standard inline

There is a single shape that looks like data-fetch but is supported, because it was validated on its own rather than
assumed: an **inline** sub-skill that surfaces a shared _standard or reference set_ into the caller's context and then
hands control straight back for the caller to apply. The motivating case is a guidance skill that reads one canonical
copy of a writing or review standard and surfaces it into whichever skill is about to produce output, so the standard
lives in one place instead of being vendored into every plugin that needs it.

Three properties separate this from the data-fetch pattern you should avoid:

1. **It is inline, never `context: fork`.** The documented early-exit failure is fork-specific: a forked sub-skill
   returns a value, an `api_retry` fires, and the caller anchors on that value as its final answer. An inline sub-skill
   renders into the shared context and never returns a value to anchor on. A dedicated spike ran a heavy consumer skill
   through an inline guidance skill many times, including a worst-case run with every continuation guardrail removed and
   a deliberately final-sounding closing line, and the caller resumed and finished every time with no early exit. The
   forked variant of the same skill was disqualified for a separate reason: the fork isolated the guidance so its
   content never reached the caller.
2. **It surfaces a whole standard, not a few values.** Retrieving a docs directory or a test command is still
   data-fetch; do that inline (above). This exception is for surfacing a substantial shared reference that would
   otherwise be duplicated into every consumer, which is closer to orchestration's "duplicating a whole skill's worth of
   work" test than to fetching a setting.
3. **The caller still owns and finishes its own workflow.** The sub-skill adds content to the context and returns; it
   does not produce the caller's deliverable. Keep an explicit "proceed to the next step" instruction after the
   invocation as cheap insurance, even though the spike completed without it.

One honest limit on that evidence: the spike could not induce a real `api_retry`, which is the specific trigger of the
forked failure. The worst-case run removed the mitigation `api_retry` is said to defeat and still held, so treat this
exception as reliable under adversarial same-context testing, not as proof the failure can never occur. If you reach for
it, keep the sub-skill inline, keep the continuation instruction, and use it only for a genuinely shared standard.

## The `context: fork` field

`context: fork` is a documented Claude Code feature (see the
[Skills documentation](https://code.claude.com/docs/en/skills) and the field inventory in
[Skill Frontmatter Fields](./skill-frontmatter-fields.md)). The guidance here is not that the field is unsupported. It
is that you should not lean on it for data-fetch sub-skills, because the early-exit failure above shows up repeatedly in
that pattern. Treat avoiding it for data-fetch as a considered choice, not an oversight.

## Deciding which way to go

Ask what you would be duplicating if you did not compose:

- **A whole user-facing workflow that owns an artifact** (a planning run, a documentation pass, a publish step):
  compose, using the orchestration discipline above. Duplicating an entire skill is worse than the cost of a careful
  Skill call.
- **A few values** (paths, commands, settings): stay inline. Duplicate the small discovery logic. Do not reach for a
  sub-skill.
- **A whole shared standard or reference set** that every consumer would otherwise vendor a copy of: an inline sub-skill
  may surface it into the caller's context, under the narrow exception above. Keep it inline (never `context: fork`) and
  keep an explicit continuation instruction after the call.

Cross-references:

- [Skill Decomposition](./skill-decomposition.md). When to split skills.
- [Writing Effective Instructions](./writing-effective-instructions.md). Instruction clarity and the inline-discovery
  before/after.
- [Skill Frontmatter Fields](./skill-frontmatter-fields.md). The `context` field and `allowed-tools`.

---
paths:
  - "**/skills/**/*.md"
---

# Skill Decomposition

## Contents

- The Rules
- Composition Patterns
- Summary Checklist

A skill should do one thing well. When a skill handles too many responsibilities, it becomes fragile, hard to debug, and
difficult for the LLM to follow consistently. Split monolithic skills into focused units and extract reusable agent
definitions.

## The Rules

### Rule: Single responsibility, one skill, one concern

A skill should address a single concern. If a skill does both analysis and integration, or both gathering and posting,
it's doing too much.

**Before (monolithic):** Picture a `pr-review` skill that performs the full code review AND posts it to GitHub. Two
fundamentally different concerns:

- **Analysis.** Reading code, applying a checklist, generating findings.
- **Integration.** Calling the GitHub API, handling JSON encoding, managing auth.

Bundling them means a bug in the GitHub posting logic requires debugging the entire review skill, and the code review
logic can't be reused without GitHub.

**After (decomposed):** Split into two skills:

- A review skill. The review itself (analysis only, no GitHub dependency).
- A GitHub-integration skill that runs the review skill, then posts results.

The review logic is now reusable. GitHub bugs are isolated to the integration skill.

### Rule: When to split a skill

Split when:

- The skill has **independent concerns** (analysis vs. integration, gathering vs. posting).
- **A bug in one part** requires debugging unrelated parts.
- **One part is reusable** without the other (for example, code review without GitHub).
- The skill prompt is **so long** the LLM struggles to follow it consistently.

Keep together when:

- The steps are sequential and tightly coupled.
- Splitting would create skills that can't function independently.
- The skill is short and focused even with multiple steps.

### Rule: Extract large inline agent definitions

If a skill contains large blocks of agent instructions inline in the SKILL.md, extract them into standalone agent files
under `agents/`.

**Before (inline agents):** Picture an investigation skill that contains full agent definitions for an investigator
agent and a validator agent inline in SKILL.md. Hundreds of lines of protocols mixed with the skill's own steps.

**After (extracted):** Extract the agents into standalone agent files:

- `agents/evidence-based-investigator.md`
- `agents/adversarial-validator.md`

The skill now references these agents via the `Agent` tool rather than duplicating their definitions inline. The same
move applies when a documentation skill carries explorer and content-audit logic inline: extract each into its own file
under `agents/`.

## Composition Patterns

### Skills calling skills

Use the `Skill` tool to compose skills. The calling skill orchestrates while the called skill executes its single
responsibility.

Two composition patterns exist with different requirements:

- **Orchestration.** Delegating a self-contained task (for example, a PR-posting skill running a review skill). Works
  inline.
- **Data-fetch.** Retrieving specific values for immediate use. Prefer inline discovery (context injection + Read) over
  forked sub-skill calls to avoid early-exit failures. See `writing-effective-instructions.md` for details.

See [Skill Composition](./skill-composition.md) for the full pattern.

```markdown
## Step 3: Run Code Review

Use the `Skill` tool to run the code-review skill on the current branch.
```

Add `Skill` to the calling skill's `allowed-tools`:

```yaml
allowed-tools: Bash(gh *), Read, Grep, Glob, Skill, ExitPlanMode
```

### Skills referencing agents

Use the `Agent` tool to dispatch extracted agent definitions for specialized subtasks.

```markdown
## Step 2: Investigate

Use the `Agent` tool with `example-plugin:evidence-based-investigator` to gather evidence.
```

Add `Agent` to the skill's `allowed-tools`:

```yaml
allowed-tools: Read, Grep, Glob, Agent, EnterPlanMode, ExitPlanMode
```

## Summary Checklist

1. One skill, one concern. Split skills with independent responsibilities.
2. Extract large inline agent definitions to `agents/` files.
3. Use the `Skill` tool to compose skills together.
4. Use the `Agent` tool to dispatch extracted agent definitions.
5. Only split when the parts can function independently.

Cross-references:

- [External File References in Agent Definitions](../agent-building-guidelines/agent-external-files.md). Agent file
  structure constraints.
- [Skill Composition](./skill-composition.md). Orchestration vs data-fetch composition patterns.
- [Agent Dispatch Namespacing](./agent-dispatch-namespacing.md). Name a dispatched agent `your-plugin:agent-name`.

---
paths:
  - "**/skills/**/*.md"
---

# Skill Description Frontmatter

## Contents

- How Description Matching Works
- The Rules
- Common Pitfalls
- Summary Checklist

The `description` field in SKILL.md frontmatter is the primary mechanism Claude uses to decide when to invoke a skill.
Every installed skill's description is always loaded into Claude's context, where descriptions compete against each
other for selection. A thin description means missed triggers — users ask for something the skill handles, but Claude
doesn't recognize the match. An overbroad description means false triggers — Claude invokes the wrong skill because
descriptions overlap without clear boundaries.

## How Description Matching Works

Three facts shape how descriptions should be written:

1. **Descriptions compete with each other.** When a user makes a request, Claude evaluates all loaded skill descriptions
   simultaneously. A skill with a vague one-liner loses to a sibling skill that explicitly names the user's intent.

2. **Semantic matching has limits.** Claude can infer related concepts, but common trigger words must appear explicitly.
   Don't assume Claude will connect "debug" to "investigate" or "PR" to "pull request" without those words appearing in
   the description. If users commonly phrase their request a certain way, that phrasing should be in the description.

3. **Context window cost is real.** Descriptions are always loaded, so they consume tokens in every conversation. Be
   thorough but not verbose — every sentence should earn its place by improving trigger accuracy or disambiguation.

## The Rules

### Rule: Every description must cover four components

A complete description answers four questions:

- **What** — What does this skill do?
- **When to use** — What user intents or situations should trigger it?
- **Boundary** — What should NOT trigger it? (When to use a different skill or no skill at all.)
- **Trigger breadth** — What alternative phrasings, synonyms, or related concepts should also match?

Minimum 3 sentences. Typically 3-5 sentences. Skills in crowded spaces (multiple similar skills in the same plugin) may
need more to disambiguate.

**Before (1 sentence, `code-review`):**

```yaml
description: Run a full code review on the current git branch's changes
```

Missing when-to-use triggers, no boundary distinguishing it from `post-code-review-to-pr`, no trigger breadth.

**After (3 sentences):**

```yaml
description: >
  Run a full code review on the current git branch's changes against the default branch. Use when reviewing, auditing,
  or checking code quality on local changes before or after pushing. Does not post to GitHub — use
  post-code-review-to-pr to post review comments to a pull request.
```

**Before (1 sentence, `update-pr-description`):**

```yaml
description: Generate a PR description from the current branch's changes against a GitHub PR, using the gh CLI
```

**After (4 sentences):**

```yaml
description: >
  Generate a PR description from the current branch's changes against a GitHub PR, using the gh CLI. Use when writing,
  drafting, or updating pull request descriptions, PR summaries, or PR bodies. Requires the gh CLI to be installed and a
  PR to already exist for the current branch. Does not review code or post review comments — use code-review for local
  review or post-code-review-to-pr for posting a review to GitHub.
```

### Rule: Write descriptions in the third person

Describe what the skill does, not what you or the user can do with it. Anthropic's
[skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) make
this an explicit rule: write "Processes Excel files and extracts pivot tables," not "I can help you with spreadsheets"
or "Use me to handle your data." Third-person, capability-first phrasing reads as a stable description of the skill
rather than a conversational offer, and it matches how every other description in the listing is phrased.

Anthropic separately notes that tool and skill descriptions deserve as much care as the system prompt itself
([Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)) — the
`description` field is not boilerplate, it is the interface Claude routes against.

### Rule: Weave trigger words into prose — never append keyword lists

Include the words users actually type — synonyms, abbreviations, and common phrasings — but weave them into natural
sentences that provide semantic context. Never append a bare keyword list. Keyword lists lack context, making it harder
for Claude to judge relevance, and they waste tokens without improving accuracy.

**Before (keyword suffix, `writing-style`):**

```yaml
description:
  Apply your team's brand voice and writing standards when drafting, editing, or revising marketing content, thought
  leadership pieces, and practitioner-led content. Keywords - draft, edit, write, rewrite, summarize, revise, outline.
```

**After (woven prose):**

```yaml
description: >
  Apply your team's brand voice and writing standards when drafting, editing, revising, rewriting, summarizing, or
  outlining marketing content, thought leadership pieces, and practitioner-led content. Use when writing or polishing
  any content that should follow your team's style guide. Does not handle brand positioning or messaging framework, use
  brand-messaging for ICP, positioning, and campaign tone.
```

The trigger words ("draft," "edit," "rewrite," "summarize," "outline") are still present but embedded in a sentence that
tells Claude what they mean in context.

### Rule: Define boundaries by naming sibling skills or scope limits

When sibling skills exist in the same plugin, name them explicitly in the boundary statement. When no siblings exist,
describe the scope limit so Claude knows where the skill stops.

Disambiguation must work in **both directions**. If `code-review` says "use `post-code-review-to-pr` for GitHub
posting," then `post-code-review-to-pr` must also say "use `code-review` for local review without GitHub." One-way
disambiguation leaves a gap that Claude can fall through.

**Commonly confused skill pairs and their boundary statements:**

| Skill A                   | Skill B                         | How to disambiguate                             |
| ------------------------- | ------------------------------- | ----------------------------------------------- |
| `code-review`             | `post-code-review-to-pr`        | Local analysis vs. GitHub integration           |
| `update-pr-description`   | `post-code-review-to-pr`        | PR body/summary vs. review comments             |
| `project-documentation`   | `architectural-decision-record` | Feature/system docs vs. architectural decisions |
| `project-documentation`   | `coding-standard`               | Feature/system docs vs. coding standards        |
| `coding-standard`         | `architectural-decision-record` | Enforceable rules vs. decision records          |
| `project-discovery`       | `project-documentation`         | Tech stack scanning vs. feature/system docs     |
| `automated-test-planning` | `code-review`                   | Test coverage plans vs. code quality review     |
| `automated-test-planning` | `manual-test-planning`          | Coverage-gap analysis vs. hand-run test steps   |
| `automated-test-planning` | `iterative-plan-review`         | Test plans vs. refining work plans              |
| `brand-messaging`         | `writing-style`                 | Positioning/ICP/campaigns vs. prose style/voice |

**Before (no boundary, `project-documentation`):**

```yaml
description: >
  Creates and maintains project documentation for features, systems, and components. Discovers project structure
  dynamically to work across any technology stack.
```

**After (names siblings):**

```yaml
description: >
  Creates and maintains project documentation for features, systems, and components. Discovers project structure
  dynamically to work across any technology stack. Use when documenting how a feature, system, or component works. Does
  not create architectural decision records — use architectural-decision-record for ADRs. Does not create or update
  coding standards — use coding-standard instead. Does not generate PR descriptions — use update-pr-description for
  that.
```

### Rule: Mention external requirements when they affect triggering

If a skill requires external tools (gh CLI, jq), specific preconditions (a PR must already exist), or a particular
environment state, mention these in the description. This helps Claude choose between skills with different
prerequisites — for example, choosing `code-review` (no dependencies) over `post-code-review-to-pr` (requires gh CLI and
an open PR) when the prerequisites aren't met.

**Before:**

```yaml
description:
  Run a full pull request review for code changed in the current branch's GitHub PR, using the gh CLI, and post it to
  the GitHub PR
```

**After:**

```yaml
description: >
  Run a full pull request review and post it to the current branch's GitHub PR. Requires the gh CLI to be installed and
  a PR to already exist for the current branch. Use when you want review comments posted directly to GitHub. For local
  code review without GitHub, use code-review instead.
```

### Rule: Use negative triggers to prevent over-triggering

When a skill keeps activating for queries it shouldn't handle, add explicit negative trigger language to the
description. Tell Claude what the skill does NOT do and which skill to use instead.

**Before (over-triggers on simple data questions):**

```yaml
description: >
  Advanced data analysis for CSV files. Use for statistical modeling, regression analysis, and clustering.
```

**After (negative trigger added):**

```yaml
description: >
  Advanced data analysis for CSV files. Use for statistical modeling, regression analysis, and clustering. Do NOT use
  for simple data exploration or visualization — use data-viz skill instead.
```

Negative triggers are especially useful when:

- Two skills share overlapping trigger words
- Users frequently confuse two skills
- The skill triggers on a broad category but should only handle a narrow subset

### Debugging: Ask Claude when it would use the skill

When a description isn't triggering correctly — either too rarely or too often — ask Claude directly:

> "When would you use the [skill name] skill?"

Claude will quote the description back and explain its understanding. Compare what Claude says against:

- The prompts that should trigger the skill (are they covered?)
- The prompts that should NOT trigger the skill (are boundaries clear?)

This is faster than trial-and-error with test prompts and reveals exactly what's missing from the description.

## Common Pitfalls

| Anti-pattern                          | Problem                                            | Fix                                                          |
| ------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------ |
| Single sentence                       | Missing triggers, no boundary, no breadth          | Add all four components (3+ sentences)                       |
| Keyword suffix (`Keywords - x, y, z`) | No semantic context, wasted tokens                 | Weave trigger words into prose                               |
| No boundary statement                 | False triggers from overlapping skills             | Name sibling skills or scope limits                          |
| One-way disambiguation                | Skill A points to B, but B doesn't point to A      | Add boundary statements in both directions                   |
| Assumed inference                     | Expects Claude to connect "debug" to "investigate" | Include common phrasings explicitly                          |
| Excessive verbosity (7+ sentences)    | Context window bloat, diminishing returns          | Tighten to 3-5 sentences; every sentence must earn its place |

## Summary Checklist

1. Description covers **what** the skill does
2. Description covers **when to use** it (user intents and situations)
3. Description covers **boundaries** (when NOT to use it)
4. Description covers **trigger breadth** (synonyms, alternative phrasings)
5. Minimum 3 sentences; typically 3-5
6. Trigger words are woven into prose, not appended as keyword lists
7. Sibling skills are named explicitly in boundary statements
8. Disambiguation works in both directions between skill pairs
9. External requirements (tools, preconditions) are mentioned when they affect skill selection

Cross-references:

- [Skill Frontmatter Fields](./skill-frontmatter-fields.md) — The full inventory of supported SKILL.md frontmatter
  fields
- [Skill Description Length](./skill-description-length.md) — How long a description may be, and what to cut first when
  it runs over
- [Naming Conventions](./naming-conventions.md) — Plugin and skill naming rules
- [Skill Decomposition](./skill-decomposition.md) — When to split skills that share trigger space
- [Troubleshooting](./troubleshooting.md) — Fixes for triggering problems (doesn't trigger, triggers too often)
- [Context Hygiene](./context-hygiene.md) — Why every frontmatter token carries a context cost

---
paths:
  - "**/skills/**/*.md"
---

# Skill Description Length

## Contents

- The target: keep every description under 1024 characters
- Why 1024, when there are two different limits
- How to measure a description
- What gets cut first: the priority order
- What to do when a description is over the limit
- Common Pitfalls
- Summary Checklist

Every installed skill's `description` is loaded into context in every conversation, and the harness budgets how much of
it Claude actually gets to see. A description that runs too long does not fail loudly — it gets silently truncated or
dropped from the listing, and the skill quietly stops triggering as well as it should. This doc sets the length target
and explains the two separate limits that motivate it.

For _what_ to put in a description (the four components, trigger breadth, boundary statements), see
[Skill Description Frontmatter](./skill-description-frontmatter.md). This doc is only about _how long_ it can be.

## The target: keep every description under 1024 characters

**Write every skill `description` to fit within 1024 characters.** That single number keeps a skill safe on every
surface it can ship to, with headroom to spare. It is not arbitrary — it is the stricter of the two real limits below.

Count the rendered description text, not the YAML around it: the folded `>` block scalar, the `description:` key, and
indentation do not count. What counts is the string Claude receives.

## Why 1024, when there are two different limits

Two separate mechanisms cap a skill description, on two different surfaces. The 1024 target satisfies both at once.

### Limit 1 — claude.ai / cowork upload: a hard 1024-character cap

When a skill is uploaded to claude.ai or used in cowork, the `description` field has a **hard limit of 1024
characters**. Exceed it and the upload is truncated or rejected outright. This is a validation rule, not a suggestion.
See [Security Restrictions](./security-restrictions.md) and
[Cowork-Specific Skill Instructions](./cowork-specific-skill-instructions.md) for the full field-validation rules.

### Limit 2 — Claude Code listing: a 1536-character per-entry cap, then a budget sweep

In Claude Code the relevant setting is `skillListingMaxDescChars`, which **defaults to 1536 characters per
description**. The harness applies it in two passes:

1. **Per-entry cap.** Any single description longer than `skillListingMaxDescChars` (1536 by default) is truncated to
   fit before it reaches Claude. The skill keeps working, but Claude only sees a clipped description, so the trigger
   words and boundary statements past the cut are lost.
2. **Budget sweep.** The whole skill listing is then held to `skillListingBudgetFraction` of the context window (default
   ~1%, roughly 9k tokens). If the combined listing still overflows that budget, the lowest-priority skills lose their
   descriptions _entirely_.

An operator can raise `skillListingMaxDescChars` in `settings.json`, but that is opt-in: it costs more tokens in every
session and burns rate limits faster. A skill that depends on the operator having opted in is a skill that triggers
unreliably for everyone who has not. Author for the default.

### The two limits together

| Surface                       | Limit                           | What happens past it                                          |
| ----------------------------- | ------------------------------- | ------------------------------------------------------------- |
| claude.ai / cowork upload     | 1024 chars (hard)               | Truncated or rejected on upload                               |
| Claude Code listing (default) | 1536 chars per entry            | Truncated in the listing; trigger words past the cut are lost |
| Claude Code listing budget    | ~1% of context for _all_ skills | Lowest-priority skills dropped from the listing entirely      |

Targeting **1024** clears the hard cap on upload, sits comfortably under the 1536 Claude Code per-entry cap with room
for a future edit, and keeps each skill's share of the shared listing budget small so it does not crowd its siblings
out.

## How to measure a description

Count the rendered description string. This snippet reads a SKILL.md, resolves a folded (`>`) or literal (`|`) block
scalar, and prints the character count:

```bash
python3 - "path/to/SKILL.md" <<'EOF'
import re, sys
txt = open(sys.argv[1]).read()
fm = re.search(r'^---\n(.*?)\n---', txt, re.S).group(1)
m = re.search(r'^description:\s*(.*)$', fm, re.M)
rest = m.group(1).strip()
if rest in ('>', '|', '>-', '|-'):
    start = m.end()
    block = []
    for ln in fm[start:].split('\n')[1:]:
        if re.match(r'^\S', ln):
            break
        block.append(ln.strip())
    desc = ' '.join(x for x in block if x)
else:
    desc = rest.strip('"\'')
print(f"{len(desc)} chars")
EOF
```

If the count is over 1024, the description is too long no matter how good the prose is. Tighten it.

## What gets cut first: the priority order

Cutting to fit is not a free choice between equal sentences. The parts of a description carry different value, and there
is a fixed order in which they should go. Cut from the bottom of this ladder up, never from the top down:

1. **Hedges, filler, and restated capability (cut first).** "including requests like", long parenthetical example lists,
   and sentences that restate what the skill does in other words. Cheapest characters to reclaim, zero trigger value
   lost.
2. **Boundary clauses against skills no one would confuse this with.** A "Does not X — use a" clause earns its place
   only when a real request could plausibly hit the wrong skill. Drop the ones that disambiguate against a distant,
   unrelated skill.
3. **Boundary clauses against near siblings (cut last, and reluctantly).** When two skills share trigger space, the
   boundary statement between them is what prevents a misfire. These are the _lowest-priority thing to cut yet the
   highest-cost to lose_ — cut one only when nothing above remains and the description is still over budget, and prefer
   tightening its wording over deleting it.
4. **What the skill does and its primary when-to-use triggers (never cut).** This is the irreducible core. If the
   description cannot fit its what plus its primary triggers under 1024 characters, the problem is that the skill is
   doing too much — see [Skill Decomposition](./skill-decomposition.md) — not that the description needs a smaller font.

The same ladder describes what the harness takes from you if you do not trim yourself. **Claude Code truncation clips
the tail of the string**, so whatever sits at the end of the description is the first thing lost. Order the description
to match the ladder: lead with what and the primary triggers, and place the lower-priority boundary clauses last, where
an over-cap truncation does the least damage. A description that front-loads its boundaries and trails off into its core
triggers loses exactly the wrong half when it gets clipped.

## What to do when a description is over the limit

The fix is never to keep the words and hope the truncation lands somewhere harmless. The fix is to move detail out of
the description and into the body, where there is no budget pressure, then trim what remains in priority order.

- **Move the _how_ to the SKILL.md body.** The description answers what, when, boundary, and trigger breadth. Process
  detail, step lists, and caveats belong in the body (Level 2) or `references/` (Level 3). See
  [Progressive Disclosure](./progressive-disclosure.md).
- **Trim in priority order.** Apply the ladder above: hedges and filler first, distant-sibling boundaries next,
  near-sibling boundaries last. Never sacrifice the what or the primary triggers to save a boundary clause.
- **Re-order so the tail is expendable.** Put the highest-value content first and the most cuttable content last, so
  that if the description is ever clipped at the cap, the loss falls on the lowest-priority part.
- **Re-measure.** Run the snippet again. Triggering quality is set by what survives the cap, so the goal is a
  description that is fully under 1024, not one that merely starts strong.

## Common Pitfalls

| Anti-pattern                                   | Problem                                                               | Fix                                                         |
| ---------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- |
| Description over 1024 chars                    | Rejected on upload; clipped in the Claude Code listing                | Move detail to the body; tighten to under 1024              |
| "It's only over by a little"                   | A later edit pushes it past the cap; truncation already lost the tail | Leave headroom under 1024, do not author right at the limit |
| Relying on a raised `skillListingMaxDescChars` | Triggers unreliably for every operator on the default                 | Author for the 1536 default, target 1024                    |
| Long boundary chain against non-siblings       | Burns characters disambiguating skills no one confuses                | Keep only the boundaries that prevent a real misfire        |
| Measuring the YAML, not the string             | Miscounts the budget that actually applies                            | Count the rendered description text only                    |

## Summary Checklist

1. The rendered `description` is **under 1024 characters**.
2. It is fully under the Claude Code default cap of 1536, with headroom for a future edit.
3. It will survive a claude.ai / cowork upload (hard 1024 cap).
4. Detail beyond what, when, boundary, and trigger breadth lives in the SKILL.md body, not the description.
5. The skill does not depend on an operator raising `skillListingMaxDescChars`.
6. The length was measured against the rendered string, not the YAML.
7. The what and primary triggers lead; lower-priority boundary clauses trail, so a tail-clipping truncation costs the
   least.

Cross-references:

- [Skill Description Frontmatter](./skill-description-frontmatter.md) — What belongs in a description (the four
  components, trigger breadth, boundaries)
- [Security Restrictions](./security-restrictions.md) — The 1024-character hard limit as a frontmatter validation rule
- [Cowork-Specific Skill Instructions](./cowork-specific-skill-instructions.md) — Field-validation rules for the
  claude.ai / cowork upload surface
- [Progressive Disclosure](./progressive-disclosure.md) — Where description detail goes instead (body and references)
- [Context Hygiene](./context-hygiene.md) — Why every always-loaded frontmatter token carries a context cost

---
paths:
  - "**/skills/**/*.md"
---

# Skill Frontmatter Fields

This is the inventory of SKILL.md frontmatter fields Claude Code supports, with one-line semantics for each. A typical
skill uses only a handful of them (`name`, `description`, `allowed-tools`, `paths`, occasionally `argument-hint`), but
the platform supports more. Use this as the reference for what is available; the dedicated docs cover the high-traffic
fields in depth.

The authoritative source is the Claude Code [Skills documentation](https://code.claude.com/docs/en/skills). When this
doc and that page disagree, the official page wins; re-verify before relying on a field's exact behavior.

## Identity and triggering

| Field           | Required    | What it does                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | Recommended | Display label in skill listings. In Claude Code the slash command comes from the skill's directory name, not this field. The one exception is a plugin-root `SKILL.md`, where `name` sets the command. The open standard requires `name` to match the parent directory: lowercase letters, numbers, and hyphens, max 64 characters, no consecutive or leading/trailing hyphens, no reserved words (`claude`, `anthropic`). |
| `description`   | Recommended | The primary trigger signal. Always loaded; Claude reads it to decide when to invoke the skill. Max 1,024 characters (open-standard hard cap); Claude Code truncates the combined `description` + `when_to_use` at 1,536 characters in the skill listing. See [Skill Description Frontmatter](./skill-description-frontmatter.md) and [Skill Description Length](./skill-description-length.md).                            |
| `when_to_use`   | No          | Extra trigger context appended to `description`. Counts toward the 1,536-character combined listing cap.                                                                                                                                                                                                                                                                                                                   |
| `argument-hint` | No          | Autocomplete hint shown after the slash command, e.g. `[issue-number]`.                                                                                                                                                                                                                                                                                                                                                    |
| `arguments`     | No          | Named positional arguments for `$name` substitution in the skill body.                                                                                                                                                                                                                                                                                                                                                     |
| `paths`         | No          | Glob patterns that scope when the skill auto-activates. Use this on guidance and skill docs to bind them to the directories they govern.                                                                                                                                                                                                                                                                                   |

## Tool permissions

| Field              | Required | What it does                                                                                                                                                                                                                                                           |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowed-tools`    | No       | Grants tool permissions while the skill is active. Does not restrict the available tool set, it pre-approves use. See [Allowed Tools: Bash Permissions](./allowed-tools-bash-permissions.md) and [Allowed Tools: AskUserQuestion](./allowed-tools-AskUserQuestion.md). |
| `disallowed-tools` | No       | Removes tools from the available pool while the skill is active.                                                                                                                                                                                                       |

## Invocation control

| Field                      | Required | What it does                                                                                              |
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `disable-model-invocation` | No       | `true` stops Claude from auto-loading the skill (and from preloading it into subagents). Default `false`. |
| `user-invocable`           | No       | `false` hides the skill from the `/` menu. Default `true`.                                                |

## Execution and model

| Field     | Required | What it does                                                                                                                                                      |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`   | No       | Overrides the model for this skill's turn only; not saved to session settings.                                                                                    |
| `effort`  | No       | `low`, `medium`, `high`, `xhigh`, or `max`. Overrides the session's effort level for this skill.                                                                  |
| `context` | No       | Set to `fork` to run the skill in an isolated subagent context. See the caveat in [Skill Composition](./skill-composition.md) about forked data-fetch sub-skills. |
| `agent`   | No       | When `context: fork` is set, names which subagent type runs the skill (`Explore`, `Plan`, `general-purpose`, or a custom subagent).                               |
| `hooks`   | No       | Lifecycle hooks scoped to this skill's run.                                                                                                                       |
| `shell`   | No       | `bash` (default) or `powershell` for inline command blocks.                                                                                                       |

## Portability (open-standard fields)

These come from the cross-tool [Agent Skills specification](https://agentskills.io/specification) and travel to other
tools that implement the standard. Claude Code accepts them.

| Field           | Required | What it does                                                                                                                                    |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `license`       | No       | License name or a reference to a bundled license file.                                                                                          |
| `compatibility` | No       | Environment requirements; max 500 characters.                                                                                                   |
| `metadata`      | No       | Arbitrary key-value map for additional properties. Must use standard YAML types only (see [Security Restrictions](./security-restrictions.md)). |

## Notes that bite

- **The directory name is the command, not `name`.** A skill at `skills/deploy-staging/SKILL.md` produces
  `/deploy-staging` regardless of the `name` field. Plugin skills are namespaced, e.g. `example-plugin:code-review`.
- **No XML angle brackets in any frontmatter field.** Frontmatter is injected into the system prompt where `<` and `>`
  have special meaning. See [Security Restrictions](./security-restrictions.md).
- **`allowed-tools` is marked experimental at the open-standard level** because cross-tool support varies. In Claude
  Code it is a stable, fully-supported field.

## Summary Checklist

1. `name` matches the directory name; lowercase, hyphens, max 64 chars, no reserved words.
2. `description` is present and under 1,024 characters.
3. Tool fields (`allowed-tools`, `disallowed-tools`) follow the Bash-permission granularity rules.
4. Any invocation-control field (`disable-model-invocation`, `user-invocable`) is set deliberately, not by accident.
5. No XML angle brackets in any frontmatter value.

Cross-references:

- [Skill Description Frontmatter](./skill-description-frontmatter.md) — Writing the `description` field for trigger
  accuracy.
- [Skill Description Length](./skill-description-length.md) — The two character caps and what to cut first.
- [Allowed Tools: Bash Permissions](./allowed-tools-bash-permissions.md) — Correct `Bash()` permission syntax.
- [Security Restrictions](./security-restrictions.md) — Frontmatter rules that prevent injection and upload failures.
- [Progressive Disclosure](./progressive-disclosure.md) — How frontmatter, body, and references load at different times.

---
paths:
  - "**/skills/**/*.md"
---

# Skill Reference Files

## Contents

- Why References Exist: Progressive Disclosure
- The Rule
- Keep Reference Links One Level Deep from SKILL.md
- Give a Reference File Over 100 Lines a Table of Contents
- Directory Structure
- The `assets/` Directory
- Skills vs. Agents
- Summary Checklist

Skills can include reference documents — templates, checklists, examples, and other supporting content — in a
`references/` subdirectory within the skill folder. These files are loaded into the skill's context on demand when a
step explicitly references them.

## Why References Exist: Progressive Disclosure

References are the third level of the skill's progressive disclosure architecture. The SKILL.md body (Level 2) contains
process steps — _what to do_. References (Level 3) contain domain knowledge — _what to know_. This separation keeps the
skill body focused on execution logic while making domain knowledge available on demand.

Extract content to `references/` when it represents domain knowledge rather than process steps:

- **Templates** that define output structure (ADR templates, PR description templates, documentation templates)
- **Checklists** that guide evaluation (OWASP top 10, review checklists, documentation checklists)
- **Rate tables and formulas** used in calculations (pricing tables, complexity scores, risk assessments)
- **Decision matrices** with multiple criteria (scoring rubrics, selection frameworks)
- **Style guides** that define standards (voice guidelines, formatting rules, naming conventions)
- **Canonical examples** that demonstrate conventions the skill enforces (2-3 representative "do this / not this" code
  samples per convention)

Reference files are not passive lookups — they are demonstration material the model pattern-matches against during
execution. Every example in a reference file functions as a few-shot demonstration that calibrates the model's output.

Keep content in SKILL.md when it's a process step: numbered instructions, conditional logic, tool invocations, error
handling, and context injection commands.

See [Progressive Disclosure](./progressive-disclosure.md) for the full three-level architecture.

## The Rule

Place all reference files (templates, checklists, guides, etc.) in the `references/` subdirectory of the skill, not at
the skill directory root.

**Before (wrong location):**

```
skills/
  code-review/
    SKILL.md
    owasp-top10.md     # Reference file at skill root
    template.md        # Reference file at skill root
```

Files at the skill directory root may not be properly injected as context for the skill.

**After (correct location):**

```
skills/
  code-review/
    SKILL.md
    references/
      owasp-top10.md   # Loaded when referenced by a step
      template.md       # Loaded when referenced by a step
```

Moved into `references/` where the plugin system expects them.

## Keep Reference Links One Level Deep from SKILL.md

Every reference file a run needs must be linked directly from SKILL.md. When Claude reaches a file through another
reference file — SKILL.md, then `evidence-rule.md`, then `yagni-rule.md` — it may preview that third file with a partial
read such as `head -100` rather than reading it whole, and the run proceeds on part of the content.

**Before (two hops to the content):**

```markdown
<!-- SKILL.md -->

Apply the evidence standard in [references/evidence-rule.md](./references/evidence-rule.md).

<!-- references/evidence-rule.md -->

This rule supplements [yagni-rule.md](./yagni-rule.md).
```

`yagni-rule.md` is reachable only through `evidence-rule.md`, so the run may get part of it.

**After (both files linked from SKILL.md):**

```markdown
<!-- SKILL.md -->

Apply the inclusion gate in [references/yagni-rule.md](./references/yagni-rule.md) and the evidence standard in
[references/evidence-rule.md](./references/evidence-rule.md).
```

The rule is about reachability, not about forbidding links between reference files. Once both files are linked from
SKILL.md, a cross-link from one to the other is a navigation aid rather than the only path. What the rule forbids is a
file reachable **only** through another reference file.

A reference file must also stay inside its own plugin. A link that climbs out of the plugin directory (`../../docs/`)
resolves in the source repository and breaks for everyone who installs the plugin, because only the plugin directory
ships. Name the external document in prose, or link it by its public URL.

## Give a Reference File Over 100 Lines a Table of Contents

A reference file longer than roughly 100 lines opens with a `## Contents` list of its own section headings. Claude often
previews a long file with a partial read, and a contents list at the top means even a partial read shows the full scope
of what the file holds, so nothing further down goes unnoticed.

```markdown
# API Reference

## Contents

- Authentication and setup
- Core methods
- Error handling patterns

## Authentication and setup

...
```

List the headings that name the file's real sections, and stop there. Usually those are the `##` headings. When a file
puts its sections one level down under a single `##` wrapper — a `## The Rules` holding ten `### Rule: ...` headings —
list the inner ones instead, because a two-entry contents list tells a reader nothing. A list that mirrors every
sub-heading of an already well-sectioned file costs more than the partial read it protects against.

**The exception: output templates.** A reference file that is a skeleton copied whole into a produced document — an ADR
template, a report template, a specification template — gets no contents list, because the list would be copied into
every document the template produces. Keep those files free of a table of contents no matter how long they run, and
have the SKILL.md step that loads one say it is copied whole so the run reads all of it.

## Directory Structure

The full skill directory layout:

```
skills/
  {skill-name}/
    SKILL.md           # Skill definition (frontmatter + prompt body)
    references/        # Optional: reference documents injected into context
      template.md
      checklist.md
    scripts/           # Optional: shell scripts used by the skill
      post-review.sh
```

- **`references/`** — Documents loaded into the skill's context when a step explicitly references them. Use for
  templates, checklists, style guides, and other content the skill needs to reference during execution.
- **`scripts/`** — Shell scripts called by the skill's step logic. Use for complex operations that need pipes,
  redirects, or multi-step logic (see
  [Context Injection Commands](./context-injection-commands.md#rule-use-shell-scripts-for-complex-operations)).

## The `assets/` Directory

Skills may also include an `assets/` directory for files used in output but not injected as context — templates that are
copied to the output location, fonts, icons, or other non-context resources. Unlike `references/`, files in `assets/`
are not loaded into Claude's context window.

```
skills/
  {skill-name}/
    SKILL.md
    references/        # Loaded on demand (domain knowledge)
    scripts/           # Executed by skill steps
    assets/            # Used in output, not loaded as context
      report-template.docx
      logo.png
```

Use `assets/` when a skill needs to reference files for output generation rather than for Claude's reasoning.
Establishing this convention early prevents conflicting patterns from emerging.

## Skills vs. Agents

Skills support `references/` and `scripts/` directories. Agents do not — agent definitions are self-contained markdown
files with all content inlined.

| Entity | `references/` | `scripts/` |
| ------ | ------------- | ---------- |
| Skills | Yes           | Yes        |
| Agents | No            | No         |

If an agent needs substantial reference content, inline it directly in the agent `.md` file. See
[External File References in Agent Definitions](../agent-building-guidelines/agent-external-files.md).

## Summary Checklist

1. Place templates, checklists, and reference content in `references/` within the skill directory
2. Do not place reference files at the skill directory root
3. Use `scripts/` for shell scripts, `references/` for documents
4. Use `assets/` for output files (templates, fonts, icons) not intended as context
5. Extract domain knowledge (templates, checklists, rate tables, decision matrices) to `references/`
6. Keep process steps and execution logic in SKILL.md
7. Link every reference file a run needs directly from SKILL.md, so no file is reachable only through another one
8. Keep every reference link inside the plugin directory — a link that climbs out of it breaks once the plugin is installed
9. Open a reference file over roughly 100 lines with a `## Contents` list of its `##` headings, unless it is a template copied whole into output
10. Agents are self-contained — no `references/` or `scripts/` support

Cross-references:

- [External File References in Agent Definitions](../agent-building-guidelines/agent-external-files.md) — Why agents
  don't support references
- [Context Injection Commands](./context-injection-commands.md) — How injected context relates to reference files
- [Progressive Disclosure](./progressive-disclosure.md) — The three-level architecture that references are part of
- [Skill Decomposition](./skill-decomposition.md) — What to do when a reference file grows past what one file should hold

---
paths:
  - "**/skills/**/*.md"
---

# Success Criteria and Testing

## Contents

- Triggering Tests
- Functional Tests
- Performance Comparison
- Summary Checklist

How do you know a skill is working? Without defined success criteria, "it seems fine" becomes the bar — and that bar
shifts with each conversation. This guide defines three test types that cover whether a skill triggers correctly,
executes its workflow, and actually improves outcomes compared to working without it.

Testing rigor should match the skill's audience. A skill used by one person internally has different needs than one
deployed across an organization. But every skill benefits from at least running through the triggering tests and a few
functional scenarios.

**Test against the model the skill targets.** Anthropic notes that smaller, faster models (Haiku) may need more
detailed, explicit instructions than larger ones to follow a skill reliably, while a larger model can fill gaps a terse
skill leaves. A skill that passes on Opus can still fail on Haiku. If a skill is meant to run on a faster tier (or to be
dispatched into a Haiku subagent), run the triggering and functional tests on that tier, not just on your session's
default. See
[Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).

## Triggering Tests

**Goal:** Ensure the skill loads when it should and stays silent when it shouldn't.

Triggering tests validate the `description` field. If the skill doesn't trigger on a paraphrased request, the
description is missing trigger phrases. If it triggers on an unrelated topic, the description is too broad or missing
boundary statements.

### Test cases

Build three categories of test prompts:

| Category                 | Purpose                                            | Target              |
| ------------------------ | -------------------------------------------------- | ------------------- |
| **Obvious triggers**     | The most direct way a user would invoke the skill  | Should trigger 100% |
| **Paraphrased triggers** | Alternative phrasings, synonyms, indirect requests | Should trigger 90%+ |
| **Unrelated prompts**    | Requests the skill should NOT handle               | Should NOT trigger  |

### Example test suite

For a `code-review` skill:

**Should trigger (obvious):**

- "Review my code"
- "Run a code review"
- "Check the code on this branch"

**Should trigger (paraphrased):**

- "Look over these changes"
- "Audit the diff"
- "What do you think of the code I wrote?"

**Should NOT trigger:**

- "Write a unit test for this function"
- "Help me debug this error"
- "Create a PR description" (should trigger `update-pr-description` instead)

### How to measure

Run 10-20 test prompts that span all three categories. Track how many times the skill loads automatically versus
requires explicit invocation (`/skill-name`).

**Passing criteria:** 90%+ of relevant prompts trigger the skill. Zero unrelated prompts trigger it.

### Debugging approach

If triggering tests fail, ask Claude directly: "When would you use the [skill name] skill?" Claude will quote the
description back. Compare what Claude says against your test prompts to identify missing trigger phrases or overly broad
language.

## Functional Tests

**Goal:** Verify the skill produces correct outputs and handles errors.

Functional tests validate the SKILL.md body — the process steps, tool usage, and error handling. Each use case from the
planning phase becomes a functional test.

### Test cases

| Category               | What to verify                                                               |
| ---------------------- | ---------------------------------------------------------------------------- |
| **Valid outputs**      | Skill produces the expected result for each use case                         |
| **Tool calls succeed** | All tool invocations (Read, Grep, Bash, Agent, Skill) execute without errors |
| **Error handling**     | Skill responds correctly when prerequisites are missing or steps fail        |
| **Edge cases**         | Unusual inputs, empty results, very large files, missing files               |

### Example functional test

```
Test: Review a branch with no changes
Given: Current branch is identical to the default branch (empty diff)
When: User says "Review my code"
Then:
  - Skill triggers
  - Detects empty diff
  - Informs user there are no changes to review
  - Does NOT produce a review document with fabricated findings
```

```
Test: Review a branch with 50+ changed files
Given: Current branch has changes across 50 files
When: User says "Run a code review"
Then:
  - Skill triggers
  - Reviews all changed files (not just the first few)
  - Groups findings by file
  - Completes within a reasonable number of tool calls
```

### How to measure

Run each use case as a test. For each run, verify:

1. The skill triggered (not a sibling)
2. All steps executed in order
3. Tool calls succeeded
4. Output matches expected structure
5. Error cases are handled gracefully

Run the same request 3-5 times to check for consistency. If results vary significantly across runs, the instructions are
ambiguous — tighten them.

## Performance Comparison

**Goal:** Prove the skill improves results versus working without it.

Performance comparison answers the question: "Is this skill worth having?" A skill that triggers correctly and produces
valid output still isn't valuable if the user could accomplish the same thing just as easily without it.

### Metrics to compare

Run the same task with and without the skill enabled:

| Metric                 | Without Skill                | With Skill                   | What It Shows                      |
| ---------------------- | ---------------------------- | ---------------------------- | ---------------------------------- |
| **Messages exchanged** | Count of back-and-forth      | Count of back-and-forth      | Skill reduces interaction overhead |
| **Tool calls**         | Total tool invocations       | Total tool invocations       | Skill is more efficient with tools |
| **Tokens consumed**    | Total token usage            | Total token usage            | Skill uses context efficiently     |
| **Errors**             | Failed tool calls, retries   | Failed tool calls, retries   | Skill handles errors better        |
| **User corrections**   | Times user redirected Claude | Times user redirected Claude | Skill follows the right workflow   |

### Example comparison

```
Task: Generate a PR description for the current branch

Without skill:
  - 15 back-and-forth messages (user explaining format, sections, what to include)
  - 3 failed gh CLI calls requiring retry
  - 12,000 tokens consumed
  - 2 user corrections ("include the test plan", "use bullet points")

With skill:
  - 2 clarifying questions only
  - 0 failed API calls
  - 6,000 tokens consumed
  - 0 user corrections
```

### Qualitative signals

Beyond the numbers, watch for:

- **Users don't need to prompt about next steps** — the skill drives the workflow
- **Workflows complete without user correction** — steps execute in the right order with the right tools
- **Consistent results across sessions** — a new user gets the same quality as an experienced one

## Summary Checklist

1. Build triggering tests: obvious triggers, paraphrased triggers, and unrelated prompts that should NOT trigger
2. Target 90%+ trigger accuracy on relevant prompts
3. Debug triggering issues by asking Claude "When would you use [skill name]?"
4. Build functional tests from each use case: valid outputs, tool calls, error handling, edge cases
5. Run functional tests 3-5 times to check consistency
6. Compare performance with and without the skill: messages, tool calls, tokens, errors, corrections
7. Match testing rigor to the skill's audience and visibility

Cross-references:

- [Use Case Planning](./use-case-planning.md) — Use cases become the functional test cases
- [Iterative Plugin Development](../iterative-plugin-development.md) — Testing evidence informs when to stop iterating
- [Skill Description Frontmatter](./skill-description-frontmatter.md) — Triggering test failures indicate description
  problems

---
paths:
  - "**/skills/**/*.md"
---

# Troubleshooting

## Contents

- Skill Won't Upload
- Skill Doesn't Trigger
- Skill Triggers Too Often
- Instructions Not Followed
- Allowed-Tools Issues
- A Probe Reading Outside the Project Is Refused by the Classifier
- A Probe Naming an Environment Variable Is Refused
- A Script Probe Aborts the Skill
- Context Injection Syntax in Prose Triggers Execution
- Sub-Skill Output Lost
- Summary Checklist

This guide covers common problems encountered when building and using skills, organized by symptom. Each section
describes the symptom, explains the likely cause, and provides a concrete fix.

For historical context on how specific issues were discovered and resolved, see the failure evidence tables in
[Context Injection Commands](./context-injection-commands.md).

## Skill Won't Upload

### File not recognized

**Symptom:** "Could not find SKILL.md in uploaded folder" or skill doesn't appear after upload.

**Cause:** The file is not named exactly `SKILL.md` (case-sensitive).

**Fix:**

```bash
# Check the actual filename in the skill directory
find . -maxdepth 1 -name "SKILL*" -o -name "skill*"

# Must be exactly:
SKILL.md

# These are all wrong:
skill.md
SKILL.MD
Skill.md
```

See [Naming Conventions](./naming-conventions.md) for the full naming rules.

### Invalid frontmatter

**Symptom:** "Invalid frontmatter" error during upload.

**Cause:** YAML formatting issue — missing delimiters, unclosed quotes, or invalid syntax.

**Before (broken):**

```yaml
name: my-skill
description: Does things
```

Missing `---` delimiters.

```yaml
---
name: my-skill
description: "Does things
---
```

Unclosed quote on description.

**After (correct):**

```yaml
---
name: my-skill
description: "Does things"
---
```

### Invalid skill name

**Symptom:** "Invalid skill name" error during upload.

**Cause:** Name contains spaces, capitals, or reserved prefixes.

**Before (rejected):**

```yaml
name: My Cool Skill # Spaces and capitals
name: claude-helper # Reserved prefix "claude"
name: anthropic-tools # Reserved prefix "anthropic"
```

**After (accepted):**

```yaml
name: my-cool-skill # kebab-case, no reserved prefixes
```

See [Security Restrictions](./security-restrictions.md) for reserved name rules.

## Skill Doesn't Trigger

**Symptom:** Skill never loads automatically — users must invoke it explicitly with `/skill-name`.

**Cause:** The `description` field is too generic, missing trigger phrases, or missing the "when to use" component.

**Before (too generic):**

```yaml
description: "Helps with projects."
```

**After (specific triggers):**

```yaml
description: >
  Creates and maintains project documentation for features, systems, and components. Use when documenting how a feature,
  system, or component works. Does not create architectural decision records — use architectural-decision-record for
  ADRs.
```

**Debugging approach:** Ask Claude: "When would you use the [skill name] skill?" Claude will quote the description back.
Compare what it says against the prompts that should trigger the skill. If Claude can't explain when to use it, the
description needs more detail.

**Checklist:**

- Does the description include trigger phrases users actually say?
- Does it mention relevant file types or tools if applicable?
- Does it cover at least 3 sentences (what, when-to-use, boundary)?

See [Skill Description Frontmatter](./skill-description-frontmatter.md) for the full description-writing rules.

## Skill Triggers Too Often

**Symptom:** Skill loads for unrelated queries — users see it activate when they didn't intend it.

**Cause:** Description is too broad or lacks boundary statements distinguishing it from sibling skills.

### Fix 1: Add negative triggers

Tell Claude explicitly what the skill does NOT handle.

**Before:**

```yaml
description: >
  Advanced data analysis for CSV files. Use for statistical modeling, regression analysis, and clustering.
```

**After:**

```yaml
description: >
  Advanced data analysis for CSV files. Use for statistical modeling, regression analysis, and clustering. Do NOT use
  for simple data exploration or visualization — use data-viz skill instead.
```

### Fix 2: Narrow the scope

**Before:**

```yaml
description: "Processes documents"
```

**After:**

```yaml
description: >
  Processes PDF legal documents for contract review. Use when reviewing, analyzing, or extracting clauses from legal
  PDFs. Does not handle general document creation — use project-documentation for that.
```

### Fix 3: Add bidirectional boundary statements

If skill A mentions skill B in its boundary, skill B must also mention skill A.

```yaml
# code-review description:
description: >
  ...Does not post to GitHub — use post-code-review-to-pr to post review comments to a pull request.

# post-code-review-to-pr description:
description: >
  ...For local code review without posting to GitHub, use code-review instead.
```

See [Skill Description Frontmatter](./skill-description-frontmatter.md) for boundary statement patterns.

## Instructions Not Followed

**Symptom:** Skill loads but Claude doesn't follow the instructions — skips steps, improvises, or produces inconsistent
results.

### Cause 1: Instructions too verbose

Long, repetitive prose causes Claude to lose focus. Key instructions drown in filler.

**Fix:** Use numbered lists and bullet points. Cut filler words. Say it once.

**Before:**

```markdown
You should carefully look through all of the code changes that have been made and try to find any issues or problems
that might exist. It's really important to be thorough and make sure you don't miss anything.
```

**After:**

```markdown
For each changed file:

1. Check for security issues (see `references/owasp-top10.md`)
2. Check for performance problems
3. Verify adherence to project style guidelines
```

### Cause 2: Critical instructions buried

Important rules appear mid-paragraph deep in the SKILL.md. Claude may not weight them appropriately.

**Fix:** Put critical instructions at the top of the step or in a dedicated section.

**Before:**

```markdown
## Step 5: Post Review

Generate the review body, format it nicely, make sure it's well-organized, and by the way — NEVER post a review to your
own PR, use a comment instead. Then call the posting script.
```

**After:**

```markdown
## Step 5: Post Review

**CRITICAL:** If the PR author matches the current git user, use `scripts/post-pr-comment.sh` instead of
`scripts/post-pr-review.sh`. GitHub does not allow reviewing your own PR.

Generate the review body, then run the appropriate script.
```

### Cause 3: Ambiguous language

**Fix:** Replace vague instructions with specific, testable criteria.

**Before:**

```markdown
Make sure to validate things properly.
```

**After:**

```markdown
Before calling create_project, verify:

- Project name is non-empty
- At least one team member assigned
- Start date is not in the past
```

### Cause 4: Stale documentation

**Symptom:** Skill produces structurally correct but factually wrong output — references non-existent files, uses old
API patterns, follows deprecated conventions.

**Cause:** The SKILL.md or its `references/` describe files, paths, tool flags, or conventions that have changed since
the skill was written. The model reads these faithfully and follows the outdated instructions. This looks like a model
failure but is actually a documentation failure.

**Fix:** Audit SKILL.md and `references/` against the current state of what they describe. Treat doc-code contradictions
as functional bugs — they actively poison output rather than passively going unnoticed.

See [Documentation Maintenance](./documentation-maintenance.md) for the audit triggers, the worked before-and-after on a
renamed script, and the co-versioning rule that prevents the drift in the first place.

### Advanced: Use scripts for critical validation

For validations where correctness is essential, use a script rather than language instructions. Code is deterministic;
language interpretation varies.

```markdown
Run `scripts/validate-output.sh {output_file}` to verify the output.
```

See [Writing Effective Instructions](./writing-effective-instructions.md) for detailed guidance.

## Allowed-Tools Issues

### Repeated permission prompts

**Symptom:** Claude keeps asking the user for permission to run tools that the skill should have access to.

**Cause:** The tool is not listed in `allowed-tools`, or Bash commands are not properly scoped.

**Fix:** Add each tool to `allowed-tools`. For Bash commands, each prefix needs its own `Bash()` entry.

**Before (broken):**

```yaml
allowed-tools: Bash(git *, find *, which *)
```

**After (correct):**

```yaml
allowed-tools: Bash(git *), Bash(find *), Bash(which *)
```

See [Bash Permission Patterns](./allowed-tools-bash-permissions.md) for the full rules.

### AskUserQuestion silently fails

**Symptom:** The skill tries to ask the user a question but the prompt never appears. The skill hangs or skips the step.

**Cause:** `AskUserQuestion` is listed in `allowed-tools`. An upstream Claude Code bug (#29547) causes interactive
prompts to silently fail when this tool is auto-approved.

**Fix:** Remove `AskUserQuestion` from `allowed-tools`. The tool works correctly when the user is prompted for
permission each time.

**Before (broken):**

```yaml
allowed-tools: Read, Grep, Glob, AskUserQuestion
```

**After (correct):**

```yaml
allowed-tools: Read, Grep, Glob
```

See [AskUserQuestion Bug](./allowed-tools-AskUserQuestion.md) for details.

## A Probe Reading Outside the Project Is Refused by the Classifier

**Symptom:** A skill fails on load, naming one context injection command, with an error ending in
`Permission for this action was denied by the Claude Code auto mode classifier. Reason: Blocked by classifier.` The
command uses an allowlisted read-only tool such as `cat`, so the allowlist says it should have been fine. The observed
case:

```
Error: Shell command permission check failed for pattern
"!`cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.han/config.md" 2>/dev/null || echo ""`":
Permission for this action was denied by the Claude Code auto mode classifier.
Reason: Blocked by classifier.
```

**Cause:** The command's target sits outside the project working directory, in this case the Claude Code configuration
directory, which also holds credentials and settings. The allowlist covers the command, not what it is pointed at, and a
permission layer this guidance does not otherwise describe declined the read. Because context injection never prompts,
the refusal aborted the whole skill instead of degrading.

Note the error text differs from the two failure modes below and above: it names an auto mode classifier rather than
`This command requires approval`. Search on either phrase lands here.

**Fix:** Resolve the path in the probe, and read the file with the Read tool during the run.

**Before (broken — probe reads outside the project):**

```markdown
- personal config: !`cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.han/config.md" 2>/dev/null || echo ""`
```

**After (correct — probe resolves the location only):**

```markdown
- personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above.
```

The probe runs a script because naming an environment variable in probe text is refused outright. See the next section.

See [Context Injection Commands](./context-injection-commands.md) for the full rule.

## A Probe Naming an Environment Variable Is Refused

**Symptom:** The skill aborts at load with

```
Shell command permission check failed for pattern "!`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"`": Contains expansion
```

In a non-interactive run there is no symptom at all. A `claude -p` session exits successfully with `is_error: false`,
an empty result, and zero model turns, and `--debug` prints nothing extra. A skill that appears to do nothing is the
thing to recognize.

**Cause:** The loader inspects the probe's text before running it. A bare `$HOME` is permitted; brace syntax is refused
even for `$HOME`, and every other variable name is refused whether or not it exists. `printenv` is refused in any
position. No `allowed-tools` grant changes this, because the refusal happens before any permission question is asked.

Permission mode does not rescue it either. `default`, `plan`, `acceptEdits`, and `auto` all abort. Only
`bypassPermissions` lets it through, which is why a probe can look fine in one session and break for everyone else.

**Fix:** Move the variable into a script and run the script from the probe, behind a grant naming that exact command.

```markdown
- personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
```

```yaml
allowed-tools: Read, Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")
```

See [Context Injection Commands](./context-injection-commands.md) for the measured results table and the four
conditions that form has to meet.

## A Script Probe Aborts the Skill

**Symptom:** The same silent abort as above, from a probe that runs a script and names no variable.

**Cause:** One of two things, and both look identical from outside.

1. **No matching grant.** A script probe is refused without one, even with no variable anywhere in the command.
2. **The script is missing or failed.** An unguarded probe whose script does not exist, or exits non-zero, takes the
   skill down exactly as a refused probe does.

**Fix:** Grant the exact command in `allowed-tools`, and guard the invocation so a broken script degrades instead of
aborting:

```markdown
- personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
```

Verify a script probe as an installed plugin rather than as a local skill under `.claude/skills/`. `${CLAUDE_PLUGIN_ROOT}`
is only defined inside a plugin, and the same line aborts outside one.

## Context Injection Syntax in Prose Triggers Execution

**Symptom:** Skill fails on load with
`Shell command permission check failed for pattern "!`command`": This command requires approval` — but the SKILL.md has
no actual context injection commands.

**Cause:** The SKILL.md body text contains the literal bang-backtick pattern as documentation or an example (e.g.,
describing what context injection commands look like). The skill loader scans the raw SKILL.md text for the pattern and
does not respect markdown escaping — double backticks, inline code spans, and fenced code blocks are all parsed.

**Fix:** Replace the literal pattern with a description that does not trigger the parser.

**Before (broken — loader tries to execute `command`):**

```markdown
- A context injection command (`` !`command` `` syntax)
```

**After (correct):**

```markdown
- A context injection command (bang-backtick syntax for runtime context)
```

**Note:** Files in `references/` are not parsed by the loader, so they can safely contain the literal pattern.

See [Context Injection Commands](./context-injection-commands.md) for the full rule.

## Sub-Skill Output Lost

**Symptom:** A skill calls another skill via the Skill tool. The sub-skill runs and produces output on screen, but the
calling skill never picks up the results.

### Cause 1: Data-fetch sub-skill (forked or inline)

The skill calls another skill only to retrieve a few values (a config path, a command, a setting). This is unreliable in
both forms. Inline, the model has no structured return mechanism and must manually context-switch back to the parent
workflow. Forked with `context: fork`, an `api_retry` event can anchor the model on the sub-skill's returned output and
bypass every remaining step, the early-exit failure documented in [Skill Composition](./skill-composition.md).

**Fix:** Do not use a data-fetch sub-skill at all. Discover the values inline: detect config files via context
injection, Read them directly in the skill's own steps, and fall back to conventional defaults. Duplicate the handful of
discovery lines rather than sharing them through a sub-skill.

### Cause 2: Orchestration sub-skill, but the orchestrator lost its workflow

The skill legitimately hands heavy work to a substantial sub-skill, but never picks the workflow back up after the Skill
call returns. The calling model treats the sub-skill's output as its own final answer and stops.

**Fix:** Keep the orchestrator thin so it has little state to lose across the call, and end the invoking step with an
explicit instruction to proceed to the next step. Never rely on implicit continuation. See
[Skill Composition](./skill-composition.md) for the full orchestration discipline.

## Summary Checklist

1. **Won't upload:** Check `SKILL.md` naming (case-sensitive), YAML delimiters, and reserved name prefixes
2. **Doesn't trigger:** Add specific trigger phrases, "when to use" context, and boundary statements to description
3. **Triggers too often:** Add negative triggers, narrow scope, ensure bidirectional boundary statements
4. **Instructions not followed:** Shorten verbose prose, surface critical instructions, replace ambiguous language, use
   scripts for validation
5. **Permission prompts:** Add tools to `allowed-tools`; use separate `Bash()` entries per command prefix
6. **AskUserQuestion fails:** Remove it from `allowed-tools` — the bug causes silent failures when auto-approved
7. **Context injection in prose:** Never use the literal bang-backtick pattern in SKILL.md body text — the loader parses
   raw text and tries to execute it
8. **Sub-skill output lost:** Replace data-fetch sub-skills with inline discovery; for orchestration sub-skills, keep
   the orchestrator thin and instruct it to proceed explicitly after the Skill call

Cross-references:

- [Naming Conventions](./naming-conventions.md) — Skill naming rules
- [Security Restrictions](./security-restrictions.md) — Reserved names and frontmatter restrictions
- [Skill Description Frontmatter](./skill-description-frontmatter.md) — Description-writing rules for trigger accuracy
- [Writing Effective Instructions](./writing-effective-instructions.md) — How to write instructions Claude follows
  consistently
- [Bash Permission Patterns](./allowed-tools-bash-permissions.md) — Bash tool permission scoping
- [AskUserQuestion Bug](./allowed-tools-AskUserQuestion.md) — The silent failure bug
- [Context Injection Commands](./context-injection-commands.md) — Historical failure evidence for command patterns

---
paths:
  - "**/skills/**/*.md"
---

# Use Case Planning

## Contents

- The Rules
- Use Case Template
- Summary Checklist

Before writing a SKILL.md, define 2-3 concrete use cases the skill should handle. Use cases ground the skill in real
user workflows rather than abstract capabilities, and they become the test cases you run after building.

Skipping this step leads to skills that sound good in their description but fail in practice — trigger phrases that
don't match how users actually ask, missing tool permissions, or domain knowledge gaps that only surface during
execution. Spending 10 minutes defining use cases before writing saves iterations later.

This guide covers _pre-development_ planning — what happens before iteration 1. For the iterative development process
that follows, see [Iterative Plugin Development](../iterative-plugin-development.md).

## The Rules

### Rule: Define 2-3 concrete use cases before building

Each use case should represent a distinct way a user would invoke the skill. Two use cases is the minimum to avoid
building a one-trick skill. Three is usually enough to cover the primary workflows without over-engineering.

**Before (no use cases — jumping straight to SKILL.md):**

```yaml
---
name: "project-documentation"
description: "Creates project documentation"
---
## Step 1: Find the project structure
## Step 2: Write documentation
```

This skill was built without thinking about _who_ would use it or _how_. The description is vague, the steps are
generic, and there's no way to test whether it works.

**After (use cases defined first):**

Use Case 1: Document an existing feature

- **Trigger:** "Document how the authentication system works"
- **Steps:** Discover project structure, trace the feature through code, write documentation
- **Tools:** Read, Grep, Glob, Agent (a codebase-explorer agent)
- **Domain knowledge:** Documentation templates, section structure conventions

Use Case 2: Update outdated documentation

- **Trigger:** "Update the API docs — the endpoints changed last sprint"
- **Steps:** Find existing docs, compare against current code, update with changes
- **Tools:** Read, Grep, Glob, Agent (a content-auditor agent)
- **Domain knowledge:** How to identify stale sections, change detection patterns

Use Case 3: Create documentation for a new component

- **Trigger:** "Write docs for the new payment service"
- **Steps:** Scan component structure, identify public interfaces, generate documentation
- **Tools:** Read, Grep, Glob, Agent (a codebase-explorer agent)
- **Domain knowledge:** Component documentation template, API documentation conventions

### Rule: Each use case answers four questions

Every use case must answer these four questions. Missing any one creates a gap that surfaces during development or
testing.

| Question                                        | What It Reveals                         |
| ----------------------------------------------- | --------------------------------------- |
| **What does the user want to accomplish?**      | The trigger phrases for the description |
| **What multi-step workflow does this require?** | The numbered steps in SKILL.md          |
| **What tools are needed?**                      | The `allowed-tools` frontmatter         |
| **What domain knowledge should be embedded?**   | The `references/` content               |

**Before (incomplete use case):**

```
Use Case: Code review
Trigger: "Review my code"
```

This tells you nothing about the workflow, tools, or knowledge needed.

**After (complete use case):**

```
Use Case: Review current branch for quality issues
Trigger: "Review my code" / "Check this branch" / "Run a code review"
Workflow:
  1. Get current branch and default branch
  2. Read the diff between them
  3. Analyze changes against review checklist
  4. Generate structured findings with severity ratings
Tools: Read, Grep, Glob, Agent (for parallel file analysis)
Domain knowledge: OWASP top 10, code review checklist, severity rating scale
```

Now you know the description needs trigger phrases like "review," "check," and "code review." You know `allowed-tools`
needs `Read, Grep, Glob, Agent`. You know `references/` needs a review checklist and OWASP guide.

### Rule: Use cases become your test cases

Each use case is a test case you can run after building the skill. The trigger phrase tests whether the skill activates.
The workflow tests whether the steps execute correctly. The expected result tests whether the output meets quality
standards.

**Use case as test case:**

```
Test: Document an existing feature
Given: A repository with an authentication system
When: User says "Document how the authentication system works"
Then:
  - Skill triggers (not a sibling like a coding-standard or ADR skill)
  - The codebase-explorer agent discovers auth-related files
  - Output follows documentation template from references/
  - All public interfaces are documented
  - No fabricated details (only documents what exists in code)
```

If a use case can't be turned into a testable scenario, it's too vague. Rewrite it with specific triggers, steps, and
expected results.

## Use Case Template

Use this template when planning a new skill. Fill in one copy per use case.

```
Use Case: [Short descriptive name]
Trigger: "[What the user says]" / "[Alternative phrasing]" / "[Another variant]"
Workflow:
  1. [First step — what happens]
  2. [Second step — what happens]
  3. [Continue as needed]
Expected Result: [What the user gets when the skill succeeds]
Tools: [Which tools the skill needs — Read, Grep, Bash, Agent, Skill, etc.]
Domain Knowledge: [Templates, checklists, rules the skill needs to reference]
```

**Filled example:**

```
Use Case: Generate PR description from branch changes
Trigger: "Write a PR description" / "Generate PR summary" / "Draft the PR body"
Workflow:
  1. Check gh CLI is installed and a PR exists for the current branch
  2. Gather branch diff, commit log, and changed file list
  3. Analyze changes to identify the purpose and scope
  4. Generate structured PR description with summary, changes, and test plan
Expected Result: PR description posted to GitHub via gh CLI
Tools: Bash(gh *), Bash(git *), Read, Grep, Glob
Domain Knowledge: PR description template (summary, changes, test plan sections)
```

## Summary Checklist

1. Define 2-3 concrete use cases before writing SKILL.md
2. Each use case answers: what to accomplish, what workflow, what tools, what domain knowledge
3. Include realistic trigger phrases — these feed the `description` field
4. Include expected results — these become your acceptance criteria
5. Convert each use case into a testable scenario after building
6. Use cases end where iteration 1 begins — hand off to the iterative development process

Cross-references:

- [Success Criteria and Testing](./success-criteria-and-testing.md) — How to turn use cases into structured test suites
- [Iterative Plugin Development](../iterative-plugin-development.md) — The development process that follows use case
  planning
- [Skill Description Frontmatter](./skill-description-frontmatter.md) — Use case trigger phrases inform the description
  field

---
paths:
  - "**/skills/**/*.md"
---

# Workflow Patterns

## Contents

- Choosing Your Approach: Problem-First vs. Tool-First
- Sequential Workflow Orchestration
- Iterative Refinement
- Context-Aware Tool Selection
- Domain-Specific Intelligence
- Combining Patterns
- Human Gates in Workflow Steps
- Ordering Within Steps: Recency Bias
- Summary Checklist

Skills encode workflows — multi-step processes that Claude executes in a specific order with specific tools. This guide
documents four structural patterns that appear across well-built skills. Each pattern solves a different workflow shape,
and most real skills combine two or more.

These patterns describe the _internal structure_ of a skill's workflow — how to organize steps within a single SKILL.md.
For guidance on _when to split a skill_ into multiple skills or _how to compose_ skills together, see
[Skill Decomposition](./skill-decomposition.md).

The four patterns below map onto the agent workflow patterns Anthropic describes in
[Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) (prompt chaining, routing,
parallelization, orchestrator-workers, evaluator-optimizer). That post's overarching advice also applies here: start
with the simplest structure that works, and add steps or branches only when the task genuinely needs them.

## Choosing Your Approach: Problem-First vs. Tool-First

Before selecting a pattern, consider which framing fits your skill:

- **Problem-first:** The user describes an outcome ("set up a new project," "review this code"). The skill orchestrates
  the right tools in the right sequence. Users don't need to know which tools are involved.
- **Tool-first:** The user has tools available (gh CLI, an MCP server) and wants Claude to use them effectively. The
  skill teaches Claude the optimal workflows and best practices for those tools.

Most skills lean one direction. Problem-first skills tend toward sequential orchestration and iterative refinement.
Tool-first skills tend toward context-aware selection and domain-specific intelligence. Knowing your framing helps you
choose the right starting pattern.

## Sequential Workflow Orchestration

**Use when:** The skill follows a fixed sequence of steps where each step depends on the previous one's output.

This is the most common pattern. Steps execute in order, each building on the results of the previous step. Validation
gates between steps catch failures before they propagate.

### Structure

```markdown
## Step 1: [Gather Context]

[What to do, what tools to use, what to capture]

Validate: [What must be true before proceeding]

## Step 2: [Process/Analyze]

Using the output from Step 1, [what to do next]

Validate: [What must be true before proceeding]

## Step 3: [Generate Output]

[What to produce, what format, where to save]

## Step 4: [Deliver/Integrate]

[How to deliver the result — post to GitHub, write to file, show to user]

If Step 4 fails: [Rollback instructions — what to undo or retry]
```

### Key techniques

- **Explicit step ordering** — number every step, state dependencies clearly
- **Validation gates** — check preconditions at each step before proceeding
- **Rollback instructions** — tell Claude what to do when a later step fails

### Example: `update-pr-description`

```markdown
## Step 1: Verify Prerequisites

Check that gh CLI is installed and a PR exists for the current branch. If either is missing, inform the user and stop.

## Step 2: Gather Branch Context

Read the diff, commit log, and changed file list.

## Step 3: Analyze Changes

Identify the purpose, scope, and impact of the changes.

## Step 4: Generate Description

Write a structured PR description with summary, changes, and test plan.

## Step 5: Post to GitHub

Run `scripts/post-description.sh` to update the PR body. If posting fails, show the generated description so the user
can post manually.
```

## Iterative Refinement

**Use when:** Output quality improves with review cycles — drafts, reports, documentation.

The skill generates an initial output, evaluates it against quality criteria, then refines. A bounded loop prevents
infinite iteration.

### Structure

```markdown
## Step 1: [Initial Draft]

Generate the first version based on [inputs].

## Step 2: [Quality Check]

Evaluate the draft against these criteria:

- [Criterion 1]
- [Criterion 2]
- [Criterion 3]

## Step 3: [Refinement Loop]

For each issue found in the quality check:

1. Identify the specific problem
2. Apply the fix
3. Re-check that specific criterion

Maximum 3 refinement passes. If issues persist after 3 passes, present the current version with a note about remaining
issues.

## Step 4: [Finalization]

Apply final formatting and deliver the result.
```

### Key techniques

- **Explicit quality criteria** — define what "good" looks like before the loop
- **Bounded iteration** — set a maximum pass count (2-3) to prevent infinite loops
- **Targeted refinement** — fix specific issues, don't regenerate everything

### Example: `project-documentation`

```markdown
## Step 3: Generate Documentation Draft

Write documentation for the discovered feature using the template from `references/documentation-template.md`.

## Step 4: Validate Documentation

Use the `Agent` tool with `example-plugin:content-auditor` to verify:

- No fabricated details (only documents what exists in code)
- All public interfaces are covered
- Code examples compile/run

## Step 5: Refine

Address each issue found by the content auditor. Re-validate after fixes. Maximum 2 refinement passes.
```

## Context-Aware Tool Selection

**Use when:** The skill needs to choose different tools or approaches based on runtime context.

Instead of a fixed sequence, the skill evaluates the current situation and branches to the appropriate approach.
Decision trees make the selection criteria explicit.

### Structure

```markdown
## Step 1: [Assess Context]

Determine the current situation:

- [Check condition A]
- [Check condition B]
- [Check condition C]

## Step 2: [Select Approach]

Based on the assessment:

- If [condition A]: [Use approach/tool X]
- If [condition B]: [Use approach/tool Y]
- If [neither]: [Use fallback approach Z]

Explain to the user why this approach was selected.

## Step 3: [Execute Selected Approach]

[Proceed with the chosen approach]
```

### Key techniques

- **Clear decision criteria** — don't let Claude guess; specify what determines the choice
- **Fallback options** — always include a default path when no condition matches
- **Transparency** — tell the user which approach was selected and why

### Example: `investigation`

```markdown
## Step 2: Select Investigation Strategy

Based on the issue description:

- If a specific error message is provided: Start with error trace analysis
- If a behavior regression: Start with git bisect approach
- If a performance issue: Start with profiling approach
- If unclear: Start with broad evidence gathering, then narrow

Inform the user which strategy was selected and why.
```

## Domain-Specific Intelligence

**Use when:** The skill's value comes from embedded expertise — rules, regulations, best practices — not just tool
orchestration.

The skill applies domain knowledge before, during, or after tool operations. The domain knowledge lives in `references/`
and is consulted at specific steps.

### Structure

```markdown
## Step 1: [Gather Data]

[Collect the raw inputs using tools]

## Step 2: [Apply Domain Rules]

Consult `references/[domain-rules].md` and apply:

- [Rule category 1]: [What to check, what to flag]
- [Rule category 2]: [What to check, what to flag]

Document which rules were applied and their results.

## Step 3: [Decision Based on Rules]

If all rules pass: [Proceed with action] If any rule fails: [Flag for review, create case, or stop]

## Step 4: [Audit Trail]

Log all rule checks, decisions, and outcomes for review.
```

### Key techniques

- **Embedded expertise** — domain knowledge in `references/`, not in the user's head
- **Validation before action** — apply rules before executing irreversible operations
- **Audit trail** — document what was checked and decided

### Example: `code-review`

```markdown
## Step 3: Apply Review Checklist

Consult `references/review-checklist.md` and evaluate each changed file against:

- Security (OWASP top 10 from `references/owasp-top10.md`)
- Error handling patterns
- Test coverage expectations
- Naming conventions

For each finding, record: file, line, severity, rule, and recommendation.
```

## Combining Patterns

Most skills use more than one pattern. Common combinations:

| Primary Pattern          | Combined With                | Example                                                                     |
| ------------------------ | ---------------------------- | --------------------------------------------------------------------------- |
| Sequential orchestration | Domain-specific intelligence | `code-review`: sequential steps with checklist-based analysis               |
| Sequential orchestration | Iterative refinement         | `project-documentation`: sequential discovery with draft-review-refine loop |
| Context-aware selection  | Sequential orchestration     | `investigation`: select strategy, then execute sequentially                 |
| Iterative refinement     | Domain-specific intelligence | `coding-standard`: draft standard, validate against conventions, refine     |

When combining, use one pattern as the primary structure (the step sequence) and embed the other pattern within specific
steps.

## Human Gates in Workflow Steps

The Sequential Orchestration pattern includes **validation gates** — automated checks that verify preconditions before
proceeding. **Human gates** are different: they pause execution to ask the user for confirmation before an irreversible
operation. Both are workflow controls, but they serve different purposes and appear at different points.

### When to place a human gate

This is the skill-level form of the checkpoint guidance in
[Building effective agents](https://www.anthropic.com/engineering/building-effective-agents): build a point where the
workflow pauses for human review before an irreversible action. Place a human gate before operations that are expensive
or impossible to reverse:

- Posting to external systems (GitHub comments, PR reviews, Slack messages)
- Deleting files, branches, or resources
- Writing to production systems or shared infrastructure
- Committing or pushing changes

Do not place human gates before reversible operations (writing a local file, reading code, running tests). Gates on
reversible decisions waste the user's attention and train them to approve without reading.

### How to implement

Use `AskUserQuestion` to present a structured summary of what is about to happen, then handle the response:

```markdown
## Step 4: Post Review to GitHub

Before posting, use `AskUserQuestion` to confirm with the user:

- Show the review summary (number of findings by severity)
- Show the target PR (owner/repo#number)
- Ask whether to post, revise, or cancel

If the user cancels: show the generated review so they can use it manually. If the user asks to revise: return to Step 3
with their feedback.
```

Note: Do not add `AskUserQuestion` to `allowed-tools` — see [AskUserQuestion Bug](./allowed-tools-AskUserQuestion.md)
for details.

### How many gates

Target 2-3 human gates per skill at most. Every gate is friction — a circuit breaker at an irreversible decision, not a
toll booth at every step. If a gate never gets rejected, it is not at a real decision point and should be removed. If a
gate gets rejected more than 20% of the time, the preceding steps are producing unreliable output and need improvement.

**Before (no human gate — silent external action):**

```markdown
## Step 5: Post Review

Run `scripts/post-review.sh {owner/repo} {pr_number}` to post the review.
```

**After (human gate before irreversible action):**

```markdown
## Step 5: Post Review

Present the review summary to the user and ask for confirmation before posting. If confirmed, run
`scripts/post-review.sh {owner/repo} {pr_number}`. If rejected, display the review content so the user can post or edit
manually.
```

## Ordering Within Steps: Recency Bias

Within any step, the model weights the last instruction or example more heavily than earlier ones. When a step contains
multiple conventions, criteria, or examples, place the most critical or representative item last.

This applies to:

- The last item in a numbered checklist within a step
- The last example in a set of canonical examples
- The last validation criterion in a quality check

This is an attention effect, not a logical dependency — it works alongside step ordering (which is driven by
dependencies between steps). The model also weights the first item in a sequence more heavily than items in the middle
(a "lost in the middle" effect). Both the existing guidance to put critical instructions at the top of a step (to avoid
mid-paragraph burial) and this guidance to put the most important list item last target the same enemy: the middle
position.

**Before (most critical criterion buried in the middle):**

```markdown
## Step 3: Validate Changes

Check each changed file against:

1. Naming conventions match project style
2. No hardcoded secrets or credentials
3. Error messages include debugging context
4. Import order follows project convention
```

**After (most critical criterion placed last):**

```markdown
## Step 3: Validate Changes

Check each changed file against:

1. Naming conventions match project style
2. Import order follows project convention
3. Error messages include debugging context
4. No hardcoded secrets or credentials
```

## Summary Checklist

1. Choose problem-first or tool-first framing to guide pattern selection
2. Use **sequential orchestration** for fixed-order workflows with step dependencies
3. Use **iterative refinement** for output that improves with review cycles
4. Use **context-aware selection** for workflows that branch based on runtime context
5. Use **domain-specific intelligence** for workflows driven by embedded expertise
6. Include validation gates, bounded loops, decision criteria, or audit trails as appropriate
7. Combine patterns by using one as the primary structure and embedding others within steps
8. Within a step, place the most critical instruction or most representative example last (recency bias)

Cross-references:

- [Skill Decomposition](./skill-decomposition.md) — When and how to split workflows across multiple skills
- [Skill Reference Files](./skill-reference-files.md) — Where to store domain knowledge referenced by workflow steps
- [Progressive Disclosure](./progressive-disclosure.md) — How the three-level architecture supports workflow patterns
- [Context Hygiene](./context-hygiene.md) — Why position effects matter for skill structure
- [Agent Dispatch Namespacing](./agent-dispatch-namespacing.md) — Dispatch agents by `plugin-name:agent-name`, never
  bare

---
paths:
  - "**/skills/**/*.md"
---

# Writing Effective Instructions

## Contents

- The Rules
- Rule: Be specific and actionable
- Rule: Write constraints with embedded reasoning
- Rule: Include error handling in instructions
- Rule: Prefer inline discovery over forked data-fetch sub-skills
- Rule: Reference bundled resources clearly
- Rule: Use progressive disclosure for instruction length
- Rule: Avoid verbose, buried, or ambiguous instructions
- Rule: Structure conventions as heading + one-line rule + example
- Rule: Resolve variation at the point of use
- Rule: Include canonical examples for conventions the skill enforces
- Rule: Use scripts for deterministic validation
- Summary Checklist

The SKILL.md body — everything below the YAML frontmatter — is where you tell Claude _how_ to execute the skill. These
instructions load when the skill triggers (Level 2 in the progressive disclosure model) and guide Claude through the
workflow step by step.

Poorly written instructions produce inconsistent results: Claude skips steps, misinterprets intent, or improvises when
it should follow a specific process. Well-written instructions are specific, actionable, and structured so Claude can
follow them reliably across sessions.

## The Rules

### Rule: Be specific and actionable

Every instruction should tell Claude exactly what to do, not vaguely gesture at an outcome. Specific instructions
produce consistent results; vague instructions produce different results each time.

**Before (vague):**

```markdown
## Step 3: Validate the Data

Validate the data before proceeding.
```

Claude doesn't know _what_ to validate, _how_ to validate, or _what to do_ if validation fails.

**After (specific):**

```markdown
## Step 3: Validate the Data

Run `python scripts/validate.py --input {filename}` to check data format. If validation fails, common issues include:

- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)
- Duplicate entries (remove or merge)
```

**Before (abstract):**

```markdown
## Step 2: Analyze Changes

Look at the changes and provide feedback.
```

**After (concrete):**

```markdown
## Step 2: Analyze Changes

For each changed file in the diff:

1. Read the full file (not just the diff) for context
2. Check against `references/review-checklist.md`
3. Classify each finding by severity: critical, warning, or suggestion
4. Include the file path and line number for each finding
```

### Rule: Write constraints with embedded reasoning

When a skill instruction prohibits or requires something, include the reason. A bare directive — "Never use X" — covers
only the literal case described. A directive with reasoning — "Never use X BECAUSE Y" — lets the model generalize to
analogous situations where the same reasoning applies.

Format: `Always/Never [action] BECAUSE [reason]`

**Before (bare directive):**

```markdown
## Constraints

- Never use `Array<T>` syntax
- Always use named exports
```

The model follows these literally but can't generalize. It avoids `Array<T>` but doesn't know why, so it can't apply
similar reasoning to other style decisions.

**After (directive with reasoning):**

```markdown
## Constraints

- Never use `Array<T>` syntax BECAUSE the project ESLint config enforces `T[]` via the `array-type` rule — `Array<T>`
  triggers lint failures
- Always use named exports BECAUSE the project relies on tree-shaking, which works reliably only with named exports
```

The model understands the underlying reasons and generalizes: if lint enforcement is the concern, it checks for similar
patterns; if tree-shaking is the concern, it avoids other constructs that break it.

### Rule: Include error handling in instructions

Tell Claude what to do when things go wrong. Without error handling instructions, Claude either ignores failures or
invents its own recovery strategy — neither is reliable.

**Before (no error handling):**

```markdown
## Step 1: Fetch PR Metadata

Run `scripts/pr-metadata.sh` to gather PR information.
```

**After (with error handling):**

```markdown
## Step 1: Fetch PR Metadata

Run `scripts/pr-metadata.sh` to gather PR information.

If the script fails:

- Exit code 1 (no PR found): Inform the user that no PR exists for the current branch and stop
- Exit code 2 (gh CLI not authenticated): Ask the user to run `gh auth login` and stop
- Any other error: Show the error output to the user and stop
```

Error handling is especially important for steps that depend on external tools (gh CLI, APIs, MCP servers) or
user-provided input.

### Rule: Prefer inline discovery over forked data-fetch sub-skills

Data-fetch sub-skills using `context: fork` can cause the calling skill to exit early. This has been observed in
practice: after a forked config-reading sub-skill returns "Not found: ...", an `api_retry` event can fire and the
calling model treats the sub-skill's output as its final answer, bypassing all subsequent workflow steps. Adding
explicit "proceed immediately... do not stop here" wording and conventional defaults does not reliably prevent it. The
`context: fork` mechanism plus explicit continuation instructions is necessary but not sufficient.

The solution is to replace forked data-fetch sub-skill calls with inline discovery: use context injection to detect
config files, then read and extract values directly in the skill's own step logic. This eliminates the forked sub-skill
entirely, avoiding the early-exit failure mode.

**Before (forked sub-skill — causes early exit):**

```markdown
## Step 1: Identify Changes

Call `read-project-config` via the `Skill` tool with arguments "docs directory, ADR directory, coding standards
directory, test command, lint command, build command". After the Skill tool returns, proceed immediately to **Detect
review context** below — do not stop here.
```

**After (inline discovery — no sub-skill call):**

```markdown
## Project Context

- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`

## Step 1: Identify Changes

Resolve project config: read CLAUDE.md's `## Project Discovery` section for docs, ADR, and coding-standards directories
plus test, lint, and build commands; fall back to project-discovery.md; fall back to Glob defaults (`docs/`,
`docs/adr/`, `docs/coding-standards/`). Continue without any keys that remain unfound.
```

The skill reads config files directly using Read — no forked sub-skill, no `api_retry` interaction, no early-exit risk.

This rule applies to data-fetch sub-skills that return structured values. Orchestration sub-skills (where the called
skill drives the remaining output) are unaffected.

### Rule: Reference bundled resources clearly

When a step uses content from `references/` or `scripts/`, reference it by exact path and explain what the resource
contains and how to use it. Don't assume Claude will discover the file's purpose on its own.

**Before (unclear reference):**

```markdown
## Step 3: Apply Standards

Check the references for the coding standard.
```

**After (clear reference):**

```markdown
## Step 3: Apply Standards

Consult `references/coding-standard.md` for:

- Naming conventions (Section 1)
- Error handling patterns (Section 2)
- Test structure requirements (Section 3)

Apply each applicable section to the code under review. Cite the section name when reporting a finding.
```

### Rule: Use progressive disclosure for instruction length

Keep the SKILL.md body focused on process steps. Move domain knowledge — templates, checklists, rate tables, decision
matrices — to `references/`. This keeps the Level 2 content manageable and lets Claude load detailed knowledge only when
a step needs it.

**Before (everything in SKILL.md):**

```markdown
## Step 4: Score the Proposal

Use the following scoring matrix:

| Criterion   | Weight | 1 (Poor)                  | 2 (Fair)        | 3 (Good)        | 4 (Excellent)       |
| ----------- | ------ | ------------------------- | --------------- | --------------- | ------------------- |
| Feasibility | 30%    | No path to implementation | Major obstacles | Minor obstacles | Clear path          |
| Impact      | 25%    | No measurable impact      | Low impact      | Moderate impact | High impact         |
| Cost        | 25%    | Over budget               | Near budget     | Under budget    | Significant savings |
| Timeline    | 20%    | >12 months                | 6-12 months     | 3-6 months      | <3 months           |

Calculate the weighted score for each criterion... [40 more lines of scoring formulas and examples]
```

**After (extracted to references/):**

`references/scoring-matrix.md`:

```markdown
# Proposal Scoring Matrix

[Full matrix, formulas, and examples]
```

`SKILL.md`:

```markdown
## Step 4: Score the Proposal

Apply the scoring matrix from `references/scoring-matrix.md` to evaluate the proposal. Calculate weighted scores for
each criterion and produce a final recommendation.
```

### Rule: Avoid verbose, buried, or ambiguous instructions

Three anti-patterns cause Claude to ignore or misinterpret instructions:

| Anti-pattern                     | Problem                                                                                              | Fix                                                                                                 |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Too verbose**                  | Claude loses focus in long, repetitive prose. Key instructions drown in filler.                      | Use numbered lists and bullet points. Cut filler words. Say it once.                                |
| **Buried critical instructions** | Important rules appear mid-paragraph on step 7. Claude may not weight them appropriately.            | Put critical instructions at the top of the step or in a dedicated `## Important` section.          |
| **Ambiguous language**           | Phrases like "validate things properly" or "make sure it's good" give Claude no actionable criteria. | Replace with specific checks: "Verify project name is non-empty and start date is not in the past." |

**Before (verbose and buried):**

```markdown
## Step 2: Review the Code

You should carefully look through all of the code changes that have been made and try to find any issues or problems
that might exist. It's really important to be thorough and make sure you don't miss anything. You should pay special
attention to security issues. Also, don't forget to check for performance problems too. And make sure the code follows
the project's style guidelines. One more thing — verify that all the tests pass.
```

**After (structured and direct):**

```markdown
## Step 2: Review the Code

For each changed file:

1. Check for security issues (see `references/owasp-top10.md`)
2. Check for performance problems (unnecessary loops, missing indexes, N+1 queries)
3. Verify adherence to project style guidelines
4. Confirm existing tests still pass
```

### Rule: Structure conventions as heading + one-line rule + example

When a skill's instructions define conventions the model must follow — coding standards, review criteria, documentation
formats — each convention should follow a specific formula: markdown heading, one-line rule statement, 2-3 code
examples. Structured formats have exactly one interpretation. Prose paragraphs that list multiple conventions require
the model to infer where one instruction ends and the next begins.

**Before (conventions as prose paragraph):**

```markdown
## Step 3: Apply Review Standards

When reviewing code, make sure that error handling follows the project pattern where all async functions use try/catch
and errors are logged with context before being re-thrown. Also check that public API functions validate their inputs at
the boundary and return typed errors rather than throwing. Finally, ensure that side effects like network calls and file
writes are explicit in function names so callers know what to expect.
```

Three conventions are buried in a single paragraph. The model must parse sentence boundaries to separate them.

**After (each convention as its own block):**

````markdown
## Step 3: Apply Review Standards

### Error handling

Async functions must use try/catch, log errors with context, and re-throw.

```typescript
// do this
async function fetchUser(id: string) {
  try {
    return await db.users.find(id);
  } catch (err) {
    logger.error("fetchUser failed", { id, err });
    throw err;
  }
}
```

### Input validation at boundaries

Public API functions must validate inputs and return typed errors, not throw.

```typescript
// do this
function createProject(name: string): Result<Project, ValidationError> {
  if (!name.trim()) return err(new ValidationError("name is required"));
  return ok(new Project(name));
}
```

### Side effects in function names

Functions with network calls or file writes must name the side effect.

```typescript
// do this:  fetchPricing(), writeSummaryToFile()
// not this: getPricing(), generateSummary()
```

````

Each convention is independently parseable: heading, rule, example.

### Rule: Resolve variation at the point of use

When a step drives several similar items that each take a slightly different set of inputs — dispatching sub-agents with different reference files, applying rules each scoped to different files — do not express the variation as a matrix the model must join against a separate list. Reading a table, extracting each item's cells, and binding them to a separate enumeration makes the model do an in-head join. That such a join trips the model is a reasoned bet — by analogy to documented weaknesses in large-table lookup and multi-hop binding, though no study tests it at this small a scale — so prefer to remove the join rather than rely on the model to get it right. Give each item its resolved, self-contained set instead.

Keep the _source_ normalized — author the shared parts once — but denormalize into the point of use, resolving the variation with a deterministic step (a script, or the driver that assembles each dispatch) where one exists. This does not contradict [Progressive Disclosure](./progressive-disclosure.md): a reference resolved by a Read co-locates its content at the point of use, so it is not an in-head join. See [Context Hygiene](./context-hygiene.md) for the loadable-pointer vs. in-head-reference distinction.

**Before (variation as a matrix the model must join):**

```markdown
## Step 4: Dispatch Reviewers

Files each reviewer receives:

| Reviewer | api.ts | schema.sql | auth.ts |
|---|---|---|---|
| security | no | no | yes |
| data | no | yes | no |
| api | yes | no | no |

Prompts:
1. Review for injection and authz.
2. Review schema normalization and indexes.
3. Review endpoint contracts.
```

The model must read the matrix, extract each reviewer's "yes" columns, and bind them to the right numbered prompt before
it can dispatch anything.

**After (each item resolved and self-contained):**

```markdown
## Step 4: Dispatch Reviewers

Dispatch one reviewer per block. Each block lists exactly what that reviewer gets:

### security reviewer

- Files: `auth.ts`
- Prompt: Review for injection and authz.

### data reviewer

- Files: `schema.sql`
- Prompt: Review schema normalization and indexes.

### api reviewer

- Files: `api.ts`
- Prompt: Review endpoint contracts.
```

Nothing to join: each reviewer's files and prompt sit together.

At small scale — two or three items, two or three inputs, no growth — a compact table you or a script reads once while
assembling each item is fine; the join cost lands on an LLM only when the model itself must resolve the matrix at read
time. Reach for resolved, self-contained items as the count of items and varying inputs grows.

### Rule: Include canonical examples for conventions the skill enforces

When a skill teaches or enforces patterns, include 2-3 representative "do this / not this" examples. The model
pattern-matches examples more reliably than it follows abstract rules — research shows 3 well-chosen examples match 9 in
effectiveness. Place the most representative example last — the model weights it more heavily. Put examples in
`references/` if they are substantial (following the progressive disclosure model), or inline in SKILL.md if they are
brief (1-3 lines each).

**Before (rule stated without examples):**

```markdown
## Step 4: Check Naming Conventions

Verify that all new functions follow the project's naming conventions:

- Use camelCase for functions and variables
- Use PascalCase for classes and types
- Prefix boolean variables with is/has/should
- Prefix event handlers with handle
```

The model knows the _rules_ but has no demonstrations to pattern-match against.

**After (rule with canonical examples):**

```markdown
## Step 4: Check Naming Conventions

Verify that all new functions follow the project's naming conventions:

**camelCase for functions and variables:**

- `getUserById`, `totalCount`, `isValid`

**PascalCase for classes and types:**

- `UserService`, `ApiResponse`, `ValidationError`

**Prefix boolean variables with is/has/should:**

- not this: `active`, `loaded`, `visible`
- do this: `isActive`, `hasLoaded`, `isVisible`

**Prefix event handlers with handle:**

- not this: `clickSubmit`, `changeInput`
- do this: `handleSubmitClick`, `handleInputChange`
```

### Rule: Use scripts for deterministic validation

When a step requires deterministic validation — checking file formats, verifying data integrity, running calculations —
use a shell script instead of asking Claude to interpret natural language instructions about what to check. Code
produces consistent results; language interpretation varies.

**Before (language-based validation):**

```markdown
## Step 4: Validate the Output

Check that the generated file:

- Has valid JSON syntax
- Contains all required fields
- Has no duplicate keys
- File size is under 1MB
```

**After (script-based validation):**

```markdown
## Step 4: Validate the Output

Run `scripts/validate-output.sh {output_file}` to verify JSON syntax, required fields, duplicate keys, and file size.

If validation fails, the script prints which checks failed. Fix each issue before proceeding.
```

## Summary Checklist

1. Every instruction tells Claude exactly what to do — no vague directives
2. Error handling instructions cover what to do when steps fail
3. Reference bundled resources by exact path with explanation of contents and usage
4. Keep SKILL.md focused on process steps — extract domain knowledge to `references/`
5. Use numbered lists and bullet points — avoid long prose paragraphs
6. Put critical instructions at the top, not buried mid-step
7. Replace ambiguous language with specific, testable criteria
8. Use scripts for deterministic validation instead of language instructions
9. After Skill tool calls mid-workflow, explicitly instruct Claude to proceed immediately — never rely on implicit
   continuation
10. Can an agent extract every convention from this SKILL.md without ambiguity? If a section requires inference about
    where one instruction ends and the next begins, restructure it
11. When a step drives several varying items, give each its resolved, self-contained inputs — don't make the model join
    a matrix against a separate list

Cross-references:

- [Progressive Disclosure](./progressive-disclosure.md) — The three-level architecture that determines where content
  belongs
- [Skill Reference Files](./skill-reference-files.md) — How to structure and place reference documents
- [Context Injection Commands](./context-injection-commands.md) — How to inject runtime data into instructions
- [Skill Composition](./skill-composition.md) — `context: fork` for data-fetch sub-skills; necessary but not sufficient
  for continuation
- [Context Hygiene](./context-hygiene.md) — Why conciseness is a performance concern, not just a style preference

{
  "name": "example-marketplace",
  "description": "An example marketplace demonstrating all available marketplace.json fields",
  "version": "1.0.0",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "pluginRoot": "./plugins",
    "description": "Alternate description location (merged with root description)",
    "version": "1.0.0"
  },
  "allowCrossMarketplaceDependenciesOn": ["other-internal-marketplace", "partner-tools-marketplace"],
  "plugins": [
    {
      "name": "relative-path-plugin",
      "displayName": "Relative Path Plugin",
      "source": "./relative-path-plugin",
      "description": "A plugin loaded from a relative path within this repository",
      "version": "1.2.0",
      "defaultEnabled": true,
      "author": {
        "name": "Your Name",
        "email": "you@example.com"
      },
      "homepage": "https://github.com/your-org/your-plugin",
      "repository": "https://github.com/your-org/your-plugin",
      "license": "MIT",
      "keywords": ["example", "relative"],
      "category": "productivity",
      "tags": ["reference", "template"],
      "strict": true,
      "skills": "./skills/",
      "commands": "./commands/",
      "agents": "./agents/",
      "hooks": "./hooks/hooks.json",
      "mcpServers": {
        "example-server": {
          "command": "${CLAUDE_PLUGIN_ROOT}/servers/example-server",
          "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
        }
      },
      "lspServers": "./.lsp.json"
    },
    {
      "name": "github-plugin",
      "source": {
        "source": "github",
        "repo": "your-org/example-claude-plugin",
        "ref": "v2.0.0",
        "sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
      },
      "description": "A plugin loaded from a GitHub repository at a pinned tag and SHA",
      "version": "2.0.0",
      "author": {
        "name": "Your Name",
        "email": "you@example.com"
      },
      "homepage": "https://github.com/your-org/example-claude-plugin",
      "repository": "https://github.com/your-org/example-claude-plugin",
      "license": "Apache-2.0",
      "keywords": ["github", "example"],
      "category": "developer-tools",
      "tags": ["ci", "automation"],
      "strict": true
    },
    {
      "name": "url-plugin",
      "source": {
        "source": "url",
        "url": "https://gitlab.com/example-org/claude-plugin.git",
        "ref": "main",
        "sha": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3"
      },
      "description": "A plugin loaded from a non-GitHub git host",
      "version": "0.9.0",
      "author": {
        "name": "Example Org",
        "email": "team@example-org.com"
      },
      "homepage": "https://gitlab.com/example-org/claude-plugin",
      "repository": "https://gitlab.com/example-org/claude-plugin",
      "license": "MIT",
      "keywords": ["gitlab", "url-source"],
      "category": "utilities",
      "tags": ["external"],
      "strict": false
    },
    {
      "name": "monorepo-plugin",
      "source": {
        "source": "git-subdir",
        "url": "https://github.com/your-org/internal-monorepo.git",
        "path": "tools/claude-plugin",
        "ref": "v1.5.0",
        "sha": "c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
      },
      "description": "A plugin sourced from a subdirectory of a monorepo using sparse checkout",
      "version": "1.5.0",
      "author": {
        "name": "Your Name",
        "email": "you@example.com"
      },
      "homepage": "https://github.com/your-org/internal-monorepo",
      "repository": "https://github.com/your-org/internal-monorepo",
      "license": "MIT",
      "keywords": ["monorepo", "git-subdir"],
      "category": "internal",
      "tags": ["sparse-checkout"],
      "strict": true
    },
    {
      "name": "npm-plugin",
      "source": {
        "source": "npm",
        "package": "@your-scope/claude-plugin-example",
        "version": "^3.0.0",
        "registry": "https://registry.npmjs.org"
      },
      "description": "A plugin distributed as an npm package with a semver range",
      "version": "3.1.0",
      "author": {
        "name": "Your Name",
        "email": "you@example.com"
      },
      "homepage": "https://www.npmjs.com/package/@your-scope/claude-plugin-example",
      "repository": "https://github.com/your-org/claude-plugin-example",
      "license": "MIT",
      "keywords": ["npm", "package"],
      "category": "developer-tools",
      "tags": ["published"],
      "strict": true
    }
  ]
}

[
  {
    "name": "deploy-status",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Polls the deployment API for status changes and notifies Claude when a deploy completes or fails"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Streams application error log entries so Claude can surface new errors in real time",
    "when": "on-skill-invoke:debug"
  },
  {
    "name": "build-watcher",
    "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && ./scripts/watch-build.sh",
    "description": "Watches the build system for failures and reports them as notifications",
    "when": "on-skill-invoke:run-build"
  },
  {
    "name": "data-dir-changes",
    "command": "fswatch \"${CLAUDE_PLUGIN_DATA}\"",
    "description": "Monitors the plugin persistent data directory for file changes between sessions",
    "when": "always"
  }
]

{
  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
  "name": "example-plugin",
  "displayName": "Example Plugin",
  "version": "1.0.0",
  "description": "An example plugin demonstrating all available plugin.json fields",
  "defaultEnabled": true,
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://github.com/your-org/your-plugin",
  "repository": "https://github.com/your-org/your-plugin",
  "license": "MIT",
  "keywords": ["example", "reference", "template"],
  "skills": ["./skills/", "./extra-skills/"],
  "commands": "./commands/",
  "agents": "./agents/",
  "hooks": "./hooks/hooks.json",
  "mcpServers": {
    "example-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/example-server",
      "args": ["--data-dir", "${CLAUDE_PLUGIN_DATA}", "--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./output-styles/",
  "experimental": {
    "monitors": "./monitors/monitors.json",
    "themes": "./themes/"
  },
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API Endpoint",
      "description": "Base URL for the API this plugin connects to",
      "required": true,
      "default": "https://api.example.com"
    },
    "api_token": {
      "type": "string",
      "title": "API Token",
      "description": "Authentication token for the API",
      "sensitive": true,
      "required": true
    },
    "allowed_environments": {
      "type": "string",
      "title": "Allowed Environments",
      "description": "Comma-separated list of deployment environments this plugin may target",
      "multiple": true,
      "default": "staging"
    },
    "max_retries": {
      "type": "number",
      "title": "Max Retries",
      "description": "Number of times to retry failed requests before giving up",
      "min": 0,
      "max": 10,
      "default": 3
    },
    "verbose_logging": {
      "type": "boolean",
      "title": "Verbose Logging",
      "description": "Enable detailed logging output for debugging",
      "default": false
    },
    "config_file": {
      "type": "file",
      "title": "Config File",
      "description": "Path to an optional local config file to merge with plugin defaults"
    },
    "workspace_dir": {
      "type": "directory",
      "title": "Workspace Directory",
      "description": "Directory where the plugin stores working files"
    }
  },
  "channels": [
    {
      "server": "example-server",
      "userConfig": {
        "channel_name": {
          "type": "string",
          "title": "Slack Channel Name",
          "description": "Name of the Slack channel to post notifications to",
          "required": true,
          "default": "#deployments"
        }
      }
    }
  ],
  "dependencies": ["helper-lib", { "name": "secrets-vault", "version": "~2.1.0" }]
}

# {Plugin Name} Plugin

{One paragraph: what this plugin does, how it does it, and why a reader would reach for it. Keep it to a paragraph. The
per-skill detail lives in each skill's long-form doc under `docs/skills/`, not here.}

{Bundled-vs-opt-in and dependencies. Pick one shape:}

**Bundled.** Installed with the `han` meta-plugin. Depends on `{dependency}`{, `{dependency}`}.

<!-- or -->

**Opt-in.** Installed on its own, not bundled by the `han` meta-plugin. Depends on `{dependency}`{ and requires a
configured {MCP server} MCP server}.

<!-- Optional: one short ordered line only when skills build on each other's output
     (one skill writes a reference file a later skill consumes). Skip it for
     independent-skill plugins. -->

**Getting started:** run [`/first-skill`](docs/skills/first-skill.md) to {produce X}, then
[`/second-skill`](docs/skills/second-skill.md) to {consume it}.

## Skills

<!-- One scent line per skill. Reuse the long-form doc's own canonical summary line;
     do not write a fresh one. No per-skill paragraph, files line, or example prompts. -->

- [`/skill-name`](docs/skills/skill-name.md) — {canonical summary line from the long-form doc}
- [`/another-skill`](docs/skills/another-skill.md) — {canonical summary line from the long-form doc}

<!-- Owned agents: include this section ONLY for han-core, han-communication, and han-research.
     Every other plugin omits it and uses the shared-agent-dispatch note below instead. -->

## Agents

- [`agent-name`](docs/agents/agent-name.md) — {canonical summary line from the long-form doc}

<!-- Shared-agent-dispatch note: for every plugin that owns no agents (all except
     han-core, han-communication, and han-research), use this line in place of an Agents section. -->

Its skills dispatch shared agents that live in `han-core` (and, for the readability-editor, in `han-communication`).

## Installation

Add your marketplace to Claude Code, then install the plugin:

```
/plugin marketplace add your-org/your-marketplace
/plugin install {plugin-name}@your-marketplace
```

---

[Plugin index](../docs/choosing-a-han-plugin.md) · [Repo root](../README.md) · [Workflows](../docs/workflows.md)

{
  "name": "Example Theme",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "text": "#f8f8f2",
    "inverseText": "#282a36",
    "inactive": "#6272a4",
    "subtle": "#44475a",
    "permission": "#ffb86c",
    "remember": "#8be9fd",

    "success": "#50fa7b",
    "error": "#ff5555",
    "warning": "#ffb86c",
    "merged": "#bd93f9",

    "promptBorder": "#6272a4",
    "planMode": "#ffb86c",
    "autoAccept": "#50fa7b",
    "bashBorder": "#ff79c6",
    "ide": "#8be9fd",
    "fastMode": "#f1fa8c",

    "diffAdded": "#14532d",
    "diffRemoved": "#7f1d1d",
    "diffAddedDimmed": "#052e16",
    "diffRemovedDimmed": "#450a0a",
    "diffAddedWord": "#16a34a",
    "diffRemovedWord": "#dc2626",

    "userMessageBackground": "#1e1b4b",
    "selectionBg": "#44475a",

    "claudeShimmer": "#caa9fa",
    "successShimmer": "#69fb8f",
    "errorShimmer": "#ff7777",
    "warningShimmer": "#ffc97a",
    "mergedShimmer": "#caa9fa",
    "planModeShimmer": "#ffc97a",
    "autoAcceptShimmer": "#69fb8f",
    "bashBorderShimmer": "#ff93d4",
    "ideShimmer": "#a5eeff",
    "fastModeShimmer": "#f5fc9a",

    "red_FOR_SUBAGENTS_ONLY": "#ff5555",
    "blue_FOR_SUBAGENTS_ONLY": "#8be9fd",
    "green_FOR_SUBAGENTS_ONLY": "#50fa7b",
    "yellow_FOR_SUBAGENTS_ONLY": "#f1fa8c",
    "purple_FOR_SUBAGENTS_ONLY": "#bd93f9",
    "orange_FOR_SUBAGENTS_ONLY": "#ffb86c",
    "pink_FOR_SUBAGENTS_ONLY": "#ff79c6",
    "cyan_FOR_SUBAGENTS_ONLY": "#8be9fd"
  }
}