# Cross-Skill Composition

How skills depend on, invoke, and fan out to other skills.

## Contents

- Cross-Skill Dependencies
- Explicitly Invoke Skills When the Verb Matches a Skill Name
- Keep One Concern's Fan-Out Inside One Skill

## Cross-Skill Dependencies

When a skill depends on another skill, make it an explicit numbered step. Use "Run `/skill-name` Skill" as the heading and "Run the `/skill-name` skill" in the step body. Including "skill" signals to invoke via the Skill tool rather than treating it as a general reference.

```markdown
## Step 1: Run `/<rules-skill>` Skill

Run the `/<rules-skill>` skill to load shared rules and conventions.

## Step 2: Do the Work

- The actual steps of this skill
```

**Style-guide dependencies get their own step, placed late:** When a skill depends on a style-guide skill that loads conventions, give the load its own discrete instruction: a numbered step, or a numbered item in an ordered list. Burying it in a paragraph of prose is what makes it skippable.

Place it before the first step the guide governs, with no work-producing step in between. In a short skill that is Step 1, as in the example above. In a longer one it lands later. Loading at Step 1 anyway can put the load ahead of the values it depends on: a guide that inspects an artifact needs the step that fetches that artifact to have run first, or it silently takes a fallback path. Late placement also skips the load entirely on runs that exit before the governed output is produced. When the governed output lives inside a conditional branch, the load is the first line of that branch.

- ✗ **Avoid**: A six-step skill loads the style guide at Step 1, gathers context through Step 5, then drafts at Step 6.
- ✓ **Good**: The same skill gathers context through Step 4, loads the style guide at Step 5, then drafts at Step 6.

Late placement has a floor: the load still precedes any step whose condition the guide defines. A step that tests for the presence, location, or shape of something the guide specifies is governed by that guide even though it produces no output of its own. Run it first and it resolves against a default the guide would have overridden, so the skill exits as a silent no-op on exactly the projects that customized that detail. Moving a cheap check ahead of an expensive load is safe only when the check's subject is fixed independently of what the guide defines.

- ✗ **Avoid**: A skill checks whether the target artifact exists, exits when it does not, and loads the style guide that defines where that artifact lives afterward.
- ✓ **Good**: The same skill loads the style guide first, then applies the existence check to the location the guide resolves.

## Explicitly Invoke Skills When the Verb Matches a Skill Name

When a step body uses an action verb that is also the name of an existing skill, the bare verb reads as inline reasoning and the agent skips the actual Skill tool call. Name the skill explicitly so the invocation is unambiguous.

- ✗ **Avoid**: "If a check fails, halt and `<verb>`."
- ✓ **Good**: "If a check fails, run the `/<verb>` skill."

This complements the explicit numbered-step rule above by covering verb collisions inside step bodies.

## Keep One Concern's Fan-Out Inside One Skill

When a workflow needs N parallel reviewers/dimensions/perspectives (e.g., internal review + peer review, or multiple review types in one pass), put the fan-out inside one skill body rather than splitting it across sibling skills that a parent loads "in parallel" via the Skill tool. Splitting one fan-out across siblings leaks their implementation details into the parent step.

The right shape is a single skill that emits N+1 Agent tool calls in one message. Add an opt-out (e.g., "skip peer review") for runs that want only the internal pass.

- ✗ **Avoid**: Parent skill Step says "Run `/<review-skill>` and `/<peer-review-skill>` skills concurrently", leaving neither sibling able to cover the concern alone.
- ✓ **Good**: `/<review-skill>` internally launches both internal reviewer Agents and a peer reviewer Agent in one message; the parent just calls `/<review-skill>`.

A parent may batch Skill calls when each sibling already fans out on its own and covers a distinct concern. A Skill call only loads instructions into the current context, so batching two lands both bodies in the same agent, which then emits every sibling's Agent call in one message. Keep such a parent to the scope it resolves and the ordering it imposes, and leave each sibling's criteria in the sibling.

- ✓ **Good**: `/<combined-skill>` batches the Skill calls for `/<code-skill>` and `/<docs-skill>`, launches every agent both define in one message, then applies a single round of fixes.

# Evaluation and Iteration

How to validate that a skill actually works and refine it from observed behavior.

## Contents

- Build Evaluations First
- Develop Skills Iteratively with Claude
- Observe How Claude Navigates Skills

## Build Evaluations First

**Create evaluations BEFORE writing extensive documentation.** This ensures your Skill solves real problems rather than documenting imagined ones.

**Evaluation-driven development:**

1. **Identify gaps**: Run Claude on representative tasks without a Skill. Document specific failures or missing context
2. **Create evaluations**: Build three scenarios that test these gaps
3. **Establish baseline**: Measure Claude's performance without the Skill
4. **Write minimal instructions**: Create just enough content to address the gaps and pass evaluations
5. **Iterate**: Execute evaluations, compare against baseline, and refine

This approach ensures you're solving actual problems rather than anticipating requirements that may never materialize.

**Evaluation structure**: name the skills under test, the query, any input files, and a list of expected behaviors specific enough to grade against.

```json
{
  "skills": ["<skill-name>"],
  "query": "<the request a user would actually make>",
  "files": ["<input file path>"],
  "expected_behavior": [
    "<observable behavior 1, stated specifically enough to grade>",
    "<observable behavior 2>",
    "<observable behavior 3>"
  ]
}
```

> **Note:** This example demonstrates a data-driven evaluation with a simple testing rubric. There is not currently a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness.

## Develop Skills Iteratively with Claude

The most effective Skill development process involves Claude itself. Work with one instance ("Claude A") to design and refine the Skill, and test it with a fresh instance ("Claude B") on real tasks. Claude A understands agent needs; Claude B reveals gaps through real usage.

1. **Complete a task without a Skill** with Claude A. Notice what context you repeatedly provide.
2. **Ask Claude A to create the Skill**, capturing that context. Claude understands the Skill format natively and will generate properly structured SKILL.md content.
3. **Review for conciseness** and information architecture. Ask Claude A to remove explanations Claude already knows, and to split reference content into separate files when it grows.
4. **Test with Claude B** (a fresh instance with the Skill loaded) on related tasks. Observe whether it finds the right information, applies rules correctly, and succeeds.
5. **Return to Claude A with specifics** when Claude B struggles: "It forgot to filter by date — should we make that more prominent?" Apply refinements, then test again.
6. **Gather team feedback**: share with teammates and ask whether the Skill activates when expected, whether instructions are clear, and what's missing.

## Observe How Claude Navigates Skills

As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:

- **Unexpected exploration paths**: Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
- **Missed connections**: Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent
- **Overreliance on certain sections**: If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
- **Ignored content**: If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions

Iterate based on these observations rather than assumptions. The `name` and `description` in your Skill's metadata are particularly critical. Claude uses these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.

# Harness Reference

Quick reference for the Claude Code harness: canonical tool names, limits, and discovery paths.

**Tools (canonical names):**

- `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` — task tracking. Statuses: `pending`, `in_progress`, `completed`, plus `deleted` for removal. Tasks support `owner`, `blocks` / `blockedBy`, and arbitrary `metadata`.
- `AskUserQuestion` — structured user prompts. 1-4 questions per call, 2-4 options per question, "Other" free-form option appended automatically.
- `Edit` / `Write` / `Read` / `NotebookEdit` — file operations. `Edit` requires the file to be read first.
- `Bash` — shell execution; supports `run_in_background` for long-running commands.
- `Skill tool` — invoke an installed skill by name.
- `Agent tool` — spawn a sub-agent. The `subagent_type` field selects a specialized agent (built-ins include `Explore`, `Plan`, `general-purpose`, plus user-defined types). Generic sub-agents accept a `model` override. The `name` field makes the sub-agent an addressable teammate, which changes how its result is delivered; see Never Name a Spawned Agent in `tools.md`.
- `SendMessage` — message another agent by name, or by the raw `agent_id` from its spawn result when it has no name. Background sub-agents can also message `main`.

