Skill Manager
Comprehensive toolkit for managing Claude Code skills - create, validate, merge, convert, and deduplicate.
Topics
| Topic | Description | Guide |
|---|---|---|
| architecture | Multi-topic skill directory structure and templates | architecture.md |
| convert | Convert agent (.md) to skill structure | convert.md |
| dedup | Find and clean up duplicate skills between user and plugins | dedup.md |
| lint | Validate and fix SKILL.md frontmatter issues | lint.md |
| merge | Combine multiple related skills into one | merge.md |
| route | Topic description → scan existing skills → recommend placement | route.md |
| upgrade | Enhance existing skills: add topics, improve frontmatter, restructure scripts | upgrade.md |
| writer | Create new Agent Skills with proper structure and frontmatter | writer.md |
Quick Reference
Writer (Create Skills)
/skill-manager writer # Interactive skill creation
Key steps:
- Determine scope and location
- Create directory structure
- Write SKILL.md with proper frontmatter
- Add supporting files if needed
- Validate and test
Lint (Validate/Fix)
/skill-manager lint # Scan all skills for issues
/skill-manager lint --fix # Auto-fix common issues
Checks for:
- Missing
name:ordescription:fields - Invalid fields (
triggers:→ description,tools:→allowed-tools:) - Frontmatter position errors
Merge (Combine Skills)
/skill-manager merge skill-a skill-b # Merge two skills
Creates unified skill with topic files:
new-skill/
├── SKILL.md
├── topic-a.md
└── topic-b.md
Dedup (Find Duplicates)
/skill-manager dedup # Find user skills that duplicate plugins
Compares:
~/.claude/skills/(user skills)~/.claude/plugins/*/skills/(plugin skills)
Convert (Agent → Skill)
/skill-manager convert <agent-name> # Convert agent to skill
Converts:
- Agent frontmatter → Skill frontmatter
- External scripts →
scripts/folder - Removes
-resolver,-agentsuffixes
Upgrade (Enhance Skills)
/skill-manager upgrade <skill-name> # Enhance existing skill
/skill-manager upgrade # Enhance current skill
Improvement types:
- Add new topics
- Add trigger keywords to frontmatter description
- Restructure into scripts/ folder
Route (Topic Placement)
/skill-manager route "Helm chart lint" # Recommend where to place a topic
Verdict types:
- Add topic to existing skill → chains to
upgrade - Add section to existing topic → direct Edit
- Create new skill → chains to
writer
Architecture (Multi-Topic Structure)
For skills with multiple related topics:
skill-name/
├── SKILL.md # Entry point with frontmatter
├── topic1.md # Topic content (no frontmatter)
└── topic2.md
Skill Locations
| Location | Purpose |
|---|---|
~/.claude/skills/ |
Personal skills |
.claude/skills/ |
Project skills (committed to git) |
~/.claude/plugins/*/skills/ |
Plugin skills |
Frontmatter Reference
---
name: skill-name # Required: lowercase, hyphens, max 64 chars
description: ... # Required: what + when + triggers, max 1024 chars
allowed-tools: [...] # Optional: restrict tool access
model: claude-sonnet-4-... # Optional: specific model
context: fork # Optional: context handling
depends-on: [skill-a] # Optional: dependent skills
---
Safe Delete (Required Rule)
When removing or replacing skills under .claude, always move to a root .bak folder:
mkdir -p ~/.claude/.bak
mv ~/.claude/skills/{old-skill} ~/.claude/.bak/
Never add .bak suffix in the same directory:
# Bad — Claude Code loads .bak folders as skills
mv ~/.claude/skills/old-skill ~/.claude/skills/old-skill.bak
# Good
mv ~/.claude/skills/old-skill ~/.claude/.bak/
Add timestamp on name conflicts:
mv ~/.claude/skills/{old-skill} ~/.claude/.bak/{old-skill}_$(date +%Y%m%d_%H%M%S)
Notes
- Always backup before merging:
~/.claude/.bak/(NOTskills/.bak/) - Restart Claude Code after skill changes
- Use
claude --debugfor troubleshooting