Agent Skill to folder z plikiem SKILL.md. W pliku jest krótki nagłówek YAML (nazwa i opis) oraz instrukcja w Markdownie. Obok mogą leżeć skrypty, dokumentacja i szablony. Agent na starcie widzi tylko nazwę i opis, a resztę czyta dopiero wtedy, gdy zadanie do skilla pasuje.
Ten sam folder działa w Claude Code i w Codexie, bo oba narzędzia trzymają się otwartej specyfikacji z agentskills.io. Różni się głównie to, gdzie każde z nich szuka skilli. 22 października 2026 Anthropic przekazał standard Agent Skills do Agentic AI Foundation, fundacji działającej przy Linux Foundation. Wcześniej trafił tam MCP.
Pracuję na zmianę w Codexie i Claude Code i trzymam dla nich wspólne instrukcje i skille. Poniżej opisuję, jak to poukładać, żeby nie utrzymywać dwóch kopii tego samego.
Co to jest SKILL.md?
Minimalny skill to jeden katalog i jeden plik:
seo-audit/
├── SKILL.md # wymagany: metadane + instrukcja
├── scripts/ # opcjonalnie: kod do uruchomienia
├── references/ # opcjonalnie: dokumentacja czytana na żądanie
└── assets/ # opcjonalnie: szablony, dane
Plik zaczyna się od frontmattera. Specyfikacja wymaga dwóch pól:
---
name: seo-audit
description: Audits one page for technical SEO issues (status, canonical, schema, sitemap). Use when the user asks to check or verify a page after deploy.
---
# SEO audit
1. Fetch the page and check the HTTP status.
2. ...
Zasady z specyfikacji:
namema od 1 do 64 znaków: małe litery, cyfry i myślniki. Nie może zaczynać się ani kończyć myślnikiem, nie może mieć dwóch myślników pod rząd i musi być taki sam jak nazwa katalogu.descriptionma od 1 do 1024 znaków i mówi, co skill robi i kiedy go użyć.- Opcjonalne pola to
license,compatibility(do 500 znaków),metadatai eksperymentalneallowed-tools.
Poprawność folderu sprawdzisz narzędziem skills-ref validate ./seo-audit, które wskazuje specyfikacja.
Jak agent ładuje skille
Specyfikacja opisuje to jako progressive disclosure, czyli ładowanie w trzech krokach:
- Na starcie agent czyta tylko
nameidescriptionkażdego skilla (około 100 tokenów na skill). - Gdy uzna, że skill pasuje do zadania, wczytuje całe
SKILL.md. Specyfikacja zaleca poniżej 5000 tokenów i poniżej 500 linii. - Pliki ze
scripts/,references/iassets/czyta dopiero wtedy, gdy instrukcja ich potrzebuje.
Z tego wynika praktyczna zasada: długie materiały przenieś do references/ i linkuj je z SKILL.md na jeden poziom w głąb. Specyfikacja odradza głębokie łańcuchy odwołań.
Lista skilli też kosztuje kontekst. Dokumentacja Codexa podaje, że początkowa lista skilli zajmuje najwyżej 2% okna kontekstu (8000 znaków, gdy okno jest nieznane). Limit można podnieść w konfiguracji przez skills.max_context_tokens, maksymalnie do 10 000. Przy kilkudziesięciu skillach z długimi opisami część opisów się po prostu nie zmieści, więc opis warto pisać krótko.
Gdzie Claude Code i Codex szukają skilli
| Claude Code | Codex | |
|---|---|---|
| Skille projektu | .claude/skills/<nazwa>/SKILL.md | .agents/skills/ w każdym katalogu od bieżącego aż do roota repo |
| Skille osobiste | ~/.claude/skills/<nazwa>/SKILL.md | $HOME/.agents/skills |
| Poziom maszyny lub firmy | ustawienia managed (enterprise) | /etc/codex/skills |
| Ręczne wywołanie | /nazwa-skilla | $nazwa-skilla albo /skills |
| Dowiązania symboliczne | obsługiwane | obsługiwane, Codex idzie za celem linku |
Źródła: dokumentacja skilli Claude Code i Build skills w dokumentacji OpenAI.
Oba narzędzia potrafią też same uruchomić skill na podstawie opisu. W Claude Code wyłączysz to polem disable-model-invocation: true, a w Codexie ustawieniem allow_implicit_invocation: false w pliku agents/openai.yaml obok skilla. Ręczne wywołanie dalej działa.
Jeden zestaw skilli dla obu narzędzi
Skoro format jest wspólny, a różnią się katalogi, wystarczy jedna prawdziwa kopia i dowiązania. W repozytorium projektu może to wyglądać tak:
# skill trzymasz raz, w katalogu, który czyta Codex
mkdir -p .agents/skills/seo-audit
# Claude Code dostaje dowiązanie do tego samego folderu
mkdir -p .claude/skills
ln -s ../../.agents/skills/seo-audit .claude/skills/seo-audit
Dla skilli osobistych analogicznie: prawdziwy folder w ~/.agents/skills/, link w ~/.claude/skills/. Po zmianie w jednym miejscu oba narzędzia widzą tę samą wersję. Według dokumentacji Codex sam wykrywa zmiany w skillach, a Claude Code obserwuje katalogi skilli i wczytuje zmiany w SKILL.md w trakcie sesji, bez restartu.
Żeby skill naprawdę był przenośny, trzymaj się pól ze specyfikacji. Claude Code ma własne rozszerzenia, na przykład disable-model-invocation, context: fork (uruchomienie skilla w subagencie) czy wstawianie wyniku polecenia przez !`polecenie`. Dokumentacja Claude Code zaznacza, że przy wgrywaniu skilla do claude.ai, w Skills API i przy pakowaniu działają tylko pola ze specyfikacji. Każdy inny klucz kończy się twardym błędem Unexpected key(s), a nie cichym pominięciem. Jeśli potrzebujesz takiego pola, zrób z niego osobny skill tylko dla Claude Code albo najpierw sprawdź, jak drugie narzędzie traktuje nieznane klucze.
To samo dotyczy treści. Instrukcja typu „uruchom subagenta Explore” ma sens w Claude Code, ale w Codexie nic nie znaczy. Pisz kroki w kategoriach zadania (co przeczytać, co uruchomić, jak sprawdzić wynik), a nie konkretnych funkcji jednego narzędzia.
Jak napisać opis, żeby skill się uruchamiał
Opis decyduje, czy agent w ogóle sięgnie po skill. Dokumentacja OpenAI radzi napisać wprost, kiedy skill powinien, a kiedy nie powinien się uruchomić. Dobre praktyki Anthropic dodają, żeby pisać opis zawsze w trzeciej osobie (opis trafia do promptu systemowego) i zawrzeć w nim konkretne słowa kluczowe oraz sytuacje, w których skill ma się uruchomić.
Przykład z mojego zestawu, ze skilla do codziennej pracy z Search Console:
description: >-
Use when picking one Search Console gap (impressions without clicks, striking-
distance positions ~5-30) and turning it into one high-quality guide or page
expansion plus an internal-links plan for approval, on demand or from a daily
gap routine.
Ten opis mówi, co jest wejściem (luka w Search Console), co wychodzi (jeden poradnik i plan linków) i w jakiej sytuacji go użyć. Opis w stylu „Helps with SEO” pasowałby do dziesięciu innych skilli i agent nie miałby jak ich odróżnić. Według zaleceń Anthropic poprawiłbym jeszcze początek: zamiast „Use when…” najpierw w trzeciej osobie to, co skill robi, na przykład „Turns one Search Console gap into…”.
Kilka zasad, które pomagają:
- Jeden skill, jedno zadanie. Audyt strony i pisanie artykułu to dwa skille.
- Kroki w trybie rozkazującym, z jasnym wejściem i wyjściem.
- Na końcu instrukcji sposób sprawdzenia wyniku: komenda, test, lista kontrolna.
- Powtarzalną, kruchą logikę (parsowanie, walidacja) przenieś do skryptu w
scripts/, zamiast opisywać ją słowami.
Skill warto sprawdzić na kilku prawdziwych zadaniach z włączonym skillem i bez niego. Dokumentacja Claude opisuje, że skill-creator w Claude Code robi to automatycznie: uruchamia te same prompty bez skilla jako punkt odniesienia i pokazuje skuteczność, czas i liczbę tokenów obu wariantów. Jeśli różnicy nie widać, skill jest do poprawki albo niepotrzebny. Więcej o testowaniu agentów piszę w tekście Jak testować agentów AI: evals i trace.
Skill, AGENTS.md, MCP czy subagent?
| Potrzeba | Co wybrać |
|---|---|
| Zasady, które mają obowiązywać w każdej rozmowie w projekcie (styl kodu, komendy, zakazy) | AGENTS.md (Codex) lub CLAUDE.md (Claude Code) |
| Procedura potrzebna co jakiś czas, z własnymi skryptami i materiałami | Skill |
| Dostęp do żywych danych albo zewnętrznego systemu (baza, CRM, API) | MCP |
| Osobny kontekst dla dużej, niezależnej części pracy | Subagent |
Dokumentacja Claude mówi to samo od drugiej strony: skill nie jest dobrym wyborem dla jednorazowego zadania, dla danych na żywo (do tego jest MCP) ani dla instrukcji, które mają działać zawsze. Skill i MCP dobrze się uzupełniają. MCP daje agentowi dostęp do narzędzia, skill mówi, jak tego narzędzia używać w Twoim procesie. Szerzej porównuję skille, subagentów i systemy multi-agent w tekście Skill, subagent czy multi-agent?, a o tym, co trafia do kontekstu agenta, w tekście Context engineering dla agentów AI.
Bezpieczeństwo: przeczytaj skill, zanim go włączysz
Skill to instrukcja dla agenta i często kod, który agent uruchomi na Twojej maszynie. Anthropic pisze wprost, że skille udostępniane przez innych użytkowników nie są przez nich sprawdzane, i zaleca przeczytać SKILL.md przed włączeniem.
Przed instalacją cudzego skilla sprawdzam trzy rzeczy:
- Co robią skrypty w
scripts/i czy coś wysyłają poza maszynę. - Czy instrukcja nie każe agentowi czytać sekretów, plików
.envani kluczy. - Czy pole
allowed-toolsnie daje szerszych uprawnień, niż zadanie wymaga. Dokumentacja Claude Code ostrzega, że w skillach projektu to pole działa także w folderze, któremu nigdy nie dałeś zaufania.
W Codexie skill wyłączysz bez usuwania, dodając w ~/.codex/config.toml wpis [[skills.config]] ze ścieżką i enabled = false.
Co zmienia przekazanie Agent Skills do AAIF
Według ogłoszenia Anthropic:
- Skille wystartowały w październiku 2025, a otwarty standard opublikowano w grudniu 2025. Od tego czasu przyjęło go ponad 70 platform, w tym ChatGPT, Cursor, GitHub Copilot i VS Code.
- Opublikowano ponad milion skilli, zainstalowano je prawie 280 milionów razy.
- Fundacja dostała nazwę, logo, organizację na GitHubie i domenę agentskills.io. Agentic AI Foundation działa przy Linux Foundation, a Anthropic współtworzył ją z Block i OpenAI.
- Głównymi maintainerami zostali David Soria Parra i Mahesh Murag. W planach są wersjonowane wydania, formalny proces zgłaszania zmian i wytyczne bezpieczeństwa dla autorów i osób instalujących skille.
Dla kogoś, kto pisze skille, wniosek jest prosty. Format nie zmienia się z dnia na dzień, a o zmianach będzie decydował otwarty proces zamiast jednej firmy. Opłaca się pisać pod specyfikację, a rozszerzenia konkretnego narzędzia trzymać na marginesie.
Kiedy skille mają sens w firmie
Skille najlepiej działają tam, gdzie zespół powtarza tę samą procedurę i za każdym razem tłumaczy ją agentowi od nowa: przegląd PR według firmowych zasad, przygotowanie release notes, raport z danych w stałym formacie, wdrożenie i sprawdzenie strony. Jeśli macie taki proces i chcecie go przenieść na agentów (w Claude Code, Codexie albo we własnej aplikacji), pomagam firmom budować agentów AI i wdrażać AI w istniejących produktach. Zaczynamy od warsztatu, na którym wybieramy jeden proces, potem wycena, UX i praca w dwutygodniowych sprintach. Rozliczam się godzinowo, na fakturę B2B. Pełną ofertę znajdziesz na stronie usługi.
Najczęstsze pytania
Co to jest SKILL.md?
To plik z instrukcją dla agenta AI w otwartym formacie Agent Skills. Zaczyna się od frontmattera YAML z polami name i description, a dalej zawiera kroki w Markdownie. Leży w katalogu o tej samej nazwie co pole name, obok opcjonalnych folderów scripts/, references/ i assets/.
Czy ten sam skill zadziała w Claude Code i w Codexie?
Tak, jeśli używa tylko pól ze specyfikacji agentskills.io i nie odwołuje się do funkcji jednego narzędzia. Claude Code czyta skille z .claude/skills, a Codex z .agents/skills, więc najprościej trzymać jedną kopię i podlinkować ją dowiązaniem symbolicznym. Oba narzędzia obsługują symlinki.
Czym skill różni się od MCP?
MCP daje agentowi dostęp do zewnętrznych danych i narzędzi, na przykład bazy danych albo API. Skill to zapisana procedura: jak wykonać zadanie, w jakiej kolejności i jak sprawdzić wynik. Często działają razem.
Czym skill różni się od AGENTS.md albo CLAUDE.md?
AGENTS.md i CLAUDE.md są wczytywane zawsze, więc nadają się na zasady obowiązujące w całym projekcie. Skill wczytuje się w całości dopiero wtedy, gdy pasuje do zadania, więc nadaje się na dłuższe procedury, które przydają się od czasu do czasu.
Ile skilli można mieć naraz?
Specyfikacja nie podaje limitu, ale lista nazw i opisów zajmuje kontekst. Codex przeznacza na nią domyślnie najwyżej 2% okna kontekstu. Przy dużej liczbie skilli krótkie i konkretne opisy są ważniejsze niż ich liczba.
Źródła
Chcesz zbudować agenta AI, MVP albo aplikację?
Projektuję i buduję produkty z AI od pierwszej wersji do produkcji: MVP, aplikacje mobilne w React Native, web appy i agentów AI. Napisz, co chcesz zbudować, a odpowiem, od czego zacząć.