Tutorial: Retire skills

The Retire stage is short. Uninstall is a single command. But running it deliberately — knowing what you remove, what stays, and what to clean up afterward — keeps your ~/.claude/ tree honest and your audit log readable.

These tutorials show Skillsmith in Claude Code. For installation in your preferred runtime (Cursor, Continue, Copilot, Windsurf), see Getting Started.

What you will do

• Uninstall a skill from the runtime's skills directory
• Verify the uninstall actually landed
• Check for orphaned references (companion subagents, namespace overrides)

Tools that map to Retire

Step 1 — Uninstall a skill

Try these prompts:

• "Uninstall community/jest-helper"
• "Remove the git-commit skill"
• "Uninstall jest-helper from my skills directory"

Or from the terminal:

skillsmith remove community/jest-helper

Skillsmith deletes the skill bundle from the runtime's skills directory and writes an uninstall event to the audit log. On Claude Code that means removing ~/.claude/skills/<author>/<name>/ entirely.

Step 2 — Verify the uninstall

Run this in your terminal:

ls ~/.claude/skills/community/jest-helper 2>&1
# Expected: "No such file or directory"

If the directory still exists, the uninstall did not complete. Check the Skillsmith log for the failure reason and re-run.

Step 3 — Clean up orphaned references

Some skills generate companion artifacts that uninstall_skill does not remove automatically — by design, since you may want to keep them.

Companion subagents

If you generated a Claude Code subagent for the skill via skillsmith author subagent, the agent definition lives at ~/.claude/agents/<name>.md. Remove it manually if you no longer need the subagent:

rm ~/.claude/agents/jest-helper.md

Namespace overrides

If you applied a rename via apply_namespace_rename, that decision is persisted in ~/.skillsmith/namespace-overrides.json. Future installs of a skill with the renamed name will pick up the override, which usually is what you want — but if you uninstall a skill and want to clear the override too, edit the file directly.

Configuration entries

If your skill required configuration in ~/.skillsmith/config.json (for example, a per-skill API key or feature flag), those entries persist after uninstall. Review the file periodically and prune entries for skills you have removed.

Common pitfalls

"Skill not found"

Same root cause as Evaluate: skill IDs are case-sensitive and require the author/name form. community/jest-helper resolves; jest-helper alone does not.

Uninstall succeeded but the skill still triggers

Most runtimes load the skills directory once at startup. Restart the runtime so it forgets the uninstalled skill. If you restart and the skill still loads, check whether you have a duplicate copy — a namespace audit (Maintain Step 3) will surface it.

Audit log shows uninstall but I never ran it

On Team and Enterprise tiers, anyone with admin access can uninstall a skill on a managed device. Query the audit log (Govern Step 3) to see who initiated the uninstall.

Where to next

You have completed the lifecycle. Most users loop back through Discover when a new need arises, or through Maintain on a regular cadence to keep the inventory healthy.

Reference: MCP uninstall_skill · CLI remove.

Previous: Govern — Back to: Tutorials overview