skill-creator
Creates new Claude Code skills with proper structure and best practices. Use when user wants to create a skill, add a new command, scaffold a workflow, or asks "how do I make a skill".
When & Why to Use This Skill
The Skill Creator is a powerful meta-tool designed to automate the development of Claude Code skills. It ensures all custom skills adhere to official best practices, including optimized directory structures, proper frontmatter configuration, and efficient context management. By providing a standardized framework for scaffolding workflows and defining tool permissions, it enables developers to extend Claude's capabilities with domain-specific knowledge while maintaining high performance and reliability.
Use Cases
- Skill Scaffolding: Automatically generate the required directory structure (scripts/, references/, templates/) and SKILL.md frontmatter for new projects.
- Workflow Standardization: Implementing multi-phase execution gates and 'degrees of freedom' to ensure the agent follows specific organizational patterns or fragile operations safely.
- Context Optimization: Applying progressive disclosure techniques to split large documentation into reference files, preventing context window bloat.
- Meta-Development: Using the skill to add new commands, validate existing skill packages, or scaffold complex integrations like MCP builders.
| name | skill-creator |
|---|---|
| description | Creates new Claude Code skills with proper structure and best practices. Use when user wants to create a skill, add a new command, scaffold a workflow, or asks "how do I make a skill". |
| allowed-tools | Read Glob Grep AskUserQuestion |
Skill Creator
Creates Claude Code skills following official best practices.
Official spec: https://agentskills.io/specification (append .md for markdown)
Core Principles
Only Add What Claude Doesn't Have
Claude is already smart. Only include domain-specific context it lacks:
- API quirks, library gotchas, edge cases
- Your org's conventions and patterns
- Domain knowledge not in training data
Degrees of Freedom
Match instruction specificity to task fragility:
| Level | When | Example |
|---|---|---|
| High freedom | Multiple valid approaches | Code review (heuristics, not rigid steps) |
| Medium freedom | Preferred pattern exists | Reports (customizable scripts) |
| Low freedom | Fragile operations | DB migrations (exact commands, no deviation) |
Progressive Disclosure
Context loads in 3 levels:
- Metadata (~100 words) - name + description, always in context
- SKILL.md body (<5000 words) - loaded when skill triggers
- Resources (unlimited) - scripts/, references/, templates/ loaded as needed
Workflow
Step 1: Gather Requirements
Use AskUserQuestion to collect:
Skill name - lowercase, hyphens only, ≤64 chars
- Good:
pdf-processor,code-reviewer,deploy-helper - Bad:
PDF_Processor,my cool skill
- Good:
Description - what it does + when to use it
- Third person ("Processes...", "Generates...")
- Include ALL trigger keywords in description (primary discovery mechanism)
- Example: "Processes PDF files to extract text and tables. Use when working with PDFs, extracting document content, or converting PDF to markdown."
Allowed tools (optional) - restrict capabilities
- Space-delimited:
Read Glob Grep - YAML list (cleaner for many tools):
allowed-tools: - Read - Write - Bash(git:*) - Bash patterns:
Bash(git:*),Bash(git diff:*) - Unrestricted: omit field entirely
- Space-delimited:
Complexity - determines resource structure
- Simple: SKILL.md only
- Medium: + references/ for docs
- Complex: + scripts/ for automation, templates/ for output
Execution context (optional)
- Needs isolated context? →
context: fork - Specific agent type? →
agent: Explore/Plan
- Needs isolated context? →
Visibility (optional)
- Hide from slash commands? →
user-invocable: false
- Hide from slash commands? →
Hooks (optional) - lifecycle automation
- Validation after writes?
- Logging before tool use?
- See
references/hooks.mdfor patterns
Step 2: Validate Name
- Only lowercase letters, numbers, hyphens
- No leading/trailing hyphens
- ≤64 characters
- Not reserved: anthropic, claude, official
Step 3: Generate Skill
Default location: ~/.claude/skills/{skill-name}/
Create SKILL.md with:
---
name: {skill-name}
description: {description}
allowed-tools: {tools} # space-delimited or YAML list, omit if unrestricted
context: fork # optional: isolated execution
agent: {agent-type} # optional: Explore, Plan, etc.
user-invocable: true # optional: slash command visibility
hooks: {} # optional: see references/hooks.md
---
Generate skill body matching the degree of freedom needed. Use imperative/infinitive form for instructions.
Step 4: Post-Creation
✅ Skill created at: ~/.claude/skills/{skill-name}/
✅ Skill is immediately available (hot-reload enabled)
Step 5: Iterate (User)
Inform user of the iteration loop:
- Test skill on real tasks
- Note where Claude struggles or produces poor output
- Return to refine SKILL.md or add references/scripts
- Repeat until quality is consistent
Workflow Patterns
Sequential: Step 1 → 2 → 3 (most skills)
Conditional: Decision trees based on input type or user choice (see webapp-testing/)
Multi-phase: Plan → validate → execute → verify (for destructive operations)
Enforcing Phase Gates
Claude tends to rush ahead. To force hard stops between phases, use AskUserQuestion as a gate:
## Phase 1: Gather Input
**STOP. Use AskUserQuestion before proceeding.**
[phase instructions...]
**Do NOT proceed to Phase 2 until user responds.**
## Phase 2: Confirm Understanding
**STOP. Use AskUserQuestion to confirm before execution.**
[present what you understood, then ask confirmation...]
**Do NOT proceed to Phase 3 until user confirms.**
Key elements:
- Bold STOP directive at phase start
- Explicit instruction to use
AskUserQuestion - Clear "do NOT proceed until..." at phase end
Resource Types
| Type | Purpose | Context Loading |
|---|---|---|
scripts/ |
Executables for deterministic tasks | Run as black-box, don't read into context |
references/ |
Documentation, API specs | Loaded on-demand when needed |
templates/ |
Output scaffolds (HTML, PPTX) | Used for generation, not loaded into context |
assets/ |
Images, fonts, static files | Never loaded into context |
Anti-patterns: No README.md, CHANGELOG.md, INSTALLATION_GUIDE.md - only include what Claude needs to execute.
Isolated Execution
Use context: fork for skills that need isolated sub-agent context:
---
name: code-analyzer
context: fork
agent: Explore
---
When forked:
- Skill runs in separate context
- Parent conversation state preserved
- Results returned to main context
Skill Hooks
Skills can define lifecycle hooks scoped to their execution. See references/hooks.md for full documentation.
Quick example:
hooks:
PostToolUse:
- matcher: Write
hooks:
- type: command
command: "jq -r '.tool_input.file_path' | xargs -I{} ./validate.sh \"{}\""
Skill Spec (Condensed)
Required Frontmatter
name: lowercase, hyphens, ≤64 charsdescription: what + when (triggers), third person, ≤1024 chars
Optional Frontmatter
allowed-tools: pre-approved tools (space-delimited or YAML list)context:forkfor isolated sub-agent executionagent: agent type for execution (e.g.,Explore,Plan)hooks: skill-specific lifecycle hooks (seereferences/hooks.md)language: response language (e.g.,japanese)user-invocable:falseto hide from slash command menu (default:true)license: e.g., "MIT"
Body Guidelines
- Keep under 500 lines
- Use progressive disclosure: split to references/ when approaching limit
- No time-sensitive information
- Consistent terminology
Directory Structure
skill-name/
├── SKILL.md # Required entry point
├── scripts/ # Executables (run, don't read)
├── references/ # Docs loaded as needed
├── templates/ # Output scaffolds
└── assets/ # Static files (images, fonts)
Reference Files
- Keep one level deep from SKILL.md (no nested references)
- Files >100 lines should include a TOC at the top
Examples
Clone the official repo for real examples:
git clone https://github.com/anthropics/skills.git /tmp/claude-skills-examples
Example patterns:
| Skill | Shows |
|---|---|
mcp-builder/ |
reference/ + scripts/ |
algorithmic-art/ |
templates/ for HTML output |
docx/ |
scripts/ + scripts/templates/ + reference docs |
pptx/ |
Complex: scripts/, ooxml/, multiple reference docs |
skill-creator/ |
Meta: references/workflows.md, init/package scripts |
Tooling (in cloned repo):
skill-creator/scripts/init_skill.py- scaffolds new skill directoryskill-creator/scripts/package_skill.py- validates and packages skill
Best Practices Checklist
Before finalizing:
- Description is third person with ALL trigger keywords
- SKILL.md under 500 lines (split to references/ if needed)
- Degree of freedom matches task fragility
- No hardcoded paths or time-sensitive info
- Consistent terminology throughout
- Reference files >100 lines have TOC
- Scripts are black-box (documented inputs/outputs, not read into context)