Fix:

• Add more examples showing pattern
• Make examples more complete
• Show edge cases in examples
• Add anti-pattern examples (what not to do)

</common_iteration_patterns>

<iteration_velocity> Small, frequent iterations beat large, infrequent rewrites.

<fast_iteration> Good approach:

1. Make one targeted change
2. Test on specific scenario
3. Verify improvement
4. Commit change
5. Move to next issue

Total time: Minutes per iteration Iterations per day: 10-20 Learning rate: High </fast_iteration>

<slow_iteration> Problematic approach:

1. Accumulate many issues
2. Make large refactor
3. Test everything at once
4. Debug multiple issues simultaneously
5. Hard to know what fixed what

Total time: Hours per iteration Iterations per day: 1-2 Learning rate: Low </slow_iteration>

<benefits_of_fast_iteration>

• Isolate cause and effect
• Build pattern recognition faster
• Less wasted work from wrong directions
• Easier to revert if needed
• Maintains momentum </benefits_of_fast_iteration> </iteration_velocity>

<success_metrics> Define how you’ll measure if the skill is working. Quantify success.

<objective_metrics>

• Success rate: Percentage of tasks completed correctly
• Token usage: Average tokens consumed per task
• Iteration count: How many tries to get correct output
• Error rate: Percentage of tasks with errors
• Discovery rate: How often skill loads when it should </objective_metrics>

<subjective_metrics>

• Output quality: Does output meet requirements?
• Appropriate detail: Too verbose or too minimal?
• Claude confidence: Does Claude seem uncertain?
• User satisfaction: Does skill solve the actual problem? </subjective_metrics>

<tracking_improvement> Compare metrics before and after changes:

• Baseline: Measure without skill
• Initial: Measure with first version
• Iteration N: Measure after each change

Track which changes improve which metrics. Double down on effective patterns. </tracking_improvement> </success_metrics>

Reference: Official Spec

Official Skill Specification (2026)

Source: code.claude.com/docs/en/skills

Commands and Skills Are Merged

Custom slash commands have been merged into skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work the same way. Existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.

If a skill and a command share the same name, the skill takes precedence.

SKILL.md File Structure

Every skill requires a SKILL.md file with YAML frontmatter followed by standard markdown instructions.

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

# Your Skill Name

## Instructions
Clear, step-by-step guidance.

## Examples
Concrete examples of using this skill.

Complete Frontmatter Reference

All fields are optional. Only description is recommended.

Invocation Control

Skill Locations & Priority

Enterprise (highest priority) → Personal → Project → Plugin (lowest priority)

Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict with other levels.

How Skills Work

1. Discovery: Claude loads only name and description at startup (2% of context window budget)
2. Activation: When your request matches a skill’s description, Claude loads the full content
3. Execution: Claude follows the skill’s instructions

String Substitutions

Dynamic Context Injection

The !`command` syntax runs shell commands before content is sent to Claude:

## Context
- Current branch: !`git branch --show-current`
- PR diff: !`gh pr diff`

Commands execute immediately and their output replaces the placeholder. Claude only sees the final result.

Progressive Disclosure

my-skill/
├── SKILL.md           # Entry point (required)
├── reference.md       # Detailed docs (loaded when needed)
├── examples.md        # Usage examples (loaded when needed)
└── scripts/
    └── helper.py      # Utility script (executed, not loaded)

Keep SKILL.md under 500 lines. Link to supporting files:

For API details, see [reference.md](reference.md).

Running in a Subagent

Add context: fork to run in isolation:

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

Research $ARGUMENTS thoroughly...

The skill content becomes the subagent’s prompt. It won’t have access to conversation history.

Distribution

• Project skills: Commit .claude/skills/ to version control
• Plugins: Add skills/ directory to plugin
• Enterprise: Deploy organization-wide through managed settings

Reference: Recommended Structure

Recommended Skill Structure

The optimal structure for complex skills separates routing, workflows, and knowledge.

<why_this_works>

Problems This Solves

Problem 1: Context gets skipped When important principles are in a separate file, Claude may not read them. Solution: Put essential principles directly in SKILL.md. They load automatically.

