Agent Skills Should Be Versioned Business Capabilities

Consider an illustrative skill that prepares responses to customer security questionnaires. It classifies each question, retrieves approved evidence, drafts an answer, links the source, and routes unsupported claims to security or legal review.

On Monday, it answers a data-retention question from the current policy and flags a customer-specific commitment. On Thursday, someone improves the skill in place: the description becomes broader, a policy reference points to a newer draft, and the output template stops showing unresolved exceptions. The next questionnaire looks cleaner and reaches the reviewer faster.

It is also harder to trust. No one can identify which behavior produced each answer, whether the change was approved, or how to reproduce Monday's result.

A skill becomes a business capability when other work depends on its behavior. At that point, editing instructions is a release decision, even when the artifact still looks like a Markdown file.

One edit can change four different behaviors

The Agent Skills specification defines a portable package built around SKILL.md. The required frontmatter names the skill and describes what it does and when to use it. The body carries instructions. Optional references/, scripts/, and assets/ directories can supply documentation, executable code, and templates. Agents load this material progressively: metadata is available for discovery, the full instructions load after activation, and supporting files are read when required.

That structure creates several behavioral surfaces inside one directory.

Changing the description can change when the agent selects the skill. A broader phrase such as "answer compliance questions" may activate it for privacy, regulatory, or contract questions that its evidence set was never designed to handle.

Changing the instructions can alter the decision path. Replacing "pause when approved evidence is missing" with "draft from the closest available source" may improve completion rate while weakening the review boundary.

Changing a reference can alter the facts available to the run without changing SKILL.md at all. A path that once resolved to an approved retention policy may now resolve to a draft. If the reference uses a live URL, the content can change while the skill package remains byte-for-byte identical.

Changing a script or template can alter execution and output. A parser may begin normalizing questionnaire rows differently. A script may gain network access or a new dependency. A template may remove the field that tells a reviewer which answers still lack evidence.

Format validation can confirm that the directory and frontmatter follow the specification. It cannot establish that these changes preserve the business promise. The release boundary therefore has to include every artifact and dependency capable of changing selection, reasoning, execution, or review.

The version should identify the business promise

For the security-review skill, the useful promise is not "produce questionnaire text." A reviewable release might promise to:

• classify each question against a defined taxonomy;
• use only approved sources with identifiable versions;
• preserve the link between every draft answer and its evidence;
• separate unsupported claims and customer-specific commitments;
• route material exceptions to named owners; and
• produce a package that a human approves before external delivery.

That promise gives the version operational meaning. A team can test whether a release still satisfies it and can explain which changes require broader review.

The skill format permits a version value in optional metadata, but the specification does not prescribe an enterprise release lifecycle. The organization still has to decide what the identifier covers. At minimum, a release record should resolve to the exact instructions, description, references, scripts, assets, compatible tool contracts, policy versions, evaluation suite, and accountable owner.

A label alone is insufficient. security-review@2.3.0 is useful only if the registry can retrieve the immutable package and its dependencies. If 2.3.0 points to a folder whose policy files continue to change, the version describes a name rather than behavior.

Teams can borrow the language of Semantic Versioning, but the numbers should follow the business contract rather than software convention by reflex. A practical interpretation might look like this:

| Change | What may break | Release treatment | | --- | --- | --- | | Clarify wording without changing routing, sources, decisions, tools, or output | Reviewer understanding | Patch candidate after regression checks | | Add a supported questionnaire type while preserving the existing contract | Skill selection and new evaluation paths | Minor candidate with routing and coverage tests | | Change authoritative sources, approval rules, tool permissions, or required output fields | Compliance boundary and downstream review | Major candidate with owner approval and migration plan | | Modify an executable script, external dependency, or write-capable tool | Runtime and security behavior | Code review, sandbox tests, and a new immutable release regardless of label |

The exact labels matter less than the rule that meaningful behavior does not change behind an existing identifier.

Running work should keep the release it started with

A security review can remain open for days. Evidence owners respond at different times, product facts change, and legal may revise a proposed answer. Automatically switching the run to the latest skill release halfway through creates a mixed execution that no single evaluation covered.

The task should retain the release selected at creation. Its state needs the skill identifier, release digest, policy references, tool contract versions, model and runtime release, and any approved migration. New tasks can adopt the new skill after rollout. Existing tasks should continue on the pinned release unless an owner chooses to migrate them.

Migration is a business decision when the release changes authority or evidence. Suppose version 3.0 removes a retired policy and requires a new approval for data-residency answers. An open questionnaire on version 2.4 cannot simply finish with the old rules, but switching silently would discard the meaning of earlier decisions. The migration should identify which answers must be recomputed, which approvals are invalidated, and which prior evidence remains usable.

This means two releases may operate at once. The registry and runtime need to resolve both. Dashboards have to separate their results. Exception owners need to know which rules produced a case. Rollback must restore the previous package and activation behavior, not merely reverse the latest file commit.

