Przenośność SKILL.md: Techniczne spojrzenie na Claude Code vs. Codex CLI

Format SKILL.md to prosty i potężny standard rozszerzania możliwości agentów kodujących. Obsługują go zarówno Claude Code od Anthropic, jak i Codex CLI od OpenAI. Prowadzi to do kluczowego pytania dla deweloperów: czy ten sam plik SKILL.md zadziała na obu? Prosta odpowiedź brzmi: tak, sam plik jest przenośny. Użyteczna odpowiedź jest bardziej złożona i ma mniej wspólnego z formatem pliku, a więcej ze środowiskiem wykonawczym, które zapewnia każdy z agentów.

W SkillProof instalujemy i uruchamiamy umiejętności Claude Code na rzeczywistych zadaniach, aby sprawdzić, czy przechodzą testy. Publikujemy wyniki, włączając w to porażki. Z 2090 umiejętności przetestowanych w środowisku Claude Code, 1291 przeszło pomyślnie (62%), 697 zadziałało dopiero po konfiguracji, którą musi szczegółowo opisać oferta, a 102 otrzymało werdykt negatywny: niektóre uruchomiły się, pogarszając sytuację, inne nie mogły zostać uruchomione w ogóle z powodu brakującego CLI, martwej zależności lub przykładu, który powodował awarię. Nigdy nie uruchamialiśmy umiejętności na Codex CLI. Cały nasz zbiór danych opiera się na wykonaniu w Claude Code.

Nasz korpus testowy zawiera jednak unikalny, jednostronny zbiór dowodów. Ten artykuł analizuje techniczne różnice w obsłudze SKILL.md przez obu agentów i co nasze dane, pochodzące wyłącznie z Claude, ujawniają na temat przenośności z Codex do Claude.

Wspólna podstawa: Format SKILL.md

Zanim porównamy agentów, kluczowe jest zrozumienie, czym jest plik SKILL.md. To plik tekstowy, który łączy instrukcje dla agenta z metadanymi. Struktura jest prosta:

1. Frontmatter YAML: Blok na początku pliku, otoczony ---, zawiera pary klucz-wartość. name i description są fundamentalne. Agent używa opisu, aby zdecydować, kiedy wywołać umiejętność. Opcjonalny klucz allowed-tools wymienia narzędzia, na których użycie umiejętność chce mieć wstępną zgodę, aby nie zatrzymywać się w trakcie działania z prośbą o akceptację. Jest to pole dla wygody, a nie sandbox: nie odbiera modelowi dostępu do narzędzi. Szczegółowy opis można znaleźć w naszym przewodniku po frontmatter.
2. Treść w Markdown: Poniżej frontmatter znajduje się zestaw instrukcji dla agenta, napisany w czystym markdownie. Mówi on modelowi, jak krok po kroku wykonać zadanie.
3. Dołączone pliki: Umiejętność może zawierać inne pliki, takie jak skrypty czy dane referencyjne, które są z nią spakowane.

Co kluczowe, SKILL.md nie zawiera sygnatur funkcji ani schematów argumentów. Jest to format instrukcji w języku naturalnym, a nie ustrukturyzowany manifest do wywoływania funkcji. To domena MCP, osobnego i odrębnego protokołu. Aby zgłębić ten temat, zobacz nasze porównanie Claude Skills vs. MCP.

Ponieważ SKILL.md to tylko ustrukturyzowany tekst, każdy zgodny parser może go odczytać. Zarówno Claude Code, jak i Codex CLI mogą załadować ten sam plik bez modyfikacji. Różnica polega na tym, co dzieje się później.

Ładowanie i wykonanie: Dwa różne środowiska

Chociaż plik jest ten sam, kontekst, w którym jest uruchamiany, już nie. Architektura agenta, domyślne ustawienia i dostępne narzędzia definiują środowisko wykonawcze. To tutaj pojawiają się praktyczne różnice między Claude Code a OpenAI Codex.

Claude Code

W naszej pracy testujemy wyłącznie z użyciem Claude Code. Umiejętności są ładowane z ~/.claude/skills dla umiejętności osobistych i z .claude/skills wewnątrz projektu dla tych o zasięgu repozytorium. Kiedy dajesz agentowi zadanie, dopasowuje on twój prompt do pola description wszystkich dostępnych umiejętności. Możesz również wywołać jedną bezpośrednio po nazwie za pomocą polecenia z ukośnikiem.

