---
title: "What You're Actually Writing When You Write a SKILL.md"
source: "https://internals.laxmena.com/p/what-youre-actually-writing-when"
type: articles
ingested: 2026-05-08
tags: [skill-architecture, agent-engineering, context-optimization, progressive-disclosure]
summary: "A SKILL.md-ek nem promptok, hanem loader specifikációk. Három betöltési szint (frontmatter mindig, body triggerre, refs/scripts on-demand) és az építészeti döntések hogyan határozzák meg a kontextus költséget. 3× különbség ugyanazon instrukcióknál pusztán struktúra alapján. Részletes antipattern katalógus és javítási stratégiák."
---

# 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