skill-builder

Original source / Raw SKILL.md

---
name: skill-builder
description: Expert guidance for creating, writing, building, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure, progressive disclosure, workflows, validation patterns, and XML formatting.
allowed-tools:
  - Read
  - Write
  - Glob
  - Bash
  - AskUserQuestion
---

<objective>
Agent Skills are modular, filesystem-based capabilities that provide domain-specific expertise through progressive disclosure. This Skill teaches you how to create effective Skills that Claude can discover and use successfully.

Skills are organized prompts that get loaded on-demand. All prompting best practices apply, with an emphasis on pure XML structure for consistent parsing and efficient token usage.
</objective>

<quick_start>
<workflow>
1. **Gather requirements**: Ask targeted questions to understand scope, complexity, and specific needs
2. **Detect project context**: Determine if skill should be project-specific or global
3. **Research if needed**: For external APIs/standards, offer to fetch current documentation
4. **Create directory and SKILL.md**:
   - Directory name: Follow verb-noun convention: `create-*`, `manage-*`, `setup-*`, `generate-*`
   - YAML frontmatter: `name` (matches directory), `description` (third person, triggers)
5. **Write concise instructions**: Use pure XML structure, appropriate tags for complexity level
6. **Apply progressive disclosure**: Keep SKILL.md under 500 lines, split details to reference files
7. **Validate structure**: Run automated checks (YAML, line count, required tags, naming)
8. **Test with real scenario**: Invoke skill to verify guidance is clear and actionable
9. **Create slash command**: Lightweight wrapper at correct location (project or global)

See [references/skill-structure.md](references/skill-structure.md) for complete details.
</workflow>

<example_skill>
```yaml
---
name: process-pdfs
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.
---

<objective>
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
</objective>

<quick_start>
Extract text with pdfplumber:

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

<advanced_features>
**Form filling**: See [forms.md](forms.md)
**API reference**: See [reference.md](reference.md)
</advanced_features>
```
</example_skill>
</quick_start>

<xml_structure>
<required_tags>
All skills must have these tags:

- **`<objective>`** - What the skill does and why it matters
- **`<quick_start>`** - Immediate, actionable guidance
- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
</required_tags>

<conditional_tags>
Based on skill complexity, add these tags as needed:

- **`<context>`** - Background/situational information
- **`<workflow>` or `<process>`** - Step-by-step procedures
- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
- **`<validation>`** - How to verify outputs
- **`<examples>`** - Multi-shot learning
- **`<anti_patterns>`** - Common mistakes to avoid
- **`<security_checklist>`** - Non-negotiable security patterns
- **`<testing>`** - Testing workflows
- **`<common_patterns>`** - Code examples and recipes
- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
</conditional_tags>

<critical_rule>
**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
</critical_rule>
</xml_structure>

<intelligence_rules>
<simple_skills>
Single domain, straightforward tasks: Use required tags only.

Example: Text extraction, file format conversion, simple API calls
</simple_skills>

<medium_skills>
Multiple patterns, some complexity: Use required tags + workflow/examples as needed.

Example: Document processing with multiple steps, API integration with configuration
</medium_skills>

<complex_skills>
Multiple domains, security concerns, API integrations: Use required tags + conditional tags as appropriate.

Example: Payment processing, authentication systems, multi-step workflows with validation
</complex_skills>

<principle>
Don't over-engineer simple skills. Don't under-specify complex skills. Match tag selection to actual complexity and user needs.
</principle>
</intelligence_rules>

<generation_protocol>
<step_0>
<description>
**Adaptive Requirements Gathering**: Before building, gather requirements through intelligent questioning that infers obvious details and asks about genuine gaps.
</description>

<critical_first_action>
**BEFORE doing anything else**, check if context was provided.

IF no context provided (user just invoked the skill without describing what to build):
→ **IMMEDIATELY use AskUserQuestion** with these exact options:

1. **Create a new skill** - Build a skill from scratch
2. **Update an existing skill** - Modify or improve an existing skill
3. **Get guidance on skill design** - Help me think through what kind of skill I need

**DO NOT** ask "what would you like to build?" in plain text. **USE the AskUserQuestion tool.**

Routing after selection:
- "Create new" → proceed to adaptive intake below
- "Update existing" → enumerate existing skills as numbered list (see below), then gather requirements for changes
- "Guidance" → help user clarify needs before building

<update_existing_flow>
When "Update existing" is selected:

1. **List all skills in chat as numbered list** (DO NOT use AskUserQuestion - there may be many skills):
   - Glob for `~/skills/*/SKILL.md`
   - Present as numbered list in chat:
     ```
     Available skills:
     1. create-agent-skills
     2. generate-natal-chart
     3. manage-stripe
     ...
     ```
   - Ask: "Which skill would you like to update? (enter number)"

2. After user enters number, read that skill's SKILL.md
3. Ask what they want to change/improve using AskUserQuestion or direct question
4. Proceed with modifications
</update_existing_flow>

IF context was provided (user said "build a skill for X"):
→ Skip this gate. Proceed directly to adaptive intake.
</critical_first_action>

<adaptive_intake>
<analyze_description>
Parse the initial description:
- What's explicitly stated (operations, services, outputs)
- What can be inferred without asking (skill type, complexity, obvious patterns)
- What's genuinely unclear or ambiguous (scope boundaries, edge cases, specific behaviors)

Do NOT ask about things that are obvious from context.
</analyze_description>

<generate_questions>
Use AskUserQuestion to ask 2-4 domain-specific questions based on actual gaps.

Question generation guidance:
- **Scope questions**: "What specific operations?" not "What should it do?"
- **Complexity questions**: "Should this handle [specific edge case]?" based on domain knowledge
- **Output questions**: "What should the user see/get when successful?"
- **Boundary questions**: "Should this also handle [related thing] or stay focused?"

Avoid:
- Questions answerable from the initial description
- Generic questions that apply to all skills
- Yes/no questions when options would be more helpful
- Obvious questions like "what should it be called?" when the name is clear

Each question option should include a description explaining the implications of that choice.
</generate_questions>

<decision_gate>
After receiving answers, present decision gate using AskUserQuestion:

Question: "Ready to proceed with building, or would you like me to ask more questions?"

Options:
1. **Proceed to building** - I have enough context to build the skill
2. **Ask more questions** - There are more details to clarify
3. **Let me add details** - I want to provide additional context

If "Ask more questions" selected → loop back to generate_questions with refined focus
If "Let me add details" → receive additional context, then re-evaluate
If "Proceed" → continue to research_trigger, then step_1
</decision_gate>

<research_trigger>
<detection_patterns>
Detect if the skill involves ANY of the following:

**External APIs or web services:**
- Keywords: "API", "endpoint", "REST", "GraphQL", "webhook", "HTTP"
- Service names: "Stripe", "AWS", "Firebase", "OpenAI", "Anthropic", etc.

**Standard vocabularies and ontologies:**
- Keywords: "schema.org", "vocabulary", "ontology", "JSON-LD", "RDF", "microdata"
- Examples: Schema.org types, Dublin Core, FOAF

**Protocol specifications:**
- Keywords: "specification", "standard", "protocol"
- Examples: "HTTP", "WebSocket", "MQTT", "OAuth", "SAML"

**Third-party libraries or frameworks:**
- Keywords: "library", "package", "framework", "npm", "pip", "cargo"
- Examples: "React", "Django", "pandas", "TensorFlow"

**Data format standards:**
- Keywords: "format", "parser", "serialization"
- Examples: "CSV", "Parquet", "Protocol Buffers", "Avro", "XML"

Detection method: Check user's initial description and all collected requirements for these keywords or patterns.
</detection_patterns>

<research_prompt>
When detected, use AskUserQuestion:

"This skill involves [detected technology/standard]. Would you like me to research current [technology] documentation and patterns before building?"

Options:
1. **Yes, research first** - Fetch 2024-2025 documentation for accurate, up-to-date implementation
2. **No, proceed with general patterns** - Use knowledge cutoff data (January 2025)
3. **I'll provide the documentation** - User will supply relevant documentation or links

If option 1 selected:
- For web APIs: Use WebSearch for "[technology] API documentation 2024 2025"
- For libraries: Use Context7 MCP if available, otherwise WebSearch
- For standards/vocabularies: Use WebSearch for "[standard] specification latest"
- Focus on: current versions, recent changes, migration guides, common patterns
- Summarize findings in internal notes for use in skill generation

If option 3 selected:
- Wait for user to provide documentation
- Read provided links or files
- Summarize key information for skill generation
</research_prompt>

<research_findings_usage>
Incorporate research findings into:
- **Step 1** (Domain analysis): Update with current patterns and best practices
- **Step 4** (Content writing): Use current syntax, API endpoints, method signatures
- **Step 5** (Reference files): Include links to up-to-date documentation
- **Examples and code blocks**: Ensure all code examples use current versions

Note findings in skill generation process:
```
Research findings for [technology]:
- Current version: [version]
- Key changes from knowledge cutoff: [summary]
- Recommended patterns: [list]
- Documentation links: [urls]
```
</research_findings_usage>
</research_trigger>
</adaptive_intake>
</step_0>

<step_0_5>
<description>**Project Context Detection**: Determine if skill should be project-specific or global.</description>

<detection_logic>
Check for project indicators in current working directory or parent directories:

1. **Primary indicators** (strong project context):
   - `CLAUDE.md` file exists
   - `.claude/` directory exists
   - Git repository root (`.git/` directory)

2. **Secondary indicators** (language-specific projects):
   - `package.json` (Node.js)
   - `pyproject.toml` or `setup.py` (Python)
   - `Cargo.toml` (Rust)
   - `pom.xml` or `build.gradle` (Java)
   - `go.mod` (Go)

3. **Path determination**:
   ```bash
   # Use Bash to check project context:
   if [ -f "CLAUDE.md" ] || [ -d ".claude" ]; then
     PROJECT_CONTEXT=true
     PROJECT_ROOT=$(pwd)
   elif git rev-parse --git-dir > /dev/null 2>&1; then
     PROJECT_CONTEXT=true
     PROJECT_ROOT=$(git rev-parse --show-toplevel)
   else
     PROJECT_CONTEXT=false
   fi
   ```

4. **Set paths based on context**:
   - If `PROJECT_CONTEXT=true`:
     - `SKILLS_PATH="$PROJECT_ROOT/skills/"`
     - `COMMANDS_PATH="$PROJECT_ROOT/commands/"`
   - If `PROJECT_CONTEXT=false`:
     - `SKILLS_PATH="$HOME/skills/"`
     - `COMMANDS_PATH="$HOME/commands/"`
</detection_logic>

<user_confirmation>
If project context detected, use AskUserQuestion:

"Detected project context at: [project_root]

Where should this skill be created?"

Options:
1. **Project-specific** (skills/) - Tracked in git, shared with team, specific to this codebase
2. **Global** (~/skills/) - Personal use across all projects, general-purpose skill

Provide recommendation based on skill purpose:
- If skill mentions project-specific terms (file paths, module names, codebase concepts) → Recommend project-specific
- If skill is general-purpose (works with any codebase) → Recommend global
- If user explicitly mentioned "for this project" → Recommend project-specific
- Default recommendation: Project-specific (safer, can be moved to global later)
</user_confirmation>

<path_usage>
Use the determined paths for all file operations:

- **Step 0.5**: Create directory at `$SKILLS_PATH/[skill-name]/`
- **Step 3-5**: Write SKILL.md to `$SKILLS_PATH/[skill-name]/SKILL.md`
- **Step 5**: Create references at `$SKILLS_PATH/[skill-name]/references/`
- **Step 8**: Create slash command at `$COMMANDS_PATH/[skill-name].md`
- **Step 8.5** (if applicable): Create README at `$SKILLS_PATH/[skill-name]/README.md`

All subsequent file operations MUST use these paths, not hardcoded paths.
</path_usage>

<no_project_context>
If NO project context detected:
- Skip user confirmation
- Use global paths: `~/skills/` and `~/commands/`
- Inform user: "Creating global skill at ~/skills/[skill-name]/"
</no_project_context>
</step_0_5>

<step_1>
**Analyze the domain**: Understand what the skill needs to teach and its complexity level. Incorporate gathered requirements and any research findings from step_0.
</step_1>

<step_2>
**Select XML tags**: Choose required tags + conditional tags based on intelligence rules.
</step_2>

<step_3>
**Write YAML frontmatter**: Validate name (matches directory, verb-noun convention) and description (third person, includes triggers).
</step_3>

<step_4>
**Structure content in pure XML**: No markdown headings in body. Use semantic XML tags for all sections.
</step_4>

<step_5>
**Apply progressive disclosure**: Keep SKILL.md under 500 lines. Split detailed content into reference files.
</step_5>

<step_6>
<description>**Validate Structure**: Run automated checks to ensure skill meets all requirements.</description>

<validation_execution>
Execute the following validation checks and report results:

**1. File Structure Checks:**
```bash
# Check SKILL.md exists
[ -f "$SKILLS_PATH/$SKILL_NAME/SKILL.md" ] && echo "✅ SKILL.md exists" || echo "❌ SKILL.md missing"

# Check directory name matches YAML name
YAML_NAME=$(head -20 "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | grep "^name:" | cut -d: -f2 | tr -d ' ')
[ "$YAML_NAME" = "$SKILL_NAME" ] && echo "✅ Name matches directory" || echo "⚠️  Name mismatch"
```

**2. YAML Frontmatter Validation:**
```bash
# Extract and validate YAML
head -20 "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | python3 -c "
import yaml, sys
try:
    doc = yaml.safe_load(sys.stdin)
    print('✅ YAML syntax valid')

    # Check required fields
    if 'name' in doc:
        print(f'✅ Name field present: {doc[\"name\"]}')
        if len(doc['name']) <= 64:
            print(f'✅ Name length OK: {len(doc[\"name\"])} chars')
        else:
            print(f'⚠️  Name too long: {len(doc[\"name\"])} chars (max 64)')
    else:
        print('❌ Name field missing')

    if 'description' in doc:
        print(f'✅ Description field present: {len(doc[\"description\"])} chars')
        if len(doc['description']) <= 1024:
            print(f'✅ Description length OK')
        else:
            print(f'⚠️  Description too long: {len(doc[\"description\"])} chars (max 1024)')
    else:
        print('❌ Description field missing')

except yaml.YAMLError as e:
    print(f'❌ YAML parse error: {e}')
"
```

**3. Line Count Check:**
```bash
LINE_COUNT=$(wc -l < "$SKILLS_PATH/$SKILL_NAME/SKILL.md")
echo "SKILL.md line count: $LINE_COUNT"
if [ $LINE_COUNT -lt 500 ]; then
    echo "✅ Line count under 500 limit ($LINE_COUNT lines, $(( (500 - LINE_COUNT) )) remaining)"
else
    echo "⚠️  Line count exceeds 500 limit ($LINE_COUNT lines, $(( (LINE_COUNT - 500) )) over)"
fi
```

**4. XML Structure Checks:**
```bash
# Check for markdown headings
HEADING_COUNT=$(grep -c '^#' "$SKILLS_PATH/$SKILL_NAME/SKILL.md" || echo 0)
if [ $HEADING_COUNT -eq 0 ]; then
    echo "✅ No markdown headings found"
else
    echo "⚠️  Found $HEADING_COUNT markdown headings - should use XML tags instead"
    grep -n '^#' "$SKILLS_PATH/$SKILL_NAME/SKILL.md"
fi

# Check required tags
for TAG in "objective" "quick_start" "success_criteria"; do
    if grep -q "<$TAG>" "$SKILLS_PATH/$SKILL_NAME/SKILL.md"; then
        echo "✅ Required tag <$TAG> present"
    else
        if [ "$TAG" = "success_criteria" ]; then
            if grep -q "<when_successful>" "$SKILLS_PATH/$SKILL_NAME/SKILL.md"; then
                echo "✅ Alternative tag <when_successful> present"
            else
                echo "❌ Missing required tag: <$TAG> or <when_successful>"
            fi
        else
            echo "❌ Missing required tag: <$TAG>"
        fi
    fi
done

# List all XML tags found
echo "XML tags found:"
grep -oE '<[a-z_]+>' "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | sort | uniq -c | sort -rn
```