Jednym z krytycznych zachowań, które udokumentowaliśmy, jest jego tryb awarii. Jeśli frontmatter YAML w pliku SKILL.md jest źle sformatowany — błędnie umieszczony tabulator, brakujący cudzysłów — Claude Code nie generuje błędu walidacji. Umiejętność po prostu staje się niewidoczna dla agenta. Nie będzie widoczna na liście i nigdy nie zostanie wywołana. Ta cicha awaria może być trudna do debugowania, co omawiamy w naszym poście o tym, co zrobić, gdy umiejętność się nie uruchamia.

Nasza metodologia polega na uruchamianiu każdej umiejętności w ramach rzeczywistego zadania. Wyniki naszych 2090 testów pokazują, że pomyślne przejście ('pass') nie jest gwarantowane. 697 umiejętności, które otrzymały status 'setup', wymagało nietrywialnej konfiguracji, którą musieliśmy udokumentować. 102 umiejętności z wynikiem 'fails' albo nie mogły zostać w ogóle uruchomione z powodu brakujących zależności, albo dawały gorszy rezultat niż brak użycia umiejętności.

Codex CLI

Codex CLI to open-source'owy terminalowy agent kodujący od OpenAI. Nie jest to wrapper na API; to samodzielne narzędzie, które odczytuje bazę kodu, wykonuje edycje w wielu plikach i uruchamia polecenia w twoim lokalnym środowisku. Wsparcie dla SKILL.md wprowadzono w grudniu 2025 roku, początkowo jako funkcję eksperymentalną.

Ścieżki wykrywania umiejętności zmieniły się od czasu premiery, co warto wiedzieć, jeśli korzystasz ze starszego przewodnika. Obecna dokumentacja OpenAI wymienia .agents/skills w katalogu roboczym i jego rodzicach dla umiejętności o zasięgu repozytorium, $HOME/.agents/skills dla osobistych oraz /etc/codex/skills dla umiejętności ogólnosystemowych. Oryginalna lokalizacja ~/.codex/skills to ta, którą wciąż można zobaczyć w większości plików README umiejętności firm trzecich. Umiejętność można wywołać jawnie, wpisując $ i wybierając z listy, lub może być wywołana niejawnie, jeśli zadanie pasuje do jej opisu.

Jego główny plik konfiguracyjny to ~/.codex/config.toml, a jego podstawowy zestaw instrukcji można dostosować za pomocą pliku o nazwie AGENTS.md. Zapewnia to inny punkt wejścia do personalizacji w porównaniu z modelem Claude Code, który jest skoncentrowany na umiejętnościach.

Więc, czy Codex obsługuje SKILL.md? Tak, natywnie. Format pliku jest traktowany priorytetowo (first-class citizen). Rozbieżność wynika ze środowiska, które zapewnia do uruchomienia tego pliku.

Jednostronna przenośność: Co pokazują nasze dane

To jest sedno problemu. Nigdy nie testowaliśmy umiejętności na Codex CLI. Nie możemy podać wskaźnika zdawalności dla Codex ani bezpośredniego porównania w oparciu o nasze własne dane testowe. Twierdzenie inaczej byłoby zmyślaniem zbioru danych.

To, co możemy zaoferować, to uczciwe spojrzenie na specyficzny wzorzec w naszych wynikach testów Claude Code. Z 2090 przetestowanych przez nas umiejętności, nasze notatki wskazują, że 47 z nich wspomina o środowisku Codex lub je zakłada. Te umiejętności zostały napisane dla Codex, ale uruchomiliśmy je w środowisku testowym Claude Code. Daje nam to unikalny, jednostronny wgląd w przenośność.

Wyniki dla tych 47 umiejętności są następujące:

• Przeszło pomyślnie: 11
• Wymagana konfiguracja: 34
• Niepowodzenie: 2

Mówi to jasno: plik SKILL.md napisany dla Codex z dużym prawdopodobieństwem będzie wymagał ręcznej konfiguracji, aby uruchomić go na Claude Code. Nie dlatego, że plik jest nieprawidłowy, ale dlatego, że instrukcje umiejętności opierają się na narzędziach lub ścieżkach, które nie istnieją w nowym środowisku.

