Write Skills
Claude Actually Uses

Concise is key

The context window is a public good. SKILL.md shares it with everything else Claude needs — system prompt, conversation history, other Skills' metadata, and the user's request.

At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant. But once loaded, every token competes with conversation context.

## Extract PDF text

Use pdfplumber:

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

## Extract PDF text

PDF (Portable Document Format) files
are a common file format that contains
text, images, and other content. To
extract text you'll need a library.
There are many options but pdfplumber
is recommended because it's easy to
use and handles most cases well.
First, install it using pip...

Set appropriate degrees of freedom

Match specificity to the task's fragility and variability. Think of Claude as a robot on a path: a narrow bridge with cliffs needs exact guardrails; an open field just needs a general direction.

## Code review process
1. Analyze structure and organization
2. Check for bugs and edge cases
3. Suggest readability improvements
4. Verify project conventions

## Generate report
Use this template and customize as needed:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
```

## Database migration
Run exactly this script:

```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add flags.

Test with all models you plan to use

Skills act as additions to models — effectiveness depends on the underlying model. A Skill that over-explains wastes tokens on Opus; one that under-explains fails on Haiku.

Naming conventions

Use gerund form (verb + -ing) for Skill names — this clearly describes the activity the Skill provides.

Writing effective descriptions

Include what the Skill does and when to use it. Claude uses the description to choose from potentially 100+ available Skills.

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.

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

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

Pattern: High-level guide with references

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md)
- **Examples**: See [EXAMPLES.md](EXAMPLES.md)

Claude loads FORMS.md or REFERENCE.md only when needed — zero token cost otherwise.

Pattern: Domain-specific organization

For Skills with multiple domains, organize by domain so Claude only loads what's relevant to the current task.

bigquery-skill/
├── SKILL.md
└── reference/
    ├── finance.md   # revenue, billing metrics
    ├── sales.md     # opportunities, pipeline
    └── product.md   # API usage, features

Table of contents for long reference files

For reference files longer than 100 lines, add a TOC at the top so Claude can see the full scope even when previewing.

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Error handling patterns

## Authentication and setup
...

Use checklists for complex tasks

For complex operations, provide a checklist Claude can copy into its response and check off as it progresses.

## Research synthesis workflow

Copy this checklist and track 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
```

## PDF form filling workflow

Task Progress:
- [ ] Step 1: Analyze 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)

Implement feedback loops

The run validator → fix errors → repeat pattern greatly improves output quality for document editing, code generation, or any structured output.

## 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 issues in the XML
   - Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`

Avoid time-sensitive information

If before August 2025, use old API.
After August 2025, use new API.

## Current method
Use v2: `api.example.com/v2/messages`

## Old patterns
<details>
<summary>Legacy v1 (deprecated)</summary>
...
</details>

Use consistent terminology

Template pattern

Provide templates for output format. Match strictness level to requirements.

## Report structure

ALWAYS use this exact template:

```markdown
# [Analysis Title]

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

## Key findings
- Finding 1 with supporting data

## Recommendations
1. Specific actionable recommendation
```

Examples pattern

For Skills where output quality depends on seeing examples, provide input/output pairs — just like prompting.

## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:
```
fix(reports): correct date formatting in timezone conversion
```

Conditional workflow pattern

## Document modification workflow

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow"
   **Editing existing content?** → Follow "Editing workflow"

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change

Build evaluations first

Create evaluations before writing extensive documentation. This ensures your Skill solves real problems rather than documenting imagined ones.

Develop Skills iteratively with Claude

Use Claude A to create and refine the Skill, and Claude B (fresh instance) to test it in real tasks.

Solve, don't punt

Handle error conditions in scripts rather than letting Claude figure them out.

def process_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        with open(path, "w") as f:
            f.write("")
        return ""

def process_file(path):
    # Just fail and let
    # Claude figure it out
    return open(path).read()

No magic numbers

# HTTP requests typically
# complete in 30 seconds
REQUEST_TIMEOUT = 30

# Three retries balances
# reliability vs speed
MAX_RETRIES = 3

TIMEOUT = 47  # Why 47?
RETRIES = 5   # Why 5?

Document utility scripts clearly

Make clear whether Claude should execute or read the script. Pre-made scripts are more reliable than generated code.

## Utility scripts

**analyze_form.py** — Extract all form fields from PDF
```bash
python scripts/analyze_form.py input.pdf > fields.json
```

**validate_boxes.py** — Check for overlapping bounding boxes
```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```

MCP tool references

Always use fully qualified tool names to avoid "tool not found" errors.

Use BigQuery:bigquery_schema to retrieve table schemas.
Use GitHub:create_issue to create issues.

Package dependencies