Versioning, Lifecycle and Design Patterns¶

A skill legyen kezelt software artifact¶

Ha egy skill production capability, akkor idővel változni fog:

prompt/instruction javul,
input/output schema változik,
model cserélődik,
új tool kerül alá,
permission policy szigorodik,
evaluation dataset bővül,
régi implementation deprecated lesz.

Ezért hasznos úgy gondolni rá, mint egy verziózott software artifactra:

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

Nem kell minden rendszert túlbonyolítani enterprise registryvel, de a lifecycle kérdéseket tudatosan kezelni kell.

Mi változik valójában?¶

Egy skillnél több külön réteg változhat.

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

Ezek nem feltétlenül ugyanazzal a verziószámmal mozognak.

Contract version vs implementation version¶

Például:

review_pull_request contract v2

maradhat ugyanaz, miközben:

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

A caller számára nincs breaking change, ha a contract és semantic expectation stabil marad.

Ezért jó különválasztani:

public skill interface
        ≠
internal implementation

Mikor breaking change?¶

Tipikusan breaking lehet:

required input mező hozzáadása,
output mező eltávolítása,
enum jelentésének megváltoztatása,
success/failure semantics változása,
capability responsibility jelentős módosítása,
side-effect profil megváltozása.

Például v1:

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

v2:

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

A downstream caller ezt nem biztos, hogy kompatibilisen fogyasztja.

Semantic versioning mint inspiráció¶

Nem kötelező klasszikus SemVer, de hasznos mental model:

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

AI skillnél azonban semantic behavior változás nehezebben formalizálható.

Például prompt javítás schema változás nélkül is jelentős regressziót okozhat.

Ezért versioning mellé evaluation baseline kell.

Lifecycle status¶

Skill registryben hasznos lehet:

EXPERIMENTAL
STABLE
DEPRECATED
DISABLED

Experimental¶

változhat contract,
szűk user group,
nincs erős compatibility guarantee.

Stable¶

explicit contract,
baseline eval,
owner,
controlled rollout.

Deprecated¶

még használható,
replacement ismert,
migration deadline lehet.

Disabled¶

nem route-olható,
security vagy reliability okból azonnal lekapcsolható.

Ownership¶

Minden production skillnek legyen owner.

owner: Payments Platform

vagy:

owner: AI Platform / Support Automation

Különben idővel lesznek „senki skilljei”:

outdated policy,
stale examples,
régi model,
senki nem figyeli az evalot.

Owner felelőssége lehet:

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

Change process¶

Egyszerű production lifecycle:

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

Nem minden kis skillhez kell minden lépés, de high-risk capabilitynél indokolt.

Shadow testing¶

Új implementation production requesteken futhat úgy, hogy outputját nem használjuk side effectre.

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

Utána compare:

quality
latency
cost
routing/tool behavior

Ez különösen hasznos model migrationnél.

Canary rollout¶

Például:

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

Ha metric romlik:

rollback to v2

Ehhez fontos, hogy a runtime explicit skill versiont route-oljon.

Rollback legyen ténylegesen lehetséges¶

Ha skill update közben output contract is megváltozik, és downstream rendszert migráltuk, rollback már nem biztos, hogy egyszerű.

Ez klasszikus deployment compatibility probléma.

Pattern:

expand contract
 ↓
migrate consumers
 ↓
remove old contract later

ugyanúgy működhet, mint API/database migrationnél.

Deprecation¶

Deprecated skill ne tűnjön el váratlanul.

Registry metadata:

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

A runtime logolhatja, mely caller használja még.

usage telemetry
 ↓
migration list

Skill library design patterns¶

1. Narrow Capability Pattern¶

Egy skill egy koherens responsibility.

Analyze Test Failure

nem:

Do Software Engineering

Előny:

route-olható,
evaluálható,
szűk permission,
könnyebb reuse.

2. Capability Contract + Adapter Pattern¶

Skill dependency:

repository_reader

Runtime adapter:

