Versioning, Lifecycle and Design Patterns¶

Treat a skill as a managed software artifact¶

If a skill is a production capability, it will evolve over time:

prompts/instructions improve,
input/output schemas change,
models are replaced,
new tools are added,
permission policies tighten,
evaluation datasets grow,
old implementations become deprecated.

It is therefore useful to model a skill as a versioned software artifact:

Skill
├── identity
├── contract version
├── implementation version
├── owner
├── lifecycle status
├── evaluation baseline
└── rollout policy

Not every system needs an enterprise-grade registry, but lifecycle concerns should be explicit.

What actually changes?¶

Several independent layers can evolve:

Capability contract
├── purpose
├── input schema
├── output schema
└── failure semantics

Behavior implementation
├── instructions / prompt
├── examples
├── model
├── context strategy
└── tool strategy

Runtime policy
├── permission
├── timeout
├── retry
└── rollout

They do not necessarily share one version number.

Contract version vs implementation version¶

For example:

review_pull_request contract v2

may remain stable while:

prompt v14 → v15
model A → model B
retrieval strategy 3 → 4

changes internally.

There is no caller-visible breaking change if the contract and semantic expectations remain stable.

This is why it helps to separate:

public skill interface
        ≠
internal implementation

What is a breaking change?¶

Typical breaking changes include:

adding a required input field,
removing an output field,
changing enum meaning,
changing success/failure semantics,
materially changing the capability responsibility,
changing the side-effect profile.

For example, v1:

{
  "severity": "HIGH",
  "summary": "..."
}

and v2:

{
  "risk": {
    "level": "HIGH",
    "category": "CORRECTNESS"
  }
}

may not be compatible for downstream callers.

Semantic versioning as inspiration¶

Classic SemVer is not mandatory, but it provides a useful mental model:

MAJOR → caller-visible breaking contract/behavior change
MINOR → backwards-compatible capability addition
PATCH → implementation fix, contract unchanged

AI skills complicate this because semantic behavior can change without schema changes.

A prompt update can create a major regression while leaving the contract identical.

That is why versioning needs an evaluation baseline.

Lifecycle status¶

A registry can use statuses such as:

EXPERIMENTAL
STABLE
DEPRECATED
DISABLED

Experimental¶

contract may change,
limited user group,
weak compatibility guarantee.

Stable¶

explicit contract,
baseline evaluation,
owner,
controlled rollout.

Deprecated¶

still available,
replacement known,
migration deadline may exist.

Disabled¶

no longer routable,
can be shut down immediately for security or reliability reasons.

Ownership¶

Every production skill should have an owner.

owner: Payments Platform

or:

owner: AI Platform / Support Automation

Otherwise “ownerless skills” accumulate:

outdated policies,
stale examples,
old models,
unmonitored evaluation.

The owner may be responsible for:

contract,
evaluation,
rollout,
deprecation,
security review,
incident response.

Change process¶

A simple production lifecycle:

change proposed
      ↓
offline eval
      ↓
security/contract checks
      ↓
staging / shadow
      ↓
canary rollout
      ↓
monitor
      ↓
full rollout or rollback

Not every small skill requires every step, but high-risk capabilities often justify them.

Shadow testing¶

A new implementation can process production requests without affecting real side effects.

production request
   ├── current skill → real result
   └── candidate skill → shadow result

Then compare:

quality
latency
cost
routing/tool behavior

This is especially useful for model migrations.

Canary rollout¶

For example:

5% traffic → skill v3
95% traffic → skill v2

If metrics degrade:

rollback to v2

The runtime must route explicit skill versions for this to work.

Rollback must actually be possible¶

If a skill update changes its output contract and downstream consumers have already migrated, rollback may no longer be simple.

This is a classic deployment-compatibility problem.

A pattern such as:

expand contract
 ↓
migrate consumers
 ↓
remove old contract later

works just as it does for API/database migrations.

Deprecation¶

A deprecated skill should not disappear unexpectedly.

Registry metadata can include:

status: deprecated
replacement: review_pull_request_v3
sunset: 2026-12-01

The runtime can log which callers still use it.

usage telemetry
 ↓
migration list

Skill-library design patterns¶

1. Narrow Capability Pattern¶

One skill, one coherent responsibility.

Analyze Test Failure

not:

Do Software Engineering

Benefits:

routable,
evaluable,
narrow permissions,
easier reuse.

2. Capability Contract + Adapter Pattern¶

Skill dependency:

repository_reader

Runtime adapters:

GitHub connector
local checkout
GitLab API

The skill is not coupled to a concrete provider.

3. Evidence-Grounded Result Pattern¶

Semantic claims carry evidence:

