Maintaining and Evolving Skills

Skills rot. Not dramatically, not with error messages. They just quietly become wrong, and Claude Code follows the wrong instructions, and you wonder why it keeps making the same mistake.

Why This Happens

Your setup changes fast. New testing framework. REST to GraphQL. Project restructure. Monorepo migration. Every one of these can make existing skills partially or fully wrong.

A skill that says "use Jest for testing" when you switched to Vitest three months ago won't crash. It'll just waste your time every session as you correct Claude's test runner choice. Over and over. Maddening.

There's also a hard budget constraint. Claude Code loads skill descriptions into context, capped at about 2% of the context window (fallback: 16k characters). Twenty skills accumulated, only eight still relevant? Those twelve dead ones are stealing context from the ones that matter. Run /context and look for exclusion warnings to see if this is happening to you.

A System That Works

Treat skills like code. Review on a schedule, not just when something breaks.

Weekly glance. Two minutes at the end of the week. Scan .claude/skills/. One question per skill: did this come up this week? If a skill has been irrelevant for a few weeks running, flag it.

Monthly review. Actually open each SKILL.md and read it. Do the instructions match your current workflow? Has the phrasing gotten janky? If Claude's been ignoring a skill or interpreting it oddly, rewrite it. Be more specific. Keep files under 500 lines; anything longer should be split into supporting files.

Quarterly prune. Delete what you haven't used. This feels wasteful. It isn't. An unused skill costs context budget every session. If you need it later, pull it from git history. That's literally why you version things.

Versioning With Git

Project-level skills in .claude/skills/ should be committed. Full stop. You get change history, revert capability, team contributions, and pruned skills are never truly gone (just a git log away).

Commit messages matter here. "Updated deploy skill to use new staging environment" is useful. "update skill" isn't. When you delete a skill, say why so future-you doesn't wonder what happened.

Global skills in ~/.claude/skills/ are trickier since they live outside any repo. A small dotfiles repo that includes your global Claude configuration handles this. At minimum, back them up somewhere versioned.

Tracking What Works

You don't need an analytics system. When Claude nails something it used to get wrong, note which skill drove that. When it still struggles with something a skill should cover, open that skill and figure out why.

Skills usually fail for three reasons: description too vague for matching, conflicting guidance in the instructions, or trying to cover too many scenarios. The fix is almost always "get more specific," not "add more content."

A lightweight trick: add a "last verified" date comment at the top of each SKILL.md. Update it when you confirm the skill still works. Anything older than two months gets closer inspection.

Context Budget Management

Growing skills library means you'll eventually hit the character budget. Claude Code silently excludes skills that don't fit. You only find out through /context. Not a crisis, but a clear signal to curate.

You can override the budget with the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable. That's a band-aid. The real solution: keep skills lean. Each one should earn its context window space.

One-sentence test: if you can't explain in one sentence why a skill exists and when it activates, it's too broad or unnecessary.

Try It

Open your .claude/skills/ directory right now and pick any skill file. Read through it with fresh eyes and ask these questions:

1. Does every instruction still match my current workflow?
2. Is the description specific enough for Claude Code to know when to load this skill?
3. Has this skill been useful in the last month?

If any answer is no, fix it or delete it. Then commit the change with a descriptive message:

git add .claude/skills/
git commit -m "Prune outdated deploy skill, update test runner references to Vitest"

Run /context in your next Claude Code session and check whether your remaining skills all fit within the budget. If you see exclusion warnings, you know there is more pruning to do.

Evolving With Your Workflow

Your skills library isn't documentation. It's configuration. Documentation describes what exists. Configuration shapes what happens next. Big difference.

When you adopt a new tool, update the skills that reference the old one before you forget. When you notice Claude Code doing something brilliant unprompted, consider codifying that behavior into a skill so it stays consistent.

Skills follow the Agent Skills open standard (agentskills.io), so the patterns transfer to other tools that adopt the same format.

The short version: skills rot silently, so review them regularly. Weekly glance, monthly review, quarterly prune. Commit project skills to git. Keep each SKILL.md under 500 lines with one concern per file. And run /context occasionally to check for exclusion warnings.