GitHub connector
local checkout
GitLab API

A skill nem konkrét providerhez kötődik.

3. Evidence-Grounded Result Pattern¶

Semantic claimhez evidence:

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

Ez segíti:

human review,
evaluation,
hallucination detection.

4. Read → Propose → Execute Pattern¶

High-risk operation:

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

Ez erősebb, mint egy mindent intéző write-capable skill.

5. Result Envelope Pattern¶

Explicit outcome:

SUCCESS
PARTIAL_RESULT
INSUFFICIENT_CONTEXT
NOT_AUTHORIZED
TOOL_UNAVAILABLE

A caller nem szabad szöveget parse-ol.

6. Router + Specialists Pattern¶

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

A specialist skill kevesebb contextet és toolt kap.

7. Deterministic Shell Pattern¶

validation
policy
state
retry
idempotency
      ↓
LLM semantic capability
      ↓
validation

A probabilistic magot deterministic software veszi körül.

Ez az egész knowledge base egyik visszatérő architekturális elve.

8. Explicit State Ownership Pattern¶

runtime owns state
skill receives input
skill returns result

ne:

skills share hidden mutable memory

9. Human Escalation Pattern¶

Ha:

high risk
low confidence
conflicting evidence
policy ambiguity

akkor:

ESCALATE_TO_HUMAN

legyen first-class outcome.

10. Budgeted Execution Pattern¶

Skill/agent runtime rendelkezzen:

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

és explicit budget-exceeded outcome-mal.

Anti-pattern: Mega Skill¶

UniversalEnterpriseAgentSkill

minden tudással és minden toolal.

Problémák:

routing ambiguity,
giant prompt,
broad permissions,
nehéz eval,
nagy blast radius,
erős coupling.

Anti-pattern: Hidden Business Logic¶

Business policy csak promptban:

"Refund above 100 EUR needs approval."

ha ez hard invariant, application policyben is legyen.

Anti-pattern: Provider-Coupled Skill¶

Skill contract mentions exact provider SDK classes everywhere.

Ez megnehezíti model/tool migrationt.

Preferáljuk capability abstractiont.

Anti-pattern: Implicit State¶

Skill csak azért működik, mert „előző chatben már elhangzott”.

Reusable contractnál a szükséges input legyen explicit vagy runtime által explicit resolve-olt dependency.

Anti-pattern: Unlimited Permission¶

„Később még jól jöhet” alapon minden toolt megadni rossz security design.

Anti-pattern: No eval, no owner¶

Egy skill, amelynek nincs:

owner
baseline
usage
version

idővel legacy black box lesz.

Anti-pattern: Prompt patch accumulation¶

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

Néha a helyes megoldás:

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

Reference skill package¶

Egy mature skill konceptuálisan így nézhet ki:

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

Ez nem kötelező fizikai folder structure.

Ez egy mental model, hogy milyen concernök léteznek.

Az Agent Skills helye az egész agentic rendszerben¶

Most már összeáll a kép:

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

A skill tehát:

nem agent,
nem tool,
nem workflow,
nem pusztán prompt.

Hanem reusable capability unit, amelyet egy nagyobb runtime használ.

Mikor kész egy skill first production versionje?¶

Minimum checklist:

Takeaways¶

A production skill legyen verziózott, owned és evaluált software artifact.
Contract versiont és implementation versiont érdemes külön kezelni.
Schema-stabil prompt/model változás is okozhat semantic breaking change-et, ezért evaluation kell.
Lifecycle status: experimental → stable → deprecated/disabled.
Controlled rolloutnál shadow, canary és rollback használható.
Deprecationhez replacement és migration visibility kell.
Jó design pattern: narrow capability, adapter, evidence grounding, read/propose/execute, result envelope, router+specialists, deterministic shell, explicit state ownership.
Kerüljük a mega-skillt, hidden business logicot, provider couplingot, implicit state-et és unlimited permissiont.
Az Agent Skill a nagyobb agentic runtime moduláris capability unitja.