Claude Skills Best Practices

Build reliable, maintainable Claude Skills following industry best practices.

1. Clear Naming

✅ Good: pdf-invoice-extractor ❌ Bad: skill1, my_cool_skill

Use descriptive, URL-friendly names that indicate purpose.

2. Detailed Instructions

markdown
1## Instructions
2When extracting invoice data:
31. Validate PDF format (reject if corrupted)
42. Extract text from first 3 pages only
53. Parse fields: invoice_number, date, amount, vendor
64. If field missing, return null (don't guess)
75. Validate amount is numeric
86. Return JSON object
1## Instructions
2When extracting invoice data:
31. Validate PDF format (reject if corrupted)
42. Extract text from first 3 pages only
53. Parse fields: invoice_number, date, amount, vendor
64. If field missing, return null (don't guess)
75. Validate amount is numeric
86. Return JSON object

Be explicit about every step, edge case, and validation.

3. Comprehensive Examples

Provide multiple scenarios:

markdown
1### Example 1: Standard Invoice
2**Input**: standard_invoice.pdf
3**Output**: {"invoice_number": "INV-001", ...}
4
5### Example 2: Multi-page Invoice
6**Input**: long_invoice.pdf
7**Output**: {"invoice_number": "INV-002", ...}
8
9### Example 3: Corrupted File
10**Input**: broken.pdf
11**Output**: {"error": "Invalid PDF format"}
1### Example 1: Standard Invoice
2**Input**: standard_invoice.pdf
3**Output**: {"invoice_number": "INV-001", ...}
4
5### Example 2: Multi-page Invoice
6**Input**: long_invoice.pdf
7**Output**: {"invoice_number": "INV-002", ...}
8
9### Example 3: Corrupted File
10**Input**: broken.pdf
11**Output**: {"error": "Invalid PDF format"}

4. Error Handling

Define all failure modes:

markdown
## Error Handling
- Invalid file format → Return {"error": "Invalid format"}
- Missing required fields → Return partial data with null
- Processing timeout → Return {"error": "Timeout"}
- Permission denied → Return {"error": "Access denied"}
## Error Handling
- Invalid file format → Return {"error": "Invalid format"}
- Missing required fields → Return partial data with null
- Processing timeout → Return {"error": "Timeout"}
- Permission denied → Return {"error": "Access denied"}

5. Version Control

Use semantic versioning:

• 1.0.0 - Initial release
• 1.1.0 - New feature added
• 1.1.1 - Bug fix
• 2.0.0 - Breaking change

6. Security

markdown
## Security
- Input validation: Always validate file types
- Sandboxing: Run scripts in isolated environment
- Secrets: Never hardcode API keys
- Permissions: Request minimum necessary access
## Security
- Input validation: Always validate file types
- Sandboxing: Run scripts in isolated environment
- Secrets: Never hardcode API keys
- Permissions: Request minimum necessary access

7. Performance

• Cache expensive operations
• Stream large files don't load into memory
• Set execution timeouts
• Optimize dependencies (use lightweight libraries)

8. Testing

Test your skill thoroughly:

python
1def test_pdf_extraction():
2    # Test valid input
3    result = extract_invoice("test.pdf")
4    assert result["invoice_number"] is not None
5
6    # Test invalid input
7    result = extract_invoice("broken.pdf")
8    assert "error" in result
1def test_pdf_extraction():
2    # Test valid input
3    result = extract_invoice("test.pdf")
4    assert result["invoice_number"] is not None
5
6    # Test invalid input
7    result = extract_invoice("broken.pdf")
8    assert "error" in result

9. Documentation

Include comprehensive docs:

markdown
## Documentation

### Installation
```bash
pip install -r requirements.txt
## Documentation

### Installation
```bash
pip install -r requirements.txt

Configuration

Set environment variables:

• API_KEY: Your API key
• MAX_PAGES: Maximum pages to process (default: 10)

Troubleshooting

Problem: Skill not loading Solution: Check folder structure matches specification

## 10. Maintenance

- Update dependencies regularly
- Monitor skill performance
- Collect user feedback
- Iterate on edge cases

## Real-World Example

Here's a well-structured skill:

```markdown
# Invoice Data Extractor

## Metadata
- Name: invoice-extractor
- Description: Extract structured data from PDF invoices
- Version: 2.1.0
- Author: Finance Team
- Tags: pdf, invoices, data-extraction
- License: MIT

## Instructions
[Detailed 10-step process]

## Usage Examples
[5 different scenarios]

## Dependencies
- Python >= 3.8
- pdfplumber >= 0.9.0
- python-dateutil >= 2.8.0

## Error Handling
[All failure modes documented]

## Security
[Security considerations listed]

## Performance
- Average execution: 2-3 seconds
- Memory usage: < 100MB
- Concurrent executions: Safe

## Changelog
### 2.1.0 (2025-01-15)
- Added multi-currency support
- Improved date parsing
### 2.0.0 (2025-01-01)
- Breaking: Changed output format to JSON

Checklist

• [ ] Clear, descriptive name
• [ ] Detailed step-by-step instructions
• [ ] 3+ usage examples
• [ ] All error cases documented
• [ ] Security considerations noted
• [ ] Dependencies with versions
• [ ] Performance characteristics
• [ ] Test suite included
• [ ] Comprehensive documentation
• [ ] Version history maintained

---

Reading Time: 5 minutes