Spójrzmy na konkretne przykłady z naszego katalogu:

• Generate 2D Map (Werdykt: Wymagana konfiguracja): Plik README tej umiejętności jawnie stwierdza, że jest przeznaczona dla Codex/Grok i podaje ścieżki instalacji ~/.codex/skills oraz ~/.grok/skills, a nie ~/.claude/skills, jak twierdziła jej oferta. Jej główny potok przetwarzania wymaga wbudowanej pary narzędzi do generowania i przeglądania obrazów, których Claude Code nie posiada. Przetestowaliśmy ją na jedynym branchu, który nie wymaga obrazów — budując ortogonalną mapę Tiled jako JSON — i umiejętność dorównała dokładnie modelowi bazowemu: identyczne co do bajta tablice kafelków, identyczne metadane punktu startowego i wyjścia. Plik załadował się; część, dla której warto było ją instalować, nie zadziałała.

• Generate 2D Sprite (Werdykt: Wymagana konfiguracja): Ta umiejętność ma ten sam problem. Jest ściśle zależna od możliwości generowania obrazów, które są dostarczane z Codex i Grok, ale nie z Claude Code. Potrafi zaplanować arkusz sprajtów, ale nie może wykonać ostatniego kroku, czyli stworzyć grafiki.

• Ablation Planner (Werdykt: Wymagana konfiguracja): Główny mechanizm tej umiejętności polega na przekazywaniu pracy projektowej do konkretnego narzędzia Codex. Po uruchomieniu w naszym środowisku testowym Claude Code, to narzędzie było niedostępne. Krok musiał zostać wykonany ręcznie, co jest definicją werdyktu 'setup'.

Z drugiej strony, 11 z tych umiejętności zorientowanych na Codex przeszło testy bez problemu. Umiejętności takie jak Better Codex i PinMe Share pomyślnie przeszły nasze testy na Claude Code. Obie niosą swoją wartość w tekście, a nie w narzędziach dostawcy. Better Codex to czysto promptowa nakładka behawioralna bez zewnętrznych plików czy skryptów, a i tak pokonała model bazowy w zadaniu parsowania konfiguracji, gdzie model bazowy po cichu psuł się na wartościach zawierających znak równości. PinMe Share instaluje się z jednego, poprawnego pliku SKILL.md bez wiszących odwołań, a jej przewaga polega na dokładnej znajomości zwykłego CLI npm: wyemitowała kanoniczne polecenie do wysyłania plików i wymagane kroki autoryzacji, podczas gdy model bazowy zgadł polecenie i pominął logowanie. Tak wygląda przenośna umiejętność. Potrzebuje narzędzia, które można zainstalować, a nie wbudowanego, które jest dostarczane z agentem jednego dostawcy.

Kluczowe różnice w skrócie

A direct comparison highlights the trade-offs when considering codex cli or claude code for coding with skills.

Cecha	Claude Code	Codex CLI
Ścieżka umiejętności	~/.claude/skills (osobiste), .claude/skills (projektowe)	$HOME/.agents/skills (osobiste), .agents/skills (repozytorium), /etc/codex/skills (systemowe)
Konfiguracja	settings.json oraz CLAUDE.md dla instrukcji	~/.codex/config.toml oraz AGENTS.md dla instrukcji
Sandboxing	Opcjonalny (opt-in); zmienne środowiskowe dziedziczone z powłoki nadrzędnej	Domyślnie włączony w trybie zapisu do przestrzeni roboczej, sieć wyłączona, chyba że zostanie włączona
Błędny SKILL.md	Cicha porażka przy ładowaniu	(Zachowanie nietestowane przez nas)

Kompromis związany z sandboxingiem

Najważniejszą różnicą w środowiskach wykonawczych jest domyślne zachowanie sandboxingu.

Codex CLI, zgodnie ze swoją dokumentacją, działa z bardziej rygorystycznym domyślnym podejściem do bezpieczeństwa. W trybie zapisu do przestrzeni roboczej dostęp do sieci jest wyłączony, chyba że jawnie włączysz go w config.toml. Zapisy do systemu plików są ograniczone do bieżącej przestrzeni roboczej, a domyślna polityka zatwierdzania agenta polega na proszeniu o potwierdzenie przed podjęciem działania. Jest to model 'domyślnie odmawiaj' ('default-deny').

