Optymalizacja AGENTS.md i skilli w Codex

Optymalizacja AGENTS.md i skilli w Codex polega na tym, by stale ładowany łańcuch instrukcji był krótki i warstwowy, wieloetapowe procedury trafiały do skilli ładowanych tylko na potrzeby zadania, a to, co Codex faktycznie załadował, sprawdzało polecenie codex debug prompt-input. Codex łączy pliki projektu od korzenia do liścia w budżecie 32 KiB, więc najgłębsze ucina jako pierwsze.

Ta strona jest dla programisty albo tech leada, który odpowiada za konfigurację Codex w repozytorium. Objaw jest znajomy: w zeszłym tygodniu dopisałeś precyzyjną regułę do services/payments/AGENTS.md, a Codex dalej rzuca w tym serwisie surowe błędy, choć przestrzega każdej ogólnikowej reguły z korzenia. Zanim obwinisz model, sprawdź, czy ten plik w ogóle trafił do promptu.

Jeśli piszesz swój pierwszy AGENTS.md, zacznij od konfiguracji AGENTS.md i wróć tutaj, gdy pliki już istnieją.

Co daje dostrojony AGENTS.md i skille

Sposób, by zobaczyć dokładnie te instrukcje, które dostał Codex, bez proszenia modelu, żeby je sobie przypomniał.
Skrypt budżetu, który uruchomisz lokalnie i w CI i który zawiedzie, zanim jakiś plik zostanie po cichu ucięty.
Regułę rozstrzygającą, czy wskazówka należy do AGENTS.md, do skilla, do konfiguracji czy do bramki testowej.
Układ skilli, który Codex wykrywa, z własnym budżetem kontekstu pod kontrolą.
Cztery prompty do skopiowania: przycięcie szkicu, znalezienie ucięcia, awans procedury do skilla i wyszukanie sprzeczności.

Jak Codex wybiera pliki AGENTS.md do załadowania?

Loader w codex-rs/core/src/agents_md.rs (sprawdzone na Codex CLI 0.157.1, 26.09.2026) buduje łańcuch w tej kolejności:

Plik globalny. Codex czyta ~/.codex/AGENTS.override.md, jeśli istnieje, a w przeciwnym razie ~/.codex/AGENTS.md. Trafia on do modelu jako instrukcje użytkownika i nie liczy się do budżetu projektu.
Korzeń projektu. Codex idzie w górę od katalogu startowego, aż znajdzie wpis z project_root_markers (domyślnie .git). Bez znacznika przeszukuje tylko katalog startowy. Pusta lista (project_root_markers = []) wyłącza to przejście.
Jeden plik na katalog. Od korzenia w dół do katalogu startowego Codex bierze pierwszą nazwę, która istnieje jako plik: AGENTS.override.md, potem AGENTS.md, potem kolejne wpisy project_doc_fallback_filenames.
Łączenie. Pliki są sklejane od korzenia do liścia, więc najbardziej szczegółowy plik ląduje w prompcie na końcu.
Budżet. Pliki projektu dzielą project_doc_max_bytes, domyślnie 32 KiB (32 768 bajtów).
Zaufanie. Od Codex 0.150.0 niezaufany projekt nie dostarcza do sesji żadnego projektowego AGENTS.md. Ładuje się tylko plik globalny.

Krok 3 ma ostrą krawędź. Pusty AGENTS.override.md i tak wygrywa w swoim katalogu, nic nie wnosi i zasłania leżący obok AGENTS.md. Odtworzysz to w testowym repozytorium w niecałą minutę.

Zobacz dokładnie, co Codex załadował, poleceniem `codex debug prompt-input`

Pytanie agenta „które pliki instrukcji załadowałeś?” daje streszczenie, które model pisze z pamięci. codex debug prompt-input zamiast tego renderuje widoczny dla modelu prompt jako JSON, więc odpowiedź jest deterministyczna. Uruchom je z katalogu, z którego zwykle startujesz Codex:

# terminal, z twojego zwykłego katalogu startowego
codex debug prompt-input "ping" > /tmp/prompt.json
grep -o 'AGENTS.md instructions for [^"]*' /tmp/prompt.json

Dopasowanie pokazuje cały blok <INSTRUCTIONS>, który wyśle Codex, z każdym załadowanym plikiem po kolei. Żeby zobaczyć cięcie budżetu bez edytowania konfiguracji, obniż limit na jedno uruchomienie:

