Tutorial: Maintain installed skills

Skills drift. Authors release fixes; your local install grows stale; two skills you installed last month now claim overlapping trigger phrases. The Maintain stage is the regular hygiene pass that keeps your installed inventory healthy.

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

What you will do

• Check which installed skills have updates available
• Pin a skill to a specific version
• Audit your local ~/.claude/ inventory for namespace collisions
• Apply rename suggestions and recommended edits
• Choose an audit mode that matches your tier and risk tolerance

Tools that map to Maintain

Step 1 — Find skills with updates

Try these prompts:

• "Which of my installed skills have updates?"
• "Check for outdated skills"
• "List skills I should update"

Skillsmith reads your installed skills directory, looks each one up in the registry, and returns those whose registry version is newer than your local copy.

The MCP returns two related tools: skill_updates reports every newer version; skill_outdated applies a stricter staleness threshold (typically 30 days) so you only see skills that are falling behind.

Update from the CLI

Run this in your terminal:

skillsmith update                       # Update all installed skills
skillsmith update community/jest-helper # Update one skill
skillsmith update --dry-run             # See what would change without applying

Before a major-version update, run a diff first to see what changed.

Step 2 — Pin a skill to a specific version

Pinning is CLI-only. It locks a skill at its current installed version so subsequent update runs skip it.

Run this in your terminal:

skillsmith pin community/jest-helper      # Lock current version
skillsmith unpin community/jest-helper    # Allow updates again
skillsmith pin --list                     # See all currently pinned skills

Pin when an upgrade has known regressions in your environment, or when you have customized the installed copy and want to prevent update from clobbering it. Always pair with a Linear follow-up to revisit the pin once upstream lands a fix.

Step 3 — Audit your local inventory for collisions

Two skills can both claim "git workflows" as a trigger. When that happens, the runtime picks one — and not always the one you want. The namespace audit surfaces these collisions so you can rename or skip deliberately.

Try these prompts:

• "Audit my installed skills for namespace conflicts"
• "Run a deep namespace audit on my ~/.claude inventory"
• "Show me which of my skills overlap"

The MCP tool skill_inventory_audit walks your local ~/.claude/ tree (skills, commands, agents, CLAUDE.md contents) and returns:

• Exact-name collisions (two files claiming the same trigger)
• Generic-token flags (skills using overly broad words like "helper")
• Semantic-overlap pairs, when in power_user or governance mode
• Suggested renames with audit IDs you can pass to apply_namespace_rename

Audit modes — pick the right depth

Set the mode in ~/.skillsmith/config.json or via the CLI:

skillsmith config get audit_mode
skillsmith config set audit_mode power_user

Free and Individual tiers cannot select power_user or governance; the CLI rejects the change with a typed error. See the MCP namespace-audit tools reference for the full schema.

Step 4 — Apply rename suggestions

The audit returns suggestions with stable IDs. To act on one:

Try these prompts:

• "Apply the suggested rename for jest-helper from the last audit"
• "Skip the rename suggestion for the test-runner collision"
• "Rename the test skill to my-team-jest-helper instead"

The rename modes are apply (use the suggested name), custom (provide your own), and skip (record the decision so the audit does not re-flag it). The override is persisted to a namespace-overrides ledger so subsequent audits respect your choices.

Step 5 — Apply recommended prose edits

Beyond renames, the audit can suggest small prose edits — for example, adding a domain qualifier to a description that triggers too broadly ("helper" → "jest-helper for unit tests"). These are gated through an allow-list (APPLY_TEMPLATE_REGISTRY) so only safe templated edits can be auto-applied.

Try this prompt:

• "Apply the suggested domain-qualifier edit to my skill description"

Free-form prose edits are rejected. If the audit suggests an edit that is not in the registry, it surfaces the suggestion as text for you to apply manually.

Common pitfalls

"audit_mode requires Team tier"

You set power_user or governance on a Free or Individual subscription. Either upgrade or set preventative. The session-start audit hook (Team+) is also silent for lower tiers by design.

Update overwrote my customizations

skillsmith update replaces the installed copy with the registry's. If you have customized a skill, pin it before running update next time. If you have already lost the customizations, check git history in your dotfiles repo (if you version-control ~/.claude/) or restore from a known-good backup.

Audit reports collisions but the runtime works fine

Collisions are warnings, not errors. They mean the runtime could pick the wrong skill on a given prompt; whether that has happened depends on your prompts. Resolve high-overlap pairs eagerly; live with low-overlap warnings if the trigger phrases are different enough in practice.

Where to next

Maintain is for individual users. If you operate at team or enterprise scale, the same audit signals roll up into the Govern stage — audit logs, RBAC, SIEM export.

If you want to create rather than maintain, the Author tutorial walks you through scaffolding your own skill.

Reference: MCP audit tools · CLI audit collisions · CLI pin.

Previous: Install & Use — Next: Author