Problem 2: Wrong context loaded A “build” task loads debugging references. A “debug” task loads build references. Solution: Intake question determines intent → routes to specific workflow → workflow specifies which references to read.

Problem 3: Monolithic skills are overwhelming 500+ lines of mixed content makes it hard to find relevant parts. Solution: Small router (SKILL.md) + focused workflows + reference library.

Problem 4: Procedures mixed with knowledge “How to do X” mixed with “What X means” creates confusion. Solution: Workflows are procedures (steps). References are knowledge (patterns, examples). </why_this_works>

<skill_md_template>

SKILL.md Template

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

<essential_principles>
## How This Skill Works

[Inline principles that apply to ALL workflows. Cannot be skipped.]

### Principle 1: [Name]
[Brief explanation]

### Principle 2: [Name]
[Brief explanation]
</essential_principles>

<intake>
**Ask the user:**

What would you like to do?
1. [Option A]
2. [Option B]
3. [Option C]
4. Something else

**Wait for response before proceeding.**
</intake>

<routing>
| Response | Workflow |
|----------|----------|
| 1, "keyword", "keyword" | `workflows/option-a.md` |
| 2, "keyword", "keyword" | `workflows/option-b.md` |
| 3, "keyword", "keyword" | `workflows/option-c.md` |
| 4, other | Clarify, then select |

**After reading the workflow, follow it exactly.**
</routing>

<reference_index>
All domain knowledge in `references/`:

**Category A:** file-a.md, file-b.md
**Category B:** file-c.md, file-d.md
</reference_index>

<workflows_index>
| Workflow | Purpose |
|----------|---------|
| option-a.md | [What it does] |
| option-b.md | [What it does] |
| option-c.md | [What it does] |
</workflows_index>

</skill_md_template>

<workflow_template>

Workflow Template

# Workflow: [Name]

<required_reading>
**Read these reference files NOW:**
1. references/relevant-file.md
2. references/another-file.md
</required_reading>

<process>
## Step 1: [Name]
[What to do]

## Step 2: [Name]
[What to do]

## Step 3: [Name]
[What to do]
</process>

<success_criteria>
This workflow is complete when:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
</success_criteria>

</workflow_template>

<when_to_use_this_pattern>

When to Use This Pattern

Use router + workflows + references when:

• Multiple distinct workflows (build vs debug vs ship)
• Different workflows need different references
• Essential principles must not be skipped
• Skill has grown beyond 200 lines

Use simple single-file skill when:

• One workflow
• Small reference set
• Under 200 lines total
• No essential principles to enforce </when_to_use_this_pattern>

<key_insight>

The Key Insight

SKILL.md is always loaded. Use this guarantee.

Put unavoidable content in SKILL.md:

• Essential principles
• Intake question
• Routing logic

Put workflow-specific content in workflows/:

• Step-by-step procedures
• Required references for that workflow
• Success criteria for that workflow

Put reusable knowledge in references/:

• Patterns and examples
• Technical details
• Domain expertise </key_insight>

Reference: Skill Structure

Skill Structure Reference

Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).

Body Format

Use standard markdown headings for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).

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

# Skill Name

## Quick Start
Immediate actionable guidance...

## Instructions
Step-by-step procedures...

## Examples
Concrete usage examples...

## Guidelines
Rules and constraints...

Recommended Sections

Every skill should have:

• Quick Start - Immediate, actionable guidance (minimal working example)
• Instructions - Core step-by-step guidance
• Success Criteria - How to know it worked

Add based on complexity:

• Context - Background/situational information
• Workflow - Multi-step procedures
• Examples - Concrete input/output pairs
• Advanced Features - Deep-dive topics (link to reference files)
• Anti-Patterns - Common mistakes to avoid
• Guidelines - Rules and constraints

YAML Frontmatter

Required/Recommended Fields

---
name: skill-name-here
description: What it does and when to use it (specific triggers included)
---

Name Field

Validation rules:

• Maximum 64 characters
• Lowercase letters, numbers, hyphens only
• Must match directory name
• No reserved words: “anthropic”, “claude”

Examples:

• triage-prs
• deploy-production
• review-code
• setup-stripe-payments

Avoid: helper, utils, tools, generic names

Description Field

Validation rules:

• Maximum 1024 characters
• Include what it does AND when to use it
• Third person voice

Good:

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

Bad:

description: Helps with documents

Optional Fields

Naming Conventions

Use descriptive names that indicate purpose:

Progressive Disclosure

Keep SKILL.md under 500 lines. Split into reference files:

my-skill/
├── SKILL.md           # Entry point (required, overview + navigation)
├── reference.md       # Detailed docs (loaded when needed)
├── examples.md        # Usage examples (loaded when needed)
└── scripts/
    └── helper.py      # Utility script (executed, not loaded)

Rules:

• Keep references one level deep from SKILL.md
• Add table of contents to reference files over 100 lines
• Use forward slashes in paths: scripts/helper.py
• Name files descriptively: form_validation_rules.md not doc2.md

Validation Checklist

Before finalizing:

• YAML frontmatter valid (name matches directory, description specific)
• Uses standard markdown headings (not XML tags)
• Has Quick Start, Instructions, and Success Criteria sections
• disable-model-invocation: true if skill has side effects
• SKILL.md under 500 lines
• Reference files linked properly from SKILL.md
• File paths use forward slashes
• Tested with real usage

Anti-Patterns

• XML tags in body - Use standard markdown headings
• Vague descriptions - Be specific with trigger keywords
• Deep nesting - Keep references one level from SKILL.md
• Missing invocation control - Side-effect workflows need disable-model-invocation: true
• Inconsistent naming - Directory name must match name field
• Windows paths - Always use forward slashes

Reference: Using Scripts

Using Scripts in Skills

<when_to_use> Use scripts when:

• The same code runs across multiple skill invocations
• Operations are error-prone when rewritten from scratch
• Complex shell commands or API interactions are involved
• Consistency matters more than flexibility

Common script types:

• Deployment - Deploy to Vercel, publish packages, push releases
• Setup - Initialize projects, install dependencies, configure environments
• API calls - Authenticated requests, webhook handlers, data fetches
• Data processing - Transform files, batch operations, migrations
• Build processes - Compile, bundle, test runners </when_to_use>

<script_structure> Scripts live in scripts/ within the skill directory:

skill-name/
├── SKILL.md
├── workflows/
├── references/
├── templates/
└── scripts/
    ├── deploy.sh
    ├── setup.py
    └── fetch-data.ts

A well-structured script includes:

1. Clear purpose comment at top
2. Input validation
3. Error handling
4. Idempotent operations where possible
5. Clear output/feedback </script_structure>

<script_example>

#!/bin/bash
# deploy.sh - Deploy project to Vercel
# Usage: ./deploy.sh [environment]
# Environments: preview (default), production

set -euo pipefail

ENVIRONMENT="${1:-preview}"

# Validate environment
if [[ "$ENVIRONMENT" != "preview" && "$ENVIRONMENT" != "production" ]]; then
    echo "Error: Environment must be 'preview' or 'production'"
    exit 1
fi

echo "Deploying to $ENVIRONMENT..."

if [[ "$ENVIRONMENT" == "production" ]]; then
    vercel --prod
else
    vercel
fi

echo "Deployment complete."

</script_example>

<workflow_integration> Workflows reference scripts like this:

<process>
## Step 5: Deploy

1. Ensure all tests pass
2. Run `scripts/deploy.sh production`
3. Verify deployment succeeded
4. Update user with deployment URL
</process>

The workflow tells Claude WHEN to run the script. The script handles HOW the operation executes. </workflow_integration>

<best_practices> Do:

• Make scripts idempotent (safe to run multiple times)
• Include clear usage comments
• Validate inputs before executing
• Provide meaningful error messages
• Use set -euo pipefail in bash scripts

Don’t:

• Hardcode secrets or credentials (use environment variables)
• Create scripts for one-off operations
• Skip error handling
• Make scripts do too many unrelated things
• Forget to make scripts executable (chmod +x) </best_practices>

<security_considerations>

• Never embed API keys, tokens, or secrets in scripts
• Use environment variables for sensitive configuration
• Validate and sanitize any user-provided inputs
• Be cautious with scripts that delete or modify data
• Consider adding --dry-run options for destructive operations </security_considerations>

Reference: Using Templates

Using Templates in Skills

