# 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 that the agent should read and follow the named skill's SKILL.md before continuing.

```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 load. 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 mentions "in parallel". 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 `spawn_agent` calls and joins them with `wait_agent`. 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 spawns both internal reviewer sub-agents and a peer reviewer sub-agent; the parent just runs `$<review-skill>`.

A parent may follow two siblings together when each already fans out on its own and covers a distinct concern. Running a skill only reads its instructions into the current context, so following two lands both bodies in the same agent, which then spawns every sibling's sub-agent before joining any of them. 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>` follows `$<code-skill>` and `$<docs-skill>` together, spawns every sub-agent both define before joining any, 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 the Agent
- Observe How the Agent 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 the agent 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 the agent'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 the Agent

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

1. **Complete a task without a Skill** in Session A. Notice what context you repeatedly provide.
2. **Ask the agent to create the Skill**, capturing that context. The agent understands the Skill format natively and will generate properly structured SKILL.md content.
3. **Review for conciseness** and information architecture. Ask the agent to remove explanations it already knows, and to split reference content into separate files when it grows.
4. **Test with Session B** (a fresh session with the Skill installed) on related tasks. Observe whether it finds the right information, applies rules correctly, and succeeds.
5. **Return to Session A with specifics** when Session 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 the Agent Navigates Skills

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

- **Unexpected exploration paths**: Does the agent read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
- **Missed connections**: Does the agent fail to follow references to important files? Your links might need to be more explicit or prominent
- **Overreliance on certain sections**: If the agent repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
- **Ignored content**: If the agent 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. Codex 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 Codex CLI harness: canonical tool names, limits, and discovery paths.

**Tools (canonical names):**

- `update_plan` — task tracking. Each entry is `{step, status}` where status is `pending`, `in_progress`, or `completed`. At most one step in_progress at a time. The `plan` argument is the full list, so every call replaces the previous one. The handler stores nothing: it emits a UI event and returns `"Plan updated"`. No read-back tool exists, so the only record of the current plan is the `update_plan` call sitting in conversation history.
- `apply_patch` — file edits in the V4A diff envelope (`*** Begin Patch` / `*** Add File:` / `*** Update File:` / `*** Delete File:` / `@@` hunks).
- `request_user_input` — structured user prompts. 1-3 questions per call, 2-3 options per question, "Other" free-form option appended automatically. Available in Plan mode by default; Default mode requires the `default_mode_request_user_input` feature flag (currently `Stage::UnderDevelopment`, off by default).
- `spawn_agent` / `wait_agent` / `close_agent` / `resume_agent` / `send_input` — sub-agent control (Codex multi-agents v1). Spawned agents inherit the parent model unless `model` is set explicitly. Codex's v2 surface (`features.multi_agent_v2`, with `send_message` / `followup_task` / `list_agents` for inter-agent messaging) is feature-flagged off and mutually exclusive with `agents.max_threads`.
- `create_goal` / `update_goal` / `get_goal` — persisted thread goals (`[features] goals`, stable and on by default). One unfinished goal per thread; `create_goal` fails while one exists. The objective is re-injected into context every turn from storage, survives compaction and session restarts, and an idle turn with an active goal auto-restarts. `update_goal` accepts only `complete` or `blocked`; `blocked` is valid only after the same blocking condition has recurred for at least three consecutive goal turns, and the goal continuation enforces that threshold itself — skills mark `complete` at their terminal step and otherwise leave the goal active.

**Sub-agent limits:** `agents.max_threads` defaults to 6 (parallel cap). `agents.max_depth` defaults to 1 (a sub-agent cannot itself call `spawn_agent` under defaults).

**Sandbox modes:** `read-only`, `workspace-write`, `danger-full-access`. Bypass flag is `--dangerously-bypass-approvals-and-sandbox` (alias `--yolo`).

**Approval policies:** `untrusted`, `on-request`, `never`, `granular`. Default is `on-request`.

**Skill discovery:**

- User-scope: `~/.agents/skills/` (canonical per Codex `core-skills` loader).
- Project-scope: `.agents/skills/` walked from project root down to cwd; closer directories take precedence.
- Admin-scope: `/etc/codex/skills/`.
- Skills invoked as `$skill-name` (slash form also works); `SKILL.md` frontmatter requires `name` and `description`.

