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¶
- 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)
- Frontmatter audit — nincs tiltott frontmatter ref fájlokon
- Gotchas szekció minden skillben
- Monolitikus skill-ek szétbontása referenciákba ahol lehet
Források¶
- What You're Actually Writing (INTERNALS.md #2) (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)