Deleting Skills

Total: 18 minutes

Phase 1: Navigate to Repository Root and Validate Skill Existence

1.0 Navigate to Repository Root (MANDATORY)

Execute BEFORE any delete operation:

ROOT="$(git rev-parse --show-superproject-working-tree --show-toplevel | head -1)" && cd "$ROOT"

See: Repository Root Navigation

⚠️ 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 ✅

1.1 Find the Skill

# 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.

1.2 Verify It's a Skill

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.

Phase 2: Reference Discovery

Find ALL references across the codebase. Missing references = broken system.

2.1 Search Gateway References

# Search all gateway skills
grep -r "{skill-name}" .claude/skills/gateway-*/SKILL.md

Gateways to check:

• gateway-frontend
• gateway-backend
• gateway-testing
• gateway-security
• gateway-integrations
• gateway-mcp-tools
• gateway-capabilities
• gateway-claude

2.2 Search Command References

# Search all command files
grep -r "{skill-name}" .claude/commands/

Commands often reference skills in routing tables.

2.3 Search Skill References

# 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:

• "Integration with Other Skills" sections
• "Related Skills" sections
• Workflow instructions ("use skill X before Y")

2.4 Search Skill Descriptions

# 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.

2.5 Document All Findings

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

Phase 3: Impact Analysis

3.1 Present Findings to User

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

3.2 If "Show me references"

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.

Phase 4: Confirmation

Cannot proceed without explicit user confirmation ✅

If user confirms deletion:

• Proceed to Phase 5
• Document confirmation in output

If user cancels:

• Stop immediately
• Report "Deletion cancelled, no changes made"
• Exit skill

Phase 5: Remove Skill Directory

5.1 Final Safety Check

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

5.2 Delete Directory

rm -rf {skill-path}

5.3 Verify Deletion

ls {skill-path} 2>&1
# Should return "No such file or directory"

If directory still exists: Error - deletion failed. Report to user.

Phase 6: Gateway Sync

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.

6.1 Read syncing-gateways Skill

# 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.

6.2 Execute Gateway Sync

Follow the syncing-gateways (LIBRARY) workflow to:

1. Detect - Scan all gateway skills for references to deleted skill
2. Validate - Check if referenced skills exist in core or library
3. Report - Show which gateways have broken references
4. Fix - Remove broken routing entries from gateway skills

Why automatic? Gateways follow predictable routing table patterns. The syncing-gateways (LIBRARY) skill can detect and fix broken references automatically.

6.3 Verify Gateway Cleanup

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.

Phase 7: Cleanup Non-Gateway References

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.

7.1 Command References

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 |

7.2 Skill References

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

7.3 Track Cleanup Progress

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.

Phase 8: Verification

8.1 Re-Search for References

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

8.2 Check for Partial Matches

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/

8.3 Verify Directory Removed

find .claude -name "{skill-name}" -type d
# Should return no results

8.4 Final Report

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.

Success Criteria

Deletion complete when:

1. ✅ Skill exists and validated (Phase 1)
2. ✅ All references discovered and documented (Phase 2)
3. ✅ Impact shown to user (Phase 3)
4. ✅ User confirmed deletion (Phase 4)
5. ✅ Directory removed (Phase 5)
6. ✅ Gateway references synced and removed (Phase 6)
7. ✅ Non-gateway references cleaned (Phase 7)
8. ✅ No orphaned references remain (Phase 8)
9. ✅ TodoWrite todos complete

Common Mistakes & Rationalizations

See: references/common-mistakes.md

Integration

Called By

• /skill-manager command - Routes delete operations to this skill
• managing-skills (CORE) - Main skill management router

Requires (invoke before starting)

None - standalone skill

Calls (during execution)

Pairs With (conditional)

Safety Features

Cannot proceed without:

• ✅ User confirmation (Phase 4)
• ✅ Path safety check (Phase 5.1)
• ✅ Reference discovery (Phase 2)
• ✅ Verification (Phase 7)

Irreversible operations:

• Directory deletion (Phase 5)
• Reference cleanup (Phase 6)

No undo - deletion is permanent.