codex debug prompt-input -c project_doc_max_bytes=4096 "ping" | grep -o 'AGENTS.md instructions for [^"]*'

W testowym repozytorium z 18-bajtowym plikiem w korzeniu i 51-bajtowym services/pay/AGENTS.md wywołanie z -c project_doc_max_bytes=40 zakończyło blok na - Throw only Pay: nagłówek pliku modułu przetrwał, a jego jedyna reguła została ucięta w połowie słowa (Codex CLI 0.157.1, 26.09.2026). Tak wygląda prawdziwe ucięcie: pół reguły.

Zatrzymaj build, zanim plik zostanie ucięty

codex debug prompt-input zależy od lokalnego zaufania i konfiguracji, więc to narzędzie diagnostyczne, a nie bramka CI. Jako bramkę policz ten sam łańcuch z systemu plików. Zapisz to jako scripts/agents-md-budget.sh:

#!/usr/bin/env bash
# Usage: scripts/agents-md-budget.sh [START_DIR]
# Prints the AGENTS.md chain Codex loads for START_DIR and fails if it exceeds the budget.
set -euo pipefail
budget="${AGENTS_MD_BUDGET:-32768}"          # keep in step with project_doc_max_bytes
start="$(cd "${1:-.}" && pwd -P)"   # physical path: git prints the resolved root
root="$(git -C "$start" rev-parse --show-toplevel)"
chain=()
dir="$start"
while :; do
  for name in AGENTS.override.md AGENTS.md; do   # add your fallback names here
    if [ -f "$dir/$name" ]; then chain=("$dir/$name" ${chain[@]+"${chain[@]}"}); break; fi
  done
  [ "$dir" = "$root" ] || [ "$dir" = / ] && break
  dir="$(dirname "$dir")"
done
total=0
for file in ${chain[@]+"${chain[@]}"}; do
  size=$(wc -c < "$file")
  total=$((total + size))
  printf '%7d bytes  %7d total  %s\n' "$size" "$total" "${file#"$root"/}"
  [ "$size" -eq 0 ] && echo "  warning: empty file shadows the AGENTS.md beside it" >&2
done
if [ "$total" -gt "$budget" ]; then
  echo "AGENTS.md chain for $start is $total bytes, over the $budget-byte budget" >&2
  exit 1
fi

Potem sprawdź każdy katalog, w którym leży plik instrukcji, bo najgłębsze katalogi mają najdłuższe łańcuchy:

# terminal albo krok CI, z korzenia repozytorium
git ls-files --cached --others --exclude-standard -- \
    'AGENTS.md' '*/AGENTS.md' 'AGENTS.override.md' '*/AGENTS.override.md' \
  | xargs -n1 dirname | sort -u \
  | xargs -n1 scripts/agents-md-budget.sh

Flagi --others --exclude-standard obejmują też nowe, jeszcze niezacommitowane pliki, więc lokalnie sprawdzenie daje ten sam wynik co w CI. Skrypt celowo pomija plik globalny, tak jak loader. Zielony wynik dowodzi, że każdy łańcuch się mieści. Nie dowodzi, że reguły są dobre — tym zajmuje się następna sekcja.

Co powinno trafić do każdej warstwy AGENTS.md?

Każda warstwa odpowiada na jedno pytanie. Wszystko, co na nie nie odpowiada, należy gdzie indziej.

Warstwa	Plik	Zawiera	Docelowy rozmiar
Osobista	`~/.codex/AGENTS.md`	Jak lubisz pracować w każdym repozytorium	Poniżej 20 linii
Repozytorium	`AGENTS.md` w korzeniu	Polecenia, framework testowy, konwencje odbiegające od domyślnych	Poniżej 50 linii
Moduł	`services/payments/AGENTS.md`	Reguły obowiązujące tylko w tym katalogu	Poniżej 30 linii

Plik modułu zasługuje na swoje miejsce, gdy mówi coś, czego korzeń powiedzieć nie może:

- Throw only through `PaymentError` from `src/errors.ts`; the API layer maps it to HTTP codes.
- Every public endpoint needs the `rateLimit()` middleware from `src/middleware/rate-limit.ts`.
- Run `pnpm --filter payments test` before you finish; the root test command skips this package.

Trzy rodzaje linii marnują budżet w każdej warstwie:

To, co model i tak robi. „Pisz czysty kod” i „używaj znaczących nazw” niczego nie zmieniają.
To, co mówi już kod. Mapa katalogów czy przegląd architektury starzeją się i kosztują bajty w każdej sesji.
Procedury. 15-krokowa lista kontrolna wydania ładuje się w każdej turze, nawet gdy nikt niczego nie wydaje. Przenieś ją do skilla.

Dowody na to, że warto ciąć zamiast dopisywać, oraz pełną metodę ablacji znajdziesz w przycinaniu CLAUDE.md i AGENTS.md.

Read AGENTS.md at the repository root and every nested AGENTS.md. For each line, decide:
KEEP if removing it would change what you do in this repository,
CUT if you would do it anyway or can read it from the code (overviews, directory maps, generic style advice),
MOVE if it is a multi-step procedure that only some tasks need (name the skill it should become).
Output a table with file, line, decision and a one-sentence reason, then propose the new files.
Do not edit anything yet. Flag any rule you cannot confirm from the code or config.

Kiedy reguła powinna stać się skillem, konfiguracją albo testem?

AGENTS.md to rada, którą model czyta. Niektóre wskazówki potrzebują mocniejszego miejsca.

Wskazówka to…	Miejsce	Dlaczego
Krótka konwencja dotycząca większości zadań	`AGENTS.md`	Ładowana w każdej sesji, tania, jeśli krótka
Wieloetapowa procedura dla części zadań (wydanie, migracja, przygotowanie PR)	Skill	Do chwili użycia ładują się tylko nazwa i opis
Ustawienie (model, sandbox, serwery MCP)	`config.toml`	Konfiguracja jest stosowana, a nie interpretowana
Polecenie, którego agent nigdy nie może uruchomić poza sandboxem	Reguły Codex (`.rules`)	Wymuszane poza modelem
Reguła, która musi obowiązywać zawsze (żadnych surowych błędów, żadnego `console.log`)	Reguła lintera albo test plus jedna linia w `AGENTS.md`	Build pada, gdy agent zapomni

Ostatni wiersz to sposób, w jaki jakość pozostaje dowodliwa. AGENTS.md zwiększa szansę na dobry wynik. Reguła lintera albo test sprawia, że zły wynik wywraca build, więc regułę weryfikujesz, patrząc na czerwony lub zielony check, a nie czytając każdy diff.

Napisz skill, który Codex wykryje

Skill to katalog z plikiem SKILL.md. Codex umieszcza nazwę i opis każdego skilla w spisie skilli w prompcie, a pełny plik czyta dopiero wtedy, gdy wywołasz skill albo twój prompt pasuje do jego opisu.

.agents/skills/pr-ready/
  SKILL.md            # required: frontmatter + instructions
  scripts/            # optional: code the skill runs
  references/         # optional: docs the skill reads on demand
  agents/openai.yaml  # optional: Codex UI metadata and dependencies

---
name: pr-ready
description: Prepare the current branch for a pull request. Use when the user asks to get changes
  PR-ready, open a PR, or check a branch before review. Not for reviewing someone else's PR.
---

1. Run `pnpm lint --fix`, then `pnpm lint`. Stop and report if errors remain.
2. Run `pnpm test`. Fix failures caused by this branch; report pre-existing ones separately.
3. Run `pnpm typecheck`.
4. Write a PR description: what changed and why, how it was tested, breaking changes.
5. End with a table of each check and its pass or fail result.

To opis kieruje ruchem. Napisz, kiedy używać skilla, a kiedy nie, bo inaczej niejawne dopasowanie odpali się na niewłaściwych promptach.

Gdzie Codex szuka skilli

Zakres	Lokalizacja	Uwagi
Repozytorium	`.agents/skills/<name>/SKILL.md`	Commitowane i współdzielone. Skanowane od katalogu roboczego w górę do korzenia repozytorium
Osobisty	`~/.agents/skills/<name>/SKILL.md`	Czytane przez Codex 0.157.1 (sprawdzone 26.09.2026)
Cel instalatora	`$CODEX_HOME/skills` (domyślnie `~/.codex/skills`)	Tam zapisuje dołączony `$skill-installer`
Dołączone	Dostarczane z Codex	`imagegen`, `openai-docs`, `plugin-creator`, `review-agent`, `skill-creator` i `skill-installer` w 0.157.1; `review-agent` jest dołączony, ale domyślnie nie pojawia się w katalogu

