Creating A New Skill

Comprehensive Agent Skills Documentation

This document contains ALL the information needed to create effective Agent Skills for Claude Code, Claude.ai, and the Claude Developer Platform.

Agent Skills are now a formal open standard at agentskills.io, adopted by 35+ tools (Cursor, Gemini CLI, GitHub Copilot, VS Code, OpenAI Codex, Goose, Kiro, OpenHands, Letta, Amp, Junie, Databricks Genie, Snowflake Cortex Code, Spring AI, Laravel Boost, Factory, OpenCode, Roo Code, and more). Claude Code implements a superset of the standard — see Agent Skills Open Standard for the spec and the Claude-Code-only extensions.

Table of Contents

1. Introduction
2. What are Agent Skills?
3. How Skills Work
4. Core Principles for Creating Skills
5. Skill Structure
6. Invocation Control
7. String Substitutions
8. Dynamic Context Injection
9. Running Skills in a Subagent 9a. Skill Content Lifecycle (Claude Code) 9b. Reference vs Task Content
10. Writing Effective Descriptions
11. Progressive Disclosure Patterns
12. Workflows and Feedback Loops
13. Content Guidelines
14. Common Patterns
15. Anti-Patterns to Avoid
16. Advanced: Skills with Executable Code
17. Using Skills Across Platforms
18. Bundled Skills (Claude Code)
19. Skill Permission Control (Claude Code)
20. Evaluation and Iteration
21. Security Considerations
22. Troubleshooting
23. Complete Examples
24. Agent Skills Open Standard (agentskills.io)
25. Checklist for Effective Skills

Introduction

Agent Skills are organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks. Skills provide Claude with domain-specific expertise, workflows, context, and best practices that transform general-purpose agents into specialists.

Why Use Skills

Skills are reusable, filesystem-based resources that provide:

• Specialize Claude: Tailor capabilities for domain-specific tasks
• Reduce repetition: Create once, use automatically across multiple conversations
• Compose capabilities: Combine Skills to build complex workflows
• Efficient context usage: Only loads what's needed, when it's needed
• Portable: Same format works across Claude.ai, Claude API, Claude Code, and Claude Agent SDK

Key Characteristics

Skills are:

• Dual-invocable: Both model-invoked (Claude autonomously decides when to use them) AND user-invocable (type /skill-name to invoke directly). Frontmatter fields let you restrict to one or the other
• Composable: Skills stack together. Claude automatically identifies which skills are needed and coordinates their use
• Portable: Skills use the same format everywhere. Build once, use across Claude apps, Claude Code, and API
• Efficient: Progressive disclosure - only loads what's needed, when it's needed
• Powerful: Skills can include executable code for tasks where traditional programming is more reliable than token generation

Note: Custom commands (.claude/commands/) have been merged into skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work the same way. Your existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and the ability for Claude to load them automatically when relevant. If a skill and a command share the same name, the skill takes precedence.

What are Agent Skills?

Agent Skills package expertise into discoverable capabilities. Each Skill consists of:

1. SKILL.md file (required) with YAML frontmatter containing name and description
2. Instructions in the body of SKILL.md that Claude reads when relevant
3. Optional supporting files like additional markdown documentation, scripts, templates, and resources

Skills leverage Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials.

Skills vs Prompts

How Skills Work

Three Levels of Loading (Progressive Disclosure)

Skills leverage progressive disclosure: Claude loads information in stages as needed, rather than consuming context upfront.

Level 1: Metadata (always loaded)

Content type: Instructions. The Skill's YAML frontmatter provides discovery information:

---
name: pdf-processing
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.
---

Claude loads this metadata at startup and includes it in the system prompt. This lightweight approach means you can install many Skills without context penalty; Claude only knows each Skill exists and when to use it.

Token cost: ~100 tokens per Skill

Level 2: Instructions (loaded when triggered)

Content type: Instructions. The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance.

When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem via bash. Only then does this content enter the context window.

Token cost: Under 5k tokens (keep SKILL.md body under 500 lines)

Level 3: Resources and Code (loaded as needed)

Content types: Instructions, code, and resources. Skills can bundle additional materials:

pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)

• Instructions: Additional markdown files containing specialized guidance and workflows
• Code: Executable scripts that Claude runs via bash; scripts provide deterministic operations without consuming context
• Resources: Reference materials like database schemas, API documentation, templates, or examples

Claude accesses these files only when referenced.

