Use when removing skills from the codebase - guides through reference discovery, impact analysis, user confirmation, directory removal, and cleanup verification to ensure no orphaned references remain
Instruction-driven skill deletion workflow with impact analysis and verification.
You MUST use TodoWrite to track phases. Deletion is irreversible and requires careful validation.
Use this skill when:
NOT for:
renaming-skills (LIBRARY) skill)migrating-skills (LIBRARY) skill)| Phase | Purpose | Time | Checkpoint |
|---|---|---|---|
| 1. Validate | Navigate to root, verify skill exists | 1 min |
| Skill found |
| 2. Discover | Find all references | 3 min | References documented |
| 3. Analyze | Show impact to user | 2 min | Impact clear |
| 4. Confirm | User approval before deletion | 1 min | Confirmed |
| 5. Remove | Delete skill directory | 1 min | Directory removed |
| 6. Gateway | Sync gateway routing tables | 3 min | Gateways synced |
| 7. Cleanup | Remove non-gateway references | 5 min | References cleaned |
| 8. Verify | Ensure no orphaned references | 2 min | Clean verified |
Total: 18 minutes
Execute BEFORE any delete operation:
ROOT="$(git rev-parse --show-superproject-working-tree --show-toplevel | head -1)" && cd "$ROOT"
⚠️ If skill file not found: You are in the wrong directory. Navigate to repo root first. The file exists, you're just looking in the wrong place.
Cannot proceed without navigating to repo root ✅
# Check core skills
find .claude/skills -name "{skill-name}" -type d
# Check library skills
find .claude/skill-library -name "{skill-name}" -type d
If not found: Error - skill doesn't exist. Confirm spelling with user.
If found: Record the full path for deletion.
Check that the directory contains SKILL.md:
ls {skill-path}/SKILL.md
If SKILL.md missing: This isn't a valid skill directory. Investigate before deletion.
Find ALL references across the codebase. Missing references = broken system.
# Search all gateway skills
grep -r "{skill-name}" .claude/skills/gateway-*/SKILL.md
Gateways to check:
gateway-frontendgateway-backendgateway-testinggateway-securitygateway-integrationsgateway-mcp-toolsgateway-capabilitiesgateway-claude# Search all command files
grep -r "{skill-name}" .claude/commands/
Commands often reference skills in routing tables.
# Search other skills (core)
grep -r "{skill-name}" .claude/skills/*/SKILL.md
# Search other skills (library)
grep -r "{skill-name}" .claude/skill-library/*/SKILL.md
Skills reference related skills in:
# Search for skill name in descriptions (case-insensitive)
grep -ri "{skill-name}" .claude/skills/*/SKILL.md | grep -i "description"
grep -ri "{skill-name}" .claude/skill-library/*/*/SKILL.md | grep -i "description"
Descriptions sometimes mention related skills.
Create a structured list:
## References Found
### Gateways
- `.claude/skills/gateway-testing/SKILL.md:45` - Routes to skill
- `.claude/skills/gateway-frontend/SKILL.md:78` - Mentions in description
### Commands
- `.claude/commands/skill-manager.md:23` - Routing table
### Skills
- `.claude/skill-library/testing/test-infrastructure-discovery/SKILL.md:219` - Integration section
- `.claude/skills/developing-with-tdd/SKILL.md:156` - Related skills
### Total References: 4
Use AskUserQuestion to show impact:
Question: I found {X} references to {skill-name}. Deleting this skill will break:
**Gateways:**
- gateway-testing (routing table)
**Commands:**
- skill-manager (routing)
**Skills:**
- test-infrastructure-discovery (integration section)
- developing-with-tdd (related skills)
**Impact:**
- Gateway routes will fail
- skill-manager command will have broken reference
- 2 skills will have outdated recommendations
Do you want to proceed with deletion?
Options:
- Yes - Delete skill and clean up all references
- No - Cancel deletion
- Show me the references first
Read and display each reference context:
# For each reference, show 5 lines of context
grep -A 5 -B 5 "{skill-name}" {file-path}
Then re-ask the confirmation question.
Cannot proceed without explicit user confirmation ✅
If user confirms deletion:
If user cancels:
Before deletion, verify path contains .claude/skill:
echo "{skill-path}" | grep -q ".claude/skill"
if [ $? -ne 0 ]; then
echo "❌ SAFETY CHECK FAILED: Path doesn't contain .claude/skill"
exit 1
fi
rm -rf {skill-path}
ls {skill-path} 2>&1
# Should return "No such file or directory"
If directory still exists: Error - deletion failed. Report to user.
Automatically detect and remove broken gateway paths using syncing-gateways (LIBRARY) skill.
This phase mirrors the pattern from migrating-skills (LIBRARY) Step 4: after directory deletion, automatically sync gateway routing tables to remove broken references.
# Read the syncing-gateways (LIBRARY) skill to understand the workflow
# Located at: .claude/skill-library/claude/skill-management/syncing-gateways/SKILL.md
Use Read tool to load the syncing-gateways (LIBRARY) skill.
Follow the syncing-gateways (LIBRARY) workflow to:
Why automatic? Gateways follow predictable routing table patterns. The syncing-gateways (LIBRARY) skill can detect and fix broken references automatically.
After running syncing-gateways (LIBRARY), verify no gateway references remain:
grep -r "{skill-name}" .claude/skills/gateway-*/SKILL.md
# Should return no results
If references found: The syncing-gateways (LIBRARY) skill should have removed them. If not, investigate and clean manually.
For each non-gateway reference found in Phase 2, remove or update it.
Note: Gateway references should already be cleaned by Phase 6 (Gateway Sync). This phase handles commands and skills only.
If skill is in routing table: Remove routing section using Edit tool.
Example:
# Before
| create | creating-skills |
| delete | deleting-skills |
| update | updating-skills |
# After
| create | creating-skills |
| update | updating-skills |
For "Related Skills" sections: Remove the skill from the list.
For "Integration" sections: Remove or update the integration note.
Example:
# Before
**Related Skills:**
- creating-skills
- deleted-skill-name
- updating-skills
# After
**Related Skills:**
- creating-skills
- updating-skills
Use TodoWrite to track each reference cleanup:
- Clean gateway-testing reference
- Clean skill-manager command reference
- Clean test-infrastructure-discovery reference
- Clean developing-with-tdd reference
Mark each complete as you clean it up.
Run the same searches from Phase 2 to verify no references remain:
# Should return no results
grep -r "{skill-name}" .claude/skills/gateway-*/SKILL.md
grep -r "{skill-name}" .claude/commands/
grep -r "{skill-name}" .claude/skills/*/SKILL.md
grep -r "{skill-name}" .claude/skill-library/*/*/SKILL.md
Search for partial skill name matches (in case of hyphenation issues):
# Example: if deleting "mock-contract-validation", search for "contract-validation"
grep -r "{partial-skill-name}" .claude/
find .claude -name "{skill-name}" -type d
# Should return no results
Present verification results:
## Deletion Complete ✅
**Skill Removed:**
- Path: {skill-path}
- Status: Directory deleted
**References Cleaned:**
- ✅ gateway-testing:45 - Removed routing entry
- ✅ skill-manager.md:23 - Removed from command table
- ✅ test-infrastructure-discovery:219 - Removed from integration section
- ✅ developing-with-tdd:156 - Removed from related skills
**Verification:**
- ✅ No references found in grep search
- ✅ No partial matches found
- ✅ Directory no longer exists
**Summary:**
Skill "{skill-name}" successfully deleted. 4 references cleaned. No orphaned references remain.
Deletion complete when:
/skill-manager command - Routes delete operations to this skillmanaging-skills (CORE) - Main skill management routerNone - standalone skill
| Skill | Phase/Step | Purpose |
|---|---|---|
syncing-gateways (LIBRARY) | Phase 6 | Automatically detect and remove broken gateway paths - Read(".claude/skill-library/claude/skill-management/syncing-gateways/SKILL.md") |
| Skill | Trigger | Purpose |
|---|---|---|
renaming-skills (LIBRARY) | When skill needs new name instead of deletion | Consider renaming instead of deleting - Read(".claude/skill-library/claude/skill-management/renaming-skills/SKILL.md") |
migrating-skills (LIBRARY) | When skill needs location change instead of deletion | Consider migrating instead of deleting - Read(".claude/skill-library/claude/skill-management/migrating-skills/SKILL.md") |
auditing-skills (LIBRARY) | After deletion | Verify cleanup success and no orphaned references - Read(".claude/skill-library/claude/skill-management/auditing-skills/SKILL.md") |
Cannot proceed without:
Irreversible operations:
No undo - deletion is permanent.