Jak psát AGENTS.md, skilly a zadání pro AI agenty

S každým novým modelem stárnou i instrukce, které jste pro AI agenty během práce nasbírali. Co dřív pomáhalo, dnes může brzdit. Dlouhé soubory zabírají kontext, příliš široké popisy spouštějí nevhodné skilly a přísné zákazy můžou agenta zastavit dřív, než je práce hotová.

OpenAI to 11. září 2026 rozebralo v článku o skillech a promptech pro model GPT-6 Astra. Píše hlavně o Codexu, podobné zásady ale uvádí i dokumentace Claude Code.

Co agent čte vždycky a co jen někdy

Codex před začátkem práce načte globální AGENTS.md ze složky ~/.codex a pak soubory AGENTS.md na cestě od kořene projektu k aktuální složce. Claude Code podobně načítá CLAUDE.md na začátku každého sezení. Oba navíc agentovi předají název a popis každého nainstalovaného skillu, aby poznal, kdy který použít.

Celý návod skillu, soubor SKILL.md, agent načte až ve chvíli, kdy skill vybere. Další soubory ve složce skillu, třeba podrobné postupy nebo skripty, otevře jen tehdy, když je úkol potřebuje. Tomuto postupnému načítání se říká progressive disclosure. Popisuje ho otevřená specifikace Agent Skills, ze které vychází Codex i Claude Code.

Zvětšit schéma

Řádky v AGENTS.md a popisy skillů tedy zabírají kontext v každém úkolu, i když s ním nesouvisejí. Návod skillu a další soubory přijdou na řadu, jen když se hodí. Do AGENTS.md proto patří jen to, co se týká skoro každé práce v projektu.

Popis skillu má říct, kdy ho použít

Popisy všech skillů se musí vejít do omezeného prostoru. Codex jim vyhrazuje nejvýš 2 % kontextového okna modelu. Když máte skillů hodně, nejdřív zkracuje jejich popisy a u velkých sad může některé skilly ze seznamu vynechat. Claude Code počítá s 1 % kontextu, popisy také zkracuje, a když se nevejdou, vynechá nejdřív popisy skillů, které používáte nejméně. Agent pak z každého popisu vidí jen část a hůř se rozhoduje, který skill vybrat.

Časté jsou i popisy, které si odporují nebo přehánějí, kdy se má skill použít. Agent pak načte návod, který úkolu nepomůže. OpenAI ukazuje rozdíl na skillu pro migrace databáze:

• Příliš široký popis: „Vytváří a ověřuje migrace schématu Postgres. Použij při práci s databázemi, dotazy, modely nebo ukládáním dat.“

• Přesný popis: „Vytváří a ověřuje migrace schématu Postgres. Použij, když přidáváš či měníš migraci, nebo když kontroluješ její nasazení.“

První popis přitáhne skill ke každé práci s databází, druhý jen k migracím. Hlavní použití a klíčová slova dejte na začátek, aby je agent viděl i ve zkráceném popisu. Pište slovy, která při zadávání práce opravdu používáte.

Z dlouhého skillu udělejte rozcestník

Načtený skill zabírá kontext. Agent se tak dřív dostane k bodu, kdy musí starší část konverzace zhustit do shrnutí, a navíc čte pokyny, které se k úkolu nemusí hodit. Když skill pokrývá víc postupů, nechte v SKILL.md jen účel, hranice a odkazy na podrobné dokumenty ve složce references/ nebo na skripty. Agent pozná, kam se podívat, a zbytek nečte. Krátký skill s jedním postupem rozcestník nepotřebuje.

Mnoho skillů vzniklo jako podrobný itinerář nebo recept. Modely dnes lépe chápou nuance a nejednoznačné zadání, takže postup rozepsaný krok za krokem může výsledek zhoršit tam, kde dřív pomáhal. Aktualizovaný skill-creator v Codexu proto vychází z toho, že agent je schopný. Do skillu patří jen informace, které změní jeho rozhodnutí nebo zlepší práci. Přesné kroky a absolutní formulace si nechte pro situace, kde jde o správnost, bezpečnost, oprávnění nebo opravdu křehký postup.

Skilly uložené v repozitáři čtou i agenti kolegů, kteří můžou používat jiný model. Podle OpenAI může pokyn, který pomáhá Solu nebo Luně, Astru zbytečně svazovat. Text OpenAI vyšel před vydáním GPT-6 Sol a Luny 22. září, mluví tedy o modelech GPT-5.6. Průvodce OpenAI k modelům GPT-6 vychází z chování Astry a doporučuje pokyny ověřit na modelu, který opravdu používáte. Čím se nové modely liší, porovnáváme v článku GPT-6 Sol a Luna proti Opusu 5.5.