{
  "finding": "Retry may duplicate payment",
  "evidence": ["RetryService.java:87"],
  "confidence": 0.88
}

This helps with:

human review,
evaluation,
hallucination detection.

4. Read → Propose → Execute Pattern¶

For high-risk operations:

read state
 ↓
analyze
 ↓
propose action
 ↓
authorize / approve
 ↓
revalidate
 ↓
execute

This is stronger than one all-powerful write-capable skill.

5. Result Envelope Pattern¶

Use explicit outcomes:

SUCCESS
PARTIAL_RESULT
INSUFFICIENT_CONTEXT
NOT_AUTHORIZED
TOOL_UNAVAILABLE

The caller does not parse free text.

6. Router + Specialists Pattern¶

Router
├── PR Review Skill
├── Incident Triage Skill
└── Support Billing Skill

Each specialist receives less context and fewer tools.

7. Deterministic Shell Pattern¶

validation
policy
state
retry
idempotency
      ↓
LLM semantic capability
      ↓
validation

Deterministic software surrounds the probabilistic core.

This is a recurring architectural principle throughout the knowledge base.

8. Explicit State Ownership Pattern¶

runtime owns state
skill receives input
skill returns result

rather than:

skills share hidden mutable memory

9. Human Escalation Pattern¶

When there is:

high risk
low confidence
conflicting evidence
policy ambiguity

support a first-class:

ESCALATE_TO_HUMAN

outcome.

10. Budgeted Execution Pattern¶

Skill/agent runtime should support:

max steps
max model calls
max tool calls
max cost
max time

with an explicit budget-exceeded outcome.

Anti-pattern: Mega Skill¶

UniversalEnterpriseAgentSkill

with all knowledge and all tools.

Problems:

routing ambiguity,
giant prompt,
broad permissions,
hard evaluation,
large blast radius,
strong coupling.

Anti-pattern: Hidden Business Logic¶

Hard business policy exists only in a prompt:

"Refund above 100 EUR needs approval."

If this is an invariant, enforce it in application policy too.

Anti-pattern: Provider-Coupled Skill¶

Skill contract mentions exact provider SDK classes everywhere.

This makes model/tool migration harder.

Prefer capability abstractions.

Anti-pattern: Implicit State¶

A skill works only because “something was mentioned in a previous chat”.

Reusable contracts should make required input explicit or resolve dependencies explicitly through the runtime.

Anti-pattern: Unlimited Permission¶

Giving every tool “because it might be useful later” is poor security design.

Anti-pattern: No eval, no owner¶

A skill without:

owner
baseline
usage
version

will eventually become a legacy black box.

Anti-pattern: Prompt patch accumulation¶

edge case fails
 ↓
add sentence
 ↓
another edge case
 ↓
add exception
 ↓
500-line prompt

Sometimes the correct fix is:

contract redesign,
new deterministic validation,
split skill,
better routing,
retrieval,
tool boundary,
evaluation improvement.

Reference skill package¶

A mature skill can conceptually look like:

review_pull_request/
├── manifest
│   ├── name
│   ├── version
│   ├── owner
│   └── status
├── contract
│   ├── input schema
│   ├── output schema
│   └── failure semantics
├── behavior
│   ├── instructions
│   └── examples
├── dependencies
│   └── repository_reader
├── policy
│   └── read-only
└── evals
    ├── dataset
    └── baseline

This is not a mandatory physical folder structure.

It is a mental model of the concerns that exist.

Where Agent Skills fit in the larger agentic system¶

The picture is now:

Skill Registry
      ↓
Routing
      ↓
Skill Contract
      ↓
Context + State Projection
      ↓
Model + Tools
      ↓
Structured Result
      ↓
Validation / Policy
      ↓
Workflow / Agent Loop

A skill is therefore:

not an agent,
not a tool,
not a workflow,
not merely a prompt.

It is a reusable capability unit used by a larger runtime.

When is a first production version ready?¶

Minimum checklist:

Takeaways¶

A production skill should be a versioned, owned, and evaluated software artifact.
Contract version and implementation version should be treated separately.
Prompt/model changes with a stable schema can still create semantic breaking changes, so evaluation is required.
Useful lifecycle states include experimental → stable → deprecated/disabled.
Shadow, canary, and rollback patterns can support controlled rollout.
Deprecation needs a replacement path and migration visibility.
Strong patterns include narrow capability, adapter, evidence grounding, read/propose/execute, result envelope, router+specialists, deterministic shell, and explicit state ownership.
Avoid mega-skills, hidden business logic, provider coupling, implicit state, and unlimited permissions.
An Agent Skill is a modular capability unit inside the larger agentic runtime.