skill-name/
├── SKILL.md                    # Required: Skill definition and content
├── examples/                   # Optional: Example usage
│   ├── basic-usage.md
│   └── advanced-patterns.md
├── templates/                  # Optional: Code templates
│   └── template-file.py
├── references/                 # Optional: Reference materials
│   └── api-docs.md
└── scripts/                    # Optional: Helper scripts
    └── helper.py

---
name: skill-name
description: >
  Detailed description of what this skill does, when Claude should use it,
  and specific trigger terms. This field is CRITICAL for skill discovery.

  Include:
  - What the skill accomplishes
  - When to activate (specific scenarios)
  - Key trigger terms users might mention
  - Concrete examples of usage

allowed-tools: Tool1, Tool2    # Optional: Tool restrictions
---

# Skill Content

Main skill content starts here. This is what Claude sees when the skill is activated.

Include:
- Clear instructions
- Examples
- Best practices
- Common patterns
- Error handling

Reference supporting files with relative paths:
- See `examples/basic-usage.md` for getting started
- Use templates from `templates/` directory
- Consult `references/api-docs.md` for API details

name: pdf-form-filling        # Good
name: PDF Form Filling        # Bad - no spaces/capitals
name: helper                  # Bad - too generic
name: skill-that-does-pdf-form-filling-and-extraction  # Bad - too long

description: >
  Extract text and tables from PDF documents, fill PDF forms programmatically,
  and merge multiple PDFs. Use when user mentions PDF files, form filling,
  document parsing, or PDF manipulation.

  Activate for:
  - "Extract data from this PDF"
  - "Fill out this PDF form"
  - "Parse tables from PDF"
  - "Combine these PDFs"

  Do NOT use for:
  - Creating PDFs from scratch (use document generation skill)
  - Image extraction (use image processing skill)

description: Helps with documents  # Too vague, no trigger terms

# Read-only skill
allowed-tools: Read, Grep, Glob

# File manipulation skill
allowed-tools: Read, Write, Edit

# Full access (can run commands)
allowed-tools: Read, Write, Bash, Grep

# Skill Name

## Overview
Brief description of what this skill provides and when to use it.

## Capabilities
- List specific capabilities
- Be concrete and actionable
- Include limitations

## Usage

When this skill is activated, follow these steps:

1. **Step 1**: Clear action with example
   ```python
   # Code example

### 3. Include Examples
```markdown
## Examples

### Basic Usage
User request: "Extract text from this PDF"

Response approach:
1. Use Read tool to access PDF
2. Parse with PDF library
3. Return extracted text

### Advanced Usage
User request: "Fill out this tax form PDF with data from CSV"

Response approach:
1. Load CSV data
2. Map fields to PDF form
3. Fill and save

## Templates

Use the templates in `templates/` directory:
- `templates/pdf-parser.py` - Basic PDF parsing
- `templates/form-filler.py` - Form field population

## Examples

See `examples/` for complete workflows:
- `examples/basic-extraction.md` - Simple text extraction
- `examples/form-automation.md` - Automated form filling

## Error Handling

Common issues and solutions:

**PDF is password protected**:
- Ask user for password
- Use PyPDF2 decrypt method

**Form fields not found**:
- List available fields
- Ask user to map fields manually

~/.claude/skills/
├── pdf-processing/
│   ├── SKILL.md
│   ├── examples/
│   └── templates/
└── data-analysis/
    ├── SKILL.md
    └── scripts/

.claude/skills/
├── api-testing/
│   ├── SKILL.md
│   ├── templates/
│   │   ├── test-template.py
│   │   └── mock-data.json
│   └── examples/
└── deployment-checks/
    └── SKILL.md

plugin-name/
└── skills/
    ├── capability-one/
    │   └── SKILL.md
    └── capability-two/
        ├── SKILL.md
        └── helpers/

# examples/basic-pdf-extraction.md

## Extracting Text from PDF

User: "Get the text from report.pdf"

Assistant approach:
1. Read the PDF file
2. Use PyPDF2 to extract text
3. Return formatted text

