tools-only Skill Design Guide
Overview
This Skill provides methods for designing and implementing effective Skills. Skills are modular packages that extend Claude's capabilities for specific domains or tasks.
About Skills
Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks.
What Skills provide:
- Specialized workflows - Multi-step procedures for specific domains
- Tool integrations - Guides for specific file formats or API operations
- Domain expertise - Company-specific knowledge, schemas, business logic
- Bundled resources - Scripts, reference documents, assets for complex and repetitive tasks
Core Principle: Concise is Key
Context window is a public good. Only add context Claude doesn't already know.
- "Does Claude really need this explanation?"
- "Does this paragraph justify its token cost?"
Prefer concise examples over verbose explanations.
Skill Creation Process (6 Steps)
Step 1: Understand with Concrete Examples
Collect and understand concrete examples of how the Skill will be used.
Step 2: Plan Reusable Content
Identify reusable resources that can be separated into scripts, references, assets.
Step 3: Initialize Skill
Create Skill directory structure. (Recommend using init_skill.py script)
Step 4: Write Skill
Implement SKILL.md and bundled resources. → See frontmatter-guide.md for frontmatter rules
Step 5: Package Skill
Package into distributable .skill file. (Use package_skill.py)
Step 6: Iterate with Real Usage
Improve based on actual usage.
SKILL.md Structure
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter (name, description)
│ └── Markdown instructions
└── Bundled Resources (optional)
├── scripts/ - Executable code
├── references/ - Documents loaded when needed
└── assets/ - Files used in output
Frontmatter Essentials
| Field | Rules |
|---|---|
name |
lowercase + hyphens, 1-64 chars, matches directory name |
description |
1-1024 chars, includes functionality + trigger conditions |
Important: Include all "when to use" info in description. "When to Use" sections in Body don't help Claude since they're only loaded after triggering.
→ See frontmatter-guide.md for detailed rules
Progressive Disclosure (3-Level Loading)
- Metadata (~100 words) - Always in context
- SKILL.md body (<500 lines) - When Skill triggers
- Bundled resources - Loaded as needed
3 Patterns
| Pattern | When to Use |
|---|---|
| Pattern 1: High-level Guide | When there are multiple related features |
| Pattern 2: Domain-specific | When there are distinct sub-domains |
| Pattern 3: Conditional Details | When advanced features are occasionally needed |
→ See progressive-disclosure.md for patterns and examples
Bundled Resources
| Directory | Purpose | Example |
|---|---|---|
scripts/ |
Code requiring deterministic reliability | rotate_pdf.py |
references/ |
Documents loaded when needed | schema.md |
assets/ |
Files used in output | template.html |
→ See bundled-resources.md for detailed guide
Decision Tree: Content Placement
Content Type → Placement
├─ Trigger conditions → description (frontmatter)
├─ Core workflow → SKILL.md body
├─ Detailed reference → references/
├─ Repetitive code → scripts/
└─ Output templates → assets/
Design Principles
- Conciseness: SKILL.md core only, under 500 lines
- Progressive Disclosure: Utilize 3-level loading
- Clear Triggers: Specify usage timing in description
- 1 Level Depth: References link directly from SKILL.md
Validation
→ See validation-checklist.md for complete checklist
Quick Check:
-
name: lowercase + hyphens, 1-64 chars -
description: functionality + trigger conditions, 1-1024 chars - SKILL.md: under 500 lines
- No unnecessary files (README.md, CHANGELOG.md, etc.)
Common Mistakes
- ❌ Missing trigger conditions in description
- ❌ Including "When to Use" section in Body
- ❌ SKILL.md over 500 lines
- ❌ References nested 2+ levels deep
- ❌ Information duplicated between SKILL.md and references