Claude Code, jak dokumentuje Anthropic, przyjmuje inne podejście. Sandboxing jest czymś, co włączasz, a nie wyłączasz, a nawet po włączeniu powłoka domyślnie dziedziczy środowisko procesu nadrzędnego. Oznacza to, że jeśli masz poświadczenia takie jak AWS_ACCESS_KEY_ID wyeksportowane w sesji terminala, umiejętność wywołana przez Claude Code może je potencjalnie odczytać. To sprawia, że umiejętności komunikujące się z zewnętrznymi usługami lub lokalnymi poświadczeniami działają od razu po instalacji, ale nakłada na ciebie ciężar zarządzania tym ryzykiem.

Żadne z podejść nie jest samo w sobie lepsze; to kompromis. Model Codex domyślnie priorytetyzuje bezpieczeństwo, co może wymagać więcej konfiguracji, aby uruchomić umiejętność sieciową. Model Claude Code priorytetyzuje funkcjonalność działającą od razu po instalacji, potencjalnie narażając więcej środowiska hosta. Umiejętność, która wywołuje curl do API, może po prostu zadziałać na Claude Code, ale być domyślnie zablokowana na Codex CLI.

Reguła decyzyjna: Oceniaj środowisko, nie plik

Zatem, Claude Code vs Codex CLI: którego używać do obsługi umiejętności?

Nasze dane dostarczają uczciwej, choć niekompletnej odpowiedzi. Sam format pliku SKILL.md nie jest czynnikiem decydującym. Prawdziwa decyzja zależy od środowiska wykonawczego i zależności umiejętności, które chcesz uruchomić.

1. Sprawdź zależności od narzędzi: Czy umiejętność opiera się na wbudowanych, specyficznych dla agenta narzędziach (jak generowanie obrazów w Generate 2D Map)? Jeśli tak, nie będzie przenośna.
2. Sprawdź zależności od uniwersalnych CLI: Czy umiejętność używa tylko wszechobecnych narzędzi wiersza poleceń? Ma dużą szansę na przenośność, jak pokazało 11 umiejętności zorientowanych na Codex, które przeszły testy w naszym środowisku Claude Code.
3. Rozważ swoje preferencje dotyczące sandboxingu: Czy wolisz system, który jest domyślnie zablokowany i wymaga jawnych uprawnień (Codex CLI)? Czy może wolisz taki, który działa z mniejszymi oporami od razu po instalacji, ale dziedziczy pełny kontekst środowiska (Claude Code)?

Nie możemy ogłosić uniwersalnego zwycięzcy, ponieważ nie testowaliśmy na obu platformach. Wybór zależy od twoich konkretnych potrzeb i podejścia do bezpieczeństwa. To, co możemy powiedzieć z całą pewnością, to że zakładanie, iż umiejętność zadziała tylko dlatego, że plik SKILL.md jest kompatybilny, jest błędem. Środowisko jest wszystkim.

Powiązane artykuły: AGENTS.md vs Claude Skills omawia drugą połowę zagadnienia między narzędziami — plik instrukcji, który każdy agent odczytuje przed załadowaniem jakiejkolwiek umiejętności. A jeśli wybierasz między agentami terminalowymi z powodów innych niż umiejętności, Claude Code vs Cursor analizuje ten kompromis.

W SkillProof naszą wartością jest eliminowanie tej niepewności dla ekosystemu Claude Code. My przeprowadzamy testy, żebyś ty nie musiał. Każdy werdykt 'pass' w naszym katalogu reprezentuje umiejętność, którą zainstalowaliśmy i uruchomiliśmy na Claude Code, na prawdziwym zadaniu. Jako wyselekcjonowany punkt startowy, nasze pakiety umiejętności oparte na rolach zbierają po dziesięć przetestowanych umiejętności dla jednej funkcji zawodowej — dewelopera, audytora bezpieczeństwa, marketingu, projektowania i czterech innych — za 10 dolarów za pakiet, z werdyktem każdej umiejętności podanym z góry.