Skill Lifecycle and Versioning

Very Few People Cover This

Most Agent Skills material — including the free companion course — stops at “how do I write and test one.” A skill that’s actually in use across a team or organization doesn’t stay static, and almost nothing addresses what happens after the first version ships: how it gets reviewed, how a breaking change gets communicated, what happens when it’s finally time to retire it. That’s the “Stale Skill” smell from Skill Quality, engineered into a real process rather than left as a thing to notice too late.

Eight Stages

Draft → Test → Review → Approve → Publish → Version → Deprecate → Archive

Draft. A skill in active development, not yet relied on by anyone besides its author. This is where the design-pattern selection (Skill Design Patterns) and initial scoping happen.

Test. The evaluation practice from Testing and Evaluation at Scale — trigger accuracy, output quality, benchmarks — run before anyone besides the author depends on the result.

Review. A second person, not the author, checks the skill against the quality checklist and the security checklist. This is the stage that catches what the author’s own familiarity with the skill makes easy to miss — an under-specified failure path, a description broad enough to raise the supply-chain concerns from the previous lesson.

Approve. A formal decision, by someone with the authority to make it, that the skill is ready for its intended trust level and audience — connecting directly to the trust-level governance from the previous lesson.

Publish. The skill becomes available to its intended audience — a team via a project repository, an organization via a registry (next lesson), or the public via a marketplace.

Version. The skill continues to exist and change after publishing — this is a distinct, ongoing stage, not a one-time event, and it’s substantial enough to deserve its own section below.

Deprecate. The skill is marked as no longer the recommended approach, with a stated reason and, ideally, a replacement — while it may still function, consumers are told explicitly not to build new dependencies on it.

Archive. The skill is retired entirely — removed from discovery, kept only for historical reference or audit purposes.

Versioning a Skill’s Behavior, Not Just Its Files

Semantic versioning (major.minor.patch) is familiar from software, but a skill’s version needs to track something subtly different: not just that the file changed, but whether its behavior changed in a way that could break something depending on it.

• Patch (1.2.0 → 1.2.1): a wording fix, a clarified instruction, a corrected typo in a reference file — no change to what the skill actually does for any input that previously worked correctly.
• Minor (1.2.1 → 1.3.0): new capability added without changing existing behavior — a new field the validator skill now checks, alongside all the ones it already checked.
• Major (1.3.0 → 2.0.0): a change that could alter results for existing use — a validator that now rejects input it previously accepted, a transformation skill whose output format changed shape.

---
name: config-validator
description: Validates a project's config.yaml file against required fields and value constraints.
metadata:
  version: "2.0.0"
  previous_version: "1.3.0"
---

The metadata field, from the free course’s SKILL.md Fundamentals, is exactly where this lives — the spec leaves it open for client- and organization-specific use, and a version number is one of the most valuable things to put there.

Why the Major/Minor/Patch Line Isn’t Always Obvious

A skill’s “breaking change” line is fuzzier than a function’s. Adding a new check to a validator sounds additive (minor), but if that check now rejects input that used to pass, every existing consumer relying on the old behavior is affected — which makes it a major change in practice, even though the change reads as “added a rule” rather than “removed one.” When in doubt, treat a change that could flip a previously-passing case to failing (or vice versa) as major, not minor — the cost of over-flagging a version bump is far lower than the cost of a silent behavior change reaching consumers who never saw it coming.

A Changelog Consumers Can Act On

Version numbers alone don’t tell a consumer what to actually check before adopting a new version. A changelog entry should:

## 2.0.0 — 2026-07-26

**Breaking:** `timeout_seconds` is now required (previously optional,
defaulted to 30). Configs without it will now fail validation instead
of silently using the default.

**Migration:** add `timeout_seconds: 30` to any config relying on the
old default.

Stating the specific behavior change and the specific migration step is what separates a changelog that’s actually useful from one that’s just a formality nobody reads before upgrading.

Deprecation, Done Properly

Deprecating a skill without a clear replacement and timeline just creates uncertainty — consumers don’t know whether to keep using it, and it lingers indefinitely instead of actually being retired.

---
name: legacy-config-validator
description: DEPRECATED — use config-validator instead. Validates config.yaml using the pre-2.0 rule set.
metadata:
  status: deprecated
  replacement: config-validator
  archive_date: "2026-10-01"
---

This skill is deprecated as of 2026-07-26 and will be archived on
2026-10-01. Use config-validator (v2.0.0+) instead — see its changelog
for the migration from the pre-2.0 rule set.

The description itself states the deprecation, which matters because description is what discovery reads — a consumer searching for validation help should learn it’s deprecated at the moment they’d otherwise start relying on it, not only after they’ve already built something on top of it.

Summary

• A skill’s lifecycle has eight real stages — draft, test, review, approve, publish, version, deprecate, archive — and most Agent Skills material only ever covers the first two
• Semantic versioning applies to a skill’s behavior, not just its files — a rule change that flips previously-passing input to failing is a major change even when it reads as “added a check”
• A useful changelog states the specific behavior change and the specific migration step, not just a version number
• Deprecation needs a stated replacement and timeline, communicated through the description itself, so consumers learn about it before building new dependencies on the deprecated skill

Next, you’ll turn this lifecycle into something that actually runs automatically — a real CI/CD pipeline that lints, tests, evaluates, and deploys a skill on every change.