<when_to_use> Use templates when:

• Output should have consistent structure across invocations
• The structure matters more than creative generation
• Filling placeholders is more reliable than blank-page generation
• Users expect predictable, professional-looking outputs

Common template types:

• Plans - Project plans, implementation plans, migration plans
• Specifications - Technical specs, feature specs, API specs
• Documents - Reports, proposals, summaries
• Configurations - Config files, settings, environment setups
• Scaffolds - File structures, boilerplate code </when_to_use>

<template_structure> Templates live in templates/ within the skill directory:

skill-name/
├── SKILL.md
├── workflows/
├── references/
└── templates/
    ├── plan-template.md
    ├── spec-template.md
    └── report-template.md

A template file contains:

1. Clear section markers
2. Placeholder indicators (use {{placeholder}} or [PLACEHOLDER])
3. Inline guidance for what goes where
4. Example content where helpful </template_structure>

<template_example>

# {{PROJECT_NAME}} Implementation Plan

## Overview
{{1-2 sentence summary of what this plan covers}}

## Goals
- {{Primary goal}}
- {{Secondary goals...}}

## Scope
**In scope:**
- {{What's included}}

**Out of scope:**
- {{What's explicitly excluded}}

## Phases

### Phase 1: {{Phase name}}
**Duration:** {{Estimated duration}}
**Deliverables:**
- {{Deliverable 1}}
- {{Deliverable 2}}

### Phase 2: {{Phase name}}
...

## Success Criteria
- [ ] {{Measurable criterion 1}}
- [ ] {{Measurable criterion 2}}

## Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| {{Risk}} | {{H/M/L}} | {{H/M/L}} | {{Strategy}} |

</template_example>

<workflow_integration> Workflows reference templates like this:

<process>
## Step 3: Generate Plan

1. Read `templates/plan-template.md`
2. Copy the template structure
3. Fill each placeholder based on gathered requirements
4. Review for completeness
</process>

The workflow tells Claude WHEN to use the template. The template provides WHAT structure to produce. </workflow_integration>

<best_practices> Do:

• Keep templates focused on structure, not content
• Use clear placeholder syntax consistently
• Include brief inline guidance where sections might be ambiguous
• Make templates complete but minimal

Don’t:

• Put excessive example content that might be copied verbatim
• Create templates for outputs that genuinely need creative generation
• Over-constrain with too many required sections
• Forget to update templates when requirements change </best_practices>

Reference: Workflows And Validation

<complex_workflows> Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist.

<pdf_forms_example>

<objective>
Fill PDF forms with validated data from JSON field mappings.
</objective>

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

Task Progress:

• Step 1: Analyze the form (run analyze_form.py)
• Step 2: Create field mapping (edit fields.json)
• Step 3: Validate mapping (run validate_fields.py)
• Step 4: Fill the form (run fill_form.py)
• Step 5: Verify output (run verify_output.py)

<step_1>
**Analyze the form**

Run: `python scripts/analyze_form.py input.pdf`

This extracts form fields and their locations, saving to `fields.json`.
</step_1>

<step_2>
**Create field mapping**

Edit `fields.json` to add values for each field.
</step_2>

<step_3>
**Validate mapping**

Run: `python scripts/validate_fields.py fields.json`

Fix any validation errors before continuing.
</step_3>

<step_4>
**Fill the form**

Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
</step_4>

<step_5>
**Verify output**

Run: `python scripts/verify_output.py output.pdf`

If verification fails, return to Step 2.
</step_5>
</workflow>

</pdf_forms_example>

<when_to_use> Use checklist pattern when:

• Workflow has 5+ sequential steps
• Steps must be completed in order
• Progress tracking helps prevent errors
• Easy resumption after interruption is valuable </when_to_use> </complex_workflows>

<feedback_loops> <validate_fix_repeat_pattern> Run validator → fix errors → repeat. This pattern greatly improves output quality.

<document_editing_example>

<objective>
Edit OOXML documents with XML validation at each step.
</objective>

<editing_process>
<step_1>
Make your edits to `word/document.xml`
</step_1>

<step_2>
**Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
</step_2>

<step_3>
If validation fails:
- Review the error message carefully
- Fix the issues in the XML
- Run validation again
</step_3>

<step_4>
**Only proceed when validation passes**
</step_4>

<step_5>
Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
</step_5>

<step_6>
Test the output document
</step_6>
</editing_process>

<validation>
Never skip validation. Catching errors early prevents corrupted output files.
</validation>

</document_editing_example>

<why_it_works>

• Catches errors early before changes are applied
• Machine-verifiable with objective verification
• Plan can be iterated without touching originals
• Reduces total iteration cycles </why_it_works> </validate_fix_repeat_pattern>

<plan_validate_execute_pattern> When Claude performs complex, open-ended tasks, create a plan in a structured format, validate it, then execute.

Workflow: analyze → create plan file → validate plan → execute → verify

<batch_update_example>

<objective>
Apply batch updates to spreadsheet with plan validation.
</objective>

<workflow>
<plan_phase>
<step_1>
Analyze the spreadsheet and requirements
</step_1>

<step_2>
Create `changes.json` with all planned updates
</step_2>
</plan_phase>

<validation_phase>
<step_3>
Validate the plan: `python scripts/validate_changes.py changes.json`
</step_3>

<step_4>
If validation fails:
- Review error messages
- Fix issues in changes.json
- Validate again
</step_4>

<step_5>
Only proceed when validation passes
</step_5>
</validation_phase>

<execution_phase>
<step_6>
Apply changes: `python scripts/apply_changes.py changes.json`
</step_6>

<step_7>
Verify output
</step_7>
</execution_phase>
</workflow>

<success_criteria>
- Plan validation passes with zero errors
- All changes applied successfully
- Output verification confirms expected results
</success_criteria>

</batch_update_example>

<implementation_tip> Make validation scripts verbose with specific error messages:

Good error message: “Field ‘signature_date’ not found. Available fields: customer_name, order_total, signature_date_signed”

Bad error message: “Invalid field”

Specific errors help Claude fix issues without guessing. </implementation_tip>

<when_to_use> Use plan-validate-execute when:

• Operations are complex and error-prone
• Changes are irreversible or difficult to undo
• Planning can be validated independently
• Catching errors early saves significant time </when_to_use> </plan_validate_execute_pattern> </feedback_loops>

<conditional_workflows> Guide Claude through decision points with clear branching logic.

<document_modification_example>

<objective>
Modify DOCX files using appropriate method based on task type.
</objective>

<workflow>
<decision_point_1>
Determine the modification type:

**Creating new content?** → Follow "Creation workflow"
**Editing existing content?** → Follow "Editing workflow"
</decision_point_1>

<creation_workflow>
<objective>Build documents from scratch</objective>

<steps>
1. Use docx-js library
2. Build document from scratch
3. Export to .docx format
</steps>
</creation_workflow>

<editing_workflow>
<objective>Modify existing documents</objective>

<steps>
1. Unpack existing document
2. Modify XML directly
3. Validate after each change
4. Repack when complete
</steps>
</editing_workflow>
</workflow>

<success_criteria>
- Correct workflow chosen based on task type
- All steps in chosen workflow completed
- Output file validated and verified
</success_criteria>

</document_modification_example>

<when_to_use> Use conditional workflows when:

• Different task types require different approaches
• Decision points are clear and well-defined
• Workflows are mutually exclusive
• Guiding Claude to correct path improves outcomes </when_to_use> </conditional_workflows>

<validation_scripts> Validation scripts are force multipliers. They catch errors that Claude might miss and provide actionable feedback for fixing issues.

<characteristics_of_good_validation> <verbose_errors> Good: “Field ‘signature_date’ not found. Available fields: customer_name, order_total, signature_date_signed”

Bad: “Invalid field”

Verbose errors help Claude fix issues in one iteration instead of multiple rounds of guessing. </verbose_errors>

<specific_feedback> Good: “Line 47: Expected closing tag </paragraph> but found </section>”

Bad: “XML syntax error”

Specific feedback pinpoints exact location and nature of the problem. </specific_feedback>

<actionable_suggestions> Good: “Required field ‘customer_name’ is missing. Add: {“customer_name”: “value”}”

Bad: “Missing required field”

Actionable suggestions show Claude exactly what to fix. </actionable_suggestions>

<available_options> When validation fails, show available valid options:

Good: “Invalid status ‘pending_review’. Valid statuses: active, paused, archived”

Bad: “Invalid status”

Showing valid options eliminates guesswork. </available_options> </characteristics_of_good_validation>

<implementation_pattern>

<validation>
After making changes, validate immediately:

```bash
python scripts/validate.py output_dir/

If validation fails, fix errors before continuing. Validation errors include:

• Field not found: “Field ‘signature_date’ not found. Available fields: customer_name, order_total, signature_date_signed”
• Type mismatch: “Field ‘order_total’ expects number, got string”
• Missing required field: “Required field ‘customer_name’ is missing”
• Invalid value: “Invalid status ‘pending_review’. Valid statuses: active, paused, archived”

Only proceed when validation passes with zero errors.

</implementation_pattern>

<benefits>
- Catches errors before they propagate
- Reduces iteration cycles
- Provides learning feedback
- Makes debugging deterministic
- Enables confident execution
</benefits>
</validation_scripts>

<iterative_refinement>
<principle>
Many workflows benefit from iteration: generate → validate → refine → validate → finalize.
</principle>

<implementation_example>
```xml
<objective>
Generate reports with iterative quality improvement.
</objective>

<workflow>
<iteration_1>
**Generate initial draft**

Create report based on data and requirements.
</iteration_1>

<iteration_2>
**Validate draft**

Run: `python scripts/validate_report.py draft.md`

Fix any structural issues, missing sections, or data errors.
</iteration_2>

<iteration_3>
**Refine content**

Improve clarity, add supporting data, enhance visualizations.
</iteration_3>

<iteration_4>
**Final validation**

Run: `python scripts/validate_report.py final.md`

Ensure all quality criteria met.
</iteration_4>

<iteration_5>
**Finalize**

Export to final format and deliver.
</iteration_5>
</workflow>

<success_criteria>
- Final validation passes with zero errors
- All quality criteria met
- Report ready for delivery
</success_criteria>

</implementation_example>

<when_to_use> Use iterative refinement when:

• Quality improves with multiple passes
• Validation provides actionable feedback
• Time permits iteration
• Perfect output matters more than speed </when_to_use> </iterative_refinement>

<checkpoint_pattern> For long workflows, add checkpoints where Claude can pause and verify progress before continuing.

<implementation_example>

<workflow>
<phase_1>
**Data collection** (Steps 1-3)

1. Extract data from source
2. Transform to target format
3. **CHECKPOINT**: Verify data completeness

Only continue if checkpoint passes.
</phase_1>

<phase_2>
**Data processing** (Steps 4-6)

4. Apply business rules
5. Validate transformations
6. **CHECKPOINT**: Verify processing accuracy

Only continue if checkpoint passes.
</phase_2>

<phase_3>
**Output generation** (Steps 7-9)

7. Generate output files
8. Validate output format
9. **CHECKPOINT**: Verify final output

Proceed to delivery only if checkpoint passes.
</phase_3>
</workflow>

<checkpoint_validation>
At each checkpoint:
1. Run validation script
2. Review output for correctness
3. Verify no errors or warnings
4. Only proceed when validation passes
</checkpoint_validation>

</implementation_example>

<error_recovery> Design workflows with clear error recovery paths. Claude should know what to do when things go wrong.

<implementation_example>

<workflow>
<normal_path>
1. Process input file
2. Validate output
3. Save results
</normal_path>

<error_recovery>
**If validation fails in step 2:**
- Review validation errors
- Check if input file is corrupted → Return to step 1 with different input
- Check if processing logic failed → Fix logic, return to step 1
- Check if output format wrong → Fix format, return to step 2

**If save fails in step 3:**
- Check disk space
- Check file permissions
- Check file path validity
- Retry save with corrected conditions
</error_recovery>

<escalation>
**If error persists after 3 attempts:**
- Document the error with full context
- Save partial results if available
- Report issue to user with diagnostic information
</escalation>
</workflow>

</implementation_example>

<when_to_use> Include error recovery when:

• Workflows interact with external systems
• File operations could fail
• Network calls could timeout
• User input could be invalid
• Errors are recoverable </when_to_use> </error_recovery>