Maintaining the stack as your work changes

A Skill that worked six months ago can quietly stop working. The API it referenced changed. The team's terminology shifted. The output format it produced no longer matches the downstream tool that consumes it. The Skill still runs — it just produces output that is subtly wrong. Nobody notices until someone ships the wrong thing based on confident but incorrect output.

This is the failure mode that makes a Skills registry worse than no registry. A registry with stale entries creates false confidence. A team that would have asked a question if no Skill existed instead invokes the Skill and trusts the output. The Skill is wrong. The work is wrong. The Skill is blamed last because it ran without error.

The three signals that say a Skill needs updating

First signal: a step in the procedure produces a clarifying question more than once across different teammates or different runs. Claude is hitting an implicit assumption that the procedure no longer resolves. The assumption was once obvious — the team had a shared understanding of what "the current format" meant, for example — and it is no longer obvious because something changed. Either make the assumption explicit in the step or update the step to accommodate the change.

Second signal: the output format no longer matches the downstream tool. Your incident report Skill writes in a format your ticketing system changed six months ago. The Skill is producing valid markdown, but the ticketing system's import parser expects a different structure. Update the output step in the procedure and increment the minor version.

Third signal: a teammate modified their local copy of the Skill to make it work. This is the most important signal and the easiest to miss. If one person had to adapt the Skill to use it, the canonical version is wrong. The adaptation they made is the correct procedure. Pull their changes into the shared version, increment the version, publish the update. Do not let the canonical version remain behind the in-use version.

The three signals that say a Skill needs deleting

The workflow the Skill describes no longer exists in the team's practice. The tool it invokes has been replaced. The process it encodes was deprecated. A Skill for a defunct workflow is not neutral — it will be found by a new teammate, invoked, and produce output for a process that no longer applies.

A newer Skill covers the same procedure with less friction. This happens when a Skill is rewritten as part of a larger project and the original remains in the registry. Delete the original. One procedure, one Skill.

The Skill has not been invoked in 90 days and nobody can explain why it exists. Either nobody knows what workflow it serves, or the workflow has been abandoned, or the Skill has been silently superseded by a different approach. In any of these cases, delete it. If it is needed again, it can be recovered from git history.

The maintenance cadence

Treat Skills like tests. Schedule a quarterly audit: list every installed Skill in the registry, and for each one ask two questions. Is this still the procedure we follow? If yes, is it still accurate?

A Skills audit for a registry of ten Skills takes about an hour. Run each Skill on one real instance of the task. Note any step that produced a clarifying question or a subtly wrong output. Update or delete before the audit session ends. A Skills registry that is audited quarterly and updated immediately on each audit will stay accurate. A registry that is updated "when we have time" will drift.

The quarterly cadence is a minimum. Update a Skill immediately when you encounter any of the three update signals above — do not defer to the next audit. The audit is for the Skills you have not touched since the last audit.

Versioning as a maintenance tool

The version number in the frontmatter is your primary tool for communicating that a Skill has changed. Use it deliberately:

When you fix a gotcha or add clarifying language to a step that did not change the output: patch increment (1.2.3 → 1.2.4). Teammates who have 1.2.3 installed can upgrade; their existing workflows will not break.

When you add new capability — a new optional output section, a new optional step — without changing existing output for current inputs: minor increment (1.2.4 → 1.3.0). Safe to upgrade; new capability available.

When you change the output format, remove a step, or change the required inputs: major increment (1.3.0 → 2.0.0). Teammates need to review the change before upgrading. Downstream workflows may break if they upgrade without reading the changelog.

Write a one-line changelog entry in the README every time you increment the version. "1.3.0: Added optional ## Security section for authentication changes." A teammate reading the changelog can decide whether to upgrade without reading the entire Skill file.

If you get stuck

You want to update a Skill but teammates are currently using it and a breaking change would disrupt active work. Publish the new version as a separate Skill with a -v2 suffix in the name. Announce the transition, give teammates a window to migrate, then deprecate and delete the old version. Never silently break a running workflow.

You run the quarterly audit and find that half the Skills in the registry are stale. Do not attempt to update all of them in one session. Prioritize by frequency of use: update the Skills that are invoked weekly first. Skills that are invoked rarely are less likely to cause damage when stale — fix them second, or delete them if the use frequency has dropped because the workflow is no longer active.

You cannot find the teammate who made a local modification to a Skill. Check the team's git history if the modification was committed; check Slack or your communications archive if the modification was not shared. The modification represents discovered procedure — it exists because the canonical version was incomplete. Recover it.

Cross-reference

l6 covers the repository structure and versioning conventions that make maintenance tractable. l7 covers the full bundle — the maintenance of Projects and Skills together is different from maintaining Skills alone, because the system prompt in the Project may also drift.

Deliverable

Audit the Skills you built in this course. Classify each one: current and accurate, needs update, or retire. Update or delete at least one before the session ends. Write the version number and a one-line changelog entry for any Skill you update.