**AGENTS.md hierarchy:**

- Global: `~/.codex/AGENTS.md` (with optional `AGENTS.override.md` to replace).
- Project: walked from project root down to cwd. `AGENTS.override.md` at any level *replaces* the `AGENTS.md` at that level (not additive).
- Combined cap: `project_doc_max_bytes` = 32 KiB by default.

**Config:** `~/.codex/config.toml` (user) and `.codex/config.toml` (project).

**Compaction:** several implementations exist — local, remote v1, remote v2 (the shipped default for OpenAI and Azure Responses providers), and a token-budget path that skips summarization entirely — and they differ in what they retain, so depend on none of the details. What holds across all of them: function calls and their output are dropped, so no `update_plan` call survives; skill bodies do not survive either, by a separate filter on injected context; and initial context is re-injected, so `AGENTS.md` comes back. Anything a skill must still know after a compaction has to be re-derivable, not remembered.

# 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 the agent 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. Codex injects SKILL.md as a contextual user fragment only when a `$skill-name` token appears in the current turn's input; metadata (name and description) is harvested separately for discovery. So additional reference files cost nothing until they are read. However, being concise in SKILL.md still matters: once the agent loads it, every token competes with conversation history and other context.

**Default assumption**: the agent is already very smart

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

- "Does the agent really need this explanation?"
- "Can I assume the agent 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 the agent 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. The agent 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 the agent 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 the agent 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 a Plan section 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 — terser models may need more explicit guidance, and stronger models may not need explanations that smaller ones do.

# 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 the agent.

**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 the agent**:

```python
def process_file(path):
    # Just fail and let the agent 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 the agent 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. The agent can execute them without loading their contents into context.

Make clear whether the agent 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 the agent analyze them: convert the input to images with a bundled script, then read the images to identify structure and layout. The agent'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: the agent 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 the agent iterate on the plan without touching originals. Make validation errors specific ("Field 'signature_date' not found. Available fields: customer_name, order_total") so the agent 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. The Codex CLI runs scripts under the active sandbox mode (`read-only`, `workspace-write`, or `danger-full-access`). Network access is gated by sandbox configuration, so package installs and remote fetches may be unavailable depending on the active mode.

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 the agent 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 the agent 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: "openai", "codex", "chatgpt"

`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: `openai-helper`, `codex-tools`, `chatgpt-helper`
- 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: Codex uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for the agent 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 the agent 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 the agent 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. The agent 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 the agent 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 an agent doing this skill's normal job would read it every time, or once at setup and again when something breaks.

## Avoid Deeply Nested References

The agent may partially read files when they're referenced from other referenced files. When encountering nested references, the agent 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 the agent 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 the `$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 the agent 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.

The agent 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 Sub-Agent Calls
  - Phrase Multi-Agent Parallel Dispatch Imperatively
  - Hoist Conditional Opt-Out Checks Above Dispatch Logic
  - Skill Mentions Don't Fan Out on Their Own
  - Keep Parallel Review/Analysis Sub-Agents Read-Only on the Shared Tree
  - Keep Contended Test Tiers From Colliding in the Fan-Out
- Using request_user_input
  - Output Content as Text Before request_user_input
  - Ask in the Reader's Vocabulary
  - Gate Genuine Blockers; Leave the Agent's Own Judgment to the Agent
  - request_user_input Is Gated to Interactive Modes and the Main Conversation
- Referencing MCP Tools

## Dispatching Sub-Agent Calls

When a skill spawns sub-agents, use `spawn_agent` to launch each branch and `wait_agent` to join. Sub-agents inherit the parent model unless the user has explicitly requested otherwise — do not hardcode model names. Vague phrasing like "launch concurrently" or "in parallel" causes flaky behavior because the agent has to guess which tool to use.

`spawn_agent` issues each sub-agent in its own call; the calls in a batch run concurrently up to `agents.max_threads` (default 6). Sub-agents cannot themselves call `spawn_agent` under the default `agents.max_depth` of 1, so a sub-agent must complete its work without further fan-out.

- ✗ **Avoid**: "Launch all four agents concurrently."
- ✗ **Avoid**: "Spawn a sub-agent to review the output."
- ✓ **Good**: "Issue all four `spawn_agent` calls (one per role described below) in one batch, then collect their results with `wait_agent`. Do not issue one and await its result before issuing the rest."