**5. Progressive Disclosure Check:**
```bash
if [ $LINE_COUNT -gt 300 ]; then
    if [ -d "$SKILLS_PATH/$SKILL_NAME/references" ]; then
        REF_COUNT=$(find "$SKILLS_PATH/$SKILL_NAME/references" -name "*.md" | wc -l)
        echo "✅ Progressive disclosure: $REF_COUNT reference files created"
    else
        echo "⚠️  SKILL.md is $LINE_COUNT lines but no reference files found - consider splitting"
    fi
fi
```

**6. Reference Link Validation:**
```bash
# Check all reference links exist
grep -oE '\[.*\]\([^)]+\.md\)' "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | while read link; do
    FILE=$(echo "$link" | sed 's/.*(\(.*\))/\1/')
    if [ -f "$SKILLS_PATH/$SKILL_NAME/$FILE" ]; then
        echo "✅ Reference link valid: $FILE"
    else
        echo "⚠️  Broken reference link: $FILE"
    fi
done
```

**7. Naming Convention Check:**
```bash
# Check verb-noun pattern
SKILL_FIRST_WORD=$(echo "$SKILL_NAME" | cut -d- -f1)
COMMON_VERBS="create manage setup generate analyze process coordinate build handle configure deploy execute extract transform validate parse render compile"

if echo "$COMMON_VERBS" | grep -qw "$SKILL_FIRST_WORD"; then
    echo "✅ Naming convention: '$SKILL_FIRST_WORD' follows verb-noun pattern"
else
    echo "⚠️  Naming: '$SKILL_FIRST_WORD' is not a common verb - verify it's action-oriented"
fi
```
</validation_execution>