V AGENTS.md nechte jen pravidla, která pořád platí

AGENTS.md se uplatní při každé práci v repozitáři, takže se u každého pokynu vyplatí zeptat, jestli ho agent ještě potřebuje. Codex navíc soubory AGENTS.md skládá jen do výchozího limitu 32 KiB a další už nepřidá. Claude Code doporučuje méně než 200 řádků na jeden CLAUDE.md, protože delší soubory zabírají víc kontextu a agent se jimi řídí hůř.

Typickým přežitkem je povinné čtení dokumentace před každou změnou. Na opravu překlepu je to zbytečné a Astra si podle OpenAI zjistí sama, co potřebuje přečíst. Odkaz na dokument pomáhá, když říká, kdy ho otevřít:

• Špatně: „Před každou úpravou si přečti architecture.md, database.md a deployment.md.“

• Lépe: „Pro hranice služeb použij architecture.md, pro změny schématu database.md a při přípravě nasazení deployment.md.“

Tak jsme upravili i AGENTS.md našeho webu a CRM. Místo dlouhých pravidel obsahuje tabulku, která ke každému typu práce přiřazuje jeden dokument: design, blog, CRM, klientský portál nebo měření a reklamu. Při úklidu 17. září 2026 se soubor zkrátil z 271 řádků na 41. Podrobnosti zůstaly v dokumentech, které agent otevře u souvisejícího úkolu.

Podobně zastaraly výzvy ke spouštění testů, které starší modely potřebovaly. Astra podle OpenAI kontroluje práci sama a stejné pokyny u ní vedou ke zbytečnému testování. Je ale opatrnější v tom, jak daleko úkol dotáhnout, a pomůže jí výslovné povolení pro postup, o kterém víte, že je bezpečný. OpenAI uvádí tento příklad:

Lokální testy používají jednorázová testovací data a nemají přístup k produkci. Spusť je, oprav chyby způsobené požadovanou změnou a dotčené testy spusť znovu, aniž by ses u každého kroku ptal na souhlas.

Pozornost si zaslouží i hranice. Pokud vám dřívější model dělal věci bez dovolení, možná jste do instrukcí přidali ostré „vždy se nejdřív zeptej“. OpenAI upozorňuje, že Astra má lepší úsudek o tom, co je bezpečné, a takové formulace může brát příliš vážně. Zastaví se pak tam, kde byste byli rádi, kdyby pokračovala. Nechte hranice, které mají konkrétní důvod, třeba produkci, platby, mazání dat a odesílání zpráv. Obecné zákazy přepište nebo smažte.

Zvětšit schéma

Když agent přesto čeká na souhlas tam, kde nemá, zeptejte se proč. Průvodce OpenAI k modelům GPT-6 radí nechat model jmenovat soubor a ocitovat pokyn, kvůli kterému se zastavil. Takto najdete skryté a protichůdné pokyny i ve větší sadě skillů a souborů.

AGENTS.md také není README. README je pro lidi: jak projekt spustit, co dělá a jak přispět. AGENTS.md dává agentovi příkazy, konvence, postup testování a informace o tom, co nesmí rozbít. Týmu se hodí i krátký slovník pojmů, které u vás znamenají něco jiného než jinde.

Claude Code čte AGENTS.md přímo od verze 2.1.277, a to jen tehdy, když v projektu chybí CLAUDE.md. Máte-li oba soubory, načte ve výchozím nastavení jen CLAUDE.md. Nejjednodušší je držet pravidla v AGENTS.md a do CLAUDE.md napsat jediný řádek @AGENTS.md, který jeho obsah vloží. Codex i Claude Code pak čtou stejná pravidla. Tak to máme i my.

Zadání s jasným koncem

Kdo je zvyklý na GPT-5.6 Sol, který na jedno zadání pracuje dlouho, může u Astry narazit na opatrnost. Někdy dokončí první verzi a vrátí se pro kontrolu, i když práce ještě zbývá. OpenAI proto radí popsat, co znamená hotovo, ještě před začátkem. Když k úkolu patří spuštění, kontrola výsledku a oprava chyb, napište to do zadání.

