Versioning and Maintaining Skills

Git for Skill Version History

Skills in .claude/skills/ are already in version control — commit them like any other source file. Meaningful commit messages make the history useful: skills/deploy: add --dry-run flag documentation says more than update skill, and supports git log skills/deploy/ as a focused audit trail for a single skill.

Personal skills in ~/.claude/skills/ sit outside project repositories. The practical fix is a dedicated ~/.claude git repository, or symlinks from a tracked dotfiles repo that already backs up your shell config and editor settings. Without version history, reverting a broken update to a personal skill requires rewriting it from memory.

Semantic Versioning for Shared Skills

When a skill is shared — distributed to a team or published publicly — the version frontmatter field communicates the scope of a change to consumers before they look at the diff. Set it in semantic versioning format:

---
name: deploy-staging
version: 1.2.0
description: Deploy the current branch to staging.
---

The three version numbers map directly to three categories of change in skill terms:

• Patch (1.0.0 to 1.0.1) — fix a wrong command, correct a typo, add a missing pitfall. Behavior unchanged; the fix makes the skill more accurate.
• Minor (1.0.0 to 1.1.0) — add a procedure section, introduce an optional step, add a new reference file. Existing behavior unchanged; new capability added.
• Major (1.0.0 to 2.0.0) — restructure the procedure, change required inputs, rename the skill. Consumers must adapt before updating.

For personal-only skills, version numbers are optional. They become essential the moment other people depend on the skill and need to know whether an update requires attention on their end.

The CHANGELOG Practice

For skills shared with a team or published publicly, maintain a CHANGELOG.md in the skill directory alongside SKILL.md. Keep entries brief — date, version, what changed, and why:

# CHANGELOG

## 2026-08-15 — v1.2.0
Added: pre-deploy validation step.
Why: failed deploys in staging were not caught before commit.

## 2026-07-01 — v1.1.0
Added: rollback procedure section.
Why: team requested a documented rollback path.

Consumers checking for updates can run git log skills/my-skill/ or read CHANGELOG.md without diffing the full SKILL.md body. This matters in team settings where the person checking the changelog is not the person who made the change.

Deprecation Patterns

Removing a skill that teammates use creates a silent breaking change. The deprecation pattern makes the transition visible before the skill disappears:

• Add [DEPRECATED] to the description — the / menu and auto-invocation context both show the description. The prefix is the first signal anyone sees without opening the file.
• Add a Deprecated section at the top of SKILL.md pointing to the replacement skill and the migration path.
• Use disable-model-invocation: true (Claude Code) — prevents the agent from auto-invoking the deprecated version during transition. Users can still call it manually by name.
• Archive via Curator (Hermes) — the archive state stops the skill from loading entirely without deleting it. It stops consuming Level 0 scan tokens while remaining recoverable.
• Use skillOverrides (Claude Code) — retire across a team without touching the file. Add "old-deploy": "off" to the skillOverrides block in settings.json and the skill disappears from all menus and auto-invocation context for that settings scope.

High-Drift Skill Categories

Not all skills drift at the same rate. Skills encoding stable concepts — code review principles, writing conventions — can go months without updates. Three categories drift fastest and need a scheduled review after any major platform update:

• Specific model IDs — model names and capability tiers change with each release cycle. A skill that hardcodes a model name referencing a retired version fails silently without surfacing an obvious error.
• Cloud service APIs — endpoints move, authentication schemes change, rate limits shift. A skill can produce confident wrong output against an API version it wasn't written for.
• Rapidly evolving CLIs — flags get renamed, defaults change, subcommands reorganize. A skill's commands may parse successfully while passing invalid arguments the CLI now rejects.

On Hermes, the Curator's stale state serves as an early-warning signal. When a skill enters stale — the agent has stopped using it within the configured review interval — the most common underlying cause is that the skill stopped working. Declining invocation becomes a visible flag for review rather than silent accumulating debt.