<validation_report>
After running checks, present a consolidated validation report:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skill Validation Report: [skill-name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

File Structure:     [✅/❌] [details]
YAML Frontmatter:   [✅/❌] [details]
Line Count:         [✅/⚠️]  [X lines / 500 limit]
Required Tags:      [✅/❌] [3/3 present]
No MD Headings:     [✅/⚠️]  [X found]
XML Structure:      [✅/❌] [tags properly nested]
Progressive Disc:   [✅/⚠️]  [X ref files]
Reference Links:    [✅/⚠️]  [all valid / X broken]
Naming Convention:  [✅/⚠️]  [verb-noun pattern]
Slash Command:      [✅/❌] [exists at correct path]

Overall Status: [PASS ✅ / NEEDS FIXES ⚠️  / FAIL ❌]

[If issues found, list them with suggested fixes]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
</validation_report>

<failure_handling>
If any critical validations fail (❌):

1. **Stop immediately** - Do not proceed to Step 7
2. **Report failures** clearly with specific line numbers or details
3. **Attempt automatic fixes** where possible:
   - Remove markdown headings → convert to XML tags
   - Fix YAML syntax errors if obvious
   - Rename files to match conventions
4. **If cannot auto-fix**, ask user:
   ```
   Validation failed. How should I proceed?

   Options:
   1. Let me try to fix automatically
   2. Show me the issues and I'll fix manually
   3. Proceed anyway (not recommended)
   ```
5. **Re-run validation** after fixes applied
6. **Only proceed to Step 7** when all critical checks pass

**Warning-level issues** (⚠️) can proceed but should be noted:
- Line count 400-500: "Approaching limit, future edits may need reference split"
- Uncommon verb in name: "Ensure name is clear and action-oriented"
- No reference files when >300 lines: "Consider splitting for better progressive disclosure"
</failure_handling>

<quick_validation_mode>
For simple skills or rapid iteration, offer quick validation:

"Run full validation checks or quick validation?"

Quick validation only checks:
- YAML frontmatter valid
- Required tags present
- No markdown headings
- Line count < 500

Full validation runs all 7 check categories above.
</quick_validation_mode>
</step_6>

<step_7>
<description>**Test with Real Usage**: Verify the skill works as expected through actual invocation.</description>

<test_offer>
After skill creation and validation, use AskUserQuestion:

"The [skill-name] skill has been created and validated. How would you like to proceed?"

Options:
1. **Test it now** - I'll provide a sample scenario to test the skill guidance
2. **Skip testing** - Test it later during actual usage
3. **You provide test scenario** - I'll use your scenario to test the skill

Recommendation: Option 1 (testing now catches issues before delivery)
</test_offer>

<sample_scenario_generation>
If user selects "Test it now", generate a realistic test scenario based on skill purpose:

**For different skill types:**

- **API integration skills** (e.g., manage-stripe):
  ```
  Scenario: You need to create a new subscription for a customer.
  Let's invoke the skill and see what guidance it provides.
  ```

- **Code processing skills** (e.g., coordinate-subagents):
  ```
  Scenario: You need to find all files handling user authentication.
  Let's use the skill to craft an efficient subagent prompt.
  ```

- **Data transformation skills** (e.g., process-csv):
  ```
  Scenario: You have a CSV file with 10,000 rows and need to filter
  and transform specific columns. Let's test the skill's guidance.
  ```

- **Setup/configuration skills** (e.g., setup-testing):
  ```
  Scenario: You need to add testing to a new TypeScript project.
  Let's see what the skill recommends.
  ```

Generate scenario that exercises the skill's primary workflow.
</sample_scenario_generation>

<skill_invocation>
After scenario generation:

1. **Invoke the skill** using the Skill tool:
   ```
   Skill: [skill-name]
   Context: [generated scenario]
   ```

2. **Observe the response**:
   - Is the guidance clear and actionable?
   - Are the steps in logical order?
   - Are examples helpful and realistic?
   - Is any critical information missing?
   - Are there any confusing or ambiguous instructions?

3. **Document observations**:
   ```
   Test Observations:
   ✅ Clear: [what worked well]
   ⚠️  Unclear: [what was confusing]
   ❌ Missing: [what information was needed but not provided]
   💡 Suggestions: [potential improvements]
   ```
</skill_invocation>

<iteration_prompt>
After testing and observation, ask user:

"Based on the test, the skill guidance seems [assessment]. Would you like to iterate?"

Options:
1. **Yes, make improvements** - I'll update based on testing observations
2. **No, it's good enough** - Proceed to Step 8 (slash command creation)
3. **Show me the issues first** - Let me review before deciding

If option 1 selected:
- List specific improvements to make
- Make edits to SKILL.md or reference files
- Re-run validation (Step 6)
- Offer to test again with same or different scenario

If option 2 or 3 selected:
- Proceed to Step 8
</iteration_prompt>

<user_provided_scenario>
If user selected "You provide test scenario":

1. **Wait for user scenario**: "Please describe the scenario you'd like to test with."

2. **Acknowledge scenario**: "I'll test the skill with: [user scenario]"

3. **Invoke skill** with user's scenario

4. **Follow observation and iteration process** as above
</user_provided_scenario>

<skip_testing>
If user selected "Skip testing":

1. **Note in output**: "Testing skipped - recommend testing during first actual use"

2. **Provide testing reminder**:
   ```
   When you first use this skill, observe:
   - Is the guidance immediately actionable?
   - Are there any unclear instructions?
   - Is any critical information missing?

   If issues found, you can improve the skill by editing:
   $SKILLS_PATH/[skill-name]/SKILL.md
   ```

3. **Proceed to Step 8**
</skip_testing>

<testing_benefits>
Benefits of testing before delivery:
- **Catches unclear instructions** before user encounters them
- **Validates that examples are realistic** and actually helpful
- **Ensures workflow steps are logical** and in correct order
- **Identifies missing information** that domain experts might assume
- **Improves skill quality** immediately, not after user frustration
- **Builds confidence** that skill will work when needed

Testing adds 2-5 minutes but can save hours of confusion later.
</testing_benefits>

<common_testing_findings>
Issues frequently discovered during testing:

1. **Missing context**: Skill assumes knowledge user doesn't have
   - Fix: Add `<context>` section with background

2. **Steps out of order**: Workflow jumps around
   - Fix: Reorder steps to follow actual execution sequence

3. **Examples too abstract**: Code examples don't match real use cases
   - Fix: Use more realistic, specific examples

4. **Missing error handling**: Doesn't address what to do when things fail
   - Fix: Add `<troubleshooting>` or error handling guidance

5. **Terminology mismatch**: Skill uses different terms than user expects
   - Fix: Add `<terminology>` section or adjust language

6. **Too verbose or too terse**: Wrong level of detail
   - Fix: Adjust based on complexity (intelligence rules)
</common_testing_findings>
</step_7>

<step_8>
**Create slash command wrapper**: Create a lightweight slash command that invokes the skill.

Location: `$COMMANDS_PATH/{skill-name}.md` (determined in Step 0.5)

Template:
```yaml
---
description: {Brief description of what the skill does}
argument-hint: [{argument description}]
allowed-tools: Skill({skill-name})
---

<objective>
Delegate {task} to the {skill-name} skill for: $ARGUMENTS

This routes to specialized skill containing patterns, best practices, and workflows.
</objective>

<process>
1. Use Skill tool to invoke {skill-name} skill
2. Pass user's request: $ARGUMENTS
3. Let skill handle workflow
</process>

<success_criteria>
- Skill successfully invoked
- Arguments passed correctly to skill
</success_criteria>
```

The slash command's only job is routing—all expertise lives in the skill.
</step_8>
</generation_protocol>

<yaml_requirements>
<required_fields>
```yaml
---
name: skill-name-here
description: What it does and when to use it (third person, specific triggers)
---
```
</required_fields>

<validation_rules>
See [references/skill-structure.md](references/skill-structure.md) for complete validation rules and naming conventions.
</validation_rules>
</yaml_requirements>

<when_to_use>
<create_skills_for>
- Reusable patterns across multiple tasks
- Domain knowledge that doesn't change frequently
- Complex workflows that benefit from structured guidance
- Reference materials (schemas, APIs, libraries)
- Validation scripts and quality checks
</create_skills_for>

<use_prompts_for>
One-off tasks that won't be reused
</use_prompts_for>

<use_slash_commands_for>
Explicit user-triggered workflows that run with fresh context
</use_slash_commands_for>
</when_to_use>

<reference_guides>
For deeper topics, see reference files:

**Core principles**: [references/core-principles.md](references/core-principles.md)
- XML structure (consistency, parseability, Claude performance)
- Conciseness (context window is shared)
- Degrees of freedom (matching specificity to task fragility)
- Model testing (Haiku vs Sonnet vs Opus)

**Skill structure**: [references/skill-structure.md](references/skill-structure.md)
- XML structure requirements
- Naming conventions
- Writing effective descriptions
- Progressive disclosure patterns
- File organization

**Workflows and validation**: [references/workflows-and-validation.md](references/workflows-and-validation.md)
- Complex workflows with checklists
- Feedback loops (validate → fix → repeat)
- Plan-validate-execute pattern

**Common patterns**: [references/common-patterns.md](references/common-patterns.md)
- Template patterns
- Examples patterns
- Consistent terminology
- Anti-patterns to avoid

**Executable code**: [references/executable-code.md](references/executable-code.md)
- When to use utility scripts
- Error handling in scripts
- Package dependencies
- MCP tool references

**API security**: [references/api-security.md](references/api-security.md)
- Preventing credentials from appearing in chat
- Using the secure API wrapper
- Adding new services and operations
- Credential storage patterns

**Iteration and testing**: [references/iteration-and-testing.md](references/iteration-and-testing.md)
- Evaluation-driven development
- Claude A/B development pattern
- Observing how Claude navigates Skills
- XML structure validation during testing

**Prompting fundamentals**:
- [references/clear-and-direct.md](references/clear-and-direct.md)
- [references/use-xml-tags.md](references/use-xml-tags.md)
</reference_guides>

<success_criteria>
A well-structured skill has:

- Valid YAML frontmatter with descriptive name and comprehensive description
- Pure XML structure with no markdown headings in body
- Required tags: objective, quick_start, success_criteria
- Conditional tags appropriate to complexity level
- Progressive disclosure (SKILL.md < 500 lines, details in reference files)
- Clear, concise instructions that assume Claude is smart
- Real-world testing and iteration based on observed behavior
- Lightweight slash command wrapper for discoverability
</success_criteria>


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/skill-structure.md

```markdown
<overview>
Comprehensive guide to skill organization, naming, and structure.
</overview>

<xml_structure_requirements>
<pure_xml_in_body>
**CRITICAL RULE**: Remove ALL markdown headings (#, ##, ###) from skill body content. Replace with semantic XML tags.

**Keep markdown formatting WITHIN content:**
- Bold: `**text**`
- Italic: `*text*`
- Lists: `- item` or `1. item`
- Code blocks: ` ```language ``` `
- Links: `[text](url)`
- Inline code: `` `code` ``

**Convert headings to XML tags:**

```markdown
<!-- ❌ WRONG - markdown headings -->
## Instructions
### Step 1: Setup
- Do something

<!-- ✅ CORRECT - XML tags -->
<instructions>
<step_1_setup>
- Do something
</step_1_setup>
</instructions>
```
</pure_xml_in_body>

<required_xml_tags>
Every skill MUST have these three tags:

1. **`<objective>`** - What the skill does and why it matters
   - First thing Claude reads
   - Should be 1-3 sentences
   - Focus on the goal, not the steps

2. **`<quick_start>`** - Immediate, actionable guidance
   - The "just show me how" section
   - Can include `<workflow>` for step-by-step
   - Can include `<example_skill>` for templates

3. **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
   - Observable outcomes
   - Validation checks
   - Expected artifacts
</required_xml_tags>

<conditional_xml_tags>
Add these based on complexity (see intelligence rules):

- **`<context>`** - Background/situational information
- **`<workflow>` or `<process>`** - Step-by-step procedures
- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
- **`<validation>`** - How to verify outputs
- **`<examples>`** - Multi-shot learning
- **`<anti_patterns>`** - Common mistakes to avoid
- **`<security_checklist>`** - Non-negotiable security patterns
- **`<testing>`** - Testing workflows
- **`<common_patterns>`** - Code examples and recipes
- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
</conditional_xml_tags>

<xml_best_practices>
**Semantic Naming:**
```xml
<!-- ✅ GOOD - describes purpose -->
<generation_protocol>
<adaptive_intake>
<research_trigger>

<!-- ❌ BAD - generic or unclear -->
<section_1>
<misc>
<stuff>
```

**Proper Nesting:**
```xml
<!-- ✅ GOOD - clear hierarchy -->
<generation_protocol>
  <step_0>
    <critical_first_action>
      Content here
    </critical_first_action>
  </step_0>
</generation_protocol>

<!-- ❌ BAD - flat structure -->
<generation_protocol></generation_protocol>
<step_0></step_0>
<critical_first_action></critical_first_action>
```

**Closing Tags:**
```xml
<!-- ✅ GOOD - properly closed -->
<objective>
Content here
</objective>

<!-- ❌ BAD - missing close tag -->
<objective>
Content here
```
</xml_best_practices>
</xml_structure_requirements>

<naming_conventions>
<skill_directory_name>
**Pattern:** `^[a-z0-9]+(-[a-z0-9]+)*$`

**Conventions:**
- Lowercase letters, numbers, hyphens only
- Max 64 characters
- Verb-noun pattern preferred: `create-*`, `manage-*`, `setup-*`, `generate-*`, `analyze-*`, `process-*`
- Descriptive and unique

**Examples:**
- ✅ `create-agent-skills`
- ✅ `process-pdfs`
- ✅ `manage-stripe-subscriptions`
- ✅ `generate-natal-chart`
- ❌ `CreateSkills` (uppercase)
- ❌ `create_skills` (underscores)
- ❌ `skill` (too vague)
</skill_directory_name>

<skill_name_field>
**Must match directory name exactly:**

```yaml
# Directory: skills/create-agent-skills/
---
name: create-agent-skills  # ✅ Matches directory
---
```
</skill_name_field>

<supporting_file_organization>
```
skills/skill-name/
├── SKILL.md              # Required: Main skill file
├── references/           # Optional: Progressive disclosure
│   ├── topic-1.md
│   ├── topic-2.md
│   └── topic-3.md
├── templates/            # Optional: Template files
│   ├── template-1.ext
│   └── template-2.ext
├── checklists/           # Optional: Reference checklists
│   └── checklist-1.md
├── scripts/              # Optional: Executable scripts
│   ├── script-1.sh
│   └── script-2.py
└── examples/             # Optional: Example files
    ├── before.ext
    └── after.ext
```
</supporting_file_organization>
</naming_conventions>

<writing_effective_descriptions>
<description_field_requirements>
**Validation:**
- Max 1024 characters
- Third person voice
- Include WHAT it does
- Include WHEN to use it (trigger terms)
- Include WHEN NOT to use it (if ambiguous)
</description_field_requirements>

<description_formula>
```
[What it does]. Use when [trigger scenarios]. [Optional: DO NOT use for [exclusions]].
```
</description_formula>

<good_description_examples>
✅ **Specific with clear triggers:**
```yaml
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.
```

✅ **Clear boundaries:**
```yaml
description: Expert guidance for creating, writing, building, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure, progressive disclosure, workflows, validation patterns, and XML formatting.
```

✅ **Domain-specific with exclusions:**
```yaml
description: Manage Stripe subscriptions, customers, and billing. Use when user mentions Stripe, subscriptions, payments, or billing. DO NOT use for other payment providers (PayPal, Square).
```
</good_description_examples>

<bad_description_examples>
❌ **Too vague:**
```yaml
description: Reviews code
```

❌ **Too broad:**
```yaml
description: Handles all git operations including status, diff, commit, push, pull, merge, rebase, and branch management. Use for any git task.
```

❌ **Missing triggers:**
```yaml
description: This skill helps with PDF processing tasks.
```

❌ **First person voice:**
```yaml
description: I will help you create agent skills.
```
</bad_description_examples>
</writing_effective_descriptions>

<progressive_disclosure_patterns>
<keep_skill_md_focused>
**Target: < 500 lines for main SKILL.md**

**Strategy:**
1. **Core instructions in SKILL.md**
   - Required tags (objective, quick_start, success_criteria)
   - Essential workflow
   - Common use cases

2. **Detailed content in reference files**
   - Deep-dive explanations
   - Extensive examples
   - API references
   - Advanced patterns
   - Troubleshooting guides

3. **Link from SKILL.md to references**
   ```xml
   <reference_guides>
   For detailed validation patterns, see [references/validation.md](references/validation.md)
   For API reference, see [references/api.md](references/api.md)
   </reference_guides>
   ```
</keep_skill_md_focused>

<reference_file_organization>
**By topic (recommended):**
```
references/
├── skill-structure.md      # One topic per file
├── core-principles.md
├── workflows-validation.md
└── common-patterns.md
```

**By type:**
```
references/
├── api/
│   ├── endpoint-1.md
│   └── endpoint-2.md
└── guides/
    ├── quickstart.md
    └── advanced.md
```
</reference_file_organization>

<when_to_split_content>
**Keep in SKILL.md:**
- Core workflow (step-by-step)
- Essential context
- Quick examples
- Common patterns

**Move to references/**:
- Detailed explanations (>100 lines)
- Comprehensive API docs
- Extensive code examples
- Troubleshooting matrices
- Advanced topics
</when_to_split_content>
</progressive_disclosure_patterns>

<file_organization_best_practices>
<directory_structure_by_complexity>
**Simple skill (single file):**
```
skill-name/
└── SKILL.md
```

**Medium skill (with templates):**
```
skill-name/
├── SKILL.md
└── templates/
    ├── template-1.md
    └── template-2.md
```

**Complex skill (full structure):**
```
skill-name/
├── SKILL.md
├── references/
│   ├── topic-1.md
│   ├── topic-2.md
│   └── topic-3.md
├── templates/
│   └── template-1.md
├── checklists/
│   └── checklist-1.md
└── scripts/
    └── utility-1.sh
```
</directory_structure_by_complexity>

<relative_path_references>
**From SKILL.md to supporting files:**

```markdown
See [references/api.md](references/api.md) for API details.
See [templates/component.tsx](templates/component.tsx) for template.
See [checklists/security.md](checklists/security.md) for checklist.
Run `scripts/validate.sh` to validate.
```

**Claude loads these files on-demand** - they don't consume context until referenced.
</relative_path_references>
</file_organization_best_practices>

<validation_checklist>
Before finalizing a skill:

- [ ] **Directory name**: Matches pattern, verb-noun, max 64 chars
- [ ] **YAML frontmatter**: Valid syntax, name matches directory
- [ ] **Description**: ≤1024 chars, third person, includes triggers
- [ ] **XML structure**: No markdown headings in body
- [ ] **Required tags**: Has objective, quick_start, success_criteria
- [ ] **Conditional tags**: Appropriate for complexity level
- [ ] **XML validity**: All tags properly closed, semantic names
- [ ] **Progressive disclosure**: SKILL.md < 500 lines, details in references
- [ ] **File organization**: Supporting files in correct directories
- [ ] **Relative paths**: References use correct relative paths
- [ ] **Focus**: One capability, not swiss army knife
- [ ] **Security**: allowed-tools restricted appropriately
</validation_checklist>

<common_skill_patterns>
<pattern_1_review_audit>
**Purpose:** Analyze code/docs/configs for quality

**Characteristics:**
- Read-only operations
- Structured evaluation
- Checklist-driven

**Structure:**
```
skill-name/
├── SKILL.md
└── checklists/
    ├── security-checklist.md
    └── quality-checklist.md
```

**Example tools:**
```yaml
allowed-tools:
  - Read
  - Grep
  - Glob
  # No Write/Edit
```
</pattern_1_review_audit>

<pattern_2_generation>
**Purpose:** Create new files/content

**Characteristics:**
- Template-based
- Write operations
- Structured output

**Structure:**
```
skill-name/
├── SKILL.md
└── templates/
    ├── template-1.md
    └── template-2.md
```

**Example tools:**
```yaml
allowed-tools:
  - Read
  - Write
  - Grep
  - Glob
  - Bash
```
</pattern_2_generation>

<pattern_3_transformation>
**Purpose:** Modify existing files

**Characteristics:**
- Edit operations
- Before/after examples
- Validation steps

**Structure:**
```
skill-name/
├── SKILL.md
└── examples/
    ├── before.ts
    └── after.ts
```

**Example tools:**
```yaml
allowed-tools:
  - Read
  - Edit
  - Grep
  - Glob
```
</pattern_3_transformation>

<pattern_4_analysis>
**Purpose:** Extract insights from codebase

**Characteristics:**
- Search operations
- Data aggregation
- Report generation

**Structure:**
```
skill-name/
├── SKILL.md
├── references/
│   └── metrics.md
└── scripts/
    └── analyze.sh
```

**Example tools:**
```yaml
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
```
</pattern_4_analysis>
</common_skill_patterns>

<installation_locations>
<project_skills>
**Location:** `skills/<skill-name>/`

**Characteristics:**
- Committed to version control
- Shared across team
- Team standards and workflows
- Project-specific patterns

**Usage:**
```bash
git add skills/skill-name
git commit -m "feat(skills): add skill-name skill"
git push
```
</project_skills>

<personal_skills>
**Location:** `~/skills/<skill-name>/`

**Characteristics:**
- NOT committed to version control
- Personal workflows
- Experimental skills
- Individual preferences

**Usage:**
- Simply create in `~/skills/`
- Available only to you
- Can be copied to other machines manually
</personal_skills>
</installation_locations>

```

### references/core-principles.md

```markdown
<overview>
Fundamental principles that make skills effective, efficient, and maintainable.
</overview>

<progressive_disclosure>
<description>
Progressive disclosure is the **core design principle** that makes Agent Skills flexible and scalable. It operates on three levels:
</description>

<level_1_metadata>
**What:** Name + Description (~100 tokens)
**When:** At startup, loaded into system prompt
**Purpose:** Claude knows ALL skills exist and when to use them

```yaml
---
name: process-pdfs
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.
---
```

This lightweight metadata enables skill discovery without consuming significant context.
</level_1_metadata>

<level_2_full_instructions>
**What:** Complete SKILL.md content (<5k tokens recommended)
**When:** When Claude determines the skill is relevant
**Purpose:** Full workflow, examples, validation

Claude loads SKILL.md only when needed based on the description's trigger terms matching the user's request.
</level_2_full_instructions>

<level_3_additional_resources>
**What:** Reference files, templates, scripts, checklists
**When:** When Claude references them in SKILL.md
**Purpose:** Deep-dive content, API docs, extensive examples

```markdown
See [references/api-details.md](references/api-details.md) for complete API reference.
```

Claude navigates to these files **only when necessary** for the specific task.
</level_3_additional_resources>

<why_this_matters>
**Without progressive disclosure:**
- All content loaded upfront → context window bloat
- Limited skill complexity → can't include comprehensive docs
- One-size-fits-all → inefficient for simple tasks

**With progressive disclosure:**
- Minimal baseline cost (~100 tokens per skill metadata)
- Effectively unbounded skill complexity (load only what's needed)
- Efficient scaling (10 skills = ~1k tokens, 100 skills = ~10k tokens)
- Task-appropriate depth (simple tasks don't load deep references)
</why_this_matters>

<design_implication>
**Keep SKILL.md < 500 lines:**
- Core workflow and essential context only
- Link to references/ for detailed content
- Balance thoroughness with token efficiency

**Split reference files by topic:**
- Mutually exclusive topics in separate files
- Claude loads only relevant topics
- Example: `api-authentication.md` vs `api-webhooks.md`
</design_implication>
</progressive_disclosure>

<pure_xml_structure>
<description>
Claude was **trained with XML tags** and has been **fine-tuned to pay special attention** to their structure.
</description>

<why_xml_over_markdown>
**Advantages of XML:**
1. **Semantic meaning**: `<validation>` is clearer than "## Validation"
2. **Parseability**: Claude can extract structured content reliably
3. **Nested hierarchy**: `<step_1><substep_a></substep_a></step_1>`
4. **Standardization**: Consistent structure across all skills
5. **Training alignment**: Claude was trained on XML-structured prompts

**Performance difference:**
- XML tags: Claude recognizes structure immediately
- Markdown headings: Generic text requiring interpretation
</why_xml_over_markdown>

<xml_tag_guidelines>
**Semantic naming:**
```xml
<!-- ✅ GOOD - describes purpose -->
<objective>
<quick_start>
<validation>
<success_criteria>

<!-- ❌ BAD - generic -->
<section_1>
<part_a>
<misc>
```

**Consistent closing:**
```xml
<!-- ✅ GOOD - properly closed -->
<workflow>
  <step_1>
    Content here
  </step_1>
</workflow>

<!-- ❌ BAD - missing close -->
<workflow>
  <step_1>
    Content here
```

**Appropriate nesting:**
```xml
<!-- ✅ GOOD - logical hierarchy -->
<generation_protocol>
  <step_0>
    <critical_first_action>
      Gate logic here
    </critical_first_action>
    <adaptive_intake>
      Questioning logic here
    </adaptive_intake>
  </step_0>
</generation_protocol>

<!-- ❌ BAD - flat when hierarchy exists -->
<generation_protocol></generation_protocol>
<step_0></step_0>
<critical_first_action></critical_first_action>
```
</xml_tag_guidelines>

<required_vs_conditional_tags>
**Required tags (every skill):**
- `<objective>` - What and why
- `<quick_start>` - Immediate actionable guidance
- `<success_criteria>` or `<when_successful>` - Observable outcomes

**Conditional tags (based on complexity):**
- `<context>` - Background information
- `<workflow>` or `<process>` - Step-by-step procedures
- `<advanced_features>` - Progressive disclosure to deep topics
- `<validation>` - Verification procedures
- `<examples>` - Multi-shot learning
- `<anti_patterns>` - Common mistakes
- `<security_checklist>` - Non-negotiable security patterns
- `<reference_guides>` - Links to reference files
</required_vs_conditional_tags>

<markdown_within_xml>
**Keep these markdown formats:**
- **Bold**: `**text**`
- *Italic*: `*text*`
- Lists: `- item` or `1. item`
- Code blocks: ` ```language ``` `
- Links: `[text](url)`
- Inline code: `` `code` ``

**Example:**
```xml
<workflow>
1. **First step**: Do something
   - Sub-point with `inline code`
   - Another sub-point
2. **Second step**: Do another thing
   ```python
   code_example()
   ```
</workflow>
```
</markdown_within_xml>
</pure_xml_structure>

<conciseness>
<description>
Every token in a skill competes with:
- Conversation history
- Other loaded skills
- User's files and context
- Tool outputs
</description>

<conciseness_strategies>
**Assume Claude is smart:**
```xml
<!-- ❌ VERBOSE - explaining obvious things -->
<instruction>
First, you need to open the file. To open a file, you use the Read tool.
The Read tool takes a file_path parameter. You must provide the absolute path.
An absolute path starts with / on Unix systems or C:\ on Windows...
</instruction>

<!-- ✅ CONCISE - Claude knows this -->
<instruction>
Read the file using the Read tool.
</instruction>
```

**Focus on domain knowledge Claude lacks:**
```xml
<!-- ✅ GOOD - domain-specific context Claude needs -->
<stripe_subscription_lifecycle>
Stripe subscriptions have three critical timestamps:
- `current_period_start`: When current billing cycle began
- `current_period_end`: When cycle ends (billing date)
- `trial_end`: When trial ends (may differ from period end)

DO NOT cancel at `current_period_end` thinking it's the trial end.
Use `trial_end` for trial cancellations.
</stripe_subscription_lifecycle>
```

**Reference, don't repeat:**
```xml
<!-- ❌ VERBOSE - repeating full API in SKILL.md -->
<stripe_api>
[500 lines of API documentation]
</stripe_api>

<!-- ✅ CONCISE - reference file -->
<stripe_api>
See [references/stripe-api.md](references/stripe-api.md) for complete API reference.

Common operations:
- Create subscription: `POST /v1/subscriptions`
- Update subscription: `POST /v1/subscriptions/:id`
- Cancel subscription: `DELETE /v1/subscriptions/:id`
</stripe_api>
```
</conciseness_strategies>
</conciseness>

<degrees_of_freedom>
<description>
The **degrees of freedom** principle: Be as specific as necessary, but no more specific than required.
</description>

<high_specificity>
**When:** Fragile tasks that MUST be done exactly right
**Examples:** Security reviews, API authentication, financial transactions, data validation

```xml
<security_checklist>
CRITICAL: Check these in order:

1. **Input validation**: ALWAYS sanitize user input
   - SQL: Use parameterized queries, NEVER string concatenation
   - XSS: Escape HTML entities in output
   - Path traversal: Validate file paths against whitelist

2. **Authentication**: MUST use established patterns
   - API keys: NEVER commit to version control
   - Passwords: MUST hash with bcrypt/scrypt (min 10 rounds)
   - Tokens: MUST expire (max 24h for sessions)

3. **Authorization**: Check before EVERY operation
   - Verify user owns resource
   - Check role permissions
   - Log access attempts
</security_checklist>
```
</high_specificity>

<low_specificity>
**When:** Creative tasks with many valid approaches
**Examples:** Documentation writing, code refactoring, exploratory analysis

```xml
<documentation_guidelines>
Write clear, helpful documentation that:
- Explains the "why" not just the "what"
- Includes practical examples
- Anticipates common questions
- Uses appropriate tone for audience

Structure and style are flexible based on context.
</documentation_guidelines>
```
</low_specificity>

<balanced_specificity>
**When:** Structured but not rigid tasks
**Examples:** Skill creation, code generation, file organization

```xml
<skill_creation_workflow>
Follow this general workflow, adapting as needed:

1. **Gather requirements**: Understand purpose, triggers, complexity
2. **Design structure**: Choose appropriate XML tags
3. **Write content**: Core instructions + references
4. **Validate**: Check naming, YAML, XML structure
5. **Test**: Real usage with trigger terms

Adjust order and depth based on skill complexity.
</skill_creation_workflow>
```
</balanced_specificity>

<decision_framework>
Ask: "What happens if Claude does this differently?"

**High stakes → Low freedom:**
- Security vulnerability
- Data loss
- Financial error
- System breakage
→ Use MUST, NEVER, ALWAYS, specific steps

**Low stakes → High freedom:**
- Stylistic preference
- Multiple valid approaches
- Exploratory work
- Creative output
→ Use should, consider, typically, guidelines
</decision_framework>
</degrees_of_freedom>

<model_selection>
<description>
Different Claude models excel at different tasks.
</description>

<model_characteristics>
**Haiku (Fast, Efficient):**
- Simple pattern matching
- Straightforward transformations
- Template filling
- Basic validation
- Cost: ~$0.25 per million tokens

**Sonnet (Balanced):**
- Moderate complexity
- Multi-step workflows
- Code generation
- Analysis tasks
- Cost: ~$3 per million tokens

**Opus (Powerful, Comprehensive):**
- Complex reasoning
- Novel problem solving
- Architecture design
- Security audits
- Cost: ~$15 per million tokens
</model_characteristics>

<testing_strategy>
**Start with Sonnet (default), then test edges:**

1. **Can Haiku handle this?**
   - Simple enough for fast model?
   - Pattern-based or template-driven?
   - If yes → save cost, improve speed

2. **Does this need Opus?**
   - Requires deep reasoning?
   - Novel or complex problem?
   - High stakes (security, architecture)?
   - If yes → use Opus for reliability
</testing_strategy>

<specifying_model_in_skills>
```yaml
---
name: simple-formatter
description: Format files according to template
model: haiku  # Simple transformation
---
```

```yaml
---
name: security-audit
description: Comprehensive security review
model: opus  # High stakes, deep reasoning
---
```

```yaml
---
name: code-generator
description: Generate code from specs
# No model specified → uses default (Sonnet)
---
```
</specifying_model_in_skills>
</model_selection>

<third_person_voice>
<description>
Skill descriptions are injected into Claude's **system prompt**, not shown to the user.
</description>

<why_third_person_matters>
**System prompt context:**
```
You are Claude. Your capabilities include:
- [Skill 1 description]
- [Skill 2 description]
- [Skill 3 description]
```

**First person breaks immersion:**
```
- I will help you create agent skills  ❌ (Claude thinks it's talking to itself)
```

**Third person maintains consistency:**
```
- Expert guidance for creating agent skills  ✅ (Claude understands this is a capability)
```
</why_third_person_matters>

<description_voice_examples>
✅ **Third person:**
```yaml
description: Extracts text from PDF files. Use when user mentions PDFs or document extraction.
description: Manages Stripe subscriptions and billing. Use when working with Stripe API.
description: Reviews code for security vulnerabilities. Use for security audits.
```

❌ **First person:**
```yaml
description: I extract text from PDF files when you ask me to.
description: I'll help you manage Stripe subscriptions.
description: I can review your code for security issues.
```
</description_voice_examples>
</third_person_voice>

<summary_checklist>
When creating a skill, ensure:

- [ ] **Progressive disclosure**: SKILL.md < 500 lines, details in references
- [ ] **Pure XML**: No markdown headings, semantic tag names, proper closing
- [ ] **Conciseness**: Only include what Claude doesn't already know
- [ ] **Appropriate freedom**: Match specificity to task fragility
- [ ] **Model consideration**: Test if Haiku/Opus would be better than Sonnet
- [ ] **Third person**: Description written as Claude's capability, not Claude's voice
</summary_checklist>

```

### references/workflows-and-validation.md

```markdown
<overview>
Patterns for complex workflows, validation loops, and quality assurance in agent skills.
</overview>

<complex_workflow_patterns>
<linear_workflow>
**When:** Sequential steps, each depends on the previous

```xml
<workflow>
1. **Gather requirements**: Ask user for input
2. **Design structure**: Based on requirements
3. **Create files**: Implement the design
4. **Validate**: Check against requirements
5. **Deliver**: Present to user
</workflow>
```

**Characteristics:**
- Clear sequence A → B → C
- Each step prerequisite for next
- No branching or loops
- Best for straightforward tasks
</linear_workflow>

<branching_workflow>
**When:** Different paths based on conditions

```xml
<workflow>
1. **Analyze input**: Determine input type

2. **Branch by type**:
   - If PDF → Extract with pdfplumber
   - If Word → Extract with python-docx
   - If HTML → Extract with BeautifulSoup
   - If plain text → Read directly

3. **Validate extraction**: Check output quality

4. **Return results**: Standardized format
</workflow>
```

**Characteristics:**
- Decision points create branches
- Different tools/approaches per branch
- Converges at validation/output
- Best for multi-format or multi-method tasks
</branching_workflow>

<iterative_workflow>
**When:** Quality improvements through loops

```xml
<workflow>
1. **Generate initial draft**: First attempt

2. **Validate against criteria**: Check requirements

3. **If validation fails**:
   - Identify specific issues
   - Refine draft addressing issues
   - Return to step 2 (max 3 iterations)

4. **If validation passes**: Deliver final version
</workflow>
```

**Characteristics:**
- Explicit feedback loop
- Quality gates with criteria
- Maximum iteration limit (prevent infinite loops)
- Best for creative or complex output
</iterative_workflow>

<parallel_workflow>
**When:** Multiple independent tasks can run simultaneously

```xml
<workflow>
1. **Identify components**: Break into independent parts

2. **Execute in parallel**:
   ```
   [Task A: Generate documentation]
   [Task B: Write tests]
   [Task C: Create examples]
   ```
   (Use multiple tool calls in single message)

3. **Integrate results**: Combine outputs

4. **Validate integration**: Check combined result
</workflow>
```

**Characteristics:**
- Tasks have no dependencies
- Can execute simultaneously
- Requires integration step
- Best for composite deliverables
</parallel_workflow>

<phased_workflow>
**When:** Distinct phases with different focuses

```xml
<workflow>
**Phase 1: Discovery**
1. Analyze codebase
2. Identify patterns
3. Document findings

**Phase 2: Planning**
1. Design approach based on findings
2. Get user approval
3. Refine plan if needed

**Phase 3: Execution**
1. Implement changes
2. Run tests
3. Fix issues

**Phase 4: Validation**
1. Comprehensive testing
2. Documentation update
3. User review
</workflow>
```

**Characteristics:**
- Clear phase boundaries
- Phase completion checkpoints
- May include user gates (approvals)
- Best for large, complex projects
</phased_workflow>
</complex_workflow_patterns>

<validation_patterns>
<checklist_validation>
**When:** Multiple specific criteria to verify

```xml
<validation>
<checklist>
Validate the skill against these criteria:

**Structure:**
- [ ] Directory name matches pattern `^[a-z0-9]+(-[a-z0-9]+)*$`
- [ ] SKILL.md exists with valid YAML frontmatter
- [ ] Name field matches directory name
- [ ] Description ≤1024 characters, third person

**XML:**
- [ ] No markdown headings in body
- [ ] Required tags present (objective, quick_start, success_criteria)
- [ ] All XML tags properly closed
- [ ] Semantic tag names (not generic)

**Content:**
- [ ] Clear trigger terms in description
- [ ] Focused on one capability
- [ ] Progressive disclosure (SKILL.md < 500 lines)
- [ ] References use correct relative paths

**Security:**
- [ ] allowed-tools appropriate for task
- [ ] No credentials in files
- [ ] Scripts audited if included
</checklist>

If ANY item fails, address it before proceeding.
</validation>
```
</checklist_validation>

<schema_validation>
**When:** Structured data must match specific format

```xml
<validation>
<schema_validation>
Validate YAML frontmatter against schema:

**Required fields:**
```yaml
name: string (lowercase, hyphens, max 64 chars)
description: string (max 1024 chars)
```

**Optional fields:**
```yaml
allowed-tools: string[] (valid tool names)
model: "haiku" | "sonnet" | "opus"
```

**Validation script:**
```bash
# Check YAML is parseable
python -c "import yaml; yaml.safe_load(open('SKILL.md'))"

# Check name pattern
grep -E '^name: [a-z0-9]+(-[a-z0-9]+)*$' SKILL.md

# Check description length
python -c "import yaml; d=yaml.safe_load(open('SKILL.md')); assert len(d['description']) <= 1024"
```
</schema_validation>
</validation>
```
</schema_validation>

<functional_validation>
**When:** Testing actual behavior/output

```xml
<validation>
<functional_testing>
Test the skill with real usage:

**Setup:**
1. Create test skill in temporary directory
2. Load Claude with skill available
3. Prepare test scenarios

**Test cases:**
1. **Discovery test**: Use trigger terms without mentioning skill name
   - Expected: Claude loads the skill automatically
   - Verify: Skill mentioned in Claude's response

2. **Workflow test**: Complete a full task
   - Expected: Follows skill instructions
   - Verify: Output matches success criteria

3. **Edge case test**: Unusual or boundary conditions
   - Expected: Graceful handling
   - Verify: No errors, appropriate response

**Pass criteria:**
- All test cases pass
- No tool permission errors
- References load correctly
- Output quality acceptable
</functional_testing>
</validation>
```
</functional_validation>
</validation_patterns>

<plan_validate_execute_pattern>
<description>
Structured approach for high-stakes tasks.
</description>

<pattern_structure>
```xml
<plan_validate_execute>
**Phase 1: PLAN**
1. Analyze requirements thoroughly
2. Design complete approach
3. Identify risks and edge cases
4. Create execution checklist

**Phase 2: VALIDATE PLAN**
1. Review plan against requirements
2. Check for missing elements
3. Get user confirmation if needed
4. Refine plan based on feedback

**Phase 3: EXECUTE**
1. Follow plan step-by-step
2. Mark items as complete
3. Handle unexpected issues
4. Document any deviations

**Phase 4: VALIDATE EXECUTION**
1. Check output against success criteria
2. Run functional tests
3. Verify no regressions
4. Get user approval if required

If validation fails at any phase, return to previous phase.
</plan_validate_execute>
```
</pattern_structure>

<when_to_use>
**High-stakes scenarios:**
- Security implementations
- Data migrations
- System architecture changes
- Production deployments
- Financial transactions

**Complex scenarios:**
- Multiple file modifications
- Cross-reference updates
- API integrations
- Workflow automations

**Learning scenarios:**
- Novel problems
- Unfamiliar domains
- Exploratory tasks
- Research-heavy work
</when_to_use>

<example_implementation>
```xml
<security_review_workflow>
<phase_1_plan>
1. **Identify scope**:
   - Which files/components to review
   - What security standards apply (OWASP, CWE)
   - Any specific concerns mentioned

2. **Design checklist**:
   - Input validation points
   - Authentication/authorization checks
   - Data handling (encryption, sanitization)
   - External dependencies
   - Error handling security

3. **Plan evidence collection**:
   - What to document
   - How to present findings
   - Severity classification
</phase_1_plan>

<phase_2_validate_plan>
**Verify plan completeness:**
- [ ] All security categories covered
- [ ] Appropriate depth for risk level
- [ ] Evidence collection defined
- [ ] User agrees with scope

If incomplete, refine plan.
</phase_2_validate_plan>

<phase_3_execute>
**Conduct review:**
1. Systematically check each item on checklist
2. Document findings with file:line references
3. Classify severity (Critical/High/Medium/Low)
4. Note false positives and why
5. Suggest remediation for each issue
</phase_3_execute>

<phase_4_validate_execution>
**Verify review quality:**
- [ ] All checklist items completed
- [ ] Every finding documented with location
- [ ] Severity justified
- [ ] Remediation actionable
- [ ] No missed obvious issues

If quality insufficient, return to execution.
</phase_4_validate_execution>
</security_review_workflow>
```
</example_implementation>
</plan_validate_execute_pattern>

<feedback_loop_patterns>
<simple_feedback_loop>
**When:** Single validation criterion

```xml
<simple_loop>
```python
max_attempts = 3
for attempt in range(max_attempts):
    output = generate()
    if validate(output):
        return output
    else:
        refine_based_on_issues()
return best_effort_output
```

**Instructions:**
1. Generate output
2. Validate against criteria
3. If valid → done
4. If invalid → identify issues, refine, retry (max 3 attempts)
5. If max attempts → return best effort with caveat
</simple_loop>
```
</simple_feedback_loop>

<multi_criteria_feedback_loop>
**When:** Multiple validation dimensions

```xml
<multi_criteria_loop>
**Validation criteria:**
1. **Functional**: Does it work?
2. **Quality**: Is it well-written?
3. **Complete**: All requirements met?
4. **Secure**: No vulnerabilities?

**Loop logic:**
```
For each criterion:
    If fails → address specifically
    Track which criteria passing

If all criteria pass → done
If any fail after 3 iterations → flag for manual review
```

**Advantage:** Targeted refinement per criterion, not blanket revision
</multi_criteria_loop>
```
</multi_criteria_feedback_loop>

<progressive_refinement_loop>
**When:** Quality improves incrementally

```xml
<progressive_refinement>
**Iteration 1: Core functionality**
- Focus: Does it work at all?
- Validation: Basic functional test
- If fail → fix critical issues

**Iteration 2: Quality improvement**
- Focus: Code quality, readability
- Validation: Linting, standards
- If fail → improve specific quality issues

**Iteration 3: Polish**
- Focus: Edge cases, documentation, tests
- Validation: Comprehensive review
- If fail → minor refinements

Each iteration builds on previous, no rework of passing elements.
</progressive_refinement>
```
</progressive_refinement_loop>
</feedback_loop_patterns>

<error_handling_in_workflows>
<graceful_degradation>
```xml
<error_handling>
<graceful_degradation>
When encountering errors:

1. **Attempt primary approach**
   - If succeeds → continue workflow
   - If fails → log error, try fallback

2. **Attempt fallback approach**
   - If succeeds → continue with note about fallback used
   - If fails → try minimal viable

3. **Minimal viable output**
   - Partial success if possible
   - Clear documentation of what worked/didn't
   - Actionable next steps for user

Never fail silently. Always explain what happened and why.
</graceful_degradation>
</error_handling>
```
</graceful_degradation>

<fail_fast_validation>
```xml
<error_handling>
<fail_fast>
For critical prerequisites, validate immediately:

**Before starting main workflow:**
```
1. Check required files exist
2. Verify API credentials available
3. Validate input format
4. Confirm tool permissions

If ANY prerequisite fails:
    - STOP immediately
    - Report specific failure
    - Suggest remediation
    - DO NOT proceed with main workflow
```

**Rationale:** Failing early saves tokens and time, provides clearer feedback.
</fail_fast>
</error_handling>
```
</fail_fast_validation>
</error_handling_in_workflows>

<workflow_documentation_best_practices>
<numbered_steps_with_clear_actions>
```xml
<!-- ✅ GOOD - clear, actionable -->
<workflow>
1. **Read configuration file**: Use Read tool on `config.json`
2. **Validate schema**: Check required fields present
3. **Apply defaults**: For any missing optional fields
4. **Write updated config**: Use Write tool to save
</workflow>

<!-- ❌ BAD - vague, unclear sequence -->
<workflow>
You should look at the config file and then do validation.
After that update things as needed and save it.
</workflow>
```
</numbered_steps_with_clear_actions>

<decision_points_with_clear_conditions>
```xml
<!-- ✅ GOOD - explicit conditions -->
<workflow>
3. **Check authentication type**:
   - If `auth.type === "oauth"` → Execute OAuth flow
   - If `auth.type === "api_key"` → Use API key header
   - If `auth.type === "basic"` → Use Basic Auth
   - If unrecognized → Error: unsupported auth type
</workflow>

<!-- ❌ BAD - ambiguous branching -->
<workflow>
3. Figure out what kind of auth to use and do it.
</workflow>
```
</decision_points_with_clear_conditions>

<expected_outcomes_at_each_step>
```xml
<!-- ✅ GOOD - observable outcomes -->
<workflow>
1. **Fetch user data**: API call to `/users/:id`
   - Success: JSON object with user fields
   - Failure: 404 if user not found, 401 if unauthorized

2. **Validate user active**: Check `user.status === "active"`
   - If active → proceed to step 3
   - If inactive → return error "User account inactive"
</workflow>

<!-- ❌ BAD - no outcome clarity -->
<workflow>
1. Get the user data
2. Make sure they're active
</workflow>
```
</expected_outcomes_at_each_step>
</workflow_documentation_best_practices>

<summary>
**Choose workflow pattern based on task:**
- Linear → sequential dependencies
- Branching → conditional paths
- Iterative → quality refinement
- Parallel → independent components
- Phased → complex multi-stage

**Choose validation pattern based on need:**
- Checklist → multiple specific criteria
- Schema → structured data format
- Functional → behavior/output testing

**Use plan-validate-execute for:**
- High-stakes tasks
- Complex operations
- Novel problems

**Implement feedback loops when:**
- Quality matters more than speed
- Clear validation criteria exist
- Refinement improves output

**Handle errors gracefully:**
- Fail-fast for prerequisites
- Graceful degradation for attempts
- Always explain what happened
</summary>

```

### references/common-patterns.md

```markdown
<overview>
This reference documents common patterns for skill authoring, including templates, examples, terminology consistency, and anti-patterns. All patterns use pure XML structure.
</overview>

<template_pattern>
<description>
Provide templates for output format. Match the level of strictness to your needs.
</description>

<strict_requirements>
Use when output format must be exact and consistent:

```xml
<report_structure>
ALWAYS use this exact template structure:

```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```
</report_structure>
```

**When to use**: Compliance reports, standardized formats, automated processing
</strict_requirements>

<flexible_guidance>
Use when Claude should adapt the format based on context:

```xml
<report_structure>
Here is a sensible default format, but use your best judgment:

```markdown
# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]

## Recommendations
[Tailor to the specific context]
```

Adjust sections as needed for the specific analysis type.
</report_structure>
```

**When to use**: Exploratory analysis, context-dependent formatting, creative tasks
</flexible_guidance>
</template_pattern>

<examples_pattern>
<description>
For skills where output quality depends on seeing examples, provide input/output pairs.
</description>

<commit_messages_example>
```xml
<objective>
Generate commit messages following conventional commit format.
</objective>

<commit_message_format>
Generate commit messages following these examples:

<example number="1">
<input>Added user authentication with JWT tokens</input>
<output>
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```
</output>
</example>

<example number="2">
<input>Fixed bug where dates displayed incorrectly in reports</input>
<output>
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```
</output>
</example>

Follow this style: type(scope): brief description, then detailed explanation.
</commit_message_format>
```
</commit_messages_example>

<when_to_use>
- Output format has nuances that text explanations can't capture
- Pattern recognition is easier than rule following
- Examples demonstrate edge cases
- Multi-shot learning improves quality
  </when_to_use>
  </examples_pattern>

<consistent_terminology>
<principle>
Choose one term and use it throughout the skill. Inconsistent terminology confuses Claude and reduces execution quality.
</principle>

<good_example>
Consistent usage:
- Always "API endpoint" (not mixing with "URL", "API route", "path")
- Always "field" (not mixing with "box", "element", "control")
- Always "extract" (not mixing with "pull", "get", "retrieve")

```xml
<objective>
Extract data from API endpoints using field mappings.
</objective>

<quick_start>
1. Identify the API endpoint
2. Map response fields to your schema
3. Extract field values
</quick_start>
```
</good_example>

<bad_example>
Inconsistent usage creates confusion:

```xml
<objective>
Pull data from API routes using element mappings.
</objective>

<quick_start>
1. Identify the URL
2. Map response boxes to your schema
3. Retrieve control values
</quick_start>
```

Claude must now interpret: Are "API routes" and "URLs" the same? Are "fields", "boxes", "elements", and "controls" the same?
</bad_example>

<implementation>
1. Choose terminology early in skill development
2. Document key terms in `<objective>` or `<context>`
3. Use find/replace to enforce consistency
4. Review reference files for consistent usage
</implementation>
</consistent_terminology>

<provide_default_with_escape_hatch>
<principle>
Provide a default approach with an escape hatch for special cases, not a list of alternatives. Too many options paralyze decision-making.
</principle>

<good_example>
Clear default with escape hatch:

```xml
<quick_start>
Use pdfplumber for text extraction:

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

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
</quick_start>
```
</good_example>

<bad_example>
Too many options creates decision paralysis:

```xml
<quick_start>
You can use any of these libraries:

- **pypdf**: Good for basic extraction
- **pdfplumber**: Better for tables
- **PyMuPDF**: Faster but more complex
- **pdf2image**: For scanned documents
- **pdfminer**: Low-level control
- **tabula-py**: Table-focused

Choose based on your needs.
</quick_start>
```

Claude must now research and compare all options before starting. This wastes tokens and time.
</bad_example>

<implementation>
1. Recommend ONE default approach
2. Explain when to use the default (implied: most of the time)
3. Add ONE escape hatch for edge cases
4. Link to advanced reference if multiple alternatives truly needed
</implementation>
</provide_default_with_escape_hatch>

<anti_patterns>
<description>
Common mistakes to avoid when authoring skills.
</description>

<pitfall name="markdown_headings_in_body">
❌ **BAD**: Using markdown headings in skill body:

```markdown
# PDF Processing

## Quick start
Extract text with pdfplumber...

## Advanced features
Form filling requires additional setup...
```

✅ **GOOD**: Using pure XML structure:

```xml
<objective>
PDF processing with text extraction, form filling, and merging capabilities.
</objective>

<quick_start>
Extract text with pdfplumber...
</quick_start>

<advanced_features>
Form filling requires additional setup...
</advanced_features>
```

**Why it matters**: XML provides semantic meaning, reliable parsing, and token efficiency.
</pitfall>

<pitfall name="vague_descriptions">
❌ **BAD**:
```yaml
description: Helps with documents
```

✅ **GOOD**:
```yaml
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.
```

**Why it matters**: Vague descriptions prevent Claude from discovering and using the skill appropriately.
</pitfall>

<pitfall name="inconsistent_pov">
❌ **BAD**:
```yaml
description: I can help you process Excel files and generate reports
```

✅ **GOOD**:
```yaml
description: Processes Excel files and generates reports. Use when analyzing spreadsheets or .xlsx files.
```

**Why it matters**: Skills must use third person. First/second person breaks the skill metadata pattern.
</pitfall>

<pitfall name="wrong_naming_convention">
❌ **BAD**: Directory name doesn't match skill name or verb-noun convention:
- Directory: `facebook-ads`, Name: `facebook-ads-manager`
- Directory: `stripe-integration`, Name: `stripe`
- Directory: `helper-scripts`, Name: `helper`

✅ **GOOD**: Consistent verb-noun convention:
- Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
- Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
- Directory: `process-pdfs`, Name: `process-pdfs`

**Why it matters**: Consistency in naming makes skills discoverable and predictable.
</pitfall>

<pitfall name="too_many_options">
❌ **BAD**:
```xml
<quick_start>
You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or pdfminer, or tabula-py...
</quick_start>
```

✅ **GOOD**:
```xml
<quick_start>
Use pdfplumber for text extraction:

```python
import pdfplumber
```

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
</quick_start>
```

**Why it matters**: Decision paralysis. Provide one default approach with escape hatch for special cases.
</pitfall>

<pitfall name="deeply_nested_references">
❌ **BAD**: References nested multiple levels:
```
SKILL.md → advanced.md → details.md → examples.md
```

✅ **GOOD**: References one level deep from SKILL.md:
```
SKILL.md → advanced.md
SKILL.md → details.md
SKILL.md → examples.md
```

**Why it matters**: Claude may only partially read deeply nested files. Keep references one level deep from SKILL.md.
</pitfall>

<pitfall name="windows_paths">
❌ **BAD**:
```xml
<reference_guides>
See scripts\validate.py for validation
</reference_guides>
```

✅ **GOOD**:
```xml
<reference_guides>
See scripts/validate.py for validation
</reference_guides>
```

**Why it matters**: Always use forward slashes for cross-platform compatibility.
</pitfall>

<pitfall name="dynamic_context_and_file_reference_execution">
**Problem**: When showing examples of dynamic context syntax (exclamation mark + backticks) or file references (@ prefix), the skill loader executes these during skill loading.

❌ **BAD** - These execute during skill load:
```xml
<examples>
Load current status with: !`git status`
Review dependencies in: @package.json
</examples>
```

✅ **GOOD** - Add space to prevent execution:
```xml
<examples>
Load current status with: ! `git status` (remove space before backtick in actual usage)
Review dependencies in: @ package.json (remove space after @ in actual usage)
</examples>
```

**When this applies**:
- Skills that teach users about dynamic context (slash commands, prompts)
- Any documentation showing the exclamation mark prefix syntax or @ file references
- Skills with example commands or file paths that shouldn't execute during loading

**Why it matters**: Without the space, these execute during skill load, causing errors or unwanted file reads.
</pitfall>

<pitfall name="missing_required_tags">
❌ **BAD**: Missing required tags:
```xml
<quick_start>
Use this tool for processing...
</quick_start>
```

✅ **GOOD**: All required tags present:
```xml
<objective>
Process data files with validation and transformation.
</objective>

<quick_start>
Use this tool for processing...
</quick_start>

<success_criteria>
- Input file successfully processed
- Output file validates without errors
- Transformation applied correctly
</success_criteria>
```

**Why it matters**: Every skill must have `<objective>`, `<quick_start>`, and `<success_criteria>` (or `<when_successful>`).
</pitfall>

<pitfall name="hybrid_xml_markdown">
❌ **BAD**: Mixing XML tags with markdown headings:
```markdown
<objective>
PDF processing capabilities
</objective>

## Quick start

Extract text with pdfplumber...

## Advanced features

Form filling...
```

✅ **GOOD**: Pure XML throughout:
```xml
<objective>
PDF processing capabilities
</objective>

<quick_start>
Extract text with pdfplumber...
</quick_start>

<advanced_features>
Form filling...
</advanced_features>
```

**Why it matters**: Consistency in structure. Either use pure XML or pure markdown (prefer XML).
</pitfall>

<pitfall name="unclosed_xml_tags">
❌ **BAD**: Forgetting to close XML tags:
```xml
<objective>
Process PDF files

<quick_start>
Use pdfplumber...
</quick_start>
```

✅ **GOOD**: Properly closed tags:
```xml
<objective>
Process PDF files
</objective>

<quick_start>
Use pdfplumber...
</quick_start>
```

**Why it matters**: Unclosed tags break XML parsing and create ambiguous boundaries.
</pitfall>
</anti_patterns>

<progressive_disclosure_pattern>
<description>
Keep SKILL.md concise by linking to detailed reference files. Claude loads reference files only when needed.
</description>

<implementation>
```xml
<objective>
Manage Facebook Ads campaigns, ad sets, and ads via the Marketing API.
</objective>

<quick_start>
<basic_operations>
See [basic-operations.md](basic-operations.md) for campaign creation and management.
</basic_operations>
</quick_start>

<advanced_features>
**Custom audiences**: See [audiences.md](audiences.md)
**Conversion tracking**: See [conversions.md](conversions.md)
**Budget optimization**: See [budgets.md](budgets.md)
**API reference**: See [api-reference.md](api-reference.md)
</advanced_features>
```

**Benefits**:
- SKILL.md stays under 500 lines
- Claude only reads relevant reference files
- Token usage scales with task complexity
- Easier to maintain and update
</implementation>
</progressive_disclosure_pattern>

<validation_pattern>
<description>
For skills with validation steps, make validation scripts verbose and specific.
</description>

<implementation>
```xml
<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"

Only proceed when validation passes with zero errors.
</validation>
```

**Why verbose errors help**:
- Claude can fix issues without guessing
- Specific error messages reduce iteration cycles
- Available options shown in error messages
</implementation>
</validation_pattern>

<checklist_pattern>
<description>
For complex multi-step workflows, provide a checklist Claude can copy and track progress.
</description>

<implementation>
```xml
<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>
```

**Benefits**:
- Clear progress tracking
- Prevents skipping steps
- Easy to resume after interruption
  </implementation>
  </checklist_pattern>

```

### references/executable-code.md

```markdown
<when_to_use_scripts>
Even if Claude could write a script, pre-made scripts offer advantages:
- More reliable than generated code
- Save tokens (no need to include code in context)
- Save time (no code generation required)
- Ensure consistency across uses

<execution_vs_reference>
Make clear whether Claude should:
- **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
- **Read it as reference** (for complex logic): "See `analyze_form.py` for the extraction algorithm"

For most utility scripts, execution is preferred.
</execution_vs_reference>

<how_scripts_work>
When Claude executes a script via bash:
1. Script code never enters context window
2. Only script output consumes tokens
3. Far more efficient than having Claude generate equivalent code
   </how_scripts_work>
   </when_to_use_scripts>

<file_organization>
<scripts_directory>
**Best practice**: Place all executable scripts in a `scripts/` subdirectory within the skill folder.

```
skill-name/
├── SKILL.md
├── scripts/
│   ├── main_utility.py
│   ├── helper_script.py
│   └── validator.py
└── references/
    └── api-docs.md
```

**Benefits**:
- Keeps skill root clean and organized
- Clear separation between documentation and executable code
- Consistent pattern across all skills
- Easy to reference: `python scripts/script_name.py`

**Reference pattern**: In SKILL.md, reference scripts using the `scripts/` path:

```bash
python ~/skills/skill-name/scripts/analyze.py input.har
```
</scripts_directory>
</file_organization>

<utility_scripts_pattern>
<example>
## Utility scripts

**analyze_form.py**: Extract all form fields from PDF

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

Output format:
```json
{
  "field_name": { "type": "text", "x": 100, "y": 200 },
  "signature": { "type": "sig", "x": 150, "y": 500 }
}
```

**validate_boxes.py**: Check for overlapping bounding boxes

```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```

**fill_form.py**: Apply field values to PDF

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```
</example>
</utility_scripts_pattern>

<solve_dont_punt>
Handle error conditions rather than punting to Claude.

<example type="good">
```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:
        print(f"File {path} not found, creating default")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        print(f"Cannot access {path}, using default")
        return ''
```
</example>

<example type="bad">
```python
def process_file(path):
    # Just fail and let Claude figure it out
    return open(path).read()
```
</example>

<configuration_values>
Document configuration parameters to avoid "voodoo constants":

<example type="good">
```python
# HTTP requests typically complete within 30 seconds
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
MAX_RETRIES = 3
```
</example>

<example type="bad">
```python
TIMEOUT = 47  # Why 47?
RETRIES = 5   # Why 5?
```
</example>
</configuration_values>
</solve_dont_punt>

<package_dependencies>
<runtime_constraints>
Skills run in code execution environment with platform-specific limitations:
- **claude.ai**: Can install packages from npm and PyPI
- **Anthropic API**: No network access and no runtime package installation
  </runtime_constraints>

<guidance>
List required packages in your SKILL.md and verify they're available.

<example type="good">
Install required package: `pip install pypdf`

Then use it:

```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```
</example>

<example type="bad">
"Use the pdf library to process the file."
</example>
</guidance>
</package_dependencies>

<mcp_tool_references>
If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names.

<format>ServerName:tool_name</format>

<examples>
- Use the BigQuery:bigquery_schema tool to retrieve table schemas.
- Use the GitHub:create_issue tool to create issues.
</examples>

Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
</mcp_tool_references>

```

### references/api-security.md

```markdown
<overview>
Best practices for handling API credentials and sensitive data in skills.
</overview>

<core_problem>
**Raw curl commands with environment variables expose credentials** when Claude executes them, making API keys visible in chat conversations.

Skills that interact with external APIs need credentials, but:
1. **Credentials in chat = security breach**: API keys exposed in conversation history
2. **Hardcoded credentials = version control leak**: Secrets committed to git
3. **User prompts for keys = poor UX**: Interrupts workflow, keys visible in chat
4. **Environment vars in commands = exposure**: `curl -H "Authorization: Bearer $API_KEY"` exposes the key
</core_problem>

<secure_api_wrapper_solution>
<primary_solution>
**Use `~/.claude/scripts/secure-api.sh`**

This wrapper script loads credentials internally rather than exposing them in commands.

**DO NOT:**
- Use raw curl commands with `$API_KEY` environment variables
- Include API keys directly in skills or chat
- Ask user to paste API keys in chat
- Store credentials in skill files

**DO:**
- Use `~/.claude/scripts/secure-api.sh` as a wrapper
- Store credentials in `~/.claude/.env`
- Reference credentials internally within the wrapper
- Validate credential availability before operations
</primary_solution>

<implementation_steps_for_new_services>
<step_1_add_operations>
**Add operations to secure-api.sh wrapper**

Implement service cases with curl calls that reference environment variables internally:

```bash
# Inside ~/.claude/scripts/secure-api.sh

case "$service" in
  "stripe")
    case "$operation" in
      "get-customer")
        customer_id="$1"
        curl -s "https://api.stripe.com/v1/customers/$customer_id" \
          -H "Authorization: Bearer $STRIPE_API_KEY"
        ;;
      "create-subscription")
        # Read JSON from stdin for POST
        curl -s -X POST "https://api.stripe.com/v1/subscriptions" \
          -H "Authorization: Bearer $STRIPE_API_KEY" \
          -H "Content-Type: application/json" \
          -d @-
        ;;
    esac
    ;;
esac
```
</step_1_add_operations>

<step_2_enable_profile_support>
Add profile remapping logic for multiple accounts:

```bash
# Profile naming convention: SERVICENAME_PROFILENAME_APIKEY

if [ -n "$profile" ]; then
  # Remap environment variables for selected profile
  eval "STRIPE_API_KEY=\$STRIPE_${profile}_API_KEY"
fi
```
</step_2_enable_profile_support>

<step_3_create_credential_placeholders>
Create credential placeholders in ~/.claude/.env:

```bash
# ~/.claude/.env

# Stripe credentials
STRIPE_MAIN_API_KEY=
STRIPE_TEST_API_KEY=

# Add entries so users know what to configure
```
</step_3_create_credential_placeholders>

<step_4_document_workflow>
Document workflow in SKILL.md:

```xml
<api_workflow>
<check_profiles>
Check if user has saved a profile preference:

```bash
profile-state get stripe-profile
```

If profile is set, use it. Otherwise, discover available profiles.
</check_profiles>

<discover_profiles>
List available Stripe profiles:

```bash
list.md-profiles stripe
```

Output example:
```
Available Stripe profiles:
- main
- test
```

If multiple profiles exist, prompt user to select one.
</discover_profiles>

<save_selection>
After user selects profile, save it:

```bash
profile-state set stripe-profile main
```

This persists the selection for future operations.
</save_selection>

<make_api_call>
Always announce which profile before API calls:

```
Using Stripe profile: main
```

Then execute operation via secure wrapper:

```bash
~/.claude/scripts/secure-api.sh stripe get-customer cus_123
```
</make_api_call>
</api_workflow>
```
</step_4_document_workflow>

<step_5_common_api_patterns>
**Simple GET request:**
```bash
# Inside secure-api.sh
"get-resource")
  resource_id="$1"
  curl -s "https://api.service.com/v1/resources/$resource_id" \
    -H "Authorization: Bearer $SERVICE_API_KEY"
  ;;
```

**POST with JSON body (accepts piped input):**
```bash
"create-resource")
  curl -s -X POST "https://api.service.com/v1/resources" \
    -H "Authorization: Bearer $SERVICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d @-  # Read from stdin
  ;;
```

**Form data submission:**
```bash
"upload-file")
  file_path="$1"
  curl -s -X POST "https://api.service.com/v1/upload" \
    -H "Authorization: Bearer $SERVICE_API_KEY" \
    -F "file=@$file_path"
  ;;
```
</step_5_common_api_patterns>
</implementation_steps_for_new_services>
</secure_api_wrapper_solution>

<key_security_patterns>
<never_demonstrate_raw_credentials>
❌ **WRONG - exposes credentials:**
```xml
<examples>
Call the API with your key:

```bash
curl -H "Authorization: Bearer $STRIPE_API_KEY" https://api.stripe.com/v1/customers
```
</examples>
```

✅ **RIGHT - uses secure wrapper:**
```xml
<examples>
Get customer information:

```bash
~/.claude/scripts/secure-api.sh stripe get-customer cus_123
```

Credentials loaded internally from ~/.claude/.env
</examples>
```
</never_demonstrate_raw_credentials>

<auto_generate_credential_placeholders>
When adding a new service, immediately create placeholder in `~/.claude/.env`:

```bash
# ServiceName credentials
SERVICENAME_MAIN_API_KEY=
SERVICENAME_MAIN_API_SECRET=
```

This documents what needs to be configured without committing actual keys.
</auto_generate_credential_placeholders>

<centralized_credential_storage>
**One credential file** (`~/.claude/.env`), not scattered across:
- ❌ Multiple `.env` files
- ❌ Individual skill directories
- ❌ Script files
- ❌ Configuration files

**Rationale:** Single source of truth, easier to audit, consistent permissions.
</centralized_credential_storage>

<document_each_operation>
For each API operation in the wrapper, document:

**Operation purpose:**
```bash
# get-customer: Retrieve customer details by ID
# Args: customer_id
# Returns: JSON customer object
"get-customer")
  customer_id="$1"
  curl -s "https://api.stripe.com/v1/customers/$customer_id" \
    -H "Authorization: Bearer $STRIPE_API_KEY"
  ;;
```
</document_each_operation>
</key_security_patterns>

<environment_variable_pattern>
<description>
Alternative approach using environment variables.
</description>

<step_1_set_environment_variables>
```bash
# ~/.bashrc or ~/.zshrc
export STRIPE_API_KEY="sk_live_..."
export OPENAI_API_KEY="sk-..."
```
</step_1_set_environment_variables>

<step_2_access_in_scripts>
```python
import os

api_key = os.environ.get("STRIPE_API_KEY")
if not api_key:
    print("ERROR: STRIPE_API_KEY environment variable not set")
    print("Add to ~/.bashrc: export STRIPE_API_KEY='sk_live_...'")
    exit(1)

# Use api_key without printing
```
</step_2_access_in_scripts>

<step_3_skill_documents_requirement>
```xml
<prerequisites>
<environment_setup>
Set environment variable before using this skill:

```bash
export STRIPE_API_KEY="sk_live_YOUR_KEY_HERE"
```

Verify:
```bash
echo $STRIPE_API_KEY
```

**Security note**: Never commit .bashrc/.zshrc with actual keys. Use placeholders in docs.
</environment_setup>
</prerequisites>
```
</step_3_skill_documents_requirement>
</environment_variable_pattern>

<api_key_validation>
Always validate credentials before attempting operations.

**Good validation pattern:**

```python
def validate_stripe_credentials():
    """Validate Stripe API key without exposing it."""
    api_key = get_credential("stripe", "api_key")

    if not api_key:
        return False, "Stripe API key not configured"

    if not api_key.startswith("sk_"):
        return False, "Invalid Stripe API key format (must start with 'sk_')"

    # Test key with minimal API call
    try:
        import stripe
        stripe.api_key = api_key
        stripe.Account.retrieve()  # Lightweight validation
        return True, "Credentials valid"
    except stripe.error.AuthenticationError:
        return False, "Invalid Stripe API key (authentication failed)"
    except Exception as e:
        return False, f"Credential validation error: {type(e).__name__}"

# In skill workflow
valid, message = validate_stripe_credentials()
if not valid:
    print(f"ERROR: {message}")
    exit(1)
```

**Benefits:**
- Fails fast if credentials missing/invalid
- Clear error messages for user
- No credential values in output
</api_key_validation>

<multi_service_credentials>
<description>
For skills using multiple APIs.
</description>

<credential_file_structure>
```json
{
  "stripe_api_key": "sk_live_...",
  "stripe_webhook_secret": "whsec_...",
  "openai_api_key": "sk-...",
  "github_token": "ghp_...",
  "sendgrid_api_key": "SG_..."
}
```
</credential_file_structure>

<helper_function>
```python
def get_all_credentials(*required_keys):
    """
    Get multiple credentials at once.

    Args:
        *required_keys: Tuples of (service, key_name)

    Returns:
        dict of credentials or None if any missing
    """
    creds = {}
    missing = []

    for service, key_name in required_keys:
        cred = get_credential(service, key_name)
        if not cred:
            missing.append(f"{service}_{key_name}")
        else:
            creds[f"{service}_{key_name}"] = cred

    if missing:
        print(f"ERROR: Missing credentials: {', '.join(missing)}")
        return None

    return creds

# Usage
creds = get_all_credentials(
    ("stripe", "api_key"),
    ("stripe", "webhook_secret"),
    ("sendgrid", "api_key")
)

if not creds:
    exit(1)

stripe_key = creds["stripe_api_key"]
webhook_secret = creds["stripe_webhook_secret"]
sendgrid_key = creds["sendgrid_api_key"]
```
</helper_function>
</multi_service_credentials>

<preventing_credential_leaks>
<ask_user_question_tool_safety>
**❌ WRONG - credential in chat:**

```xml
<workflow>
1. Use AskUserQuestion to ask user for API key
2. Use the provided key for operations
</workflow>
```

**Problem:** API key appears in conversation history (security breach).

**✅ RIGHT - credential not in chat:**

```xml
<workflow>
1. Check if credentials configured using `verify_credentials.py`
2. If not configured, provide setup instructions
3. User sets up credentials outside of chat
4. Verify and proceed with operations
</workflow>
```
</ask_user_question_tool_safety>

<log_safety>
**❌ WRONG - credential in logs:**

```python
print(f"Connecting to Stripe with key: {api_key}")
```

**✅ RIGHT - no credential in logs:**

```python
print("Connecting to Stripe with configured credentials")
```
</log_safety>

<error_message_safety>
**❌ WRONG - credential in error:**

```python
raise Exception(f"Authentication failed for key {api_key}")
```

**✅ RIGHT - no credential in error:**

```python
raise Exception("Authentication failed (check API key configuration)")
```
</error_message_safety>
</preventing_credential_leaks>

<setup_instructions_for_users>
<first_time_credential_setup>
**What to include in skill:**

```xml
<first_time_setup>
**One-time credential configuration:**

1. **Create secure credentials directory:**
   ```bash
   mkdir -p ~/.config/claude
   chmod 700 ~/.config/claude
   ```

2. **Create credentials file:**
   ```bash
   touch ~/.config/claude/api-credentials.json
   chmod 600 ~/.config/claude/api-credentials.json
   ```

3. **Add your ServiceName API key:**

   Edit `~/.config/claude/api-credentials.json`:
   ```json
   {
     "servicename_api_key": "YOUR_ACTUAL_KEY_HERE"
   }
   ```

4. **Verify setup:**
   ```bash
   python scripts/verify_credentials.py servicename
   ```

   Expected output: "✓ ServiceName credentials configured correctly"

**Important:**
- Replace `YOUR_ACTUAL_KEY_HERE` with your actual API key
- Never commit this file to version control
- File permissions (600) ensure only you can read it
- Credentials never appear in Claude Code chat

**Where to get API keys:**
- ServiceName Dashboard → API Keys → Create new key
- Copy the key starting with `sk_...`
</first_time_setup>
```
</first_time_credential_setup>

<verification_script>
**Include in `scripts/verify_credentials.py`:**

```python
#!/usr/bin/env python3
"""Verify API credentials are configured correctly."""

import sys
from get_credential import get_credential

def verify_service(service_name, key_name="api_key"):
    """Verify service credentials without exposing them."""
    key = get_credential(service_name, key_name)

    if not key:
        print(f"✗ {service_name} {key_name} not configured")
        print(f"  Add to ~/.config/claude/api-credentials.json:")
        print(f'  "{service_name}_{key_name}": "YOUR_KEY_HERE"')
        return False

    # Show only first 7 chars for verification
    masked = key[:7] + "..." if len(key) > 10 else "***"
    print(f"✓ {service_name} {key_name} configured ({masked})")
    return True

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python verify_credentials.py <service_name>")
        sys.exit(1)

    service = sys.argv[1]
    success = verify_service(service)
    sys.exit(0 if success else 1)
```
</verification_script>
</setup_instructions_for_users>

<git_ignore_pattern>
**Always add to `.gitignore`:**

```gitignore
# API credentials
.config/claude/api-credentials.json
**/api-credentials.json
**/*credentials.json
.env
.env.local

# Environment files with secrets
*.secret
*.key
```
</git_ignore_pattern>

<security_checklist>
Before finalizing an API integration skill:

- [ ] **No hardcoded credentials**: Search for `api_key`, `secret`, `token` in skill files
- [ ] **Credential helper used**: Scripts use `get_credential()` or env vars
- [ ] **Validation before operations**: Check credentials exist and valid format
- [ ] **No credentials in output**: Print statements don't include credential values
- [ ] **No credentials in errors**: Exception messages don't expose keys
- [ ] **Setup instructions clear**: User knows how to configure credentials securely
- [ ] **Verification script provided**: User can test setup without using skill
- [ ] **Gitignore configured**: Credentials files excluded from version control
- [ ] **File permissions documented**: Instructions include `chmod 600` for cred files
</security_checklist>

<example_complete_secure_api_skill>
See the example skill showing all security patterns:

```
skills/manage-stripe/
├── SKILL.md (references credential setup)
├── scripts/
│   ├── get_credential.py (secure credential retrieval)
│   ├── verify_credentials.py (test setup without exposing)
│   ├── stripe_create_subscription.py (uses get_credential)
│   ├── stripe_get_subscription.py (uses get_credential)
│   └── stripe_cancel_subscription.py (uses get_credential)
└── references/
    ├── api-reference.md (API docs, no credentials)
    └── security.md (this document)
```

**Key principle:** Credentials configured once by user, stored securely outside version control, accessed by name (not value) in skills, never exposed in chat or logs.
</example_complete_secure_api_skill>

```

### references/iteration-and-testing.md

```markdown
<overview>
Skills improve through iteration and testing. This reference covers evaluation-driven development, Claude A/B testing patterns, and XML structure validation during testing.
</overview>

<evaluation_driven_development>
<principle>
Create evaluations BEFORE writing extensive documentation. This ensures your skill solves real problems rather than documenting imagined ones.
</principle>

<workflow>
<step_1>
**Identify gaps**: Run Claude on representative tasks without a skill. Document specific failures or missing context.
</step_1>

<step_2>
**Create evaluations**: Build three scenarios that test these gaps.
</step_2>

<step_3>
**Establish baseline**: Measure Claude's performance without the skill.
</step_3>

<step_4>
**Write minimal instructions**: Create just enough content to address the gaps and pass evaluations.
</step_4>

<step_5>
**Iterate**: Execute evaluations, compare against baseline, and refine.
</step_5>
</workflow>

<evaluation_structure>
```json
{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF file and save it to output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Successfully reads the PDF file using appropriate library",
    "Extracts text content from all pages without missing any",
    "Saves extracted text to output.txt in clear, readable format"
  ]
}
```
</evaluation_structure>

<why_evaluations_first>
- Prevents documenting imagined problems
- Forces clarity about what success looks like
- Provides objective measurement of skill effectiveness
- Keeps skill focused on actual needs
- Enables quantitative improvement tracking
  </why_evaluations_first>
  </evaluation_driven_development>

<iterative_development_with_claude>
<principle>
The most effective skill development uses Claude itself. Work with "Claude A" (expert who helps refine) to create skills used by "Claude B" (agent executing tasks).
</principle>

<creating_skills>
<workflow>
<step_1>
**Complete task without skill**: Work through problem with Claude A, noting what context you repeatedly provide.
</step_1>

<step_2>
**Ask Claude A to create skill**: "Create a skill that captures this pattern we just used"
</step_2>

<step_3>
**Review for conciseness**: Remove unnecessary explanations.
</step_3>

<step_4>
**Improve architecture**: Organize content with progressive disclosure.
</step_4>

<step_5>
**Test with Claude B**: Use fresh instance to test on real tasks.
</step_5>

<step_6>
**Iterate based on observation**: Return to Claude A with specific issues observed.
</step_6>
</workflow>

<insight>
Claude models understand skill format natively. Simply ask Claude to create a skill and it will generate properly structured SKILL.md content.
</insight>
</creating_skills>

<improving_skills>
<workflow>
<step_1>
**Use skill in real workflows**: Give Claude B actual tasks.
</step_1>

<step_2>
**Observe behavior**: Where does it struggle, succeed, or make unexpected choices?
</step_2>

<step_3>
**Return to Claude A**: Share observations and current SKILL.md.
</step_3>

<step_4>
**Review suggestions**: Claude A might suggest reorganization, stronger language, or workflow restructuring.
</step_4>

<step_5>
**Apply and test**: Update skill and test again.
</step_5>

<step_6>
**Repeat**: Continue based on real usage, not assumptions.
</step_6>
</workflow>

<what_to_watch_for>
- **Unexpected exploration paths**: Structure might not be intuitive
- **Missed connections**: Links might need to be more explicit
- **Overreliance on sections**: Consider moving frequently-read content to main SKILL.md
- **Ignored content**: Poorly signaled or unnecessary files
- **Critical metadata**: The name and description in your skill's metadata are critical for discovery
  </what_to_watch_for>
  </improving_skills>
  </iterative_development_with_claude>

<model_testing>
<principle>
Test with all models you plan to use. Different models have different strengths and need different levels of detail.
</principle>

<haiku_testing>
**Claude Haiku** (fast, economical)

Questions to ask:
- Does the skill provide enough guidance?
- Are examples clear and complete?
- Do implicit assumptions become explicit?
- Does Haiku need more structure?

Haiku benefits from:
- More explicit instructions
- Complete examples (no partial code)
- Clear success criteria
- Step-by-step workflows
  </haiku_testing>

<sonnet_testing>
**Claude Sonnet** (balanced)

Questions to ask:
- Is the skill clear and efficient?
- Does it avoid over-explanation?
- Are workflows well-structured?
- Does progressive disclosure work?

Sonnet benefits from:
- Balanced detail level
- XML structure for clarity
- Progressive disclosure
- Concise but complete guidance
  </sonnet_testing>

<opus_testing>
**Claude Opus** (powerful reasoning)

Questions to ask:
- Does the skill avoid over-explaining?
- Can Opus infer obvious steps?
- Are constraints clear?
- Is context minimal but sufficient?

Opus benefits from:
- Concise instructions
- Principles over procedures
- High degrees of freedom
- Trust in reasoning capabilities
  </opus_testing>

<balancing_across_models>
What works for Opus might need more detail for Haiku. Aim for instructions that work well across all target models. Find the balance that serves your target audience.

See [core-principles.md](core-principles.md) for model testing examples.
</balancing_across_models>
</model_testing>

<xml_structure_validation>
<principle>
During testing, validate that your skill's XML structure is correct and complete.
</principle>

<validation_checklist>
After updating a skill, verify:

<required_tags_present>
- ✅ `<objective>` tag exists and defines what skill does
- ✅ `<quick_start>` tag exists with immediate guidance
- ✅ `<success_criteria>` or `<when_successful>` tag exists
  </required_tags_present>

<no_markdown_headings>
- ✅ No `#`, `##`, or `###` headings in skill body
- ✅ All sections use XML tags instead
- ✅ Markdown formatting within tags is preserved (bold, italic, lists, code blocks)
  </no_markdown_headings>

<proper_xml_nesting>
- ✅ All XML tags properly closed
- ✅ Nested tags have correct hierarchy
- ✅ No unclosed tags
  </proper_xml_nesting>

<conditional_tags_appropriate>
- ✅ Conditional tags match skill complexity
- ✅ Simple skills use required tags only
- ✅ Complex skills add appropriate conditional tags
- ✅ No over-engineering or under-specifying
  </conditional_tags_appropriate>

<reference_files_check>
- ✅ Reference files also use pure XML structure
- ✅ Links to reference files are correct
- ✅ References are one level deep from SKILL.md
  </reference_files_check>
  </validation_checklist>

<testing_xml_during_iteration>
When iterating on a skill:

1. Make changes to XML structure
2. **Validate XML structure** (check tags, nesting, completeness)
3. Test with Claude on representative tasks
4. Observe if XML structure aids or hinders Claude's understanding
5. Iterate structure based on actual performance
   </testing_xml_during_iteration>
   </xml_structure_validation>

<observation_based_iteration>
<principle>
Iterate based on what you observe, not what you assume. Real usage reveals issues assumptions miss.
</principle>

<observation_categories>
<what_claude_reads>
Which sections does Claude actually read? Which are ignored? This reveals:
- Relevance of content
- Effectiveness of progressive disclosure
- Whether section names are clear
  </what_claude_reads>

<where_claude_struggles>
Which tasks cause confusion or errors? This reveals:
- Missing context
- Unclear instructions
- Insufficient examples
- Ambiguous requirements
  </where_claude_struggles>

<where_claude_succeeds>
Which tasks go smoothly? This reveals:
- Effective patterns
- Good examples
- Clear instructions
- Appropriate detail level
  </where_claude_succeeds>

<unexpected_behaviors>
What does Claude do that surprises you? This reveals:
- Unstated assumptions
- Ambiguous phrasing
- Missing constraints
- Alternative interpretations
  </unexpected_behaviors>
  </observation_categories>

<iteration_pattern>
1. **Observe**: Run Claude on real tasks with current skill
2. **Document**: Note specific issues, not general feelings
3. **Hypothesize**: Why did this issue occur?
4. **Fix**: Make targeted changes to address specific issues
5. **Test**: Verify fix works on same scenario
6. **Validate**: Ensure fix doesn't break other scenarios
7. **Repeat**: Continue with next observed issue
   </iteration_pattern>
   </observation_based_iteration>

<progressive_refinement>
<principle>
Skills don't need to be perfect initially. Start minimal, observe usage, add what's missing.
</principle>

<initial_version>
Start with:
- Valid YAML frontmatter
- Required XML tags: objective, quick_start, success_criteria
- Minimal working example
- Basic success criteria

Skip initially:
- Extensive examples
- Edge case documentation
- Advanced features
- Detailed reference files
  </initial_version>

<iteration_additions>
Add through iteration:
- Examples when patterns aren't clear from description
- Edge cases when observed in real usage
- Advanced features when users need them
- Reference files when SKILL.md approaches 500 lines
- Validation scripts when errors are common
  </iteration_additions>

<benefits>
- Faster to initial working version
- Additions solve real needs, not imagined ones
- Keeps skills focused and concise
- Progressive disclosure emerges naturally
- Documentation stays aligned with actual usage
</benefits>
</progressive_refinement>

<testing_discovery>
<principle>
Test that Claude can discover and use your skill when appropriate.
</principle>

<discovery_testing>
<test_description>
Test if Claude loads your skill when it should:

1. Start fresh conversation (Claude B)
2. Ask question that should trigger skill
3. Check if skill was loaded
4. Verify skill was used appropriately
   </test_description>

<description_quality>
If skill isn't discovered:
- Check description includes trigger keywords
- Verify description is specific, not vague
- Ensure description explains when to use skill
- Test with different phrasings of the same request

The description is Claude's primary discovery mechanism.
</description_quality>
</discovery_testing>
</testing_discovery>

<common_iteration_patterns>
<pattern name="too_verbose">
**Observation**: Skill works but uses lots of tokens

**Fix**:
- Remove obvious explanations
- Assume Claude knows common concepts
- Use examples instead of lengthy descriptions
- Move advanced content to reference files
  </pattern>

<pattern name="too_minimal">
**Observation**: Claude makes incorrect assumptions or misses steps

**Fix**:
- Add explicit instructions where assumptions fail
- Provide complete working examples
- Define edge cases
- Add validation steps
  </pattern>

<pattern name="poor_discovery">
**Observation**: Skill exists but Claude doesn't load it when needed

**Fix**:
- Improve description with specific triggers
- Add relevant keywords
- Test description against actual user queries
- Make description more specific about use cases
  </pattern>

<pattern name="unclear_structure">
**Observation**: Claude reads wrong sections or misses relevant content

**Fix**:
- Use clearer XML tag names
- Reorganize content hierarchy
- Move frequently-needed content earlier
- Add explicit links to relevant sections
  </pattern>

<pattern name="incomplete_examples">
**Observation**: Claude produces outputs that don't match expected pattern

**Fix**:
- Add more examples showing pattern
- Make examples more complete
- Show edge cases in examples
- Add anti-pattern examples (what not to do)
  </pattern>
  </common_iteration_patterns>

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

<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>
<principle>
Define how you'll measure if the skill is working. Quantify success.
</principle>

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

```

### references/clear-and-direct.md

```markdown
<golden_rule>
Could I hand these instructions to a junior developer and expect correct results? If someone without your context struggles, Claude will too.
</golden_rule>

<overview>
Clarity and directness are fundamental to effective skill authoring. Clear instructions reduce errors, improve execution quality, and minimize token waste.
</overview>

<guidelines>
<contextual_information>
Give Claude contextual information that frames the task:

- What the task results will be used for
- What audience the output is meant for
- What workflow the task is part of
- The end goal or what successful completion looks like

Context helps Claude make better decisions and produce more appropriate outputs.

<example>
```xml
<context>
This analysis will be presented to investors who value transparency and actionable insights. Focus on financial metrics and clear recommendations.
</context>
```
</example>
</contextual_information>

<specificity>
Be specific about what you want Claude to do. If you want code only and nothing else, say so.

**Vague**: "Help with the report"
**Specific**: "Generate a markdown report with three sections: Executive Summary, Key Findings, Recommendations"

**Vague**: "Process the data"
**Specific**: "Extract customer names and email addresses from the CSV file, removing duplicates, and save to JSON format"

Specificity eliminates ambiguity and reduces iteration cycles.
</specificity>

<sequential_steps>
Provide instructions as sequential steps. Use numbered lists or bullet points.

```xml
<workflow>
1. Extract data from source file
2. Transform to target format
3. Validate transformation
4. Save to output file
5. Verify output correctness
</workflow>
```

Sequential steps create clear expectations and reduce the chance Claude skips important operations.
</sequential_steps>
</guidelines>

<example_comparison>
<unclear_example>
```xml
<quick_start>
Please remove all personally identifiable information from these customer feedback messages: {{FEEDBACK_DATA}}
</quick_start>
```

**Problems**:
- What counts as PII?
- What should replace PII?
- What format should the output be?
- What if no PII is found?
- Should product names be redacted?
  </unclear_example>

<clear_example>
```xml
<objective>
Anonymize customer feedback for quarterly review presentation.
</objective>

<quick_start>
<instructions>
1. Replace all customer names with "CUSTOMER_[ID]" (e.g., "Jane Doe" → "CUSTOMER_001")
2. Replace email addresses with "EMAIL_[ID]@example.com"
3. Redact phone numbers as "PHONE_[ID]"
4. If a message mentions a specific product (e.g., "AcmeCloud"), leave it intact
5. If no PII is found, copy the message verbatim
6. Output only the processed messages, separated by "---"
</instructions>

Data to process: {{FEEDBACK_DATA}}
</quick_start>

<success_criteria>
- All customer names replaced with IDs
- All emails and phones redacted
- Product names preserved
- Output format matches specification
</success_criteria>
```

**Why this is better**:
- States the purpose (quarterly review)
- Provides explicit step-by-step rules
- Defines output format clearly
- Specifies edge cases (product names, no PII found)
- Defines success criteria
  </clear_example>
  </example_comparison>

<key_differences>
The clear version:
- States the purpose (quarterly review)
- Provides explicit step-by-step rules
- Defines output format
- Specifies edge cases (product names, no PII found)
- Includes success criteria

The unclear version leaves all these decisions to Claude, increasing the chance of misalignment with expectations.
</key_differences>

<show_dont_just_tell>
<principle>
When format matters, show an example rather than just describing it.
</principle>

<telling_example>
```xml
<commit_messages>
Generate commit messages in conventional format with type, scope, and description.
</commit_messages>
```
</telling_example>

<showing_example>
```xml
<commit_message_format>
Generate commit messages following these examples:

<example number="1">
<input>Added user authentication with JWT tokens</input>
<output>
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```
</output>
</example>

<example number="2">
<input>Fixed bug where dates displayed incorrectly in reports</input>
<output>
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```
</output>
</example>

Follow this style: type(scope): brief description, then detailed explanation.
</commit_message_format>
```
</showing_example>

<why_showing_works>
Examples communicate nuances that text descriptions can't:
- Exact formatting (spacing, capitalization, punctuation)
- Tone and style
- Level of detail
- Pattern across multiple cases

Claude learns patterns from examples more reliably than from descriptions.
</why_showing_works>
</show_dont_just_tell>

<avoid_ambiguity>
<principle>
Eliminate words and phrases that create ambiguity or leave decisions open.
</principle>

<ambiguous_phrases>
❌ **"Try to..."** - Implies optional
✅ **"Always..."** or **"Never..."** - Clear requirement

❌ **"Should probably..."** - Unclear obligation
✅ **"Must..."** or **"May optionally..."** - Clear obligation level

❌ **"Generally..."** - When are exceptions allowed?
✅ **"Always... except when..."** - Clear rule with explicit exceptions

❌ **"Consider..."** - Should Claude always do this or only sometimes?
✅ **"If X, then Y"** or **"Always..."** - Clear conditions
</ambiguous_phrases>

<example>
❌ **Ambiguous**:
```xml
<validation>
You should probably validate the output and try to fix any errors.
</validation>
```

✅ **Clear**:
```xml
<validation>
Always validate output before proceeding:

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

If validation fails, fix errors and re-validate. Only proceed when validation passes with zero errors.
</validation>
```
</example>
</avoid_ambiguity>

<define_edge_cases>
<principle>
Anticipate edge cases and define how to handle them. Don't leave Claude guessing.
</principle>

<without_edge_cases>
```xml
<quick_start>
Extract email addresses from the text file and save to a JSON array.
</quick_start>
```

**Questions left unanswered**:
- What if no emails are found?
- What if the same email appears multiple times?
- What if emails are malformed?
- What JSON format exactly?
  </without_edge_cases>

<with_edge_cases>
```xml
<quick_start>
Extract email addresses from the text file and save to a JSON array.

<edge_cases>
- **No emails found**: Save empty array `[]`
- **Duplicate emails**: Keep only unique emails
- **Malformed emails**: Skip invalid formats, log to stderr
- **Output format**: Array of strings, one email per element
</edge_cases>

<example_output>
```json
[
  "[email protected]",
  "[email protected]"
]
```
</example_output>
</quick_start>
```
</with_edge_cases>
</define_edge_cases>

<output_format_specification>
<principle>
When output format matters, specify it precisely. Show examples.
</principle>

<vague_format>
```xml
<output>
Generate a report with the analysis results.
</output>
```
</vague_format>

<specific_format>
```xml
<output_format>
Generate a markdown report with this exact structure:

```markdown
# Analysis Report: [Title]

## Executive Summary
[1-2 paragraphs summarizing key findings]

## Key Findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation

## Appendix
[Raw data and detailed calculations]
```

**Requirements**:
- Use exactly these section headings
- Executive summary must be 1-2 paragraphs
- List 3-5 key findings
- Provide 2-4 recommendations
- Include appendix with source data
  </output_format>
```
</specific_format>
</output_format_specification>

<decision_criteria>
<principle>
When Claude must make decisions, provide clear criteria.
</principle>

<no_criteria>
```xml
<workflow>
Analyze the data and decide which visualization to use.
</workflow>
```

**Problem**: What factors should guide this decision?
</no_criteria>

<with_criteria>
```xml
<workflow>
Analyze the data and select appropriate visualization:

<decision_criteria>
**Use bar chart when**:
- Comparing quantities across categories
- Fewer than 10 categories
- Exact values matter

**Use line chart when**:
- Showing trends over time
- Continuous data
- Pattern recognition matters more than exact values

**Use scatter plot when**:
- Showing relationship between two variables
- Looking for correlations
- Individual data points matter
</decision_criteria>
</workflow>
```

**Benefits**: Claude has objective criteria for making the decision rather than guessing.
</with_criteria>
</decision_criteria>

<constraints_and_requirements>
<principle>
Clearly separate "must do" from "nice to have" from "must not do".
</principle>

<unclear_requirements>
```xml
<requirements>
The report should include financial data, customer metrics, and market analysis. It would be good to have visualizations. Don't make it too long.
</requirements>
```

**Problems**:
- Are all three content types required?
- Are visualizations optional or required?
- How long is "too long"?
  </unclear_requirements>

<clear_requirements>
```xml
<requirements>
<must_have>
- Financial data (revenue, costs, profit margins)
- Customer metrics (acquisition, retention, lifetime value)
- Market analysis (competition, trends, opportunities)
- Maximum 5 pages
</must_have>

<nice_to_have>
- Charts and visualizations
- Industry benchmarks
- Future projections
</nice_to_have>

<must_not>
- Include confidential customer names
- Exceed 5 pages
- Use technical jargon without definitions
</must_not>
</requirements>
```

**Benefits**: Clear priorities and constraints prevent misalignment.
</clear_requirements>
</constraints_and_requirements>

<success_criteria>
<principle>
Define what success looks like. How will Claude know it succeeded?
</principle>

<without_success_criteria>
```xml
<objective>
Process the CSV file and generate a report.
</objective>
```

**Problem**: When is this task complete? What defines success?
</without_success_criteria>

<with_success_criteria>
```xml
<objective>
Process the CSV file and generate a summary report.
</objective>

<success_criteria>
- All rows in CSV successfully parsed
- No data validation errors
- Report generated with all required sections
- Report saved to output/report.md
- Output file is valid markdown
- Process completes without errors
</success_criteria>
```

**Benefits**: Clear completion criteria eliminate ambiguity about when the task is done.
</with_success_criteria>
</success_criteria>

<testing_clarity>
<principle>
Test your instructions by asking: "Could I hand these instructions to a junior developer and expect correct results?"
</principle>

<testing_process>
1. Read your skill instructions
2. Remove context only you have (project knowledge, unstated assumptions)
3. Identify ambiguous terms or vague requirements
4. Add specificity where needed
5. Test with someone who doesn't have your context
6. Iterate based on their questions and confusion

If a human with minimal context struggles, Claude will too.
</testing_process>
</testing_clarity>

<practical_examples>
<example domain="data_processing">
❌ **Unclear**:
```xml
<quick_start>
Clean the data and remove bad entries.
</quick_start>
```

✅ **Clear**:
```xml
<quick_start>
<data_cleaning>
1. Remove rows where required fields (name, email, date) are empty
2. Standardize date format to YYYY-MM-DD
3. Remove duplicate entries based on email address
4. Validate email format (must contain @ and domain)
5. Save cleaned data to output/cleaned_data.csv
</data_cleaning>

<success_criteria>
- No empty required fields
- All dates in YYYY-MM-DD format
- No duplicate emails
- All emails valid format
- Output file created successfully
</success_criteria>
</quick_start>
```
</example>

<example domain="code_generation">
❌ **Unclear**:
```xml
<quick_start>
Write a function to process user input.
</quick_start>
```

✅ **Clear**:
```xml
<quick_start>
<function_specification>
Write a Python function with this signature:

```python
def process_user_input(raw_input: str) -> dict:
    """
    Validate and parse user input.

    Args:
        raw_input: Raw string from user (format: "name:email:age")

    Returns:
        dict with keys: name (str), email (str), age (int)

    Raises:
        ValueError: If input format is invalid
    """
```

**Requirements**:
- Split input on colon delimiter
- Validate email contains @ and domain
- Convert age to integer, raise ValueError if not numeric
- Return dictionary with specified keys
- Include docstring and type hints
  </function_specification>

<success_criteria>
- Function signature matches specification
- All validation checks implemented
- Proper error handling for invalid input
- Type hints included
- Docstring included
  </success_criteria>
  </quick_start>
```
</example>
</practical_examples>

```

### references/use-xml-tags.md

```markdown
<overview>
Skills use pure XML structure for consistent parsing, efficient token usage, and improved Claude performance. This reference defines the required and conditional XML tags for skill authoring, along with intelligence rules for tag selection.
</overview>

<critical_rule>
**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
</critical_rule>

<required_tags>
Every skill MUST have these three tags:

<tag name="objective">
**Purpose**: What the skill does and why it matters. Sets context and scope.

**Content**: 1-3 paragraphs explaining the skill's purpose, domain, and value proposition.

**Example**:
```xml
<objective>
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries. This skill provides patterns for common PDF operations without requiring external services or APIs.
</objective>
```
</tag>

<tag name="quick_start">
**Purpose**: Immediate, actionable guidance. Gets Claude started quickly without reading advanced sections.

**Content**: Minimal working example, essential commands, or basic usage pattern.

**Example**:
```xml
<quick_start>
Extract text with pdfplumber:

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

<tag name="success_criteria">
**Purpose**: How to know the task worked. Defines completion criteria.

**Alternative name**: `<when_successful>` (use whichever fits better)

**Content**: Clear criteria for successful execution, validation steps, or expected outputs.

**Example**:
```xml
<success_criteria>
A well-structured skill has:

- Valid YAML frontmatter with descriptive name and description
- Pure XML structure with no markdown headings in body
- Required tags: objective, quick_start, success_criteria
- Progressive disclosure (SKILL.md < 500 lines, details in reference files)
- Real-world testing and iteration based on observed behavior
</success_criteria>
```
</tag>
</required_tags>

<conditional_tags>
Add these tags based on skill complexity and domain requirements:

<tag name="context">
**When to use**: Background or situational information that Claude needs before starting.

**Example**:
```xml
<context>
The Facebook Marketing API uses a hierarchy: Account → Campaign → Ad Set → Ad. Each level has different configuration options and requires specific permissions. Always verify API access before making changes.
</context>
```
</tag>

<tag name="workflow">
**When to use**: Step-by-step procedures, sequential operations, multi-step processes.

**Alternative name**: `<process>`

**Example**:
```xml
<workflow>
1. **Analyze the form**: Run analyze_form.py to extract field definitions
2. **Create field mapping**: Edit fields.json with values
3. **Validate mapping**: Run validate_fields.py
4. **Fill the form**: Run fill_form.py
5. **Verify output**: Check generated PDF
</workflow>
```
</tag>

<tag name="advanced_features">
**When to use**: Deep-dive topics that most users won't need (progressive disclosure).

**Example**:
```xml
<advanced_features>
**Custom styling**: See [styling.md](styling.md)
**Template inheritance**: See [templates.md](templates.md)
**API reference**: See [reference.md](reference.md)
</advanced_features>
```
</tag>

<tag name="validation">
**When to use**: Skills with verification steps, quality checks, or validation scripts.

**Example**:
```xml
<validation>
After making changes, validate immediately:

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

Only proceed when validation passes. If errors occur, review and fix before continuing.
</validation>
```
</tag>

<tag name="examples">
**When to use**: Multi-shot learning, input/output pairs, demonstrating patterns.

**Example**:
```xml
<examples>
<example number="1">
<input>User clicked signup button</input>
<output>track('signup_initiated', { source: 'homepage' })</output>
</example>

<example number="2">
<input>Purchase completed</input>
<output>track('purchase', { value: 49.99, currency: 'USD' })</output>
</example>
</examples>
```
</tag>

<tag name="anti_patterns">
**When to use**: Common mistakes that Claude should avoid.

**Example**:
```xml
<anti_patterns>
<pitfall name="vague_descriptions">
- ❌ "Helps with documents"
- ✅ "Extract text and tables from PDF files"
</pitfall>

<pitfall name="too_many_options">
- ❌ "You can use pypdf, or pdfplumber, or PyMuPDF..."
- ✅ "Use pdfplumber for text extraction. For OCR, use pytesseract instead."
</pitfall>
</anti_patterns>
```
</tag>

<tag name="security_checklist">
**When to use**: Skills with security implications (API keys, payments, authentication).

**Example**:
```xml
<security_checklist>
- Never log API keys or tokens
- Always use environment variables for credentials
- Validate all user input before API calls
- Use HTTPS for all external requests
- Check API response status before proceeding
</security_checklist>
```
</tag>

<tag name="testing">
**When to use**: Testing workflows, test patterns, or validation steps.

**Example**:
```xml
<testing>
Test with all target models (Haiku, Sonnet, Opus):

1. Run skill on representative tasks
2. Observe where Claude struggles or succeeds
3. Iterate based on actual behavior
4. Validate XML structure after changes
</testing>
```
</tag>

<tag name="common_patterns">
**When to use**: Code examples, recipes, or reusable patterns.

**Example**:
```xml
<common_patterns>
<pattern name="error_handling">
```python
try:
    result = process_file(path)
except FileNotFoundError:
    print(f"File not found: {path}")
except Exception as e:
    print(f"Error: {e}")
```
</pattern>
</common_patterns>
```
</tag>

<tag name="reference_guides">
**When to use**: Links to detailed reference files (progressive disclosure).

**Alternative name**: `<detailed_references>`

**Example**:
```xml
<reference_guides>
For deeper topics, see reference files:

**API operations**: [references/api-operations.md](references/api-operations.md)
**Security patterns**: [references/security.md](references/security.md)
**Troubleshooting**: [references/troubleshooting.md](references/troubleshooting.md)
</reference_guides>
```
</tag>
</conditional_tags>

<intelligence_rules>
<decision_tree>
**Simple skills** (single domain, straightforward):
- Required tags only: objective, quick_start, success_criteria
- Example: Text extraction, file format conversion, simple calculations

**Medium skills** (multiple patterns, some complexity):
- Required tags + workflow/examples as needed
- Example: Document processing with steps, API integration with configuration

**Complex skills** (multiple domains, security, APIs):
- Required tags + conditional tags as appropriate
- Example: Payment processing, authentication systems, multi-step workflows with validation
  </decision_tree>

<principle>
Don't over-engineer simple skills. Don't under-specify complex skills. Match tag selection to actual complexity and user needs.
</principle>

<when_to_add_conditional>
Ask these questions:

- **Context needed?** → Add `<context>`
- **Multi-step process?** → Add `<workflow>` or `<process>`
- **Advanced topics to hide?** → Add `<advanced_features>` + reference files
- **Validation required?** → Add `<validation>`
- **Pattern demonstration?** → Add `<examples>`
- **Common mistakes?** → Add `<anti_patterns>`
- **Security concerns?** → Add `<security_checklist>`
- **Testing guidance?** → Add `<testing>`
- **Code recipes?** → Add `<common_patterns>`
- **Deep references?** → Add `<reference_guides>`
  </when_to_add_conditional>
  </intelligence_rules>

<xml_vs_markdown_headings>
<token_efficiency>
XML tags are more efficient than markdown headings:

**Markdown headings**:
```markdown
## Quick start
## Workflow
## Advanced features
## Success criteria
```
Total: ~20 tokens, no semantic meaning to Claude

**XML tags**:
```xml
<quick_start>
<workflow>
<advanced_features>
<success_criteria>
```
Total: ~15 tokens, semantic meaning built-in
</token_efficiency>

<parsing_accuracy>
XML provides unambiguous boundaries and semantic meaning. Claude can reliably:
- Identify section boundaries
- Understand content purpose
- Skip irrelevant sections
- Parse programmatically

Markdown headings are just visual formatting. Claude must infer meaning from heading text.
</parsing_accuracy>

<consistency>
XML enforces consistent structure across all skills. All skills use the same tag names for the same purposes. Makes it easier to:
- Validate skill structure programmatically
- Learn patterns across skills
- Maintain consistent quality
</consistency>
</xml_vs_markdown_headings>

<nesting_guidelines>
<proper_nesting>
XML tags can nest for hierarchical content:

```xml
<examples>
<example number="1">
<input>User input here</input>
<output>Expected output here</output>
</example>

<example number="2">
<input>Another input</input>
<output>Another output</output>
</example>
</examples>
```
</proper_nesting>

<closing_tags>
Always close tags properly:

✅ Good:
```xml
<objective>
Content here
</objective>
```

❌ Bad:
```xml
<objective>
Content here
```
</closing_tags>

<tag_naming>
Use descriptive, semantic names:
- `<workflow>` not `<steps>`
- `<success_criteria>` not `<done>`
- `<anti_patterns>` not `<dont_do>`

Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose.
</tag_naming>
</nesting_guidelines>

<anti_pattern>
**DO NOT use markdown headings in skill body content.**

❌ Bad (hybrid approach):
```markdown
# PDF Processing

## Quick start

Extract text with pdfplumber...

## Advanced features

Form filling...
```

✅ Good (pure XML):
```markdown
<objective>
PDF processing with text extraction, form filling, and merging.
</objective>

<quick_start>
Extract text with pdfplumber...
</quick_start>

<advanced_features>
Form filling...
</advanced_features>
```
</anti_pattern>

<benefits>
<benefit type="clarity">
Clearly separate different sections with unambiguous boundaries
</benefit>

<benefit type="accuracy">
Reduce parsing errors. Claude knows exactly where sections begin and end.
</benefit>

<benefit type="flexibility">
Easily find, add, remove, or modify sections without rewriting
</benefit>

<benefit type="parseability">
Programmatically extract specific sections for validation or analysis
</benefit>

<benefit type="efficiency">
Lower token usage compared to markdown headings
</benefit>

<benefit type="consistency">
Standardized structure across all skills in the ecosystem
</benefit>
</benefits>

<combining_with_other_techniques>
XML tags work well with other prompting techniques:

**Multi-shot learning**:
```xml
<examples>
<example number="1">...</example>
<example number="2">...</example>
</examples>
```

**Chain of thought**:
```xml
<thinking>
Analyze the problem...
</thinking>

<answer>
Based on the analysis...
</answer>
```

**Template provision**:
```xml
<template>
```markdown
# Report Title

## Summary
...
```
</template>
```

**Reference material**:
```xml
<schema>
{
  "field": "type"
}
</schema>
```
</combining_with_other_techniques>

<tag_reference_pattern>
When referencing content in tags, use the tag name:

"Using the schema in `<schema>` tags..."
"Follow the workflow in `<workflow>`..."
"See examples in `<examples>`..."

This makes the structure self-documenting.
</tag_reference_pattern>

```