Skill Creator

Guide for creating modular skills that extend Claude's capabilities through specialized knowledge, workflows, and tool integrations.

What is a Skill?

Skills are domain-specific onboarding guides that transform Claude into a specialized agent. They function as modular packages containing:

• •Specialized knowledge — domain expertise and best practices
• •Workflows — step-by-step procedures for common tasks
• •Tool integrations — scripts, utilities, and external tools
• •References — documentation and examples

Key Principles

1. Context Efficiency

"The context window is a public good."

• •Justify every piece of information included
• •Assume Claude has substantial baseline intelligence
• •Don't repeat what Claude already knows
• •Keep SKILL.md under 500 lines

2. Degrees of Freedom

Match specificity to task requirements:

3. Progressive Disclosure

Three-level loading system:

1. •Metadata — Always available (name, description in frontmatter)
2. •SKILL.md body — Loaded on trigger
3. •Bundled resources — Loaded as needed

Skill Anatomy

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/         # Executable code
    │   ├── utility.py
    │   └── helper.js
    ├── references/      # Reference documentation
    │   └── api-spec.md
    └── assets/          # Output resources
        └── template.html

SKILL.md Structure

---
name: skill-name
description: |
  Brief description of what this skill does.
  This appears in skill discovery/selection.
  Keep it under 100 words.
---

# Skill Title

Main instructions go here.

## Section 1

Detailed guidance...

## Section 2

More guidance...

---

## Quick Reference

Summary tables, command references, etc.

Frontmatter Rules

• •name: Lowercase, hyphenated (e.g., pdf-processor)
• •description: 1-3 sentences explaining when to use this skill
• •Put "when to use" information ONLY in description, not in body

Creation Workflow

1. Understand

Gather concrete examples of the task:

• •What inputs does it receive?
• •What outputs does it produce?
• •What decisions need to be made?
• •What errors commonly occur?

2. Plan

Identify reusable components:

• •Scripts: Code that performs actions
• •References: Documentation to consult
• •Assets: Templates, examples, resources

3. Initialize

Create the skill structure:

mkdir -p skill-name/{scripts,references,assets}
touch skill-name/SKILL.md

4. Write

Draft SKILL.md with:

• •Clear purpose statement
• •Step-by-step workflows
• •Code examples
• •Common pitfalls
• •Quick reference tables

5. Test

Verify the skill works:

• •Test all workflows end-to-end
• •Check all scripts execute correctly
• •Validate references are accurate
• •Ensure examples are complete

6. Iterate

Refine based on usage:

• •Remove unnecessary content
• •Add missing edge cases
• •Improve unclear sections
• •Update outdated references

Best Practices

DO

✅ Keep SKILL.md focused and concise ✅ Use tables for quick reference ✅ Include working code examples ✅ Document common errors and fixes ✅ Use clear section headings ✅ Reference bundled scripts by path ✅ Specify when to load additional resources

DON'T

❌ Create README, CHANGELOG, or auxiliary docs ❌ Duplicate information Claude already knows ❌ Include unnecessary dependencies ❌ Write overly verbose explanations ❌ Add "nice to have" information ❌ Mix multiple unrelated capabilities

Bundled Scripts

Guidelines

• •Scripts should be self-contained
• •Include shebang and usage comments
• •Handle errors gracefully
• •Support common arguments

Example Script Header

#!/usr/bin/env python3
"""
Utility for processing documents.

Usage:
    python process.py input.pdf output.txt [--verbose]

Arguments:
    input.pdf   - Input PDF file
    output.txt  - Output text file
    --verbose   - Enable detailed logging
"""

import argparse
import sys

def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('input', help='Input file')
    parser.add_argument('output', help='Output file')
    parser.add_argument('--verbose', action='store_true')
    args = parser.parse_args()

    # Implementation...

if __name__ == '__main__':
    main()

Reference Files

Use for:

• •API specifications
• •Schema definitions
• •Extended examples
• •Domain-specific documentation

Reference in SKILL.md:

For detailed API reference, read `references/api-spec.md`.

Loading Triggers

Specify when to load additional resources:

## Advanced Features

**Load `references/advanced.md` when:**
- User requests batch processing
- Error handling needs customization
- Performance optimization required

Example: Translation Skill

---
name: document-translator
description: |
  Translate documents between languages with proper
  formatting preservation. Supports PDF, DOCX, and
  images. Use for legal, technical, or general translation.
---

# Document Translator

Translate documents while preserving formatting and structure.

## Workflow

1. **Detect file type** — PDF, DOCX, or image
2. **Extract content** — Use appropriate method
3. **Translate** — Apply language rules
4. **Export** — Generate formatted output

## Supported Formats

| Format | Extract Method | Export |
|--------|---------------|--------|
| PDF | Vision/OCR | DOCX |
| DOCX | Unzip XML | DOCX |
| Image | Vision | DOCX |

## Scripts

- `scripts/extract.py` — Content extraction
- `scripts/export.js` — DOCX generation

## Quick Reference

### Arabic → English
- Use Latin numerals (0-9)
- LTR document direction
- Commas for thousands

### English → Arabic
- Use Hindi numerals (٠-٩)
- RTL document direction
- Wrap Latin text in `<span dir="ltr">`

Checklist

Before finalizing a skill:

• • SKILL.md under 500 lines
• • Clear frontmatter with name and description
• • All workflows tested end-to-end
• • Scripts executable and documented
• • No duplicate/unnecessary content
• • Quick reference tables included
• • Load triggers specified for resources
• • Common errors documented