Wywołaj skill jawnie, wpisując $pr-ready w prompcie, albo przeglądaj skille przez /skills. Żeby utworzyć nowy, wpisz $skill-creator i opisz zadanie.

Zainstaluj współdzielone skille

Katalog OpenAI to repozytorium openai/skills. W Codex dołączony instalator czyta jego wyselekcjonowaną listę:

$skill-installer install gh-fix-ci

Z terminala międzyagentowy CLI skills (1.7.0 na 26.09.2026) instaluje do .agents/skills/ w projekcie:

npx skills add openai/skills --skill gh-fix-ci -a codex

Instaluj per projekt, kiedy tylko możesz. Z flagą -g CLI zapisuje skille Codex do ~/.codex/skills/, a nie do ~/.agents/skills/, więc sprawdź przez /skills, czy Codex je widzi.

Utrzymaj spis skilli w jego budżecie

Skille są tańsze niż AGENTS.md, ale nie darmowe. Spis nazw i opisów ma własny budżet, skills.max_context_tokens, który domyślnie wynosi 2% okna kontekstu modelu, a ustawiony ręcznie jest ograniczony do 10 000 tokenów. Zbyt wiele zainstalowanych skilli wypycha się nawzajem z tego spisu: z -c skills.max_context_tokens=50 polecenie codex debug prompt-input nie wypisało ani jednego skilla. Wyłącz te, których nie używasz:

[[skills.config]]
name = "imagegen"
enabled = false

[[skills.config]]
path = "/home/you/.codex/skills/old-release/SKILL.md"
enabled = false

Wspólne standardy skilli dla zespołu opisuje strona o optymalizacji skilli i dzieleniu się nimi w zespole.

Find the longest multi-step procedure in our AGENTS.md files (release steps, migration steps,
PR checklists). Turn it into a skill at .agents/skills/<name>/SKILL.md with a description that
says when to use it and when not to. Replace the procedure in AGENTS.md with one line pointing
to $<name>. Then run scripts/agents-md-budget.sh from the deepest directory that changed and
show me the before and after byte totals.

Użyj AGENTS.override.md na czas przejściowej fazy

AGENTS.override.md zastępuje AGENTS.md w tym samym katalogu, dopóki istnieje. To czysty przełącznik na czas migracji albo zamrożenia:

# TEMPORARY: delete when the v3 router migration is merged (owner: @api-team)
- Add new endpoints only under src/routes/v3/. Do not edit v1 or v2 routes.
- Use AuthContext from src/lib/auth-v3.ts in all new middleware.
- Run `pnpm test:contract` before finishing; v2 clients must keep passing.

Override zasłania cały stały plik, więc przepisz do niego każdą stałą regułę, której nadal potrzebujesz. W pierwszych liniach wpisz właściciela i warunek wyjścia, a lista plików ze skryptu budżetu będzie ci przypominać, że override wciąż istnieje.

Ogranicz kontekst, który kosztuje ta konfiguracja

/status w TUI Codex pokazuje bieżącą konfigurację sesji i zużycie tokenów. /mcp wypisuje podłączone narzędzia MCP. Każdy serwer MCP dokłada schematy narzędzi do każdej tury, więc wyłącz te, których to repozytorium nie potrzebuje, albo zawęź je do używanych narzędzi:

# ~/.codex/config.toml albo .codex/config.toml
[mcp_servers.jira]
enabled = false

[mcp_servers.github]
enabled_tools = ["get_pull_request", "list_pull_request_files"]

Podnoś project_doc_max_bytes dopiero po przycięciu i podziale. Większy budżet zachowa plik w całości, ale każda sesja i tak za niego płaci:

project_doc_max_bytes = 65536  # default 32768

Jeśli podniesiesz limit, ustaw w CI AGENTS_MD_BUDGET na tę samą wartość. Szerszy obraz kompaktowania i kontekstu w App, CLI i chmurze znajdziesz w zarządzaniu kontekstem na powierzchniach Codex.

Read project_doc_max_bytes from my Codex config (default 32768 if unset). Walk from the
repository root down to <STARTUP_DIR>. At each level, name the ONE file Codex loads: the first
of AGENTS.override.md, AGENTS.md, then any project_doc_fallback_filenames entry that exists as a
file. An empty file still counts as the pick for its directory, so flag it. Exclude
~/.codex/AGENTS.md. List each file with its byte size and a running total. If the total passes
the limit, name the crossing file, the byte offset where it is cut, the files skipped after it,
and the specific rules I am losing. Do not edit anything.

