Skill Architecture¶

A skill egy reusable capability package, amely segít az agentnek egy feladatosztályt konzisztensen végrehajtani. Architecture szempontból nem csak az a kérdés, mit tartalmaz, hanem az is, hol éljen, mitől függjön, és hogyan discoverolja/executálja a runtime anélkül, hogy az egész application egyetlen agent frameworkhöz kötődne.

Hasznos mental model:

Skill Contract
├── purpose
├── input/output contract
├── instructions
├── context requirements
├── allowed capabilities
├── policy requirements
├── evaluation contract
└── version
        ↓
Skill Runtime Adapter
        ↓
Application Ports / Capabilities
        ↓
Infrastructure Adapters

A skill reusable behaviort ír le. Nem válhat rejtett service layerré, amely megkerüli az applicationt.

Skill vs tool vs application use case¶

Application use case
= deterministic business operation

Tool / capability
= operation the runtime can execute

Skill
= reusable guidance + contracts for solving a task, potentially using multiple capabilities

Példa:

ReviewPullRequest skill
   ├── read diff capability
   ├── read tests capability
   ├── architecture-review instructions
   └── structured findings output

A skill nem tulajdonolja a GitHub access-t. Application capabilityken keresztül kap repository data-t.

Hol éljenek a skillek?¶

Egy global dumping ground könnyen kialakul:

skills/
├── billing.md
├── support.md
├── github.md
├── legal.md
└── everything_else.md

Domain-specific skill inkább a domain/business capability közelében legyen:

support/
├── application/
├── domain/
├── skills/
│   ├── triage_ticket/
│   └── draft_response/
└── infrastructure/

agent_runtime/
├── skill_registry.py
└── skill_executor.py

A shared runtime tudja, hogyan discoveroljon és execute-oljon skillt; a support module tulajdonolja a support-specific semanticset.

Truly generic cross-cutting skill — például egyszerű summarization — mehet shared AI capability module-ba.

Skill descriptor¶

A skillnek érdemes machine-readable descriptorral rendelkeznie:

{
  "id": "support.triage_ticket",
  "version": "2.1",
  "input_schema": "TicketTriageInputV2",
  "output_schema": "TicketTriageResultV2",
  "required_capabilities": [
    "support.ticket.read",
    "customer.profile.read"
  ],
  "risk": "READ_ONLY",
  "owner": "support"
}

Így a runtime execution előtt compatibilityt és policyt ellenőrizhet.

Skill porttól függjön, ne providertől¶

Rossz:

TriageSkill
   ↓
Zendesk SDK

Jobb:

TriageSkill
   ↓
TicketReader capability / port
   ↓
Zendesk adapter

Ugyanez code reviewnál:

CodeReviewSkill
   ↓
RepositoryReader
   ↓
GitHub / GitLab / local repo adapter

Ez testable és replaceable marad.

Skill registry és discovery¶

Skill Registry
├── code.review
├── support.triage
├── support.response_draft
├── billing.explain_invoice
└── incident.analyze

A descriptor tartalmazzon annyi metadata-t, hogy candidate filteringhez ne kelljen minden full instructiont contextbe tölteni:

id
version
short description
input type
output type
required capabilities
risk class
domain/owner
cost hints
supported runtime/model features

A runtime előbb determinisztikusan szűkítsen, és csak akkor használjon model-assisted routingot, ha semantic selection kell.

Skill implementation vs runtime configuration¶

Válaszd szét a stable skill definitiont és deployment-specific configot.

Stable:

Review pull requests for correctness, architecture and backward compatibility.

Runtime config:

model = gpt-x
max_tokens = 8000
repository = foo/bar
timeout = 60s

Ugyanaz a skill más modellel, budgettel vagy providerrel is futhat a semantic contract megváltoztatása nélkül.

Input/output contract¶

Skill ne kapjon egy unstructured bag of state-et, ha nincs rá valódi szüksége.

Preferáld:

