---

name: skill-name description: TODO: [What it does]. Use when [specific triggers]. Example: "Analyzes Excel spreadsheets and generates charts. Use when working with Excel files, .xlsx, spreadsheet analysis, or data visualization." REQUIRED: Include "Use when..." with trigger keywords (file types, domains, tasks). Third person. Max 1024 chars.

Skill Name

NOTE: This is a template file. After copying this directory to create a new skill, customize the YAML frontmatter and replace all TODO sections with your skill's content.

TODO: Brief 1-2 sentence overview. Be concise - the context window is shared with conversation history, other skills, and user requests.

Overview

TODO: Detailed introduction explaining the purpose and scope of this skill (1 paragraph).

When to Use This Skill

This skill should be used when:

• TODO: List specific scenarios when this skill should activate
• TODO: Include file types, operations, or keywords that should trigger activation
• TODO: Be as specific as possible to help Claude discover when to use this

Quick Start

TODO: Provide the fastest path to value. Show the most common use case with a brief example.

Example:

# TODO: Replace with actual quick start command or code snippet
echo "Hello, world!"

[Main Instructions Section]

TODO: Choose and implement ONE of these structural patterns based on your skill's purpose:

Option 1: Workflow-Based Pattern (for sequential processes)

Use when: Multi-step processes, sequential operations, guided workflows

Pattern structure:

## Workflow Decision Tree
## Step 1: Initial Setup
## Step 2: Configuration
## Step 3: Execution
## Troubleshooting

For complex workflows, provide a checklist:

## PDF Form Filling Workflow

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

```
Task Progress:
- [ ] Step 1: Analyze the form
- [ ] Step 2: Create field mapping
- [ ] Step 3: Validate mapping
- [ ] Step 4: Fill the form
- [ ] Step 5: Verify output
```

**Step 1: Analyze the form**
[Instructions for this step]

**Step 2: Create field mapping**
[Instructions for this step]

[Continue for each step...]

Option 2: Task-Based Pattern (for collections of operations)

Use when: Tool collections, utility skills, multiple independent capabilities

Pattern structure:

## Task Category 1: [Name]
### Task 1.1: [Operation]
### Task 1.2: [Operation]
## Task Category 2: [Name]
### Task 2.1: [Operation]

Option 3: Reference-Based Pattern (for guidelines/standards)

Use when: Style guides, coding standards, brand guidelines, API specifications

Pattern structure:

## Core Principles
## Guidelines
## Specifications
## Usage Examples

Option 4: Capabilities-Based Pattern (for integrated features)

Use when: Complex systems, integrated tools, multi-capability skills

Pattern structure:

## Core Capabilities
## Capability 1: [Feature Name]
## Capability 2: [Feature Name]
## Integration Guide

Option 5: Validation Feedback Loop Pattern (for operations requiring correctness)

Use when: Complex operations, batch updates, operations where errors are costly

Pattern structure:

## Workflow with Validation

### Step 1: Analyze Input
[Understand requirements]

### Step 2: Generate Plan
Create intermediate plan file (e.g., changes.json)

### Step 3: Validate Plan

```bash
python scripts/validate_plan.py plan.json
```

### Step 4: Review Errors
If errors found, fix and return to Step 3

### Step 5: Execute Plan
Apply validated plan

### Step 6: Verify Output
Confirm output meets requirements

Key principle: Catch errors early through intermediate validation before expensive operations.

Examples

TODO: Provide concrete, representative examples with input/output pairs. Examples help Claude understand desired style and level of detail better than descriptions alone.

Example 1: Basic Usage

TODO: Show a simple, common use case. Use input/output format:

Input: [What the user provides]
Expected Output:
[Show exactly what should be produced]

Format guidance: Show concrete input → output pairs. For instance, if this skill generates commit messages, show:

• Input: "Create a commit message for these changes: Added user authentication"
• Output: "feat(auth): implement user authentication system\n\nAdd login endpoints and session management"

Example 2: Advanced Usage

TODO: Show a more complex or powerful use case using the same input/output format:

Input: [More complex scenario]
Expected Output:
[Show the complete output with all details]

Pattern tip: Use input/output pairs like in regular prompting to show Claude the desired format and quality level. This works better than descriptions alone.

Resources

This skill includes example resource directories that demonstrate how to organize different types of bundled resources:

scripts/

Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

Examples from other skills:

• PDF skill: fill_fillable_fields.py, extract_form_field_info.py - utilities for PDF manipulation
• DOCX skill: document.py, utilities.py - Python modules for document processing

Appropriate for: Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

Note: Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.

TODO: If your skill includes scripts, list them here:

• scripts/example.py - TODO: Describe what this script does

references/

Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.

Examples from other skills:

• Product management: communication.md, context_building.md - detailed workflow guides
• BigQuery: API reference documentation and query examples
• Finance: Schema documentation, company policies

Appropriate for: In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.

IMPORTANT: Keep references one level deep from SKILL.md - don't nest references beyond one level. Claude reads complete files when directly referenced from SKILL.md, but may only preview nested references.

