Skill Anatomy and Contracts

Miért kell contract egy skill köré?

Egy skill akkor lesz jól újrahasznosítható, ha nem csak azt tudjuk róla, hogy „van egy jó promptja”, hanem azt is, hogy:

• mire való,
• milyen inputot vár,
• milyen outputot ad,
• milyen toolokra vagy adatokra támaszkodik,
• milyen korlátai vannak,
• mi számít sikernek vagy hibának.

Ez nagyon hasonló ahhoz, ahogy egy normális software componentet vagy API-t tervezünk.

caller
  ↓
Skill Contract
  ↓
implementation
  ↓
model / tools / retrieval / code

A caller lehet agent, workflow vagy közvetlen application service.

Egy skill fő részei

Hasznos mental model:

Skill
├── identity / metadata
├── purpose / responsibility
├── input contract
├── instructions
├── knowledge / context policy
├── tool dependencies
├── output contract
├── constraints / permissions
├── success / failure semantics
└── evaluation criteria

Nem minden platform fogja ezt pontosan ilyen struktúrában reprezentálni, de tervezéskor érdemes ezeket külön kérdésként kezelni.

1. Identity és metadata

Minimum legyen világos:

name
version
description

Például:

name: review_pull_request
version: 1.2
description: Identify material correctness, architecture and regression risks in a pull request.

A description nem csak dokumentáció lehet. Később skill discovery/routing során a runtime akár ebből is döntheti el, melyik skill releváns.

Ezért rossz description:

Helps with GitHub things.

Jobb:

Reviews a pull request for correctness, architecture risks, regressions and missing tests. Read-only.

2. Purpose és responsibility

A skillnek legyen egy világos feladata.

Például:

Given a pull request and repository context, identify material risks and return structured review findings.

Ez meghatározza a boundaryt.

A skill nem:

• merge-eli a PR-t,
• nem javítja automatikusan a kódot,
• nem deployol,
• nem ír release note-ot.

Ezek lehetnek más skill-ek vagy workflow-lépések.

A responsibility leírása azért fontos, mert az LLM természetes hajlama lehet „segítőkészen” továbbmenni a feladatnál.

3. Input contract

A callernek tudnia kell, milyen adatot kell átadni.

Például logikai schema:

{
  "repository": "org/payment-service",
  "pull_request_number": 184,
  "review_focus": ["correctness", "architecture", "tests"]
}

Az input contract megmondhatja:

• required mezők,
• optional mezők,
• típusok,
• enumok,
• limitációk,
• defaultok.

Például:

pull_request_number: positive integer
review_focus: subset of allowed review dimensions
repository: validated repository identifier

Az input contract nem csak az LLM miatt hasznos. A runtime már modellhívás előtt kiszűrhet hibás kéréseket.

invalid input
    ↓
application validation
    ↓
reject

nem pedig:

invalid input
    ↓
LLM tries to guess what user meant

4. Instructions

Az instructions definiálja a skill semantic behaviorét.

Például:

Review only material issues.
Prioritize correctness over style.
For every finding, cite concrete evidence from the diff or retrieved file.
Do not invent repository state that was not supplied or retrieved.

Ez különbözik az inputtól.

instructions = hogyan dolgozz
input        = min dolgozz

A stabil instructions verziózott skill-rész lehet.

A task-specific kérés viszont runtime input:

Focus especially on backwards compatibility in the REST API.

5. Knowledge és context policy

A skill contract nem feltétlenül magát a teljes tudást tartalmazza. Inkább megmondhatja, milyen tudás kell és honnan jöhet.

Például:

Static knowledge:
- internal review principles
- severity definitions

Runtime context:
- current PR diff
- relevant source files
- tests
- repository-specific AGENTS.md

Ez fontos különbség:

A skill contract mondhatja meg, milyen contextre van szükség; a runtime felelőssége lehet annak beszerzése.

Például:

Skill requires: current PR diff
        ↓
Runtime resolves dependency
        ↓
GitHub connector / API

6. Tool dependencies

A skillnek jeleznie kellhet, milyen capabilitykre támaszkodik.

Például:

required capabilities:
- read_pull_request_diff
- read_repository_file

optional capabilities:
- read_test_results

Érdemes task-level dependencyban gondolkodni, nem feltétlen konkrét providerben.

Gyengébb coupling:

requires GitHubToolV3.fetch_file()

Jobb absztrakció:

requires repository_file_reader

A runtime dönti el, hogy ezt GitHub connector, local checkout vagy más backend valósítja meg.

Ez software architecture szempontból lényegében port/adaptor gondolkodás.

7. Output contract

Ha a skill eredményét alkalmazás fogyasztja, ne csak szabad szövegre támaszkodjunk.

Például:

{
  "findings": [
    {
      "severity": "HIGH",
      "location": "src/payment/RetryService.java:87",
      "summary": "Retry can duplicate a non-idempotent payment request",
      "evidence": "The retry path calls charge() without an idempotency key."
    }
  ],
  "overall_risk": "HIGH",
  "summary": "The PR introduces a duplicate-payment risk."
}

Ezután az app tud:

result.findings
result.overall_risk

alapon dolgozni.

Ahogy a Foundationsnél:

A schema a struktúrát tudja garantálni, nem a semantic truthot.

Az output attól még lehet rossz következtetés, hogy valid JSON.

8. Constraints és permissions

A skill contract mondja meg a megengedett viselkedést.

