Create effective Claude Code SKILL.md files following Anthropic's official patterns. Use when writing new skills, improving existing skills, or learning skill best practices.
Skill Creator
Create skills that extend Claude's capabilities with specialized knowledge and workflows.
Core Principles
- Concise is key - Context window is shared; only add what Claude doesn't know
- < 200 lines - Split to
references/if approaching limit - Description triggers - Include "Use when..." in YAML description, not body
- Scripts for precision - Create
.pyscripts for tasks requiring exact format or validation; for templates, prefer Python scripts over raw markdown to ensure stable formatting
Skill Structure
.claude/
└── skills/
└── skill-name/
├── SKILL.md # Required: instructions (<200 lines)
├── scripts/ # Optional: executable code
├── references/ # Optional: docs loaded on-demand
└── assets/ # Optional: templates, images
Creation Process
1. Initialize
Run the init script to create proper structure:
python3 scripts/init_skill.py <skill-name>
Options:
--path,-p: Output directory (default:.claude/skills)
2. Write SKILL.md
Frontmatter (required):
---
name: my-skill
description: [What it does]. Use when [specific triggers].
---
Body: Instructions only. Keep lean—move details to references/.
3. Validate
python3 scripts/validate_skill.py <path/to/skill>
4. Test
Restart Claude Code, trigger naturally (don't mention skill name).
Degrees of Freedom
| Level | When | Format |
|---|---|---|
| High | Multiple valid approaches | Text guidance |
| Medium | Preferred pattern exists | Pseudocode |
| Low | Fragile/critical operations | Specific scripts |
Progressive Disclosure
Split content when SKILL.md grows:
## Quick start
[Essential usage]
## Advanced
- **Forms**: See [forms.md](references/forms.md)
- **API**: See [api.md](references/api.md)
Claude loads references only when needed.
What NOT to Include
- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
- Explanations Claude already knows
- "When to use" sections in body (put in description)
- Shared conventions - if multiple skills use the same convention, extract to
.claude/rules/
Relationship with Rules
Rules = conventions shared across skills.
If you find yourself repeating the same guideline in multiple skills:
- Extract to
.claude/rules/usingwrite-rulesskill - Skills automatically inherit rules (auto-injected)
- Keep skill-specific details in the skill
References
- spec.md - YAML frontmatter specification
- patterns.md - Common skill patterns
- examples.md - Before/after examples
You Might Also Like
Related Skills
coding-agent
Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
openclaw
add-uint-support
Add unsigned integer (uint) type support to PyTorch operators by updating AT_DISPATCH macros. Use when adding support for uint16, uint32, uint64 types to operators, kernels, or when user mentions enabling unsigned types, barebones unsigned types, or uint support.
pytorchat-dispatch-v2
Convert PyTorch AT_DISPATCH macros to AT_DISPATCH_V2 format in ATen C++ code. Use when porting AT_DISPATCH_ALL_TYPES_AND*, AT_DISPATCH_FLOATING_TYPES*, or other dispatch macros to the new v2 API. For ATen kernel files, CUDA kernels, and native operator implementations.
pytorchskill-writer
Guide users through creating Agent Skills for Claude Code. Use when the user wants to create, write, author, or design a new Skill, or needs help with SKILL.md files, frontmatter, or skill structure.
pytorch
implementing-jsc-classes-cpp
Implements JavaScript classes in C++ using JavaScriptCore. Use when creating new JS classes with C++ bindings, prototypes, or constructors.
oven-shimplementing-jsc-classes-zig
Creates JavaScript classes using Bun's Zig bindings generator (.classes.ts). Use when implementing new JS APIs in Zig with JSC integration.
oven-sh