Writing Skills

Level 1: Name + Description (~100 tokens)
    ↓ (triggered by user request)
Level 2: SKILL.md content
    ↓ (as needed)
Level 3: Scripts, references, templates

my-skill/
├── SKILL.md              # Required: Manifest and main instructions
├── requirements.txt      # Optional: Python dependencies
├── package.json          # Optional: Node.js dependencies
├── scripts/
│   ├── process.py        # Helper scripts
│   └── utils.js
├── reference/
│   ├── api-guide.md      # Detailed documentation
│   └── examples.md
└── templates/
    └── output.hbs        # Output templates

---
name: pdf-processing
description: Extract text, tables, and images from PDF files. Use when working with PDF documents or converting PDFs to other formats.
---

---
name: pdf-processing
description: Extract text, tables, and images from PDF files.
---

# PDF Processing

## Quick Start

Use this skill when the user needs to:

- Extract text from PDF documents
- Convert PDF tables to structured data
- Extract images from PDFs

## Usage

To extract text from a PDF:

```python
python /skills/pdf-processing/scripts/extract.py input.pdf
```

### Best Practices for SKILL.md

1. **Start with purpose** - Clearly state what the Skill does and when to use it
2. **Provide quick examples** - Show the most common usage patterns first
3. **Reference scripts** - Point to helper scripts rather than inlining code
4. **Keep it under 500 lines** - Split longer content into reference files
5. **Use clear headings** - Help the agent navigate to relevant sections

## Writing Scripts

### Script Guidelines

- **Make scripts executable** - Include shebang and proper permissions
- **Accept arguments** - Use command-line arguments for flexibility
- **Output clearly** - Print results in a parseable format
- **Handle errors** - Provide meaningful error messages

### Example Python Script

```python
#!/usr/bin/env python3
"""Extract text from PDF files."""

import sys
import pdfplumber

def extract_text(pdf_path):
    """Extract all text from a PDF file."""
    with pdfplumber.open(pdf_path) as pdf:
        text = ""
        for page in pdf.pages:
            text += page.extract_text() or ""
            text += "\n\n"
    return text.strip()

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: extract.py <pdf_path>", file=sys.stderr)
        sys.exit(1)

    pdf_path = sys.argv[1]
    try:
        result = extract_text(pdf_path)
        print(result)
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)

## Usage

Run the extraction script:

```bash
python /skills/pdf-processing/scripts/extract.py document.pdf
```

## Reference Files

Use reference files for:

- Detailed API documentation
- Complex examples
- Domain-specific guides
- Configuration templates

### Linking References

Reference additional files from SKILL.md:

```md
## Advanced Usage

For handling encrypted PDFs, see `reference/encryption.md`.

For batch processing multiple files, see `reference/batch-processing.md`.

## Workflow

1. **Validate Input** - Check file format and size
2. **Process** - Run the main transformation
3. **Validate Output** - Verify results
4. **Return** - Provide the final output

### Step 1: Validate Input

```python
python /skills/my-skill/scripts/validate.py input.pdf
```

### Template Skills

For generating structured output:

```md
## Templates

Use the Handlebars template in `templates/report.hbs`:

```python
python /skills/my-skill/scripts/generate.py --template templates/report.hbs --data input.json

### Reference Skills

For domain expertise:

```md
## Domain Knowledge

This skill provides expertise in financial reporting. Key references:

- `reference/gaap-rules.md` - GAAP compliance guidelines
- `reference/formats.md` - Standard report formats
- `reference/examples/` - Sample reports