Példa:

mode: read-only
allowed repositories: current repository only
allowed tools:
  - diff reader
  - file reader
forbidden actions:
  - modify code
  - merge PR
  - post comment

Viszont a fontos architekturális szabály:

A permissiont ne csak prompt/instruction enforce-olja.

A runtime ténylegesen csak az engedélyezett toolokat adja át, vagy tool execution előtt authorizationt végez.

Skill contract says read-only
          +
Runtime exposes only read tools

A kettő együtt erősebb, mint pusztán:

"Please do not modify anything."

9. Success és failure semantics

Egy reusable capabilitynél definiálni kell, milyen outcome-ok léteznek.

Nem csak:

success / exception

hanem például:

SUCCESS
INSUFFICIENT_CONTEXT
TOOL_UNAVAILABLE
NOT_AUTHORIZED
INVALID_INPUT
PARTIAL_RESULT

Például egy deployment health skillnél:

{
  "status": "INSUFFICIENT_CONTEXT",
  "missing": ["production deployment state"]
}

jobb, mint amikor a modell megpróbálja kitölteni a hiányzó adatot találgatással.

A failure semantics tudatosítása közvetlenül csökkentheti a hallucination pressure-t.

10. Evaluation criteria

Ha a skill külön artifact, külön is kell tudnunk értékelni.

Például PR review skill:

- megtalálja-e a valódi critical bugokat?
- mennyi false positive-ot ad?
- evidence-grounded-e minden finding?
- helyesen használja-e a toolokat?
- tartja-e a read-only boundaryt?
- mennyi a latency és cost?

Ez később külön fejezet lesz, de már a contract tervezésekor érdemes tudni, mi számít jónak.

Contract vs implementation

Ez az egyik legfontosabb különválasztás.

Skill Contract
├── purpose
├── inputs
├── outputs
├── constraints
└── required capabilities

Implementation A
├── model X
├── prompt v4
└── GitHub tools

Implementation B
├── model Y
├── prompt v9
└── local repository tools

A caller szempontjából mindkettő ugyanazt a capabilityt valósíthatja meg.

Ez loose couplinget ad.

Skill contract vs application configuration

Nem mindent kell a skillbe tenni.

Tipikusan skill contract

• capability neve és célja,
• semantic instructions,
• required input,
• output schema,
• required tool capability,
• permission expectation,
• success/failure semantics.

Tipikusan runtime/application configuration

• konkrét model provider,
• API endpoint,
• secret,
• production timeout,
• tenant-specific authorization,
• konkrét GitHub token,
• rate limit,
• feature flag,
• deployment environment.

Például ne legyen a skillben:

GitHub token = ghp_...

vagy:

Production DB hostname = ...

A skill leírhatja:

requires repository_read capability

A runtime injektálja a valódi credentialt és adaptort.

Példa: Incident Triage Skill

Egy konceptuális contract:

name: incident_triage
version: 2
purpose: Classify an incident and identify the most relevant next diagnostic action.

input:
  incident_text: string
  service: string
  environment: enum[dev, staging, production]

required_capabilities:
  - observability_query

output:
  severity: enum[SEV1, SEV2, SEV3, SEV4]
  suspected_area: string
  evidence: list[string]
  next_action: string
  confidence: number

constraints:
  read_only: true
  do_not_restart_services: true

A runtime adhat neki:

Datadog adapter

majd később:

Grafana adapter

anélkül, hogy a triage capability jelentése megváltozna.

Contract evolution

Ha egy output contractot megváltoztatunk:

v1:
severity
summary

→

v2:
severity
summary
evidence[]
recommended_action

az caller oldalon breaking change is lehet.

Ezért a skill contractokat érdemes ugyanúgy kezelni, mint más API contractokat:

• verziózás,
• compatibility,
• migration,
• regression testing.

Anti-pattern: promptból implicit contract

Gyenge:

"Review this and tell me if anything looks bad."

A caller nem tudja:

• milyen szempontok szerint review-zik,
• milyen inputot igényel,
• milyen outputot kap,
• milyen toolokat használhat,
• mit jelent, ha nincs elég adat.

Ez POC-nál lehet elég. Reusable system capabilitynél nem.

Anti-pattern: domain model közvetlenül az LLM interface-e

Nem biztos, hogy jó ötlet az alkalmazás belső, komplex domain objectjét közvetlenül modell-outputként használni.

Például:

LLM JSON
  ↓
SkillResult DTO
  ↓
validation / mapping
  ↓
Domain object

általában tisztább, mint:

LLM
 ↓
directly constructs Payment domain aggregate

Az LLM-facing contract lehet egyszerűbb és provider-independent, az application mapping pedig determinisztikus.

Takeaways

• Egy reusable skillnek érdemes explicit contracttal rendelkeznie.
• A contract fő részei: purpose, input, instructions, context policy, tools, output, constraints, failure semantics és evaluation.
• Skill interface ≠ skill implementation.
• A concrete model, credential, provider és runtime timeout általában application configuration, nem skill knowledge.
• Tool dependencyt érdemes capabilityként megfogalmazni, nem túl korán konkrét providerhez kötni.
• A structured output formális contractot ad, de semantic correctnesset továbbra is evaluálni kell.
• A failure outcome legyen explicit; a „nincs elég adat” legitim eredmény.
• A skill contract ugyanúgy verziózandó és karbantartandó lehet, mint egy API contract.