**Sub-agents:** No documented hard cap on count or nesting; pragmatic limits are whatever the parent context can manage. Sub-agents inherit the parent model unless `model` is specified. Specialized agents have restricted tool subsets defined per agent type.

**Permission modes:** `default`, `acceptEdits`, `plan`, `bypassPermissions`, `dontAsk`. Set via `--permission-mode`, `/permissions`, or per-tool allow-lists. `plan` mode blocks writes until plan approval.

**Skill discovery:**

- User-scope: `~/.claude/skills/`.
- Project-scope: `.claude/skills/` (cwd).
- Skills invoked as `/skill-name`; `SKILL.md` frontmatter requires `name` and `description`.

**CLAUDE.md hierarchy:** Auto-loaded from each ancestor of the cwd up through the home directory. Project-root `CLAUDE.md` is the canonical project instruction file; `~/.claude/CLAUDE.md` is the user-global file.

**Hook system:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, and others. Configured under `hooks` in `~/.claude/settings.json` or `.claude/settings.json`.

**Config:** `~/.claude/settings.json` (user) and `.claude/settings.json` (project, with `.local` variants for gitignored overrides).

# Core Principles

Foundational decisions that apply to every skill: what to include, what to leave out, and how much freedom to give the agent.

## Contents

- Concise Is Key
- Skill Files Are Instructions, Not Documentation
- Retire the Guardrail a New Rule Makes Unreachable
- Set Appropriate Degrees of Freedom
- Test with All Models You Plan to Use

## Concise Is Key

The context window is a public good. Your Skill shares the context window with everything else Claude needs to know, including:

- The system prompt
- Conversation history
- Other Skills' metadata
- Your actual request

Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.

**Default assumption**: Claude is already very smart

Only add context Claude doesn't already have. Challenge each piece of information:

- "Does Claude really need this explanation?"
- "Can I assume Claude knows this?"
- "Does this paragraph justify its token cost?"

Give the instruction and the minimum needed to act on it. Background on what a format is, why a library is popular, or how to install a standard tool is almost always cuttable — a concise instruction that costs 50 tokens routinely expands to 150 when padded with that kind of preamble.

## Skill Files Are Instructions, Not Documentation

A skill file tells Claude what to do. It is not a place to explain what the skill is, why it exists, how it fits into the broader collection, or what its design history is. Claude does not benefit from narrator prose — a human reader might, but skills are loaded into an agent's context, not read by humans at design time.

Common drift patterns to strip on sight:

- **Meta-framing** — sentences that describe the skill file to its own reader: "This SKILL.md is the router...", "This skill wraps X with Y...", "This file acts as..." If Claude is reading the file, it already knows it's reading the file.
- **Cross-skill commentary** — "This skill is the sibling/counterpart/successor of /other-skill." Skills should be self-contained and not reference which pipelines call them or which siblings they relate to.
- **Marketing or positioning copy** — "X is the structured alternative to Y" or "X is the preferred way to do Z." That kind of framing belongs in a README, not a skill file.
- **Architecture commentary** — explaining the data model or file layout as standalone prose when the instructions already imply the structure. If the steps tell Claude to "write the index to `<path>`," a separate sentence saying "the index is a thin manifest" adds nothing.
- **Historical rationale** — "X happens here because Y would cause Z." Keep only the rule; drop the backstory unless it actively prevents a rationalization the agent would otherwise make.
- **Tautological boundary statements** — "X is Y's job; this skill only does Z." If the positive instructions are correct, boundaries are already implicit.
- **"Caller" phrasing** — "the caller," "caller passed," "caller provides." Skills run in a conversational context, not a function-call context. This is narrator language about who invoked the skill rather than instruction to the agent, and it is ambiguous about whether "the caller" is the user, another skill, or the pipeline agent. Prefer passive voice ("if a plan path was provided") or a named role when the distinction actually matters.

When in doubt, compare a new or edited skill against the simplest existing skills in the same collection. If a lean neighbor skill opens with a one-line purpose and jumps straight into Task Tracking or Step 1, and your skill has three paragraphs of context before the first instruction, the extra paragraphs are almost certainly drift.

## Retire the Guardrail a New Rule Makes Unreachable

Much of a skill's text is a guardrail: it compensates for a failure mode, for a mode the agent might select, or for a behavior of the surrounding machinery. A change that removes what a guardrail compensates for leaves that guardrail unreachable — and unreachable text survives review, because it still reads as sound advice.

Run the check at the moment a rule is added or changed rather than as a later cleanup pass. Name what each guardrail near the change was compensating for, then establish whether that condition can still arise. When it cannot, delete the guardrail in the same edit. Sweep the skill's reference files alongside the file being edited, since a rule in one routinely guards a condition described in another.

The tell is a change that removes the condition rather than discouraging it: the harness no longer exposes the mode, the interface no longer accepts the input, or the new rule strips the precondition the guardrail needs, leaving it nothing to fire on in any run that follows the rule.

Keep the guardrail when the condition survives the rule. A prohibition constrains what the agent should do without removing what it can do, so anything guarding against the agent's own drift stays, as does every fallback for a cause the rule does not reach: harness errors, unavailable tools, and the divergences a project records deliberately.

## Set Appropriate Degrees of Freedom

Match the level of specificity to the task's fragility and variability.

**High freedom** (text-based instructions):

Use when:

- Multiple approaches are valid
- Decisions depend on context
- Heuristics guide the approach

The instruction names the objective and the checks that matter, leaving sequencing and technique to the agent.

**Medium freedom** (pseudocode or scripts with parameters):

Use when:

- A preferred pattern exists
- Some variation is acceptable
- Configuration affects behavior

The instruction supplies a template or a parameterized signature and says to customize as needed.

**Low freedom** (specific scripts, few or no parameters):

Use when:

- Operations are fragile and error-prone
- Consistency is critical
- A specific sequence must be followed

The instruction gives an exact command and states that it must not be modified or extended with additional flags.

## Test with All Models You Plan to Use

Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with each model you plan to use — what works for Opus may need more guidance for Haiku, and what's clear for Haiku may over-explain for Opus.

# Skills with Executable Code

Rules for Skills that bundle executable scripts alongside their instructions.

## Contents

- Solve, Don't Punt
- Provide Utility Scripts
- Use Visual Analysis
- Create Verifiable Intermediate Outputs
- Package Dependencies
- Runtime Environment

## Solve, Don't Punt

When writing scripts for Skills, handle error conditions rather than punting to Claude.

**Good example: Handle errors explicitly**:

```python
def process_file(path):
    """Process a file, creating it if it doesn't exist."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Create file with default content instead of failing
        print(f"File {path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""
    except PermissionError:
        # Provide alternative instead of failing
        print(f"Cannot access {path}, using default")
        return ""
```

**Bad example: Punt to Claude**:

```python
def process_file(path):
    # Just fail and let Claude figure it out
    return open(path).read()
```

Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it?

**Good example: Self-documenting**:

```python
# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3
```

**Bad example: Magic numbers**:

```python
TIMEOUT = 47  # Why 47?
RETRIES = 5  # Why 5?
```

## Provide Utility Scripts

Pre-made scripts are more reliable than generated code, save tokens (no need to include code in context), and ensure consistency. Claude can execute them without loading their contents into context.

