What You're Actually Writing When You Write a SKILL.md

Szerző: Laxmena (INTERNALS.md #2) Forrás: https://internals.laxmena.com/p/what-youre-actually-writing-when

Alaptézis

A SKILL.md-ek nem promptok, hanem loader specifikációk. Nem statikus szöveget írsz, amit a modell elolvas — hanem leírod, hogy mi kerüljön a kontextusba, mikor, és milyen áron. A szöveg számít, de a struktúra dönti el, mi marad életben a modell munkamemóriájában.

Három betöltési szint (Progresszív Disclosure)

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, szkriptek	Csak amikor a body rájuk mutat	Gyakorlatilag korlátlan

A szintek azért vannak, hogy védjék a kontextusablakot. A progresszív disclosure-el csak a "just in time" végrehajtásért fizetsz, nem a "just in case" instrukciókért.

Konyha Metafora

• Frontmatter = fali hirdetőtábla: receptcímek, egysoros leírások. A séf folyamatosan látja, kicsi, periférikus.
• SKILL.md = teljes receptkártya: csak akkor veszi le, ha vendég rendel.
• References/ = receptgyűjtemény: "lásd Szósz Referencia, 47. oldal" — csak azt az egy oldalt olvassa.
• Scripts/ = konyhai robotgép: nem a kapcsolási rajzot olvassa, hanem inputot ad, outputot kap.

Antipattern Katalógus

1. Frontmatter referencia fájlokon

Ref fájlokra YAML frontmatter-t tenni felpromotálja őket skill-szintre. A pinboard-on 50 bejegyzés jelenik meg 5 helyett. Az agent néha közvetlenül a ref fájlt triggereli a parent skill helyett → 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

1200 soros SKILL.md mindent betölt, akkor is ha csak 20%-a kell. 180 soros gerinc + 3 ref fájl = 20% → 7% kontextus csökkenés. Ugyanaz az output.

Fix: Gerinc + referencia fájlok. A megtakarítás kumulatív — több skill fér el, hosszabb session-ök.

3. Hardcode-olt elérési utak

navigate to modules/web and run build — a kolléga repo-jában packages/frontend/web van. A skill rossz könyvtárban fut, nincs hibaüzenet, csak rossz output.

Fix: Discovery-alapú instrukciók: "keresd meg a build konfigurációt", "azonosítsd a modult a package.json alapján", "olvasd a workspace struktúrát mielőtt feltételezel".

4. Hiányzó Gotchas szekció

Monorepo Turborepo-val: build-et a repo gyökérből kell futtatni, nem modulból. Az agent átlagos priorja: "web modulban vagyok, itt futtatom". Ez 90%-ban jó, de ebben a repo-ban nem.

Fix: Egy sor a Gotchas-ban: "Always run turbo build from the repository root, never from inside a module."

A Gotchas azért létezik, mert az agent alapértelmezései átlagosak, a te környezeted nem az.

5. Eval-ok hiánya (legmélyebb hiba)

Írás skill Sonnet 4.6-on → upgrade Opus-ra → rosszabb output. Sonnet értette a szellemét ("short sentences where it helps"), Opus szó szerint követte (minden mondat 5-7 szó, darabos próza).

A képességesebb modell erősebb priorokkal rendelkezik arról, mi a "jó írás". A saját hangod nem a statisztikai közép. Opus a saját esztétikája felé húzott.

Fix: Paired run eval-ok (skill-lel és anélkül), Golden Set (3-4 teszt prompt), mérhető metrikák (mondathossz, olvashatóság). Minden modellváltásnál és skill editnél újrafuttatni.

Központi Tanulság

Architecture decides cost. The same instructions, in the wrong shape, can consume 3× the context window.

A skill tuned on one model is calibrated to that model's compliance characteristics, not just its capabilities.

"It worked when I tested it" is not evidence. It's the absence of measurement.

Források

• Agent Skills overview, Claude API documentation
• Agent Skills best practices, Claude API documentation
• Equipping agents for the real world with Agent Skills, Barry Zhang, Keith Lazuka, Mahesh Murag, Anthropic Engineering, October 2025