Code:
\`\`\`python
import PyPDF2
# ... extraction code
\`\`\`

Output:
- Extracted text
- Page numbers
- Formatting preserved

# templates/pdf-parser.py
"""
Template for PDF text extraction
Usage: Adapt for specific PDF parsing needs
"""

import PyPDF2
from typing import List, Dict

def extract_text(pdf_path: str) -> List[str]:
    """Extract text from all pages."""
    with open(pdf_path, 'rb') as file:
        reader = PyPDF2.PdfReader(file)
        return [page.extract_text() for page in reader.pages]

def extract_tables(pdf_path: str) -> List[Dict]:
    """Extract tables from PDF."""
    # Implementation here
    pass

# references/pdf-libraries.md

## Python PDF Libraries

### PyPDF2
- Basic PDF manipulation
- Good for simple text extraction
- Free and lightweight

### pdfplumber
- Advanced table extraction
- Better text positioning
- Recommended for complex layouts

### reportlab
- PDF generation from scratch
- Not for reading existing PDFs

# scripts/pdf-validator.py
"""Validate PDF files before processing."""

def is_valid_pdf(file_path: str) -> bool:
    """Check if file is a valid PDF."""
    # Implementation
    pass

def get_pdf_info(file_path: str) -> dict:
    """Extract PDF metadata."""
    # Implementation
    pass

description: >
  Process Excel and CSV files, perform data transformations, generate reports.

  Trigger terms: Excel, CSV, spreadsheet, data import, pivot table, VLOOKUP,
  data cleaning, pandas, dataframe, export to Excel

description: >
  Handle authentication with JWT tokens, OAuth 2.0, and session management.
  Use for login, logout, token refresh, and authorization checks.

  Do NOT use for:
  - Password hashing (use security-utils skill)
  - User registration (use user-management skill)
  - Email verification (use notification skill)

description: >
  Database migration management with zero-downtime deployments.

  Activate when user mentions:
  - "Create a migration"
  - "Roll back database changes"
  - "Add a column without downtime"
  - "Database schema updates"

  Example: User says "I need to add a new column to the users table"
  → Activate this skill to create safe migration

# Main Skill Content (loaded immediately)

Brief instructions and common patterns.

## Detailed Examples
See `examples/advanced-usage.md` for detailed examples (loaded on demand).

## API Reference
Consult `references/api-docs.md` for complete API documentation (loaded on demand).

---
name: deployment-workflow
description: >
  Orchestrate application deployment with pre-deployment checks, rollout,
  and post-deployment verification. Use when user requests "deploy",
  "release", "push to production", or deployment-related tasks.
---

# Deployment Workflow

## Steps
1. Run pre-deployment checks (tests, linting, security scans)
2. Build application artifacts
3. Deploy to staging
4. Run smoke tests
5. Deploy to production with rollback plan
6. Verify deployment health

---
name: api-testing
description: >
  Test REST APIs with automated request/response validation. Use when user
  mentions API testing, endpoint verification, or HTTP request debugging.
allowed-tools: Bash, Read, Write
---

# API Testing Skill

Uses `curl` and `jq` to test API endpoints.

## Usage
Provide:
- Endpoint URL
- Expected status code
- Response schema validation

## Templates
See `templates/api-test-template.sh` for test script template.

---
name: code-complexity-analysis
description: >
  Analyze code complexity metrics, cyclomatic complexity, and maintainability.
  Use for code review, refactoring planning, or technical debt assessment.
allowed-tools: Read, Grep, Glob, Bash(radon:*)
---

# Code Complexity Analysis

Generates complexity reports using radon and custom metrics.

## Metrics
- Cyclomatic complexity
- Maintainability index
- Lines of code
- Cognitive complexity

description: Helps with files

description: >
  Extract text, tables, and metadata from PDF files. Use when user
  mentions PDF parsing, form filling, or document extraction.

name: backend-development
description: Handles all backend tasks

name: database-migration
description: Create and manage database migrations with zero downtime

description: Processes spreadsheets

description: >
  Process Excel and CSV files. Activate for: Excel, CSV, spreadsheet,
  XLSX, pandas, dataframe, pivot table

skill-name.md          # Just a file, not a directory

skill-name/
├── SKILL.md
├── examples/
└── templates/