class ReviewPullRequestInput:
    repository_id: str
    pull_request_id: int
    review_focus: list[str]

class ReviewPullRequestResult:
    findings: list[Finding]
    summary: str
    confidence: float

A runtime canonical state-ből mapeli a skill inputot, majd a resultot vissza application state-be.

Skill dependencyk¶

Skill függhet:

capabilities
domain knowledge
retrieval sources
deterministic services
model features

A mély skill-to-skill graphokkal óvatosan:

Skill A
 ↓
Skill B
 ↓
Skill C
 ↓
Skill D

Ez rejtett control flow-t, budget multiplicationt és circular dependency risket hoz.

Több substantial skill orchestrationje inkább explicit workflow/runtime layeren történjen:

Workflow / agent runtime
   ├── Skill A
   ├── Skill B
   └── aggregation step

Skill execution adapter¶

A runtime a skill definitiont provider-specific model requestté fordítja:

Skill contract
      ↓
Context builder
      ↓
Skill executor
      ↓
Model gateway
      ↓
Provider API

Provider-specific tool-call syntax, response parsing és tracing infrastructure concern.

Versioning¶

Legalább három verzió különböztethető meg:

Skill contract version
Skill implementation/instruction version
Runtime/provider version

Wording change contractváltozás nélkül implementation revision lehet.

Ha viszont:

findings: list[str]

helyett:

findings: list[Finding]

jön, az contract change.

Trace-ben rögzítsd a verziókat, hogy regresszió konkrét kombinációhoz köthető legyen.

Compatibility és rollout¶

Normál software rollout patternök működnek:

offline eval
   ↓
shadow / replay
   ↓
canary
   ↓
production
   ↓
monitor
   ↓
rollback if needed

Ne írj felül production skillt úgy, hogy később ne lehessen megmondani, melyik verzió adott egy decisiont.

Permission architecture¶

A skill deklarálja, milyen capabilityket kérhet, de ne tartson saját permanent credentialt.

Skill declares requirement
        ↓
Runtime resolves allowed capability
        ↓
Policy engine checks current run/user
        ↓
Execution adapter receives scoped credential

Ez least privilege és megakadályozza, hogy a skill package secret container legyen.

Context ownership¶

Skill deklarálhat context requirementet:

needs:
- pull request diff
- repository architecture guide
- failing test summary

De a context builder resolve-olja és assemble-olja ezeket. A skill ne építsen saját rejtett context universe-t random external scrapingből.

Így provenance, security policy és observability megmarad.

Evaluation a skill contract része¶

Reusable skillnél definiáld, hogyan mérjük a qualityt.

PR review skillnél:

correctness finding precision
critical issue recall
false-positive rate
schema validity
tool-call efficiency
latency
cost

Skill package példa¶

skills/code_review/
├── skill.yaml
├── instructions.md
├── examples/
│   ├── good_review.md
│   └── missed_bug.md
├── schemas/
│   ├── input.json
│   └── output.json
├── knowledge/
│   └── review_principles.md
└── evals/
    └── cases.yaml

Provider-specific code nem szükséges ebbe a package-be.

Gyakori anti-patternök¶

One giant skill az egész applicationre.
Skill közvetlenül model provider SDK-t hív.
Hidden tool access, amelynek riskje nincs deklarálva.
Recursive skill graph explicit orchestration helyett.
Skill business logic replacementként.
Everything is a skill — egyszerű deterministic transformation is LLM wrapperbe kerül.

Engineering takeaways¶

A skill versioned reusable behavior contract, nem magic prompt file.
Domain-specific skillnek világos module ownership kell.
Skill application capability/porttól függjön, ne provider SDK-tól.
Discovery metadata legyen olcsón betölthető; full instruction csak selected skillhez kell.
Significant composition explicit orchestrationban legyen.
Skill capability requirementet deklarál; runtime scoped access-t ad.
Context assembly, provider integration és credential runtime/infrastructure responsibility.
Eval, versioning és rollout teszi a skillt maintainable software artifacttá.