Skill Format

---
name: skill-name
description: A clear description of what this skill does.
---

# Skill Title

Your skill instructions go here...

# Valid names
name: pdf-processing
name: data-analysis-v2
name: my-tool-123

# Invalid names
name: PDF-Processing    # Uppercase not allowed
name: my_skill          # Underscores not allowed
name: -my-skill         # Cannot start with hyphen
name: my-skill-         # Cannot end with hyphen
name: claude            # Reserved name

# Good descriptions
description: Extract text and tables from PDF files. Use when working with PDF documents.
description: Analyze customer sentiment from feedback text. Useful for support ticket analysis.

# Poor descriptions
description: Does PDF stuff.          # Too vague
description: A skill.                 # Not helpful

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

# PDF Processing

Brief overview of the skill.

## When to Use

- Extract text from PDF documents
- Convert PDF tables to CSV
- Process multiple PDFs in batch

## Quick Start

Basic usage example:

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

python /skills/pdf-processing/scripts/extract.py report.pdf

python /skills/pdf-processing/scripts/tables.py data.pdf --output tables.csv

### Content Guidelines

1. **Be specific** - Provide exact commands and file paths
2. **Use examples** - Show real usage patterns
3. **Reference files** - Point to scripts and resources by path
4. **Keep it focused** - Move detailed docs to reference files

## Complete Example

Here's a complete, well-structured SKILL.md:

```md
---
name: image-processing
description: Resize, crop, and convert images. Use when working with image files or preparing images for specific dimensions.
---

# Image Processing

This skill provides tools for common image manipulation tasks including resizing, cropping, format conversion, and optimization.

## When to Use

Use this skill when:
- Resizing images to specific dimensions
- Converting between image formats (PNG, JPEG, WebP)
- Cropping images to specific aspect ratios
- Optimizing images for web use

## Quick Start

Resize an image to 800x600:

```bash
python /skills/image-processing/scripts/resize.py input.jpg 800 600

python /skills/image-processing/scripts/resize.py <input> <width> <height> [--output <path>]

python /skills/image-processing/scripts/convert.py <input> <format> [--quality <1-100>]

python /skills/image-processing/scripts/crop.py <input> --aspect <ratio>
python /skills/image-processing/scripts/crop.py <input> --region <x> <y> <width> <height>

# Instagram square
python /skills/image-processing/scripts/resize.py photo.jpg 1080 1080

# Twitter header
python /skills/image-processing/scripts/resize.py banner.png 1500 500

# Convert PNG to optimized WebP
python /skills/image-processing/scripts/convert.py image.png webp --quality 80

## Validation

The SKILL.md is validated during upload:

| Check | Requirement |
|-------|-------------|
| File exists | SKILL.md must be present in Skill root |
| Valid YAML | Frontmatter must be valid YAML syntax |
| Name present | `name` field is required |
| Name format | Must match naming rules |
| Description present | `description` field is required |
| Description non-empty | Must have actual content |

## Error Messages

### "Missing SKILL.md"

The Skill directory doesn't contain a SKILL.md file. Create one with proper frontmatter.

### "Skill name is required in SKILL.md frontmatter"

Add a `name` field to your frontmatter:

```yaml
---
name: my-skill
description: My skill description.
---