Zastąp STARTUP_DIR katalogiem, z którego uruchamiasz Codex, na przykład services/payments.

Udowodnij, że instrukcje działają, bez czytania każdej sesji

Porządną konfigurację da się sprawdzić po wynikach, a nie po transkryptach:

Załadowane. scripts/agents-md-budget.sh przechodzi w CI dla każdego katalogu z plikiem instrukcji.
Otrzymane. codex debug prompt-input uruchomione z katalogu każdego serwisu pokazuje ostatnią regułę tego serwisu wewnątrz <INSTRUCTIONS>.
Wymuszone. Każda reguła, która musi obowiązywać zawsze, ma regułę lintera albo test. Zgodność dowodzi wynik CI, a recenzent nie musi jej wypatrywać w diffie.
Z właścicielem. AGENTS.md, AGENTS.override.md i .agents/skills/ są objęte wpisem w CODEOWNERS dla tech leada odpowiedzialnego za konfigurację. Zmiany w nich przechodzą review jak kod, bo zmieniają każdą przyszłą sesję.

Collect ~/.codex/AGENTS.md, every AGENTS.md and AGENTS.override.md in this repository, and every
SKILL.md under .agents/skills. List pairs of instructions that contradict each other (for
example, different test commands or package managers), which file wins by load order, and
whether the winner is the one we want. Then list rules that say something a lint rule or test
could enforce, and suggest the check for each. Report only; do not edit files.

Kiedy AGENTS.md i skille w Codex zawodzą

Reguła modułu jest ignorowana, a reguły z korzenia są przestrzegane. Łańcuch przekracza budżet. Uruchom skrypt budżetu z tego katalogu, a potem przytnij albo podziel plik w korzeniu. project_doc_max_bytes podnoś tylko w ostateczności.
Zniknęły reguły całego katalogu. Pusty albo zapomniany AGENTS.override.md zasłania leżący obok AGENTS.md. Uruchom find . -name AGENTS.override.md i usuń to, co nie ma już właściciela.
Nie ładują się żadne instrukcje projektu. Projekt jest niezaufany (0.150.0 i nowsze) albo katalog startowy leży poza korzeniem repozytorium. codex debug prompt-input nie stosuje sprawdzenia zaufania (w 0.157.1 wyrenderował pliki projektu nawet z trust_level = "untrusted"), więc czysty wynik nie wyklucza tej przyczyny. Sprawdź wpis [projects."<path>"] w ~/.codex/config.toml i zaufaj projektowi, gdy Codex o to zapyta.
Reguły są przestrzegane na początku długiej sesji, a później zapominane. Kompaktowanie streściło rozmowę. Powtórz w prompcie to jedno ograniczenie, które się liczy, albo zacznij nową sesję przez /new.
Skill nigdy nie odpala się niejawnie. Jego opis nie pasuje do tego, jak ludzie proszą. Dopisz sformułowania, których używa twój zespół, wywołuj go przez $name, dopóki nie zacznie działać, i sprawdź, czy /skills go wypisuje.
Skill odpala się przy niewłaściwych zadaniach. Jego opis jest zbyt szeroki. Dodaj klauzulę „Not for…” i wyłącz nakładające się skille przez [[skills.config]].
Zadania w chmurze ignorują twoje lokalne reguły. Środowiska chmurowe czytają AGENTS.md zacommitowany do repozytorium. Commituj to, co ważne, a w ~/.codex/AGENTS.md trzymaj tylko osobiste preferencje.

Dokąd dalej z AGENTS.md i skillami

Konfiguracja AGENTS.md opisuje pisanie pierwszych plików globalnego i projektowego.
Konfiguracja Codex wyjaśnia warstwy config.toml, profile i nadpisania.
Współpraca zespołowa i wspólna konfiguracja wdraża zacommitowaną konfigurację, reguły i skille w całym zespole.
Skille agentów: polityka zamieniona w przetestowany workflow pokazuje, jak udowodnić, że skill odpala się i działa, w Claude Code, Codex i Cursorze.
Przygotowanie bazy kodu dla agentów stawia AGENTS.md obok testów i bramek, które go wspierają.
Używasz też Claude Code? System pamięci Claude Code to odpowiednik tej strony dla CLAUDE.md.