Common patterns

This reference documents common patterns for skill authoring, including templates, examples, terminology consistency, and anti-patterns. All patterns use pure XML structure.

Provide templates for output format. Match the level of strictness to your needs.

Use when output format must be exact and consistent:

<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

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

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

- 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

Choose one term and use it throughout the skill. Inconsistent terminology confuses Claude and reduces execution quality.

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

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

Inconsistent usage creates confusion:

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

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

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

Clear default with escape hatch:

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

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

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

Common mistakes to avoid when authoring skills.

❌ BAD: Using markdown headings in skill body:

# PDF Processing

## Quick start
Extract text with pdfplumber...

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

✅ GOOD: Using pure XML structure:

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

❌ BAD:

description: Helps with documents

✅ GOOD:

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

Why it matters: Vague descriptions prevent Claude from discovering and using the skill appropriately.

❌ BAD:

description: I can help you process Excel files and generate reports

✅ GOOD:

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.

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

❌ BAD:

<quick_start>
You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or pdfminer, or tabula-py...
</quick_start>

✅ GOOD:

<quick_start>
Use pdfplumber for text extraction:

```python
import pdfplumber

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.

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

<reference_guides>
See scripts/validate.py for validation
</reference_guides>

Why it matters: Always use forward slashes for cross-platform compatibility.

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:

<examples>
Load current status with: !`git status`
Review dependencies in: @package.json
</examples>

✅ GOOD - Add space to prevent execution:

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

❌ BAD: Missing required tags:

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

✅ GOOD: All required tags present:

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

❌ BAD: Mixing XML tags with markdown headings:

<objective>
PDF processing capabilities
</objective>

## Quick start

Extract text with pdfplumber...

## Advanced features

Form filling...

✅ GOOD: Pure XML throughout:

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

❌ BAD: Forgetting to close XML tags:

<objective>
Process PDF files

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

✅ GOOD: Properly closed tags:

<objective>
Process PDF files
</objective>

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

Why it matters: Unclosed tags break XML parsing and create ambiguous boundaries.

❌ BAD: Quality gate as a prompt instruction:

<step name="pre_submit">
Remember to run the test suite before creating a PR.
Check that all linting passes.
Verify no secrets are committed.
</step>

✅ GOOD: Quality gate as automated enforcement:

<step name="pre_submit">
Run: `./scripts/test-gate.sh` — blocks PR creation on failure.
Hook: `pre-commit` validates no secrets via `check-secrets.sh`.
</step>

Or use a hook in SKILL.md frontmatter:

hooks:
  PreToolUse:
    - matcher: Bash
      script: ~/.claude/hooks/check-test-gate.sh

Why it matters: Only automatically enforced checks are reliably executed. Any quality gate that depends on the agent remembering to run it will be skipped under context pressure. This anti-pattern was observed 3 times in a single project. If a check matters, make it a hook, a script, or a mandatory pre-step — not a prompt instruction.

Keep SKILL.md concise by linking to detailed reference files. Claude loads reference files only when needed.

<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

For skills with validation steps, make validation scripts verbose and specific.

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

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