--- title: "SKILL.md Architektúra — Loader Specifikáció, Nem Prompt" category: concept sources: [raw/articles/2026-05-08_skill_architecture_loader_spec.md] created: 2026-05-08 updated: 2026-05-08 tags: [skill-architecture, agent-engineering, context-optimization, progressive-disclosure] aliases: [skill-loader-specification, skill-antipatterns] confidence: high summary: "A SKILL.md-ek nem promptok, hanem loader specifikációk. Három progresszív disclosure szint (frontmatter, body, refs/scripts) határozza meg, mi kerül a kontextusba és mikor. Ugyanazok az instrukciók 3× kontextus különbséget produkálhatnak pusztán strukturális döntések miatt." --- # SKILL.md Architektúra ## Alapigazság > A SKILL.md nem prompt, hanem **loader specifikáció**. Te nem statikus szöveget írsz, amit a modell elolvas — hanem leírod, hogy *mi* kerüljön a kontextusba, *mikor*, és *milyen áron*. Ez a különbségtétel mindent megváltoztat. Ugyanazok az instrukciók, rossz struktúrában, **3× annyi kontextust** fogyasztanak. A büntetés kumulatív: minden telepített skillre és minden körre érvényesül. ## Progresszív Disclosure — Három Betöltési Szint A skillek három szinten töltődnek be, eltérő időzítéssel és költséggel: | Szint | Tartalom | Mikor töltődik | Költség | |-------|----------|---------------|---------| | **1. Frontmatter** | Név + leírás (YAML) | **Minden körben**, mindig | ~100 token/skill | | **2. SKILL.md body** | Procedurális instrukciók | Csak amikor a skill **triggerelődik** | Javasolt max **500 sor** | | **3. Refs + Scripts** | Hivatkozott fájlok, futtatható kód | Csak amikor a body **rájuk mutat** | Gyakorlatilag korlátlan | ### Miért fontos? A frontmatter az **útválasztás** mechanizmusa. Ha a leírás rossz, a skill sose triggerelődik — vagy rosszkor triggerelődik. Ez a **legfontosabb szint**, amit jól kell csinálni. A body csak akkor kerül be, amikor az agent úgy dönt, a skill releváns. Ha itt van minden (monolit), akkor minden betöltődik, akkor is ha a feladatnak csak 20%-ára van szükség. A refs/scripts on-demand: a body hivatkozik rájuk, az agent csak azt az egy fájlt olvassa vagy futtatja. **A forráskód nem kerül a kontextusba**, csak az output. ## Konyha Metafora - **Frontmatter** = Fali hirdetőtábla receptcímekkel. A séf folyamatosan látja, kicsi, periférikus. Mindig elérhető. - **SKILL.md** = Teljes receptkártya. Csak akkor veszi le, ha vendég rendel. Különben zavarná a munkát. - **References/** = Receptgyűjtemény: "lásd Szósz Referencia, 47. oldal". Csak azt az egy oldalt olvassa, nem az egész könyvet. - **Scripts/** = Konyhai robotgép. Nem a kapcsolási rajz kell, hanem input→output. Kód nem kerül kontextusba. ## Antipattern Katalógus ### 1. ❌ Frontmatter referencia fájlokon Ref fájlokra YAML frontmatter-t tenni → felpromotálja őket skill-szintre. A pinboard-on 50 entry jelenik meg 5 helyett. Az agent néha közvetlenül a ref fájlt triggereli a parent skill nélkül → **kontextus nélküli, hibás output**. ✅ **Fix:** Töröld a frontmatter-t minden referencia fájlból. Nem skillek, hanem fejezetek. ### 2. ❌ Monolitikus skill (minden egy fájlban) 1200 soros SKILL.md → minden betöltődik, akkor is ha csak 20% kell. Kontextus: 20% → lassú, drága, session-ök rövidebbek. ✅ **Fix:** 180 soros gerinc + 3 referencia fájl. Kontextus 20% → 7%. Ugyanaz az output. ### 3. ❌ Hardcode-olt elérési utak `cd modules/web && npm run build` — másik gépen `packages/frontend/web`. Nincs hiba, csak rossz output. **Akkor derül ki, amikor megosztod.** ✅ **Fix:** Discovery-alapú instrukciók. "Keresd meg a build konfigurációt", "azonosítsd a modult a package.json alapján". ### 4. ❌ Hiányzó Gotchas Turborepo: build-et **repo gyökérből** kell futtatni, nem modulból. Agent prior: "ebben a modulban vagyok, itt futtatom" — átlagosan jó, itt rossz. ✅ **Fix:** Egy sor a Gotchas-ban: "Always run turbo build from repo root". A környezeted nem átlagos, az agent priorjai igen. ### 5. ❌ Eval-ok hiánya Sonnet → Opus upgrade: írás skill rosszabb lett. Sonnet értette a szellemét, Opus szó szerint követte. **A képességesebb modell erősebb priorjai felülírják a személyes voice-t.** ✅ **Fix:** Paired run eval-ok, Golden Set (3-4 prompt), mérhető metrikák. Minden modellváltásnál újrafuttatni. > "It worked when I tested it" is not evidence. It's the absence of measurement. ## Alkalmazás a Tollaskígyó Rendszerre ### Saját skillek állapota és teendők | Skill | Frontmatter OK? | Struktúra | Gotchas? | Eval? | Teendő | |-------|----------------|-----------|----------|-------|--------| | `llm-wiki` | ✅ Jó | Monolit (~200 sor) | ❌ | ❌ | Ref fájlokba szétbont, Gotchas | | `orchestrator` | ✅ Jó | Közepes | ❌ | ❌ | Gotchas hozzáadása | | `bitcoin-knowledge-base` | ✅ Jó | Jól strukturált | ❌ | ❌ | Gotchas hozzáadása | ### Azonnali javítások 1. **SOUL.md + AGENTS.md mint "rendszerszintű Gotchas"** — ezek tartalmazzák a környezet-specifikus eltéréseket (magyar nyelv, podcast canonical nevek, workspace elérési utak) 2. **Frontmatter audit** — nincs tiltott frontmatter ref fájlokon 3. **Gotchas szekció** minden skillben 4. **Monolitikus skill-ek szétbontása** referenciákba ahol lehet ## Források - [What You're Actually Writing (INTERNALS.md #2)](skill-architecture.md) (Laxmena, 2026) - Agent Skills overview, Claude API documentation - Agent Skills best practices, Claude API documentation - Equipping agents for the real world with Agent Skills (Zhang, Lazuka, Murag, Anthropic, 2025)