For large reference files (>100 lines): Include a table of contents at the top so Claude understands available information during partial reads.

TODO: If your skill includes reference documentation, list it here:

• See references/example.md for TODO: detailed information on X

Make content greppable:

To find OAuth implementation details:
```bash
grep -i "oauth" references/authentication.md
```

assets/

Files not intended to be loaded into context, but rather used within the output Claude produces.

Examples from other skills:

• Brand styling: PowerPoint template files (.pptx), logo files
• Frontend builder: HTML/React boilerplate project directories
• Typography: Font files (.ttf, .woff2)

Appropriate for: Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.

TODO: If your skill includes assets, list them here:

• assets/example.txt - TODO: Describe what this asset is for

---

Any unneeded directories can be deleted. Not every skill requires all three types of resources.

Troubleshooting

TODO: Document common issues and solutions:

Issue: [Common Problem]

• Cause: TODO: Why this happens
• Solution: TODO: How to fix it

Issue: [Another Common Problem]

• Cause: TODO: Why this happens
• Solution: TODO: How to fix it

Best Practices

TODO: List recommendations for using this skill effectively:

• TODO: Best practice 1
• TODO: Best practice 2
• TODO: Best practice 3

Version History

• v1.0.0 (YYYY-MM-DD): Initial release

---

Template Usage Instructions

Before deploying this skill, complete all TODO items:

1. ✅ Replace skill-name in frontmatter with actual name (lowercase, hyphens, max 64 chars)
2. ✅ Write specific description with both functionality AND trigger scenarios (max 1024 chars)
3. ✅ Replace all TODO sections with actual content
4. ✅ Choose and implement ONE structural pattern (remove others)
5. ✅ Add concrete examples relevant to your skill
6. ✅ Document any supporting files (scripts, references, assets)
7. ✅ Remove this "Template Usage Instructions" section
8. ✅ Validate YAML frontmatter syntax
9. ✅ Test skill activation with representative queries
10. ✅ Ensure directory name matches name field exactly

Structural Pattern Selection:

• Workflow-Based: Sequential processes with clear steps (e.g., setup workflows, multi-step operations)
• Task-Based: Collections of related operations (e.g., PDF tools, API operations)
• Reference-Based: Standards and guidelines (e.g., brand guidelines, coding standards)
• Capabilities-Based: Integrated feature sets (e.g., platform capabilities, product features)

Content Sizing:

• Official guidance: Keep under 500 lines or 5k tokens for optimal performance
• Target: 2,000-5,000 words in SKILL.md
• Maximum: ~10,000 words - if exceeding, use references/ for details
• Minimum: ~500 words - provide sufficient context
• Move detailed documentation to references/ if approaching limits
• Keep this file focused on essential instructions

Writing Principle: "Concise is Key"

The context window is shared with conversation history, other skills, and user requests.

• Challenge each explanation: "Does Claude really need this?"
• Omit what Claude already knows (what PDFs are, what libraries do)
• Focus on your domain specifics, requirements, and workflows
• Example: Don't explain what OAuth is; explain YOUR OAuth configuration

Set Appropriate Degrees of Freedom:

Match specificity to task fragility:

• High freedom (text instructions): Multiple valid approaches, context-dependent decisions
• Medium freedom (pseudocode/templates): Preferred pattern with acceptable variation
• Low freedom (exact scripts): Fragile operations, consistency critical, specific sequence required

Description Tips:

CRITICAL: Always use third person - Description is injected into system prompt:

• ✅ "Processes Excel files and generates reports"
• ❌ "I can help you process Excel files" (first person)
• ❌ "You can use this to process Excel files" (second person)

Include these keyword types:

• File types: .md, .json, .xlsx, PDF, Excel
• Domains: API, authentication, database, testing
• Tasks: analyze, generate, create, build, validate
• Tools: Git, Docker, Kubernetes, PostgreSQL

Official Pattern: [What it does]. Use when [specific triggers].

This is the ONLY documented mechanism for skill discovery. Claude uses descriptions to choose skills from 100+ available. Include BOTH capabilities AND triggers.

Example descriptions:

✅ Excellent (follows official pattern):

description: Analyzes Excel spreadsheets, generates pivot tables, creates charts. Use when working with Excel files (.xlsx, .xls), spreadsheet analysis, or data visualization tasks.

✅ Good (clear triggers):

description: Generates descriptive commit messages by analyzing git diffs. Use when writing commit messages, reviewing staged changes, or preparing git commits.

❌ Missing "Use when..." triggers:

description: Generates descriptive commit messages.

❌ Too vague:

description: Helps with files.

❌ Wrong voice (must be third person):

description: I will help you analyze spreadsheets.

Validation Checklist:

• YAML frontmatter is valid
• name follows conventions (lowercase, hyphens, max 64 chars)
• name matches directory name exactly
• description follows official pattern: [What it does]. Use when [triggers].
• description includes "Use when..." with specific trigger keywords
• All TODO items are replaced
• Examples are concrete and representative
• Supporting files are documented (if present)
• Skill activates for expected scenarios