Požadavek zastavit se po první verzi táhne model k dřívějšímu konci, takže zvažte, jestli to rozhodnutí opravdu potřebujete dělat vy. Když chcete, aby agent zkoumal i po prvním průchodu, řekněte, co má prozkoumat a kde skončit. Zastávku si nechte u kroků, které nejdou vzít zpět nebo zasáhnou jiné lidi, například u nasazení, odeslání zprávy nebo změn ve sdíleném repozitáři.

• Bez konce: „Oprav kontaktní formulář.“

• S jasným koncem: „Kontaktní formulář na mobilu neodešle zprávu. Najdi příčinu a oprav ji. Hotovo je, až formulář v prohlížeči funguje na šířce 390 px i na desktopu a projdou jeho testy. Na produkci nic nenasazuj.“

Druhé zadání má cíl, konec a jedinou hranici, na které záleží. Podrobný seznam kroků nepotřebuje. Návod OpenAI k psaní promptů radí totéž: začít výsledkem, přidat jen užitečný kontext a hlídat jednu nebo dvě hranice, které brání skutečným problémům. Víc o předávání celých úkolů píšeme v článku GPT-6 Astra: zadejte práci a běžte dělat něco jiného.

Prompt pro vašeho agenta

OpenAI na konci svého článku radí nechat úklid na samotném modelu a požádat ho o audit podle popsaných zásad. Následující prompt je napsaný pro Codex, Claude Code i další agenty, kteří pracují se soubory projektu.

Theo z kanálu t3.gg ve videu o svých AGENTS.md a skillech vysvětluje, proč je nedal ke zkopírování. Cenné jsou podle něj hlavně důvody, které k jednotlivým pravidlům vedly. Prompt proto nepřenáší cizí pravidla. Vychází z vašich souborů, vaší historie a oprav, které agentovi opakovaně děláte.

Projdi instrukce, které čteš při práci v tomto projektu,
a ukliď je. Chci méně textu v kontextu, pravidla, která
pořád platí, a skilly, které se spustí ve správnou chvíli.

1. Najdi všechny soubory s instrukcemi: AGENTS.md a CLAUDE.md
   v projektu i podsložkách, pravidla editoru (například
   .cursor/rules nebo .claude/rules), skilly projektu
   (.agents/skills, .claude/skills) a globální instrukce
   (~/.codex/AGENTS.md, ~/.claude/CLAUDE.md, ~/.agents/skills,
   ~/.claude/skills). Rozliš, co se načítá vždy a co jen
   podle úkolu.

2. U každého pravidla posuď, jestli mění tvoje rozhodnutí.
   Smaž pravidla, která popisují, co zvládneš sám, třeba
   spouštění testů. Povinné čtení dokumentů před každou
   úpravou nahraď odkazem, který říká, kdy dokument otevřít.
   Obecné zákazy a žádosti o souhlas zuž na konkrétní
   hranice, třeba produkci, platby, mazání dat a odesílání
   zpráv. Sluč opakovaná pravidla a popis projektu určený
   lidem přesuň do README. Rozpory, o kterých nemůžeš
   rozhodnout sám, zapiš jako otázky.

3. Popis každého skillu zkrať na jednu až dvě věty: co skill
   dělá a kdy ho použít, hlavní použití na začátku. Popis
   nesmí přitahovat úkoly, pro které skill není. Z dlouhého
   SKILL.md udělej rozcestník: nech v něm účel, hranice
   a odkazy, podrobnosti přesuň do references/.

4. Pokud máš přístup k historii našich sezení (Codex ji
   ukládá do ~/.codex/sessions, Claude Code do
   ~/.claude/projects), projdi posledních 20 až 30 konverzací
   v tomto projektu. Najdi místa, kde jsem tě opravoval nebo
   kde jsi zbytečně čekal na souhlas, a zjisti, které pravidlo
   za tím stálo. Hesla, tokeny a osobní údaje z historie
   nikam nepřepisuj.

5. Měň jen soubory s instrukcemi, skilly a README
   v projektu a zachovej jejich jazyk. Nesoulad v kódu nebo
   v ostatní dokumentaci jen zapiš do přehledu. Pokud chybí,
   přidej do AGENTS.md větu, že pokyny v mém zadání mají
   přednost před skilly. Když zápis do některé složky nejde,
   pošli změny jako patch v odpovědi. Globální soubory mimo
   projekt neměň.

Hotovo je, až budou úpravy uložené a v odpovědi, ne v souboru,
mi pošleš krátký přehled: co jsi smazal, přesunul nebo přepsal
a proč, a návrhy změn globálních souborů. Na konec napiš
otázky, o kterých musím rozhodnout já. Necommituj a nepushuj.