Make clear whether Claude should **execute** the script (most common: "Run `analyze.py` to extract fields") or **read it as reference** for complex logic. Prefer execution.

Document each script with its invocation line and, when the script emits structured data another step consumes, the shape of its output. Without the output shape, the consuming step has to run the script just to discover what it produces.

## Use Visual Analysis

When inputs can be rendered as images, have Claude analyze them: convert the input to images with a bundled script, then read the images to identify structure and layout. Claude's vision capabilities help understand layouts and structures that are awkward to extract programmatically.

## Create Verifiable Intermediate Outputs

For batch operations, destructive changes, or high-stakes work, use the **plan-validate-execute** pattern: Claude first creates a plan in a structured format (e.g., `changes.json`), a script validates the plan against reality, and only then is the plan executed. The workflow becomes: analyze → create plan file → validate plan → execute → verify.

This catches errors before any changes are applied, and lets Claude iterate on the plan without touching originals. Make validation errors specific ("Field 'signature_date' not found. Available fields: customer_name, order_total") so Claude can fix issues without guessing.

## Package Dependencies

Don't assume packages are available. Declare them explicitly with install commands: give the install line first, then the usage.

- ✗ **Avoid**: "Use the <library> library to process the file."
- ✓ **Good**: "Install required package: `<install command>`" followed by the usage snippet.

Skills run in the code execution environment with platform-specific limitations:

- **claude.ai**: Can install packages from npm and PyPI and pull from GitHub repositories
- **Claude API**: Has no network access and no runtime package installation

List required packages in your SKILL.md and verify they're available in your execution environment.

## Runtime Environment

- **Scripts produce output, not context**: Utility scripts can be executed via bash without loading their contents into context. Only the script's output consumes tokens.
- **Name files descriptively**: Use names that indicate content: `form_validation_rules.md`, not `doc2.md`
- **Bundle comprehensive resources**: Include complete API docs, extensive examples, large datasets; no context penalty until accessed
- **Test file access patterns**: Verify Claude can navigate your directory structure by testing with real requests

# Skill Reviewer Guidelines

Review and improve skills for maximum effectiveness and reliability.

## Contents

- Review Process
  - 1. Locate and Read Skill
  - 2. Validate Structure
  - 3. Evaluate Description (Most Critical)
  - 4. Assess Content Quality
  - 5. Check Progressive Disclosure
  - 6. Review Supporting Files (if present)
  - 7. Identify Issues
- Quality Standards
- Output Format
  - Summary
  - Description Analysis
  - Content Quality
  - Progressive Disclosure
  - Issues by Severity
  - Positive Aspects
  - Overall Rating
  - Priority Recommendations

## Review Process

### 1. Locate and Read Skill

- Find SKILL.md file
- Read frontmatter and body content
- Check for supporting directories (references/, scripts/, assets/)

### 2. Validate Structure

- Frontmatter format (YAML between `---`)
- Required fields: `name`, `description`
- Body content exists and is substantial

### 3. Evaluate Description (Most Critical)

- **Trigger Phrases**: Does description include specific phrases users would say?
- **Third Person**: Avoids first/second person ("I can help you", "You can use this"). Imperative form ("Use when...") is fine.
- **Specificity**: Concrete scenarios, not vague
- **Length**: Appropriate (not too short <50 chars, not too long >1024 chars for description)
- **Example Triggers**: Lists specific user queries that should trigger skill

### 4. Assess Content Quality

- **Line Count**: SKILL.md body should be under 500 lines (lean, focused)
- **Writing Style**: Imperative/infinitive form ("To do X, do Y" not "You should do X")
- **Instructions vs documentation**: Every paragraph should tell the agent what to do. Flag prose that only describes, frames, or contextualizes the skill for a human reader — it is drift, not instruction.
- **Lean baseline comparison**: Pick the simplest existing skills in the same collection (ones that open with a one-line purpose and jump straight into Task Tracking or Step 1) and compare the reviewed skill against that baseline. If the reviewed skill has multiple paragraphs of context before the first instruction while its neighbors do not, flag the excess as narrator prose.
- **Organization**: Clear sections, logical flow
- **Specificity**: Concrete guidance, not vague advice

### 5. Check Progressive Disclosure

