Skiller

Generate Claude Code skills following Anthropic best practices.

Quick Start

code

Skill 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:

code

.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:

yaml

---
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:

•Quick start (most common use case)
•Workflows with checklists
•Common patterns
•Reference links
•Troubleshooting

See CONTENT.md

4. Add Documentation

README.md: Overview, installation, examples, links

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

5. Validate

bash

# 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:

6. Test

Create 3+ scenarios:

•Does description trigger correctly?
•Does Claude follow workflows?
•Works with target models?

Observe:

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

Updating Skills

•Use in real tasks
•Observe behavior
•Identify improvements
•Make targeted changes
•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

markdown

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

**Step 1**: Instructions

**Step 2**: Instructions

Validation Feedback Loop

markdown

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

Progressive Disclosure

markdown

## Quick Start
[20 lines here]

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

Conditional Workflow

markdown

**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:

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