| name | updating-skills |
| description | Guides holistic skill updates through refactoring rather than patching, maintaining quality and conciseness. Use when adding features to existing skills, fixing skill issues, restructuring for clarity, or incorporating user feedback. |
Updating Skills
Core Principle
Refactor, don't patch. When updating a skill, review and restructure the entire skill to maintain quality and
coherence.
Update Workflow
Follow this process for every skill update:
Update Checklist:
- [ ] Step 1: Assess current state (document issues)
- [ ] Step 2: Gather new requirements
- [ ] Step 3: Plan new information architecture
- [ ] Step 4: Refactor skill holistically
- [ ] Step 5: Validate conciseness (<200 lines main)
- [ ] Step 6: Test updated skill
- [ ] Step 7: Document changes made
Assessment Phase
Before making changes, evaluate:
- Current size: Is SKILL.md already too large?
- Structure: Is progressive disclosure working?
- Redundancy: Any duplicate information?
- Clarity: Are workflows clear?
- Effectiveness: Does it trigger appropriately?
Refactoring Patterns
Pattern 1: Information Overload
Symptom: SKILL.md > 300 lines
Solution:
- Extract details to reference files
- Keep only essential workflows
- Use links for advanced topics
Pattern 2: Feature Addition
Wrong approach: Append new section
Right approach:
- Reconsider entire structure
- Integrate feature naturally
- Update description to include trigger
Pattern 3: Fixing Ineffectiveness
Process:
- Test current skill behavior
- Identify why it fails
- Restructure for clarity
- Retest with fresh Claude
Quality Checklist
After updates, verify:
Common Update Mistakes
- Just appending content - Integrate properly instead
- Ignoring line limits - Extract to references
- Forgetting description - Update if scope changes
- Creating redundancy - Check for existing similar content
- Breaking structure - Maintain consistent organization
For detailed strategies:
Key Questions
Before committing updates, ask:
- Is this the right place for this information?
- Can existing content be consolidated?
- Does this maintain or improve clarity?
- Will this trigger when needed?
- Have I removed outdated information?