- **Core SKILL.md**: Essential information only
- **references/**: Detailed docs moved out of core
- **scripts/**: Utility scripts if needed
- **assets/**: Output resources separate from documentation
- **Pointers**: SKILL.md references these resources clearly

### 6. Review Supporting Files (if present)

- **references/**: Check quality, relevance, organization
- **scripts/**: Check scripts are executable and documented
- **assets/**: Verify assets are used and referenced

### 7. Identify Issues

Categorize by severity (critical/major/minor).

Anti-patterns to watch for:
- Vague trigger descriptions
- Too much content in SKILL.md (should be in references/)
- First/second person in description ("I can help you", "You can use this")
- Missing key triggers
- No references when they'd be valuable
- **Narrator prose**: meta-framing that explains the file to its own reader ("This SKILL.md is the router..."), cross-skill commentary ("This is the sibling of /other-skill"), marketing copy ("X is the structured alternative to Y"), architecture commentary that restates what the instructions already convey, historical rationale, and tautological boundary statements ("X is Y's job; this skill only does Z")
- **"Step 0" as mode detection**: a numbered step that only inspects caller input or picks a mode. Should be folded into the opening prose, not given a step heading

## Quality Standards

- Description must have strong, specific trigger phrases
- SKILL.md should be lean (under 500 lines)
- Writing style must be imperative/infinitive form
- Progressive disclosure properly implemented
- All file references work correctly

## Output Format

When reviewing a skill, produce a report with:

### Summary
Overall assessment and word counts.

### Description Analysis
- Current description
- Issues found
- Recommended improvements (with suggested text)

### Content Quality
- Line count assessment
- Writing style assessment
- Organization assessment

### Progressive Disclosure
- Current structure (file counts, word counts)
- Assessment of whether disclosure is effective
- Recommendations for better organization

### Issues by Severity

#### Critical
Issues that prevent the skill from working correctly.

#### Major
Issues that significantly reduce skill effectiveness.

#### Minor
Polish and optimization suggestions.

### Positive Aspects
What the skill does well.

### Overall Rating
Pass / Needs Improvement / Needs Major Revision

### Priority Recommendations
Top 3 fixes ordered by impact.

# Skill Metadata and Structure

Frontmatter rules, naming, and how to lay out a skill directory so Claude loads only what it needs.

## Contents

- YAML Frontmatter
- Naming Conventions
- Writing Effective Descriptions
- Progressive Disclosure Patterns
- Avoid Deeply Nested References
- Separation of Concerns Between Layers
- Use Forward Slashes in Paths
- Compute Relative Paths from the File's Actual Location
- Structure Longer Reference Files with Table of Contents

## YAML Frontmatter

The SKILL.md frontmatter requires two fields:

`name`:

- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"

`description`:

- Must be non-empty
- Maximum 1024 characters
- Cannot contain XML tags
- Should describe what the Skill does and when to use it

**Quoting values**: Quote frontmatter values that contain YAML special characters. Unquoted `: ` (colon-space) breaks parsing. When in doubt, wrap the value in double quotes and escape inner quotes with `\"`.

```yaml
# Bad — colon-space breaks YAML parsing
description: Handles two modes: draft and final

# Good — quoted value
description: "Handles two modes: draft and final"
```

## Naming Conventions

Use consistent naming patterns to make Skills easier to reference and discuss. Consider using **gerund form** (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.

Remember that the `name` field must use lowercase letters, numbers, and hyphens only.

**Good naming examples (gerund form)**:

- `processing-pdfs`
- `analyzing-spreadsheets`
- `managing-databases`
- `testing-code`
- `writing-documentation`

**Acceptable alternatives**:

- Noun phrases: `pdf-processing`, `spreadsheet-analysis`
- Action-oriented: `process-pdfs`, `analyze-spreadsheets`

**Avoid**:

- Vague names: `helper`, `utils`, `tools`
- Overly generic: `documents`, `data`, `files`
- Reserved words: `anthropic-helper`, `claude-tools`
- Inconsistent patterns within your skill collection

## Writing Effective Descriptions

The `description` field enables Skill discovery and should include both what the Skill does and when to use it.

> **Warning: Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
>
> - **Good:** "Processes Excel files and generates reports"
> - **Avoid:** "I can help you process Excel files"
> - **Avoid:** "You can use this to process Excel files"

**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.

Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details.

An effective description names the concrete operations and then the trigger contexts and user phrasings that should activate the skill. Avoid vague descriptions like `Helps with documents`, `Processes data`, or `Does stuff with files`.

## Progressive Disclosure Patterns

SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide.

**Practical guidance:**

- Keep SKILL.md body under 500 lines for optimal performance
- Split content into separate files when approaching this limit
- Use the patterns below to organize instructions, code, and resources effectively

A Skill can grow from a single SKILL.md to a directory of bundled content that Claude loads only when needed:

```text
skill-name/
├── SKILL.md              # Main instructions (loaded when triggered)
├── references/
│   ├── advanced.md       # Loaded as needed
│   └── reference.md      # API reference (loaded as needed)
└── scripts/
    ├── analyze.py        # Utility script (executed, not loaded)
    └── validate.py       # Validation script
```

Four patterns cover most cases:

- **High-level guide with references** — SKILL.md carries a quick-start path inline and links out to one file per advanced topic. Claude loads a linked file only when the task reaches that topic.
- **Domain-specific organization** — for Skills spanning multiple domains, give each domain its own reference file so a question about one domain never loads the others. Pair this with a grep hint in SKILL.md when the files are large enough that Claude should search rather than read them whole.
- **Conditional details** — keep the common path inline and link out only the branches, so the rare or heavyweight branch costs nothing on a typical run.
- **Frequency of need** — content read once at setup (installation, provisioning, credentials, permission and role setup) or only on failure (troubleshooting tables, error-code references) belongs in a reference file, even when it is topically core to the skill. Ask whether Claude doing this skill's normal job would read it every time, or once at setup and again when something breaks.

## Avoid Deeply Nested References

Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.

**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed.

- ✗ **Avoid**: SKILL.md links to `advanced.md`, which links to `details.md`, which holds the actual information.
- ✓ **Good**: SKILL.md links directly to `advanced.md`, `reference.md`, and `examples.md`, each self-contained.

## Separation of Concerns Between Layers

When SKILL.md links to sub-files, each layer must own exactly one concern:

- **SKILL.md (router)**: Routing decisions, shared config, links to sub-files. Does not summarize or repeat sub-file content.
- **Sub-files (leaves)**: Self-contained instructions for one mode or topic. Assumes the routing decision is already made. Does not contain cross-mode routing tables.

Routing tables, decision logic, and shared config belong in SKILL.md only. Sub-files should never route back to siblings, and SKILL.md should not summarize sub-file commands. When other skills reference a sub-file, they should point to the skill and name the sub-file: "Run `/skill-name` skill and consult sub-file.md to ..."

When removing content from a router because a sub-file already covers it, check whether the router loses a warning the sub-file cannot deliver. A sub-file reaches only a reader who already decided to look, so a caution against a wrong inference has to survive in the router. Merge such a line into the surrounding routing prose rather than deleting it.

## Use Forward Slashes in Paths

Always use forward slashes in file paths, even on Windows:

- ✓ **Good**: `scripts/helper.py`, `reference/guide.md`
- ✗ **Avoid**: `scripts\helper.py`, `reference\guide.md`

Unix-style paths work across all platforms; Windows-style paths cause errors on Unix systems.

## Compute Relative Paths from the File's Actual Location

When a skill file references another file in the same skill, the relative path resolves from the file's own location, not from `SKILL.md`. A reference file at `skills/X/references/foo.md` linking to a sibling at `skills/X/references/bar.md` writes `bar.md`, not `references/bar.md`.

Use markdown links rather than inline code for cross-references. `[bar.md](bar.md)` matches how `SKILL.md` links to its references and how skills link to each other; inline `` `bar.md` `` reads as a path mention but loses the click-through and the convention.

- ✗ **Avoid**: From `skills/X/references/foo.md`: "follow `references/bar.md`" — broken path; not a link.
- ✓ **Good**: From `skills/X/references/foo.md`: "follow [bar.md](bar.md)".

## Structure Longer Reference Files with Table of Contents

For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads. List the section headings under a `## Contents` heading near the top of the file, then the sections themselves.

Claude can then read the complete file or jump to specific sections as needed.

# Tool Usage in Skills

How to phrase tool invocations so the executing agent uses the right mechanism with the right parameters.

## Contents

- Dispatching Agent Tool Calls
  - Never Name a Spawned Agent
  - Phrase Multi-Agent Parallel Dispatch Imperatively
  - Hoist Conditional Opt-Out Checks Above Dispatch Logic
  - Skill Tool Calls Don't Parallelize with Agent Calls
  - Keep Parallel Review/Analysis Subagents Read-Only on the Shared Tree
  - Keep Contended Test Tiers From Colliding in the Fan-Out
- Dispatching Bash Tool Calls
- Using AskUserQuestion
  - Output Content as Text Before AskUserQuestion
  - Ask in the Reader's Vocabulary
  - Prefer AskUserQuestion Gates over Anti-Skip Prose Rules
  - AskUserQuestion Doesn't Work in Sub-Agents
- Referencing MCP Tools

## Dispatching Agent Tool Calls

Subagents run in the background and report as they finish. Constrain the message and the wait: emit the calls together, then wait for every agent to report. Keep the parenthetical to parameter values (`model`, and `no name` per Never Name a Spawned Agent below).

A spawn returns immediately, so Agent calls emitted later in the same turn still overlap. One message keeps the fan-out whole.

- ✗ **Avoid**: "Launch all four agents concurrently in a single message."
- ✗ **Avoid**: "Spawn a subagent to review the output."
- ✗ **Avoid**: "Run them in the foreground so all results return in this turn." The Agent schema carries no `run_in_background` in an interactive session, so foreground cannot be requested.
- ✓ **Good**: "Emit all four Agent tool calls in one assistant message. Each Agent call uses `model: "opus"` and no `name`. Wait for every agent to report before continuing. Do not begin the next step on a partial set, and do not relaunch an agent that has not yet reported."

### Never Name a Spawned Agent

Direct every dispatch instruction to omit the `name` parameter. Named and unnamed agents alike return a spawn receipt and report out of band; what naming changes is the payload. An unnamed agent's completion carries its full report. A named agent becomes an addressable teammate, and its completion arrives as an `idle_notification` wrapped in a `<teammate-message>` carrying a truncated summary and status in place of the report.

Because the rule prevents the teammate channel from being used at all, dispatch instructions need no paired recovery text for it. Should a named agent ever idle, read what its summary carries and continue; answering with `SendMessage` only makes a finished agent re-idle without emitting text and invites a nudge loop. Keep that knowledge here rather than repeating it in every skill that spawns.

Do not add file-based delivery fallbacks (having each agent `Write` its report to an agreed path) to work around this. Writing to disk masks the misread channel rather than fixing it, and the spawning agent still burns turns waiting on a report that already arrived.

- ✗ **Avoid**: `Agent(name: "internal-reviewer", ...)` then nudging it when it idles.
- ✓ **Good** (fan-out): "Each Agent call uses `model: "opus"` and no `name`."
- ✓ **Good** (single agent): "Spawn a single subagent (`model: "opus"`, no `name`). Wait for it to report before continuing; do not relaunch it if it has not yet reported."

### Phrase Multi-Agent Parallel Dispatch Imperatively

To fan out N Agents, emit one assistant message containing N Agent tool calls.

Write the dispatch step as one imperative sentence followed by uniform bulleted Agent roles:

> Emit all <N> Agent tool calls below in one assistant message. Each Agent call uses `model: "opus"` and no `name`. Wait for every agent to report before continuing. Do not begin the next step on a partial set, and do not relaunch an agent that has not yet reported.

Constrain the message rather than naming the outcome. "So they run concurrently" states a goal the agent can believe it is meeting while dispatching one call per turn; "emit all <N> Agent tool calls below in one assistant message" names the count and the container, which is checkable against what the message actually contains.

State the total call count as a number, even when a single bullet expands to multiple calls (e.g., "one Agent per active type, expect <N> total"). The number anchors the fan-out so the full set goes out in one batch.

When the items being parallelized are themselves skills, each parallel item is an Agent tool call whose prompt invokes the target skill via the Skill tool. The Agent fan-out parallelizes; the Skill load is the work each Agent does.

### Hoist Conditional Opt-Out Checks Above Dispatch Logic

When a step has a conditional opt-out (e.g., "skip peer review" reduces N+1 to N Agents), put the check at the top of the step before describing the dispatch. If the opt-out subsection appears after the per-Agent subsections, a reader plans the full dispatch and only learns about the opt-out after — easy to ignore at execution time.

- ✗ **Avoid**: Describe Agent A, Agent B, Agent C — then add a final "Skipping C" subsection.
- ✓ **Good**: Open the step with "Determine whether to skip C: if the run was asked to skip, set the dispatch to A+B; otherwise A+B+C." Then describe each Agent.

### Skill Tool Calls Don't Parallelize with Agent Calls

The Skill tool loads instructions and returns immediately — the actual work (Bash calls, agent spawns, etc.) happens in subsequent turns. To truly parallelize a skill's work with other agents, wrap it in an Agent that loads and executes the skill internally.

- ✗ **Avoid**: Launching Agent + Agent + Skill in one message expecting all three to do work concurrently.
- ✓ **Good**: Launching three Agents in one message, each running its respective skill.

### Keep Parallel Review/Analysis Subagents Read-Only on the Shared Tree

When a skill fans out parallel subagents that read the same working tree (reviewers, analyzers, mappers), direct each subagent's prompt to treat the shared working tree and its git index as read-only. Concurrent agents editing files or running git state-changing commands (`add`, `commit`, `checkout`, `restore`, `stash`, `reset`) on the tree they all share race each other and the orchestrator, and a botched restore can corrupt uncommitted work or poison the index.

Name the HEAD constraint in the shipped prompt rather than relying on "read-only" to imply it. A subagent that runs `git checkout` or `git switch` to inspect another ref leaves the working tree and index clean, so a verification checking only `git status` and a diff hash passes while the orchestrator sits on the wrong branch. Direct subagents to read other refs with `git show <ref>:<path>`, and have the orchestrator capture the branch before spawning and re-check it afterward.

Give a sanctioned outlet rather than banning empirical work: a subagent that needs to verify a finding (such as a mutation experiment to confirm a test is non-vacuous) creates an isolated `git worktree` under the hygiene rules below, experiments there, and discards it. Default to reading and reasoning; reach for a worktree only when empirical proof materially raises confidence.

Spell out that hygiene in the same instruction, because a subagent cannot repair what it breaks: the reinstall needs permissions it does not have. Removing a worktree deletes through symlinks, so a subagent that reaches the shared tree's dependency directory from inside its worktree destroys the shared install when it cleans up. Note also that `git status` never lists gitignored paths, so a destroyed install reads as a clean tree; a verification step that checks only git state will miss the damage entirely. Cover the shared checkout as well as the worktree: a package-manager wrapper reads as read-only while reconciling the shared install before it runs, so direct any check left running in the shared checkout to invoke an already-installed runner directly, and make the dependency-directory verification unconditional rather than a clause of the worktree teardown. Cover a failed command too: a subagent whose `cd` into its worktree fails runs everything chained after it in the shared checkout, so direct it to refer to the worktree by absolute path and join chained steps with `&&`. Have it run teardown and verification as their own commands, since the failing test a mutation check hopes for would otherwise skip them. Cover a runner that outlives its run as well, in a worktree or in the shared checkout: stopping a test runner can leave the processes it spawned alive, and a hung runner keeps going after the subagent reports, where the orchestrator's permissions may forbid killing it. Have the subagent run each runner in its own process group under a timeout enforced from outside the runner, stop those groups before teardown, confirm afterward that no process from them, and none whose command line names the worktree path, is still running, report by PID any process it could not stop, and report that check as unrun when it cannot list processes.

Pair that with a damage-reporting rule. A subagent that breaks shared state it cannot repair reports the damage and the exact repair command in place of findings, so the orchestrator repairs before dispatching more work. Without it, siblings keep running against the broken state and return failures that look like defects in the code under review.

Put the constraint in the per-subagent dispatch instruction, the text that reaches the subagent, not only in the orchestrator's Rules section. An orchestrator-level "does not modify" line governs the orchestrator, not the subagents it launches.

- ✗ **Avoid**: A Rules line "Analysis-only: does not modify source code" with no read-only constraint in the subagent prompts.
- ✗ **Avoid**: "…any empirical check runs in an isolated `git worktree` it discards afterward." This sanctions the worktree without its hygiene, and reads as license to make the worktree runnable by any means.
- ✓ **Good**: "Every agent's prompt directs it to treat the shared working tree and its git index as read-only — any empirical check runs in an isolated `git worktree` created under `$TMPDIR` and discarded afterward. HEAD stays where it is: read other refs with `git show <ref>:<path>` rather than `git checkout` or `git switch`. Refer to that worktree by absolute path in every command and join chained steps with `&&`, so a failed step cannot leave the rest running in the shared checkout. Run teardown and verification as their own commands. Give that worktree its own dependency install rather than reaching the shared tree's install by any route: removing a worktree deletes through symlinks, and a redirected suite writes into the shared install. When its own install is not possible, the check is left unrun and reported as such. Every test runner the agent starts, in a worktree or in the shared checkout, runs in its own process group under a timeout enforced from outside the runner. Before teardown, the agent stops the process group of every runner it started, since stopping a runner can leave the processes it spawned alive. Afterward the agent verifies that `git worktree list` no longer shows the worktree, that `git status --short` is clean, that HEAD is still on the branch it started on, and that the shared tree's dependency directory still resolves (a destroyed install leaves `git status` clean, since it is gitignored). It also confirms that no process from those groups, and none whose command line names the worktree path, if any, is still running, and reports by PID any process it could not stop. When it cannot list processes, it reports that check as unrun and names those process groups and the worktree path, if any. Damage the agent cannot repair is reported with the exact repair command in place of findings."

### Keep Contended Test Tiers From Colliding in the Fan-Out

Parallel subagents that each run the project's test suite collide whenever a tier depends on a resource outside the tree (a shared database, a fixed port, a cache). Tiers that reset that resource between tests have no cross-process interlock, so concurrent runs wipe each other's state and produce failures that read exactly like defects in the code under review. Contention is a property of the fan-out rather than of any one subagent: a subagent running the tier cannot see that its siblings are running it too, so a per-subagent rule cannot prevent the collision.

Resolve it in the orchestrator step, above the dispatch: have it read the project's test configuration and CI workflow, identify any tier that resets a shared external resource, and name that tier to every subagent as off-limits. Name the artifacts to consult, since an orchestrator that has only a file list cannot recognize a contended tier.

Off-limits works only while the subagents can do their job without the tier. When the scope under examination is what that tier exists to exercise, so that judging it at all requires running the tier, have the orchestrator direct each subagent to provision its own isolated instance of the resource, prepare it through the project's own setup path, run against it, and tear it down afterward. One shared instance carrying an instruction to run a single subagent at a time is not sufficient, for the same reason a per-subagent rule cannot prevent the collision: nothing enforces the ordering across subagents. Give that branch the same terminator as the read-only rules above: when a subagent's own instance cannot be provisioned, the tier is left unrun and reported as such. This branch runs the project's setup path in the shared checkout, so it is where a package-manager wrapper reconciles the shared install unnoticed; carry the shared-checkout hygiene above into it rather than leaving it to the worktree rules.

Leave the tier unrun rather than having the orchestrator run it after the fan-out. A skill invoked as a child (a review skill running inside an audit, for example) would run it once per invocation, recreating the contention one level down, and an analysis-only skill has no step or output slot for the result.

Where subagents run such a tier, have the orchestrator direct them to redirect the runner's output to a file under `$TMPDIR` and read the file. Piping a runner to `head`, `tail`, or another command that closes the stream early returns while the runner is still going, so a subagent that believes its run finished leaves one live to overlap the next. `$TMPDIR` keeps that file out of the shared tree, which the read-only rules above require the subagent to leave clean.

- ✗ **Avoid**: "Each agent runs the test suite to confirm its findings."
- ✗ **Avoid**: "Name it to every agent as off-limits, and run it once after the fan-out returns." The trailing run fires again in every nested invocation.
- ✗ **Avoid**: "Agents may run the shared tier, one at a time." Nothing carries that ordering across subagents.
- ✓ **Good** (tier not needed): "Before dispatching, read the project's test configuration and CI workflow to identify any test tier that resets a shared external resource between tests, such as a database, a fixed port, or a cache. Such tiers have no cross-process interlock, so agents running them concurrently wipe each other's state and return failures indistinguishable from defects in the change. Name any such tier to every agent as off-limits when the review does not depend on running it."
- ✓ **Good** (fan-out judges that tier): "When the change under review is what that tier exists to exercise, so that judging it at all requires running the tier, direct each agent instead to provision its own isolated instance of the resource, prepare it through the project's own setup path, run against it, and tear it down afterward. One shared instance carrying an instruction to run a single agent at a time is not sufficient, since nothing enforces that across agents. When an agent's own instance cannot be provisioned, the tier is left unrun and reported as such."
- ✓ **Good** (agents run the tier): "Direct every agent that runs a test suite to redirect the runner's output to a file under `$TMPDIR` and read the file."

## Dispatching Bash Tool Calls

When a skill's Bash invocation needs non-default parameters (`timeout`, `dangerouslyDisableSandbox`), specify them in a parenthetical the same way as for Agent calls. Vague phrasing like "use a generous timeout" leaves Claude to guess which timeout (Bash tool parameter vs. shell `timeout` command) and what value.

- ✗ **Avoid**: "Use a generous timeout."
- ✗ **Avoid**: "Wrap the command in a shell `timeout` of 1 hour: `timeout 3600 X`."
- ✓ **Good**: "Run X via the Bash tool (`timeout: 600000`, do not set `run_in_background`)."

The parenthetical names parameters and values directly, parallel to (`model: "opus"`) for Agent calls. The Bash tool stays foreground when `run_in_background` is omitted, so "do not set `run_in_background`" is the correct foreground phrasing for Bash calls (unlike the Agent tool, whose subagents always run in the background — see Dispatching Agent Tool Calls above). The Bash `timeout` maximum (600000 ms) is enforced: a larger value is not honored — the harness backgrounds the call immediately and hard-kills it at 600s, truncating output. Cap at `timeout: 600000`. A command that overruns that window is normally force-backgrounded: the result carries a task ID, and the command runs to completion recoverable from its output file. A skill whose command can overrun should say how to recover it. Rarely the command is hard-killed instead, giving an error exit reading `Command timed out after <duration>` with no task ID and no output file; that signature is a timeout, so never route it into a retry-on-crash rule that would re-run the work from scratch. Reach for a shell wrapper like GNU `timeout` only when the Bash tool's parameter cannot achieve the goal.

A skill that starts a long-running process should say to pass `run_in_background` alone, never with a trailing `&`. Backgrounding twice reports success within seconds while the process is either dead with its wrapper or orphaned still holding its port, so both a green exit code and a readiness probe can lie about it.

## Using AskUserQuestion

When a skill needs user input, reference the tool by name (`AskUserQuestion`) instead of vague phrasing like "ask the user" or "wait for user confirmation." Naming the tool directly ensures the executing Claude instance uses the right mechanism.

- ✗ **Avoid**: "Ask the user which option they prefer."
- ✓ **Good**: "Use `AskUserQuestion` to determine which option the user prefers."

### Output Content as Text Before AskUserQuestion

When a skill presents structured content (tables, plans, reports) before asking for approval, output the content as text first. `AskUserQuestion` has limited UI space and should only carry the approval prompt, not the content being reviewed.

- ✗ **Avoid**: "Present the test plan to the user with `AskUserQuestion` before executing."
- ✗ **Avoid**: "Show the drafted context to the user via `AskUserQuestion` for approval."
- ✓ **Good**: "Output the plan as text. Then use `AskUserQuestion` to ask for approval."

### Ask in the Reader's Vocabulary

A gate question has to be answerable by someone who has not read the skill. Terms the skill defines for its own use — role names, artifact shorthand, phase labels, criteria names — arrive at the gate as jargon, and options whose wording has to be decoded first cannot be weighed against each other.

State the concrete problem in plain language as text before the gate, naming what goes wrong if nothing changes. Then write each option's label and description as an observable effect: what is different afterward, and what that costs.

- ✗ **Avoid**: Options named for the internal criterion or artifact they act on.
- ✓ **Good**: Options named for what is different afterward when the user picks them.

When the user answers with a question instead of picking an option, answer it, then re-ask. Treat the question as evidence about the gate: one asking what a term or an option means says the wording was unreadable, so restate the problem plainly before re-asking. One asking something substantive the options left open says the restatement needs that information too.

### Prefer AskUserQuestion Gates over Anti-Skip Prose Rules

Workflow skills often need to prevent the agent from skipping steps ("don't rationalize away the re-run") or stopping early at iteration caps. Verbose "Do NOT" blocks and anti-rationalization prose are unreliable: the agent reads the rule and still finds ways to rationalize around it. Convert soft rules into hard gates using `AskUserQuestion`.

- **Skip gate**: When the agent might want to skip a re-run that should happen (e.g., changes were made but the agent judges re-running unnecessary), require it to use `AskUserQuestion` to request skip permission. This converts "don't skip silently" into "can't skip silently."
- **Exhaustion gate**: When a loop reaches its iteration cap but hasn't stabilized, use `AskUserQuestion` to ask whether to continue for another iteration or escalate to a different approach. This replaces the hard stop with a human-in-the-loop decision.
- **Blocker gate**: When a step is blocked by a missing dependency, unclear requirement, or environmental issue that needs user input to resolve, use `AskUserQuestion` to surface the blocker and let the user choose how to proceed. Phrasing like "halt and report" or "stop" leaves no recovery path; an `AskUserQuestion` gate keeps the workflow live.

```markdown
**If changes were made**, run `/this-skill` again using the Skill tool.

**If changes were made but you believe re-running is unnecessary**, use `AskUserQuestion` to ask for skip permission. Do not skip silently.

**If this is iteration 3 and changes were still made**, the hard cap is reached. Use `AskUserQuestion` to tell the user that 3 iterations were not enough to stabilize, summarize what is still changing, and offer two options: continue for another iteration, or escalate to a different approach for the remaining issues.
```

Removing verbose "Do NOT" blocks and "Rules" sections that restate the anti-skip rule often wins alongside adding the gates: the prose was unreliable anyway, and the gates replace it with enforceable behavior.

### AskUserQuestion Doesn't Work in Sub-Agents

`AskUserQuestion` only reaches the user when the skill runs in the main conversation. When a skill runs inside an `Agent` tool call, the question cannot be surfaced — the sub-agent either errors or drops the call silently. Skills that commonly run as sub-agents (invoked by workflow skills that fan out via the Agent tool) need deterministic fallbacks instead of interactive questions.

- **Missing input** — stop and state what could not be resolved. The parent agent reads the sub-agent's output and can relay or act on it.
- **Disambiguation** — pick a deterministic default (e.g., most recently modified file) rather than asking which option to use.
- **Main-context-only fallbacks** — a sub-agent can in principle self-detect via system-prompt phrasing and branch on whether to call `AskUserQuestion`, but the cost of that branching is usually worse than just removing the question entirely.

## Referencing MCP Tools

When referencing a *specific known* MCP (Model Context Protocol) tool, always use fully qualified tool names to avoid "tool not found" errors.

**Format**: `ServerName:tool_name`

Where `ServerName` is the MCP server name and `tool_name` is the tool within that server. Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.

When a skill needs a *category* of tool rather than a specific one (e.g., documentation lookup), reference the category generically. Different projects have different MCP servers installed.

- ✗ **Avoid**: "Use the context7 MCP to look up library docs."
- ✓ **Good**: "Use documentation MCP tools or WebSearch to look up library docs."

# Workflows and Common Patterns

How to shape multi-step skills, convergence loops, exit signals, and recurring output patterns.

## Contents

- Use Workflows for Complex Tasks
- Implement Feedback Loops
- Use Recursive Self-Invocation for Convergence Loops
- Use Neutral Exit Signals So Parent Pipelines Can Continue
- Template Pattern
- Examples Pattern
- Conditional Workflow Pattern
- Align Output Formats Across Parallel Producers

## Use Workflows for Complex Tasks

Break complex operations into clear, sequential steps. Use `## Step N:` headings for the steps. For particularly complex workflows with distinct phases, nest steps under phases using `## Phase N` with `### Step N:` subheadings.

**Simple workflow:**

```markdown
## Step 1: Analyze Input
...
## Step 2: Transform Data
...
## Step 3: Validate Output
...
```

**Complex multi-phase workflow:**

```markdown
## Phase 1: Planning

### Step 1: Gather Requirements
...
### Step 2: Design Solution
...

## Phase 2: Execution

### Step 1: Implement Changes
...
### Step 2: Run Tests
...
```

**Avoid** wrapper sections like `## Process` with `### 1.` numbered subsections. Steps should be top-level, not nested under a generic heading.

**Avoid** any section whose only purpose is to inspect input or detect a mode, regardless of what it is labeled. This includes numbered "Step 0" headings, unnumbered `## Mode Selection` sections, or any subheading that collapses to "if X, read file A; otherwise read file B." A step or section should do work the agent executes. Trivial input inspection and mode routing are one-line branches — fold them into the skill's opening prose rather than giving them their own heading.

For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses. The pattern works for any multi-step process — code-based or analysis-only. Clear steps prevent Claude from skipping critical validation, and the checklist helps both Claude and you track progress.

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

```
Task Progress:
- [ ] Step 1: <action>
- [ ] Step 2: <action>
- [ ] Step 3: <validation>
```
````

## Implement Feedback Loops

**Common pattern**: Run validator → fix errors → repeat. The validator can be a script, a reference document, or a checklist — what matters is the loop.

State the loop so the agent cannot advance past a failure: make the edit, validate immediately, review the error and fix on failure, re-validate, and only proceed once validation passes.

## Use Recursive Self-Invocation for Convergence Loops

When a skill needs to repeat its workflow until stable (e.g., simplify → review → test → repeat if changed), have the last step re-invoke the skill itself rather than encoding an internal loop. This keeps each step distinct and the flow linear. Use "skipping Step N" to bypass one-time setup steps on re-runs.

```markdown
## Step 1: Setup (first run only)
...
## Step 2: Do work
...
## Step 3: Re-run if changed

If any prior step produced changes, run the `/this-skill` skill again, skipping Step 1.

## Rules

- Cap at 3 consecutive runs to prevent runaway loops.
```

## Use Neutral Exit Signals So Parent Pipelines Can Continue

When a skill detects a clean early-exit case (a degenerate input that doesn't warrant the full output), the exit instructions need to allow parent pipelines to detect and reroute. Phrasing like "Halt and tell the user X" reads as a hard stop and terminates the agent's flow, including any parent pipeline that called the skill.

Phrasing like "Present this message: <factual summary>. Then use the TaskList tool and proceed to any remaining task." lets the agent surface what happened and continue to whatever task is next. The signal that the early-exit fired lives in the side effects (no file written, factual message shown), and the parent pipeline reads them via filesystem checks or remaining-task detection.

Blocker gates (covered in [tools.md](tools.md) under "Using AskUserQuestion") handle a different case: when the agent needs the user to choose between recoveries. Use neutral exit signals when the work simply terminates earlier than the full path.

- ✗ **Avoid**: "Halt and tell the user 'nothing produced — run `/skill-name` instead.'"
- ✓ **Good**: "Present this message: '<factual summary>'. Then use the TaskList tool and proceed to any remaining task."

## Template Pattern

Provide templates for output format. Match the level of strictness to your needs — open with "ALWAYS use this exact template" for strict requirements (API responses, data formats), or "Here is a sensible default; use your best judgment" when adaptation is useful.

Give the template as a fenced block with bracketed slots naming what goes in each one, so the structure is unambiguous and the agent fills rather than invents.

## Examples Pattern

For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting. Two or three pairs showing input and desired output, followed by a one-line statement of the rule the pairs demonstrate, convey style and level of detail more precisely than description alone.

Reserve this pattern for cases where the output has a house style that description genuinely fails to pin down. When the rule can be stated directly, state it — examples narrow the space the agent explores, so they cost more than their line count suggests.

## Conditional Workflow Pattern

Guide Claude through decision points. Open the step with the discriminating question, then give each branch its own labeled sequence:

```markdown
1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - <steps>

3. Editing workflow:
   - <steps>
```

> **Tip:** If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand.

## Align Output Formats Across Parallel Producers

When two or more skills produce findings that feed a shared downstream pipeline (for example, an evaluation or triage skill), align their default output formats so the consumer can concatenate findings without transforming them. Drift in finding shape (different metadata labels, missing source attribution, divergent priority scales) forces the consumer to reformat, which invites bugs and defeats composition.

- **Match field names** — if one producer emits `**File:** <path> (lines <start>-<end>)`, the other's default should use the same label and slot, even if the line-range slot is optional for some inputs.
- **Include source attribution** — when findings from multiple producers merge, each should carry a `**Reviewer:**` (or equivalent) line so the consumer can distinguish them.
- **Share the priority scale** — use the same labels and semantics (e.g., P0–P3) across producers so the downstream can rank findings uniformly.
- **Let the invoking skill override the default** — alignment applies to the producer's *default* format. A specific invocation can still pass a tailored output format when it needs extra fields.

# Writing the Body

Sentence-level and section-level rules for the prose inside a skill.

## Contents

- Keep a Short Intro Paragraph
- Use Consistent Terminology
- Use Generic Examples
- Keep ✓ Good Examples Identical to Shipped Text
- Prefer Positive Phrasing
- State Conditions Explicitly
- Address Subagents Directly
- Prefer Qualitative Descriptions for Judgment Calls
- Avoid Time-Sensitive Information
- Avoid Redundant Rules Sections
- Provide a Default Rather Than Too Many Options
- Verify Code Fence Pairing After Multi-Template Edits

## Keep a Short Intro Paragraph

YAML frontmatter (name, description) is stripped before the skill body is loaded into context. If the title and steps don't make the skill's purpose obvious, a one-line intro paragraph after the `# Title` heading can help orient execution. Keep it short, avoid restating the description verbatim, and omit it entirely if the steps already make the purpose clear.

## Use Consistent Terminology

Choose one term and use it throughout the Skill:

**Good - Consistent**:

- Always "API endpoint"
- Always "field"
- Always "extract"

**Bad - Inconsistent**:

- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"
- Mix "extract", "pull", "get", "retrieve"

Consistency helps Claude understand and follow instructions.

## Use Generic Examples

Skills may be used across different projects. Avoid project-specific details in examples — use generic placeholders instead.

- ✗ **Avoid**: "Run `python3 manage.py migrate` to update the Acme database schema. Click the 'Deploy to Acme Staging' button."
- ✓ **Good**: "Run the project's migration command to update the database schema. Click the deployment button for the target environment."

If a skill is project-specific by design (lives in the project repo, not in a shared location), project-specific examples are acceptable. But skills intended for reuse across projects should use generic placeholders.

Also consider whether inline examples are needed at all. Parenthetical examples like "(e.g. click the Submit button)" often add no value when the instruction is already clear. Prefer concise instructions without examples over instructions cluttered with obvious ones.

## Keep ✓ Good Examples Identical to Shipped Text

When a ✓ Good bullet supplies a phrasing that skills are expected to reproduce, update it in the same pass that changes that phrasing across skills. Authors copy such a bullet verbatim, so an example that drifts from what the collection's skills actually ship propagates the drift into every skill authored from it. Bullets that merely illustrate a rule have no shipped counterpart and need no such check.

Confirm the match by grepping the shipped string and checking that the example reproduces it character for character. When the two disagree, treat the shipped text as the source of truth: the un-updated example is the outlier, even though its position in the reference makes it look canonical.

## Prefer Positive Phrasing

State what to do. Imperative verbs ("defer", "limit", "exclude", "halt", "describe") give the agent a clear action; chains of "Never X. Don't Y. Avoid Z." force the agent to invert the prohibition into an action before acting on it.

- ✗ **Avoid**: "Never modify files in `vendor/`. Files there are managed by the package manager."
- ✓ **Good**: "Treat files in `vendor/` as read-only."

The positive form names the action and drops the explanatory clause that just restates the boundary.

Use negative phrasing only when a positive imperative cannot articulate the rule unambiguously. When an explicit enumeration of prohibited items is load-bearing, prefer positive verbs ("Exclude", "Omit", "Reserve X for Y") over "Never include" or "Don't add". Redundant negative restatements — a rule paired with a tautological-boundary clause that says the same thing — are always trim targets.

## State Conditions Explicitly

If a step has a clear condition for when to execute and when to skip, state both directly. Don't soften it with "optionally" — that creates ambiguity about whether the step should actually run.

- ✗ **Avoid**: "Optionally spawn a subagent to verify findings."
- ✓ **Good**: "Spawn a subagent when there are 3+ non-trivial findings. **Skip** when all findings are clear-cut."

## Address Subagents Directly

When a skill's body needs to constrain how a subagent invoking it should behave, address that subagent directly using "If you are a subagent" gating. Phrasings like "from inside an Agent subagent" or "when wrapped in a subagent" read as third-person references and are ambiguous: the reader may parse them as "from inside an Agent subagent that I would spawn" rather than "if I am that subagent".

- ✗ **Avoid**: "When this skill is invoked from inside an Agent subagent, the Agent prompt must include..."
- ✗ **Avoid**: "Subagents wrapping this skill should..."
- ✓ **Good**: "If you are a subagent, follow these guardrails..."

Skills are loaded by the subagent itself when it invokes the skill via the Skill tool. The body's instructions arrive in the subagent's own context, so direct second-person address is correct.

## Prefer Qualitative Descriptions for Judgment Calls

When a skill describes a threshold the agent must judge (when something is too large, when to split, when to combine), prefer qualitative descriptions over numeric heuristics. Numbers like "more than 15 files" or "3+ subsystems" feel precise but encourage box-ticking — agents tally and cross the threshold without engaging the underlying judgment. Qualitative descriptions ("the work would exhaust a session", "too many distinct conventions to absorb") force the agent to evaluate the actual situation.

- ✗ **Avoid**: "Split when a step would touch more than 15-20 files or span 3+ unrelated subsystems."
- ✓ **Good**: "Split when the combined work would exhaust a single session: too much code to read in full, or too many distinct conventions to absorb."

Use numbers only when the threshold is mechanically verifiable and the count is the actual signal (e.g., "cap at 3 retries", "every acceptance criterion must appear in at least one verification step").

## Avoid Time-Sensitive Information

Don't include information that will become outdated:

- ✗ **Avoid**: "Before August 2025, use the old API. After August 2025, use the new API."
- ✓ **Good**: Document the current method directly. If legacy guidance is needed, isolate it under an "Old patterns" section so it doesn't clutter primary instructions.

## Avoid Redundant Rules Sections

A Rules section should only contain information not already conveyed by the skill body. Before adding a rule, check whether the Process, workflow steps, or tables already encode the same behavior. If they do, the rule is wasted tokens.

## Provide a Default Rather Than Too Many Options

Don't present multiple approaches unless necessary. Name one default and give an escape hatch for the case that genuinely needs it.

- ✗ **Avoid**: "You can use library A, or library B, or library C, or..."
- ✓ **Good**: "Use library A. For <specific edge case>, use library B instead."

## Verify Code Fence Pairing After Multi-Template Edits

When inserting a second fenced code block alongside an existing one in the same skill section, verify that both fences pair correctly. Multi-template edits commonly produce orphan closing fences, especially when shared scaffolding (XML output contracts, output specs, dig-deeper nudges) needs to apply to both templates.

Two safe patterns:

1. **Each template fully self-contained**: Each fenced block contains its own copy of the shared scaffolding. Repetitive but unambiguous.
2. **Shared scaffolding in its own fence**: The shared content lives in a separate labeled fenced block, with prose explaining how to concatenate it with the template-specific blocks.

- ✗ **Avoid**: Two fenced template blocks where shared XML scaffolding appears as raw markdown between them, leaving an orphan closing ` ``` ` somewhere. Readers see the shared content as unparsed prose; rendering breaks.
- ✓ **Good**: Three fenced blocks (template A, template B, shared scaffolding) with `### ` subheadings naming each. Or two fenced blocks where each repeats the shared scaffolding internally.