### Phrase Multi-Agent Parallel Dispatch Imperatively

To fan out N sub-agents in parallel, issue N `spawn_agent` calls in one batch and then join them with `wait_agent`.

Write the dispatch step as one imperative sentence followed by uniform bulleted sub-agent roles:

> Issue all <N> `spawn_agent` calls below in one batch, then collect their results with `wait_agent`. Do not issue one and await its result before issuing the rest. Each sub-agent inherits the parent model.

Constrain the batch rather than naming the outcome. "So they run concurrently" states a goal the agent can believe it is meeting while issuing one call at a time; "do not issue one and await its result" names the behavior that would violate it, which is checkable against what the batch actually contains.

State the total call count as a number, even when a single bullet expands to multiple calls (e.g., "one sub-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 a `spawn_agent` call whose prompt instructs the sub-agent to read and follow the target `$skill-name`. The `spawn_agent` fan-out parallelizes; the skill load is the work each sub-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 sub-agents), put the check at the top of the step before describing the dispatch. If the opt-out subsection appears after the per-role subsections, a reader plans the full dispatch and only learns about the opt-out after — easy to ignore at execution time.

- ✗ **Avoid**: Describe sub-agent A, sub-agent B, sub-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 sub-agent.

### Skill Mentions Don't Fan Out on Their Own

Mentioning `$skill-name` injects the skill's SKILL.md as a contextual fragment for the current turn; it does not spawn a sub-agent. The actual work happens afterward, in the same conversation. To run several skills' work in parallel, wrap each branch in a `spawn_agent` call whose prompt tells the sub-agent to read and follow the target skill.

- ✗ **Avoid**: Mentioning `$skill-A` and `$skill-B` in the same step expecting the mentions themselves to spawn sub-agents.
- ✓ **Good**: Issuing two `spawn_agent` calls, each instructing its sub-agent to read and follow its respective skill.

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

When a skill fans out parallel sub-agents that read the same working tree (reviewers, analyzers, mappers), direct each sub-agent's prompt to treat the shared working tree and its git index as read-only. Concurrent sub-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 sub-agent 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 sub-agents 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 sub-agent 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 sub-agent cannot repair what it breaks: the reinstall needs permissions it does not have. Removing a worktree deletes through symlinks, so a sub-agent 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 sub-agent 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 sub-agent reports, where the orchestrator's permissions may forbid killing it. Have the sub-agent 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 sub-agent 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-sub-agent dispatch instruction, the text that reaches the sub-agent, not only in the orchestrator's Rules section. An orchestrator-level "does not modify" line governs the orchestrator, not the sub-agents it launches.

- ✗ **Avoid**: A Rules line "Analysis-only: does not modify source code" with no read-only constraint in the sub-agent 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**: "Each sub-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 sub-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 sub-agent stops the process group of every runner it started, since stopping a runner can leave the processes it spawned alive. Afterward the sub-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 sub-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 sub-agents 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 sub-agent: a sub-agent running the tier cannot see that its siblings are running it too, so a per-sub-agent 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 sub-agent 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 sub-agents 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 sub-agent 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 sub-agent at a time is not sufficient, for the same reason a per-sub-agent rule cannot prevent the collision: nothing enforces the ordering across sub-agents. Give that branch the same terminator as the read-only rules above: when a sub-agent'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 branches join. 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 sub-agents 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 sub-agent 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 sub-agent to leave clean.

- ✗ **Avoid**: "Each sub-agent runs the test suite to confirm its findings."
- ✗ **Avoid**: "Name it to every sub-agent as off-limits, and run it once after the fan-out returns." The trailing run fires again in every nested invocation.
- ✗ **Avoid**: "Sub-agents may run the shared tier, one at a time." Nothing carries that ordering across sub-agents.
- ✓ **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 branches running them concurrently wipe each other's state and return failures indistinguishable from defects in the change. Name any such tier to every branch 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 branch 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 branch at a time is not sufficient, since nothing enforces that across branches. When a branch's own instance cannot be provisioned, the tier is left unrun and reported as such."
- ✓ **Good** (branches run the tier): "Direct every branch that runs a test suite to redirect the runner's output to a file under `$TMPDIR` and read the file."

## Using request_user_input

When a skill needs structured user input, reference the tool by name (`request_user_input`) instead of vague phrasing like "ask the user" or "wait for user confirmation." Naming the tool directly avoids ambiguity about how the question should be surfaced.

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

### Output Content as Text Before request_user_input

When a skill presents structured content (tables, plans, reports) before asking for approval, output the content as text first. `request_user_input` 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 `request_user_input` before executing."
- ✗ **Avoid**: "Show the drafted context to the user via `request_user_input` for approval."
- ✓ **Good**: "Output the plan as text. Then use `request_user_input` 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.

### Gate Genuine Blockers; Leave the Agent's Own Judgment to the Agent

Reserve `request_user_input` for decisions that genuinely need the user. When the agent can make the call itself, let it act and state its reasoning rather than gating.

- **Blocker gate**: When a step is blocked by a missing dependency, unclear requirement, or environmental issue that needs user input to resolve, use `request_user_input` to surface the blocker and let the user choose how to proceed. Phrasing like "halt and report" or "stop" leaves no recovery path; a `request_user_input` gate keeps the workflow live.
- **Skip decision**: When the agent judges a re-run unnecessary (changes were made but re-running would surface nothing new), let it stop on its own judgment. Require it to output what changed and its reasoning for stopping so the decision stays auditable, but do not gate on the user.

```markdown
**If changes were made**, run the `$this-skill` skill again.

**If changes were made but you judge a re-run unnecessary**, output a summary of what changed and your reasoning for stopping, then stop instead of re-running.
```

Self-looping skills terminate on their own convergence signal (a run that makes no changes, or a round of only cosmetic edits). Rely on that rather than an iteration cap. Judge the signal by the trend across rounds: once rounds stop surfacing defects and keep surfacing improvements of kinds earlier rounds already applied, the loop has converged even when the edits were structural. Give the loop a durable anchor: record iteration number and applied/rejected verdicts in a ledger under `.turbo/loops/`, and anchor uncapped loops with a goal whose objective names the ledger path, so compaction cannot erase the loop's memory of its own decisions.

### request_user_input Is Gated to Interactive Modes and the Main Conversation

`request_user_input` only reaches the user from interactive sessions. Two limits apply:

- **Mode gating** — the tool is available in Plan mode by default. Default mode requires the `default_mode_request_user_input` feature flag (currently off). Non-interactive sessions (e.g., `codex exec`) drop the tool entirely.
- **Sub-agent gating** — when a skill runs inside a `spawn_agent` sub-agent, `request_user_input` cannot reach the user. The parent agent owns the conversation; the sub-agent's questions either error or get dropped silently.

Skills that commonly run as sub-agents (invoked by workflow skills that fan out via `spawn_agent`) or that may run under `codex exec` 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 skill could in principle branch on whether `request_user_input` is currently available, but the cost of that branching is usually worse than just removing the question entirely.

## Referencing MCP Tools

Codex exposes MCP (Model Context Protocol) tools through `tool_search`. Callable names use the namespaced form `mcp__<server>__<tool>` (double underscores). When a skill must reference a *specific known* MCP tool, write the fully qualified callable name so the agent doesn't need to disambiguate.

**Format**: `mcp__<server>__<tool>`

Without the namespace prefix, the agent 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 a documentation MCP tool or web search 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 the agent 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 the agent from skipping critical validation, and the checklist helps both the agent 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

- The loop ends when a run makes no changes. Rely on that convergence signal rather than a fixed iteration cap.
- Only defects justify a re-run. When a round stops surfacing defects and keeps surfacing improvements of kinds earlier rounds already applied, the loop has converged; a clean round is the termination signal, never grounds for a confirmation round.
```

## 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 call `update_plan` to mark this step completed and continue with the next step of the active workflow." 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-step detection.

Blocker gates (covered in [tools.md](tools.md) under "Using request_user_input") 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 call `update_plan` to mark this step completed and continue with the next step of the active workflow."

## 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 the agent 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 the agent 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
- 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 the agent 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 sub-agent to verify findings."
- ✓ **Good**: "Spawn a sub-agent when there are 3+ non-trivial findings. **Skip** when all findings are clear-cut."

## 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.