There is an awkward edge here: some references should remain live. A vulnerability advisory or system availability record may need the newest state rather than a pinned snapshot. The release should distinguish fixed policy dependencies from live operational inputs and record the observed version or timestamp of the latter. Pinning everything can make the answer reproducible but stale; pinning nothing makes it current but unexplainable.

Evaluation must inspect activation and execution, not only prose

A polished final answer can hide a broken skill. The agent may have activated it for the wrong task, read an unapproved source, omitted a material exception, or called a tool outside the expected path before producing text that sounds correct.

Evaluation therefore begins before generation.

Routing cases test whether the description activates the skill for intended requests and stays out of unrelated ones. Positive cases might include a standard security questionnaire and a request to assemble approved control evidence. Negative cases might include legal interpretation, a request to promise a new contractual control, or an internal incident investigation that needs a different workflow.

Execution cases inspect the path through the skill:

• which reference files were loaded;
• whether the retrieved evidence was current and approved;
• which tools were offered and called;
• whether required gaps reached the right owner;
• whether the output retained source links and unresolved decisions; and
• whether external delivery remained behind human approval.

Outcome cases then assess the package the reviewer receives: answer coverage, unsupported claims surfaced, evidence traceability, reviewer corrections, exceptions missed, cycle time, and execution cost. A release can improve writing quality while regressing the control path. Those results should not collapse into one score.

The model is another dependency. A skill that routes and executes correctly with one model may interpret an ambiguous instruction differently after a model change. The tests described in Your Agent Architecture Should Survive a Model Change apply here: hold the workflow cases stable, run the candidate release against them, and compare both outcomes and execution traces.

Non-determinism makes the release decision less tidy than a conventional unit test. One successful run does not establish a stable behavior. High-consequence cases may need repeated trials, targeted adversarial inputs, and a human review of disagreements. This costs time and tokens. It is still cheaper than discovering after distribution that a wider description caused the skill to answer questions outside its authority.

Rollout should create evidence before full replacement. A candidate can run in shadow mode against captured tasks without sending results, then serve a limited group or low-risk questionnaire class. The operating team can compare activation, tool use, exceptions, and reviewer changes with the current release. Promotion should be reversible until the candidate has handled enough representative work to justify the change.

Portability expands the supply-chain boundary

The same open format that makes skills useful across compatible agents also makes them easy to copy, install, and modify. The official MCP development skills demonstrate that portability: a skill package can carry instructions and reference material that another compatible agent loads on demand.

An enterprise should treat the package as an acquired dependency, not trusted prose.

The description influences activation. The body can direct the agent to read files and use tools. The optional scripts/ directory contains executable code. The specification's allowed-tools field is experimental, and support can vary by implementation. A declaration inside the skill cannot substitute for permissions enforced by the host and the target systems.

Before an external skill reaches production, the organization needs its source, license, owner, review record, release digest, dependency inventory, required network and filesystem access, and evaluation results in the destination environment. Scripts need code review, constrained execution, and explicit dependencies. Updates should enter as new candidates; a remote repository changing should not rewrite the approved production release automatically.

Portability also does not guarantee identical behavior. Compatible hosts may differ in how they select skills, expose tools, isolate scripts, manage context, or interpret optional metadata. A portable package reduces the work of moving instructions. It does not eliminate qualification in each runtime.

This creates an ownership question. The skill author may understand the instructions and examples. The security owner understands which evidence is approved. The platform team owns runtime permissions and sandboxing. The process owner accepts the operational result. A release needs all relevant approvals without pretending one team can review every dimension alone.

Versioning is worthwhile when the organization depends on the result

Immutable packages, registries, evaluations, staged rollout, concurrent releases, and migrations add real overhead. A personal read-only skill used to reformat notes does not need the same process as a skill that prepares external security claims. Applying the heavier path everywhere would slow useful experimentation and encourage teams to work around it.

The threshold is consequence and dependency. Versioning becomes necessary when a skill influences a controlled decision, invokes tools with side effects, supplies an artifact consumed by another process, or is reused widely enough that an in-place edit can change many people's work at once.

The Coryntas security review preparation workflow defines a concrete outcome: a complete, source-linked evidence package with material exceptions held for accountable review. A skill can encode reusable knowledge inside that workflow. The workflow still needs to pin the release, provide current business context, control tools, preserve evidence, and keep external delivery with an authorized person.

The same principle connects to Every Agent Change Needs a Release Path. A skill changes agent behavior through a particularly portable package, but portability does not reduce the need to test and own the change. It increases the number of places an unreviewed change can travel.

A business capability should have a release that can be named, retrieved, evaluated, approved, observed, migrated, and retired. Without that lifecycle, a skill may be reusable. The organization still cannot depend on it.