Token cost: Effectively unlimited. Files executed via bash don't load into context; only output consumes tokens.

The Skills Architecture

Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities.

How Claude accesses Skill content:

1. Metadata pre-loaded: At startup, name and description from all Skills' YAML frontmatter are loaded into the system prompt
2. Files read on-demand: Claude uses bash to access SKILL.md and other files from the filesystem when needed
3. Scripts executed efficiently: Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens
4. No context penalty for large files: Reference files, data, or documentation don't consume context tokens until actually read

What this architecture enables:

• On-demand file access: Claude reads only the files needed for each specific task
• Efficient script execution: When Claude runs validate_form.py, the script's code never loads into the context window. Only the script's output consumes tokens
• No practical limit on bundled content: Because files don't consume context until accessed, Skills can include comprehensive documentation, large datasets, extensive examples, or any reference materials

Example: Loading a PDF Processing Skill

Here's how Claude loads and uses a PDF processing skill:

1. Startup: System prompt includes: PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
2. User request: "Extract the text from this PDF and summarize it"
3. Claude invokes: bash: read pdf-skill/SKILL.md → Instructions loaded into context
4. Claude determines: Form filling is not needed, so FORMS.md is not read
5. Claude executes: Uses instructions from SKILL.md to complete the task

Only relevant content occupies the context window at any given time.

Core Principles for Creating Skills

1. Concise is Key

The context window is a public good. Your Skill shares it with everything else Claude needs to know.

Default assumption: Claude is already very smart. Only add context Claude doesn't already have.

Challenge each piece of information:

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

Good example: Concise (approximately 50 tokens):

## Extract PDF text

Use pdfplumber for text extraction:

```python
import pdfplumber

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

Bad example: Too verbose (approximately 150 tokens):

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

2. Set Appropriate Degrees of Freedom

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

High freedom (text-based instructions):

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

Medium freedom (pseudocode or scripts with parameters):

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

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

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

Analogy: Think of Claude as a robot exploring a path:

• Narrow bridge with cliffs: Only one safe way forward. Provide specific guardrails (low freedom)
• Open field: Many paths lead to success. Give general direction and trust Claude (high freedom)

3. Test with All Models You Plan to Use

Skills act as additions to models, so effectiveness depends on the underlying model. Test with:

• Claude Haiku (fast, economical): Does the Skill provide enough guidance?
• Claude Sonnet (balanced): Is the Skill clear and efficient?
• Claude Opus (powerful reasoning): Does the Skill avoid over-explaining?

4. Build Evaluations First

Create evaluations BEFORE writing extensive documentation. This ensures your Skill solves real problems.

Evaluation-driven development:

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

Skill Structure

Basic Directory Structure

my-skill/
├── SKILL.md              (required)
├── reference.md          (optional documentation)
├── examples.md           (optional examples)
├── scripts/
│   └── helper.py         (optional utility)
└── templates/
    └── template.txt      (optional template)

SKILL.md Format

Every Skill requires a SKILL.md file with YAML frontmatter:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

YAML Frontmatter Reference

All fields are optional. Only description is recommended so Claude knows when to use the skill.

Full example with all optional fields:

---
name: deploy
description: Deploy the application to production
argument-hint: [environment]
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
context: fork
agent: general-purpose
---

Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target

Field validation for name:

• 1–64 characters
• Lowercase a-z, digits, and hyphens only
• No leading or trailing hyphen
• No consecutive hyphens (--)
• Must match the parent directory name
• Cannot contain XML tags

Field validation for description:

• agentskills.io standard: max 1,024 characters
• Claude Code: description + when_to_use combined max 1,536 chars (tunable via maxSkillDescriptionChars)
• Cannot contain XML tags
• Should include both what the Skill does AND when Claude should use it
• Front-load the key use case — text is truncated to fit the listing budget

Naming Conventions

Use consistent naming patterns. Recommended: gerund form (verb + -ing).

Good naming examples (gerund form):

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

Acceptable alternatives:

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

Avoid:

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

Invocation Control

By default, both you and Claude can invoke any skill. You can type /skill-name to invoke it directly, and Claude can load it automatically when relevant to your conversation. Two frontmatter fields let you restrict this:

Three Invocation Modes

Default (both user and Claude can invoke): Best for general-purpose skills like code explanations, analysis tools, or reference knowledge. Both /skill-name and automatic invocation work.

disable-model-invocation: true (only user can invoke): Use for workflows with side effects or that you want to control timing: deploy, commit, send-slack-message, database migrations. You don't want Claude deciding to deploy because your code looks ready.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

user-invocable: false (only Claude can invoke): Use for background knowledge that isn't actionable as a command. A legacy-system-context skill explains how an old system works. Claude should know this when relevant, but /legacy-system-context isn't a meaningful action for users to take.

---
name: legacy-system-context
description: Context about the legacy billing system architecture. Use when working with billing code or migrating from the old system.
user-invocable: false
---

Invocation Matrix

Note: In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked.

String Substitutions

Skills support string substitution for dynamic values in the skill content. Arguments are passed when invoking a skill (e.g., /fix-issue 123).

Available Variables

Indexed arguments use shell-style quoting: /my-skill "hello world" second → $0 = hello world, $1 = second. $ARGUMENTS always expands to the full raw argument string.

Example: Using ${CLAUDE_SKILL_DIR} for bundled scripts

---
name: codebase-visualizer
description: Generate an interactive HTML tree of the codebase
allowed-tools: Bash(python3 *)
---

Run: `python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .`

This resolves correctly whether the skill lives at the personal, project, or plugin level.

Example: Fix a GitHub Issue

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

When you run /fix-issue 123, Claude receives "Fix GitHub issue 123 following our coding standards..."

Example: Positional Arguments

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

Running /migrate-component SearchBar React Vue replaces $ARGUMENTS[0] with SearchBar, $ARGUMENTS[1] with React, and $ARGUMENTS[2] with Vue.

The same skill using the $N shorthand:

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Example: Session Logging

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

Note: If you invoke a skill with arguments but the skill doesn't include $ARGUMENTS, Claude Code appends ARGUMENTS: <your input> to the end of the skill content so Claude still sees what you typed.

Dynamic Context Injection

The !`command` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.

This is preprocessing, not something Claude executes. Claude only sees the final result.

Example: PR Summary Skill

This skill summarizes a pull request by fetching live PR data with the GitHub CLI:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request. Include:
1. What changed and why
2. Key files affected
3. Potential risks or concerns

When this skill runs:

1. Each !`command` executes immediately (before Claude sees anything)
2. The output replaces the placeholder in the skill content
3. Claude receives the fully-rendered prompt with actual PR data

Multi-Line Shell Injection

For multi-line commands, use a fenced code block opened with ```! instead of the inline form:

## Environment
```!
node --version
npm --version
git status --short
```

Disabling Shell Injection

Set "disableSkillShellExecution": true in settings to block !`cmd` and ```! execution from user/project/plugin/--add-dir skills. Each command is replaced with [shell command execution disabled by policy]. Bundled and managed skills are unaffected. Most useful in managed settings where users cannot override it.

Running Skills in a Subagent

Add context: fork to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. The subagent won't have access to your conversation history.

Important: context: fork only makes sense for skills with explicit task instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output.

Example: Research Skill

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

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

When this skill runs:

1. A new isolated context is created
2. The subagent receives the skill content as its prompt ("Research $ARGUMENTS thoroughly...")
3. The agent field determines the execution environment (model, tools, and permissions)
4. Results are summarized and returned to your main conversation

The agent field specifies which subagent configuration to use. Options include built-in agents (Explore, Plan, general-purpose) or any custom subagent from .claude/agents/. If omitted, uses general-purpose.

Skills vs Subagents Comparison

Skills with context: fork and subagents work together in two directions:

With context: fork, you write the task in your skill and pick an agent type to execute it. For the inverse (defining a custom subagent that uses skills as reference material), see the Claude Code subagents documentation.

When to Use context: fork

• Isolation needed: The skill's work shouldn't pollute your conversation context
• Explicit task: The skill defines a complete, self-contained task
• Parallel execution: Multiple forked skills can run concurrently
• Specialized tools: The agent type provides appropriate tools for the task

Skill Content Lifecycle (Claude Code)

When you or Claude invoke a skill, the rendered SKILL.md content enters the conversation as a single message and stays for the rest of the session. Claude Code does not re-read the skill file on later turns.

Implication: Write guidance that should apply throughout a task as standing instructions, not one-time steps.

Auto-Compaction Behavior

When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill after the summary:

• Keeps the first 5,000 tokens of each re-attached skill
• Combined re-attachment budget: 25,000 tokens total
• Filled most-recently-invoked first; older skills may be dropped entirely if you invoked many

Debugging "Skill Stopped Working"

If a skill seems to stop influencing behavior after the first response:

1. The content is usually still present — the model is choosing other tools/approaches
2. Strengthen the skill's description and instructions so the model keeps preferring it
3. Use hooks to enforce behavior deterministically
4. If the skill is large or many others were invoked after it, re-invoke after compaction to restore the full content

Reference vs Task Content

Two patterns for SKILL.md content. Choose based on how you want it invoked and where it runs.

Reference Content (inline, model-invocable)

Knowledge Claude applies alongside your conversation: conventions, patterns, style guides, domain knowledge. Runs inline with conversation context.

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

Task Content (action, usually user-only)

Step-by-step instructions for a specific action: deploy, commit, code-generation pipelines. Often paired with disable-model-invocation: true and frequently context: fork.

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

Writing Effective Descriptions

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

Critical Rules

Always write in third person. The description is injected into the system prompt.

• Good: "Processes Excel files and generates reports"
• Avoid: "I can help you process Excel files"
• Avoid: "You can use this to process Excel files"

Be specific and include key terms. Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills.

Effective Examples

PDF Processing skill:

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.

Excel Analysis skill:

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

Git Commit Helper skill:

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Bad Examples (Too Vague)

description: Helps with documents

description: Processes data

description: Does stuff with files

Progressive Disclosure Patterns

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

Practical Guidance

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

Pattern 1: High-Level Guide with References

---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

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

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.

Pattern 2: Domain-Specific Organization

For Skills with multiple domains, organize content by domain to avoid loading irrelevant context.

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)

## Quick search

Find specific metrics using grep:

```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```

Pattern 3: Conditional Details

Show basic content, link to advanced content:

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Claude reads REDLINING.md or OOXML.md only when the user needs those features.

Avoid Deeply Nested References

Claude may partially read files when they're referenced from other referenced files.

Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.

Bad example: Too deep:

# SKILL.md
See [advanced.md](advanced.md)...

# advanced.md
See [details.md](details.md)...

# details.md
Here's the actual information...

Good example: One level deep:

# SKILL.md

**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)

Structure Longer Reference Files with Table of Contents

For reference files longer than 100 lines, include a table of contents at the top.

Example:

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples

## Authentication and setup
...

## Core methods
...

Workflows and Feedback Loops

Use Workflows for Complex Tasks

Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy and check off as it progresses.

Example 1: Research synthesis workflow (for Skills without code):

## Research synthesis workflow

Copy this checklist and track your progress:

```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```

**Step 1: Read all source documents**

Review each document in the `sources/` directory. Note the main arguments and supporting evidence.

**Step 2: Identify key themes**

Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?

**Step 3: Cross-reference claims**

For each major claim, verify it appears in the source material. Note which source supports each point.

**Step 4: Create structured summary**

Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)

**Step 5: Verify citations**

Check that every claim references the correct source document. If citations are incomplete, return to Step 3.

Example 2: PDF form filling workflow (for Skills with code):

## PDF form filling 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 2: Create field mapping**

Edit `fields.json` to add values for each field.

**Step 3: Validate mapping**

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

Fix any validation errors before continuing.

**Step 4: Fill the form**

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

**Step 5: Verify output**

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

If verification fails, return to Step 2.

Implement Feedback Loops

Common pattern: Run validator → fix errors → repeat

This pattern greatly improves output quality.

Example 1: Style guide compliance (for Skills without code):

## Content review process

1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
   - Check terminology consistency
   - Verify examples follow the standard format
   - Confirm all required sections are present
3. If issues found:
   - Note each issue with specific section reference
   - Revise the content
   - Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document

Example 2: Document editing process (for Skills with code):

## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
   - Review the error message carefully
   - Fix the issues in the XML
   - Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document

Content Guidelines

Avoid Time-Sensitive Information

Don't include information that will become outdated.

Bad example: Time-sensitive (will become wrong):

If you're doing this before August 2025, use the old API.
After August 2025, use the new API.

Good example (use "old patterns" section):

## Current method

Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns

<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>

The v1 API used: `api.example.com/v1/messages`

This endpoint is no longer supported.
</details>

Use Consistent Terminology

Choose one term and use it throughout the Skill:

Good - Consistent:

• Always "API endpoint"
• Always "field"
• Always "extract"

Bad - Inconsistent:

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

Use Forward Slashes for Paths

Always use forw

…(truncated)