majiayu000 Skill Creator
Create high-quality skills that extend Claude's capabilities using best practices for conciseness, progressive disclosure, and testability.
When to Use This Skill
Invoke this skill when:
- Creating a new skill from scratch
- Improving an existing skill's structure or content
- Reviewing a skill for best practices compliance
- Troubleshooting skill performance issues
- Planning skill architecture before implementation
Quick Start Workflow
Follow this checklist for creating a new skill:
1. Understand the Need
- Document 2-3 concrete usage examples of the skill in action
- Identify what Claude needs to know vs. what can be external references
- Determine if scripts, templates, or other assets are needed
- Assess task fragility (high freedom vs. low freedom needed)
2. Plan the Structure
- Choose skill name (gerund form:
doing-something, max 64 chars, lowercase/hyphens) - Write description (what it does + when to use, max 1024 chars)
- List required reference files for detailed content
- Identify reusable assets (templates, boilerplate, etc.)
- Plan any utility scripts for deterministic operations
3. Initialize Skill Structure
Use the init_skill.py script to scaffold your new skill:
cd .claude/skills/skill-creator/scripts
./init_skill.py your-skill-name --path /path/to/skills
This creates:
your-skill-name/
├── SKILL.md # Template with TODOs and structural guidance
├── references/ # Example reference documentation
│ └── api_reference.md
├── assets/ # Example asset placeholder
│ └── example_asset.txt
└── scripts/ # Example script
└── example.py
The script provides a comprehensive template with:
- Structural pattern guidance (workflow-based, task-based, reference-based, capabilities-based)
- Example files showing best practices
- TODOs marking sections to customize
- Resource organization examples
4. Customize SKILL.md
The generated SKILL.md includes inline guidance:
- Complete the description in YAML frontmatter (what + when to use)
- Choose appropriate structural pattern for your skill (delete guidance section when done)
- Replace placeholder sections with actual content
- Add workflows, examples, and references as needed
- Delete example files in scripts/, references/, and assets/ if not needed
5. Apply Best Practices
- Keep SKILL.md under 500 lines (move details to references)
- Use imperative language ("Do this" not "You should do")
- Include validation steps before making changes
- Provide both flexible guidance and strict templates where appropriate
- Add clear success criteria for each workflow step
6. Validate and Test
Run the validation script to check your skill structure:
cd .claude/skills/skill-creator/scripts
./quick_validate.py /path/to/your-skill-name
The validator checks:
- SKILL.md exists and has valid YAML frontmatter
- Required fields (name, description) are present
- Name follows hyphen-case convention (lowercase, hyphens, digits only)
- Description doesn't contain invalid characters
Then test with real usage:
- Create test scenarios before extensive documentation
- Test with different model sizes if relevant (Opus vs. Haiku)
- Verify progressive disclosure works (references load only when needed)
- Gather real-world usage feedback
7. Package for Distribution (Optional)
To create a distributable zip file:
cd .claude/skills/skill-creator/scripts
./package_skill.py /path/to/your-skill-name [output-directory]
This will:
- Validate the skill structure
- Create a compressed zip file
- Include all skill files (SKILL.md, references, assets, scripts)
The packaged skill can be shared with others or backed up.
Best Practices Quick Reference
Key principles: conciseness, progressive disclosure, and matching specificity to task fragility.
For comprehensive guidance, see [[references/best-practices.md]].
Common Patterns
Plan-Validate-Execute Pattern
1. Analyze requirements and create a plan
2. Show plan to user for validation
3. Execute after approval
4. Verify results and report completion
Progressive Reference Loading
## Overview
Brief summary here.
## Detailed Guide
For full implementation details, see [[references/implementation.md]].
## Examples
Review [[references/examples.md]] for common patterns.
Script Integration
## Running Analysis
Execute the analysis script:
```bash
./scripts/analyze.sh input.txt
Review output, then proceed with recommended changes.
## Reference Files
Load these on-demand for detailed guidance:
- [[references/best-practices.md]] - Comprehensive best practices guide
- [[references/structure-guide.md]] - Detailed structure and architecture patterns
- [[references/examples.md]] - Real-world skill examples and templates
## Anti-Patterns to Avoid
❌ **Don't**: Include extensive documentation in SKILL.md
✅ **Do**: Move details to reference files
❌ **Don't**: Use passive voice or vague language
✅ **Do**: Use imperative, actionable instructions
❌ **Don't**: Create deeply nested file references
✅ **Do**: Keep all references one level deep from SKILL.md
❌ **Don't**: Generate code for deterministic operations
✅ **Do**: Provide pre-made scripts for consistency
❌ **Don't**: Build skills for anticipated problems
✅ **Do**: Create test scenarios first, solve real problems
## Skill Quality Checklist
Before finalizing a skill, verify:
- [ ] Name follows gerund form and naming conventions
- [ ] Description explains both what and when (<1024 chars)
- [ ] SKILL.md is under 500 lines
- [ ] Detailed content moved to reference files
- [ ] Workflows include validation steps
- [ ] Clear success criteria provided
- [ ] Templates provided for format-critical outputs
- [ ] Scripts used for deterministic operations
- [ ] Tested with concrete examples
- [ ] Progressive disclosure working correctly
## Getting Help
For questions about skill architecture or best practices:
1. Use `./scripts/init_skill.py` to scaffold a new skill with templates
2. Review [[references/best-practices.md]] for comprehensive guidance
3. Check [[references/examples.md]] for real-world patterns
4. Run `./scripts/quick_validate.py` to validate your skill structure
---
*This skill helps you create skills that are concise, actionable, and optimized for Claude's context window through progressive disclosure.*