Skiller

Generate Claude Code skills following Anthropic best practices.

Quick Start

CopySkill Generation:
- [ ] Design structure (naming, organization)
- [ ] Create directory and files
- [ ] Write SKILL.md with frontmatter
- [ ] Add README
- [ ] Validate structure
- [ ] Test with real scenarios

Core Principles

Concise: Only add context Claude doesn't have. Challenge every token.

Progressive disclosure: SKILL.md < 500 lines. Link to reference files for details.

Degrees of freedom:

• High (text): Multiple valid approaches
• Medium (templates): Preferred patterns
• Low (scripts): Exact operations

Workflow

1. Design Structure

Naming (gerund form):

• ✓ processing-pdfs, analyzing-data, testing-code
• ✗ helper, utils, names with "anthropic"/"claude"

Organization:

• SKILL.md: Overview, quick start, workflows
• reference/: Detailed docs, examples, advanced topics
• Multi-domain? Organize by domain (finance.md, sales.md)

See STRUCTURE.md

2. Create Files

Required:

Copy.claude/skills/skill-name/
├── SKILL.md          # YAML + instructions
├── README.md         # User docs
└── outputs/.gitkeep  # Test outputs

Optional:

• CLAUDE.md - Auto-loaded context
• reference/ - Progressive disclosure files
• tools/ - Python utilities (needs init.py)

3. Write SKILL.md

Frontmatter:

Copy---
name: skill-name
description: What it does AND when to use it. Include key terms and triggers.
---

Rules:

• name: 64 chars max, lowercase-with-hyphens, no "anthropic"/"claude"
• description: 1024 chars max, third person, include WHAT and WHEN

See FRONTMATTER.md

Body structure:

1. Quick start (most common use case)
2. Workflows with checklists
3. Common patterns
4. Reference links
5. Troubleshooting

See CONTENT.md

4. Add Documentation

README.md: Overview, installation, examples, links

CLAUDE.md (optional): Context for working in skill directory

5. Validate

Copy# Check frontmatter
head -n 1 SKILL.md | grep -q "^---$"

# Check size
wc -l SKILL.md  # Should be < 500

# Check required files
test -f SKILL.md README.md

Checklist:

• Valid YAML frontmatter
• Required files present
• References one level deep
• Forward slashes (not backslashes)
• SKILL.md under 500 lines
• Consistent terminology

6. Test

Create 3+ scenarios:

1. Does description trigger correctly?
2. Does Claude follow workflows?
3. Works with target models?

Observe:

• File read order
• Reference following
• Content usage
• Skill activation

Updating Skills

1. Use in real tasks
2. Observe behavior
3. Identify improvements
4. Make targeted changes
5. Test and iterate

Common fixes:

• Make critical info more prominent
• Use stronger language ("MUST" vs "always")
• Add missing workflows
• Split large files
• Improve description triggers

Common Patterns

Workflows with Checklists

CopyCopy this checklist:
\`\`\`
Progress:
- [ ] Step 1: Action
- [ ] Step 2: Action
\`\`\`

**Step 1**: Instructions

**Step 2**: Instructions

Validation Feedback Loop

Copy1. Create output
2. **Validate**: `python validate.py output.json`
3. If fails: fix and re-validate
4. **Only proceed when passes**

Progressive Disclosure

Copy## Quick Start
[20 lines here]

## Advanced
See [ADVANCED.md](reference/ADVANCED.md) for:
- Feature 1
- Feature 2

Conditional Workflow

Copy**Creating new?** → Follow creation workflow
**Editing existing?** → Follow editing workflow

Anti-Patterns

• Too many options (provide default with escape hatch)
• Punting to Claude (scripts should handle errors)
• Vague naming ("helper", "utils")
• Nested references (keep one level deep)
• Over-explaining (assume Claude is smart)
• Time-sensitive content (use "old patterns" section)
• Inconsistent terminology (choose one term)

Reference

Guides:

• STRUCTURE.md - Directory requirements
• FRONTMATTER.md - YAML rules
• CONTENT.md - Writing guidelines

Official:

• Claude Code Best Practices
• Agent Skills Best Practices

Troubleshooting

Skill not activating: Add specific triggers and key terms to description

Claude ignoring files: Make references more prominent, use descriptive names

Context overflow: Split SKILL.md into reference files

Inconsistent behavior: Add more structure, provide defaults

Scripts failing: Handle errors explicitly, helpful messages