Prompt jsme vyzkoušeli v Codexu na ukázkovém projektu se zastaralým AGENTS.md a příliš širokým skillem. Agent zrušil plošné žádosti o souhlas i povinné testy, čtení dokumentů navázal na typ úkolu a z CLAUDE.md udělal import AGENTS.md. Popis projektu přesunul do README. Globální soubory nechal beze změny a jejich úpravy jen navrhl. Codex ve výchozím sandboxu drží složky .agents a .codex jen pro čtení, takže úpravu skillu poslal jako patch v odpovědi. Změny skillů v těchto složkách mu musíte schválit. Omezení na instrukce, skilly a README jsme doplnili po prvním běhu, ve kterém agent upravil i další dokumentaci a založil soubory se zprávou.

Výsledek si projděte v diffu jako každou jinou změnu. Agent může smazat pravidlo, jehož důvod v souboru chybí. Takový důvod k pravidlu dopište, aby ho příští úklid nesmazal znovu.

Jak si postavit vlastní skill

Skill se vyplatí, když agentovi pořád dokola vysvětlujete stejný postup nebo když ho agent dělá jinak, než chcete. Typicky jde o nasazení, přípravu pull requestu nebo kontrolu formulářů před spuštěním webu. Pravidla pro celý projekt patří do AGENTS.md, postup pro konkrétní typ práce do skillu.

Nejsnazší cesta vede přes hotovou práci. Dotáhněte úkol s agentem do podoby, se kterou jste spokojení, a pak ho požádejte, ať z postupu udělá skill. Codex má na tvorbu skillů vestavěný $skill-creator. Pro Claude Code existuje plugin skill-creator, který umí změřit i to, jestli se skill spouští na správná zadání.

Skill je složka se souborem SKILL.md. Název smí mít nejvýš 64 znaků a obsahovat jen malá písmena bez diakritiky, číslice a pomlčky. Musí se shodovat s názvem složky. Codex hledá skilly projektu ve složce .agents/skills a osobní v ~/.agents/skills, Claude Code v .claude/skills a ~/.claude/skills. Takhle může vypadat skill pro nasazení webu:

nasazeni-webu/
  SKILL.md
  references/
    vercel.md
    netlify.md
  scripts/
    kontrola-odkazu.mjs

Obsah souboru SKILL.md:

---
name: nasazeni-webu
description: Nasadí web a ověří výsledek. Použij, když chce uživatel nasadit web nebo náhled.
---

Náhledové nasazení můžeš spustit sám. Na produkci nasazuj
jen na výslovný pokyn v zadání.

Před nasazením musí projít build a scripts/kontrola-odkazu.mjs.
Po nasazení otevři web na šířce 390 px i na desktopu
a vyzkoušej hlavní stránky a formuláře.

Otevři jen návod pro použitý hosting: references/vercel.md
nebo references/netlify.md.

Hotovo je, když uživateli pošleš adresu nasazení a seznam
chyb, které jsi našel a opravil.

Popis říká, co skill dělá a kdy ho použít. Tělo povoluje bezpečné náhledy, drží hranici u produkce a popisuje, kdy je hotovo. Návody pro jednotlivé hostingy leží v samostatných souborech, takže agent načte jen ten, který potřebuje.

Když skill vzniká z hotové práce, můžete agentovi zadat tohle:

Z práce, kterou jsme právě dokončili, udělej skill pro příště.
Popis napiš jednou až dvěma větami: co skill dělá a kdy ho
použít, hlavní použití na začátku. Do SKILL.md dej jen to,
co bys bez něj udělal jinak než já: hranice, kroky, na jejichž
pořadí záleží, a příklad špatného a dobrého výsledku. Delší
podklady přesuň do references/, opakované příkazy do scripts/.
Skill ulož do složky se skilly tohoto projektu. Nakonec
navrhni tři zadání, která ho mají spustit, a dvě podobná,
která ho spustit nemají.

Skill vyzkoušejte v novém sezení. Zadejte práci, která ho má spustit, a podobnou, která ne. Pokud se spouští příliš často, zpřesněte popis. Pokud se nespouští, doplňte do něj slova, která při zadávání opravdu používáte. Skilly přidávejte postupně podle toho, kde agent chybuje. Cizí sadu skillů neinstalujte celou, stejně jako do projektu nepřidáváte všechny balíčky, které používá někdo jiný.

Až přejdete na další model, spusťte audit znovu. Pravidla, která dnes pomáhají, můžou u dalšího modelu zase brzdit. Pokud nechcete agenty ladit sami, firemní web připravíme za vás.