Skill Lifecycle and Versioning

A new course lesson on skill lifecycle and versioning for agentic AI introduces eight defined stages—draft, test, review, approve, publish, version, deprecate, and archive—and applies semantic versioning to a skill's behavior, not just its files. The lesson, part of the Production Agent Skills Engineering course, emphasizes that a skill's version must track whether behavior changes could break dependents, with patch, minor, and major versions defined accordingly. It also covers designing a changelog and deprecation process that consumers can act on.

· Agentic AI · 6 min read 📋 Prerequisites - Security and Governance previous lesson 🎯 What You'll Learn - Move a skill through eight defined lifecycle stages, from draft to archive - Apply semantic versioning to a skill's description and instructions, not just its bundled code - Design a changelog and deprecation process consumers can actually act on 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 /courses/production-agent-skills-engineering/skill-quality-anti-patterns , 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 /courses/production-agent-skills-engineering/skill-design-patterns and initial scoping happen. Test. The evaluation practice from Testing and Evaluation at Scale /courses/production-agent-skills-engineering/testing-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 /courses/production-agent-skills-engineering/skill-quality-anti-patterns and the security checklist /courses/production-agent-skills-engineering/skill-security-governance . 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 /courses/agent-skills-mastery/skill-md-format-specification , 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.