6# Skill Creator
7
8An interactive guide for creating, validating, and packaging new Claude skills. This skill helps you build high-quality skills that extend Claude's capabilities with specialized knowledge, workflows, or tool integrations.
9
10## What Are Skills?
11
12Skills are modular capabilities that extend Claude's functionality. Each skill packages:
13- **Instructions**: Step-by-step guidance for completing specific tasks
14- **Metadata**: Name and description for automatic discovery
15- **Resources**: Optional scripts, templates, and reference documentation
16
17Skills use progressive disclosure - only loading what's needed when needed - to minimize token usage while maximizing capability.
18
19## When to Use This Skill
20
21Use the skill-creator when you need to:
22- **Create a new skill** from scratch
23- **Validate an existing skill** against Claude's requirements
24- **Package a skill** for distribution
25- **Update a skill** to meet current standards
26- **Learn** skill best practices and requirements
27
28## Skill Creation Workflow
29
30### Step 1: Understand the Need
31
32Ask clarifying questions to understand:
33
341. **Purpose**: What task or domain will this skill address?
352. **Scope**: Is it simple (just instructions) or complex (with scripts/references)?
363. **Platform**: Which Claude surfaces should it target? (Claude.ai, API, Claude Code, or all)
374. **Automation**: Should it be automatically invoked or user-triggered?
38
39Example questions:
40- "What specific problem does this skill solve?"
41- "Will the skill need helper scripts or just provide guidance?"
42- "Should Claude use this skill proactively when users mention [topic]?"
43- "Does the skill need platform-specific features (like network access)?"
44
45### Step 2: Design the Skill
46
47Based on the requirements, plan:
48
49**Directory Structure Options:**
50
51**Option A: Simple Skill (Instructions only)**
52```
53skill-name/
54└── SKILL.md
55```
56
57**Option B: Skill with Scripts**
58```
59skill-name/
60├── SKILL.md
61└── scripts/
62 ├── __init__.py
63 ├── helper1.py
64 └── helper2.py
65```
66
67**Option C: Complex Skill (Full featured)**
68```
69skill-name/
70├── SKILL.md
71├── scripts/
72│ ├── __init__.py
73│ └── utilities.py
74└── references/
75 ├── specification.md
76 └── examples.md
77```
78
79**Naming Convention:**
80- Lowercase letters, numbers, and hyphens only
81- Maximum 64 characters
82- Cannot contain "anthropic" or "claude"
83- Descriptive and concise (e.g., git-helper, api-tester, doc-writer)
84
85### Step 3: Write SKILL.md
86
87Every skill must have a SKILL.md file with this structure:
88
89```markdown
90---
91name: skill-name
92description: Brief description of what this skill does and when to use it (max 1024 chars)
93---
94
95# Skill Title
96
97## Overview
98What the skill does and why it's useful.
99
100## When to Use This Skill
101Specific scenarios where this skill should be invoked.
102
103## Instructions
104
105### Step 1: [First Action]
106Detailed guidance for the first step...
107
108### Step 2: [Second Action]
109Detailed guidance for the second step...
110
111### Step N: [Final Action]
112Detailed guidance for completion...
113
114## Best Practices
115Tips for optimal results.
116
117## Common Issues
118Troubleshooting guidance.
119
120## Examples
121Concrete examples of the skill in action.
122```
123
124**Critical Requirements:**
125
126✅ **Required YAML Frontmatter**
127```yaml
128---
129name: skill-name # lowercase, hyphens, max 64 chars
130description: What it does and when to use it # max 1024 chars
131---
132```
133
134✅ **Description Best Practices**
135- Explain WHAT the skill does
136- Explain WHEN to use it
137- Use action-oriented language (e.g., "Use when...", "MUST be used for...")
138- Be specific about capabilities
139- Maximum 1024 characters
140- No XML tags
141
142✅ **Content Organization**
143- Clear hierarchy with headings
144- Step-by-step instructions
145- Concrete examples
146- Platform-specific guidance if needed
147
148### Step 4: Add Supporting Resources (Optional)
149
150**Scripts (Python recommended):**
151- Use for deterministic operations
152- Validate, transform, or package data
153- Generate templates or boilerplate
154- Follow security best practices (see references/skill-specification.md)
155
156Example script structure:
157```python
158#!/usr/bin/env python3
159"""
160Brief description of what this script does.
161"""
162import argparse
163from pathlib import Path
164from typing import Tuple
165
166def main() -> int:
167 """Main entry point."""
168 parser = argparse.ArgumentParser(description="...")
169 # ... argument parsing ...
170
171 try:
172 result = do_work(args)
173 print(f"Success: {result}")
174 return 0
175 except Exception as e:
176 print(f"Error: {e}", file=sys.stderr)
177 return 1
178
179if __name__ == "__main__":
180 sys.exit(main())
181```
182
183**Reference Documentation:**
184- Technical specifications
185- API documentation
186- Database schemas
187- Best practices guides
188- Example templates
189
190References are loaded on-demand, so include comprehensive details without worrying about token cost.
191
192### Step 5: Validate the Skill
193
194Use the validation script to ensure compliance:
195
196```bash
197python .claude-plugin/scripts/validate_skill.py path/to/skill/
198```
199
200The validator checks:
201- ✅ YAML frontmatter format
202- ✅ Required fields (name, description)
203- ✅ Naming conventions
204- ✅ Description length and format
205- ✅ No XML tags or restricted terms
206- ✅ File structure
207
208Fix any errors before proceeding.
209
210### Step 6: Test the Skill
211
2121. **Place the skill** in the appropriate location:
213 - Project-level: .claude/skills/skill-name/
214 - User-level: ~/.claude/agents/skill-name.md (for single-file skills)
215 - Plugin: .claude-plugin/ (for distribution)
216
2172. **Invoke the skill** and verify:
218 - Instructions are clear and actionable
219 - Scripts execute correctly
220 - References load when needed
221 - Platform-specific features work as expected
222
2233. **Iterate** based on results:
224 - Clarify ambiguous instructions
225 - Fix script bugs
226 - Add missing examples
227 - Improve error handling
228
229### Step 7: Package for Distribution (Optional)
230
231To share the skill:
232
233```bash
234python .claude-plugin/scripts/package_skill.py path/to/skill/ --output skill-name.zip
235```
236
237This creates a distributable package including:
238- SKILL.md
239- All scripts and references
240- Metadata/manifest
241- Installation instructions
242
243## Platform-Specific Considerations
244
245### Claude.ai
246- **Scope**: User-specific (not shared across workspace)
247- **Network**: Varies by user/admin settings
248- **Distribution**: Upload through Skills UI
249- **Best for**: Personal productivity, individual workflows
250
251### Claude API
252- **Scope**: Workspace-wide accessible
253- **Network**: No access by default
254- **Dependencies**: Pre-configured only, no dynamic installation
255- **Best for**: Programmatic workflows, enterprise deployments
256
257### Claude Code
258- **Scope**: Project-level (.claude/skills/) or user-level (~/.claude/agents/)
259- **Network**: Full access available
260- **Dependencies**: Can install packages as needed
261- **Best for**: Development workflows, technical tasks
262
263**Include platform notes when relevant:**
264```markdown
265## Platform Notes
266
267### Claude Code
268This skill requires network access to fetch API data. It works best in Claude Code where network access is available by default.
269
270### Claude API
271Note: This skill requires pre-configured API keys via environment variables.
272```
273
274## Best Practices
275
276### Token Efficiency
277- Keep SKILL.md focused on essential instructions
278- Move detailed specs to reference files
279- Use progressive disclosure (load references only when needed)
280- Aim for 30-50 tokens when skill is inactive (just frontmatter)
281
282### Discoverability
283- Write descriptions that clearly explain when to use the skill
284- Use action-oriented language: "Use PROACTIVELY when..."
285- Include relevant keywords in the description
286- Be specific about capabilities
287
288### Quality
289- Test thoroughly before distributing
290- Include concrete examples
291- Provide troubleshooting guidance
292- Handle errors gracefully
293- Validate all user inputs
294
295### Security
296- Never execute arbitrary code (no eval/exec)
297- Validate file paths (prevent traversal attacks)
298- Sanitize user inputs
299- Use allowlists over denylists
300- Follow principle of least privilege
301
302### Maintainability
303- Use clear, descriptive names
304- Document all functions and scripts
305- Keep skills focused on a single purpose
306- Version your skills for tracking changes
307- Write clear error messages
308
309## Validation Rules Reference
310
311Load the complete specification when needed:
312```
313Read .claude-plugin/references/skill-specification.md
314```
315
316Key rules:
317- **Name**: lowercase, hyphens, max 64 chars, no "anthropic"/"claude"
318- **Description**: non-empty, max 1024 chars, no XML tags
319- **Frontmatter**: Valid YAML between --- delimiters
320- **Files**: UTF-8 encoding, reasonable sizes
321- **Scripts**: Executable, proper permissions, type-safe
322
323## Example: Creating a Simple Skill
324
325**User Request**: "Create a skill to help format commit messages"
326
327**Skill Creator Response**:
328
3291. **Clarify requirements**:
330 - "Should it validate existing commits or generate new ones?"
331 - "Do you want specific commit types enforced (feat, fix, docs)?"
332 - "Should it integrate with git commands or just provide guidance?"
333
3342. **After getting answers, create the skill**:
335
336```markdown
337---
338name: commit-formatter
339description: Format git commit messages according to Conventional Commits specification. Use when writing commit messages or validating commit history.
340---
341
342# Commit Formatter
343
344Helps create well-formatted git commit messages following Conventional Commits.
345
346## When to Use This Skill
347- Writing new commit messages
348- Validating existing commits
349- Learning commit message best practices
350
351## Instructions
352
353### Step 1: Determine Commit Type
354Choose the appropriate type:
355- **feat**: New feature
356- **fix**: Bug fix
357- **docs**: Documentation only
358- **style**: Code style (formatting, missing semicolons)
359- **refactor**: Code change that neither fixes a bug nor adds a feature
360- **perf**: Performance improvement
361- **test**: Adding or updating tests
362- **chore**: Maintenance tasks
363
364### Step 2: Write Subject Line
365Format: <type>(<scope>): <subject>
366- Scope is optional but recommended (e.g., api, ui, auth)
367- Subject is lowercase, no period at end
368- Keep under 50 characters
369
370### Step 3: Add Body (Optional)
371- Wrap at 72 characters
372- Explain what and why, not how
373- Separate from subject with blank line
374
375### Step 4: Add Footer (Optional)
376- Breaking changes: BREAKING CHANGE: <description>
377- Issue references: Closes #123
378
379## Examples
380
381**Simple commit**:
382```
383feat(auth): add OAuth2 login support
384```
385
386**With body**:
387```
388fix(api): handle null response from user service
389
390The user service occasionally returns null when the user
391is not found. This commit adds proper null checking and
392returns a 404 status code.
393```
394
395**Breaking change**:
396```
397feat(api): redesign authentication endpoints
398
399BREAKING CHANGE: The /auth endpoint now requires POST instead
400of GET. Update all clients to use POST with JSON body.
401
402Closes #456
403```
404```
405
4063. **Validate the skill**:
407```bash
408python .claude-plugin/scripts/validate_skill.py .claude/skills/commit-formatter/
409```
410
4114. **Test it**:
412 - Ask Claude to help format a commit
413 - Verify the guidance is clear and actionable
414 - Check examples are helpful
415
416## Troubleshooting
417
418### Skill Not Being Invoked Automatically
419
420**Problem**: Claude doesn't use the skill even when relevant.
421
422**Solutions**:
423- Improve the description with clearer trigger phrases
424- Add "Use PROACTIVELY when..." to the description
425- Mention the skill explicitly: "Use the [skill-name] skill to..."
426
427### Validation Errors
428
429**Problem**: Validator reports errors.
430
431**Solutions**:
432- Check YAML formatting (use --- delimiters)
433- Verify name follows conventions (lowercase, hyphens only)
434- Ensure description is under 1024 characters
435- Remove any XML tags from text
436- Check file encoding is UTF-8
437
438### Scripts Not Executing
439
440**Problem**: Python scripts fail or aren't found.
441
442**Solutions**:
443- Verify script has execute permissions: chmod +x script.py
444- Check shebang line: #!/usr/bin/env python3
445- Ensure dependencies are installed
446- Test script independently before integrating
447- Check file paths are correct (use Path from pathlib)
448
449### Cross-Platform Issues
450
451**Problem**: Skill works on one platform but not another.
452
453**Solutions**:
454- Check platform constraints (network access, dependencies)
455- Use pathlib for file paths (not os.path)
456- Avoid platform-specific assumptions
457- Test on all target platforms
458- Add platform-specific guidance in SKILL.md
459
460## Getting Help
461
462For detailed technical specifications:
463```
464Read .claude-plugin/references/skill-specification.md
465```
466
467For platform-specific guidance:
468```
469Read .claude-plugin/references/platform-differences.md
470```
471
472For more examples:
473```
474Read .claude-plugin/references/skill-examples.md
475```
476
477## Creating the Skill Automatically
478
479When you're ready, I'll:
480
4811. **Create the directory structure** at the specified location
4822. **Generate SKILL.md** with proper frontmatter and content
4833. **Add scripts** if requested (using the python-dev agent for quality)
4844. **Create reference files** if needed
4855. **Validate** the entire skill
4866. **Package** if for distribution if requested
487
488Just tell me what skill you want to create, and I'll guide you through the process!
489