AGENTS.md, SKILL.md, agent-permissions.json - nowy standard plików dla AI na Twojej stronie

Jeszcze rok temu wszyscy mówili wyłącznie o llms.txt. Dziś rozmowa o optymalizacji stron pod sztuczną inteligencję wygląda zupełnie inaczej. Obok llms.txt pojawiły się trzy nowe pliki, które razem tworzą pełnoprawny protokół komunikacji między Twoją witryną a agentami AI: AGENTS.md, SKILL.md oraz agent-permissions.json.

To nie są teoretyczne koncepcje z dokumentacji. To pliki, które agenci programistyczni typu Claude Code, Cursor, Codex CLI, GitHub Copilot, Windsurf, Amp i Devin faktycznie czytają przed rozpoczęciem pracy z Twoją dokumentacją. To także pliki, których obecność sprawdzają audytory typu agentic-seo i po których AI crawlery rozpoznają, czy Twoja strona jest przyjazna automatycznym systemom.

W tym artykule wyjaśniam, czym różni się każdy z tych trzech plików, dlaczego razem tworzą komplementarną warstwę AEO (Agentic Engine Optimization) oraz jak FactorAI wdrożyło je na własnej stronie w kwietniu 2026 roku, uzyskując wynik A 97/100 w audycie agent-readiness.

Dlaczego powstał nowy standard

W 2024 roku Jeremy Howard zaproponował plik llms.txt jako mapę drogową strony dla systemów AI. Pomysł szybko się przyjął - dziś ponad 600 dużych witryn na świecie korzysta z tego standardu, w tym Stripe, Anthropic i Hugging Face. Problem w tym, że llms.txt został zaprojektowany z myślą o modelach językowych pobierających pojedyncze dokumenty.

Tymczasem w 2025 roku eksplodowała kategoria agentów AI, czyli autonomicznych programów wykorzystujących modele językowe do wykonywania zadań w imieniu użytkownika. Claude Code, Cursor, Cline, Aider, Continue.dev, Devin, Goose - każde z tych narzędzi inaczej konsumuje dokumentację niż człowiek i inaczej niż model pobierający pojedynczy URL.

Agenci potrzebują trzech dodatkowych informacji, których llms.txt nie dostarcza:

1. Kontekst projektu - kto jest właścicielem strony, jakie są konwencje, jak zbudowany jest kod
2. Opis możliwości - co usługa faktycznie robi, jakie ma ograniczenia, jakich danych oczekuje od użytkownika
3. Reguły dostępu - ile requestów na minutę wolno wysłać, czy wolno używać treści do trenowania modeli, czy wymagana jest atrybucja

Właśnie te trzy potrzeby pokryły trzy nowe pliki. Żaden z nich nie zastępuje llms.txt - razem tworzą komplementarny zestaw.

AGENTS.md - entry point dla agentów programistycznych

AGENTS.md to plik w formacie Markdown umieszczany w katalogu głównym repozytorium lub strony internetowej. Jego rolą jest stanowienie pierwszego punktu kontaktu dla agentów AI pracujących z kodem.

AGENTS.md emerged z wspólnego wysiłku ekosystemu AI software development, w tym OpenAI Codex, Amp, Jules od Google, Cursor oraz Factory. Obecnie AGENTS.md jest stewardowany przez Agentic AI Foundation pod Linux Foundation. Ponad 60 000 open-source repozytoriów na GitHubie używa już AGENTS.md.

Kto czyta AGENTS.md natywnie

Codex CLI, GitHub Copilot, Cursor, Windsurf, Amp oraz Devin czytają AGENTS.md natywnie od pierwszego dnia istnienia tego formatu. Claude Code używa obecnie odrębnego pliku CLAUDE.md z bardzo podobną rolą, ze wsparciem dla AGENTS.md planowanym w kolejnych wersjach. Większość zespołów stosuje pragmatyczne podejście - tworzy uniwersalny AGENTS.md i osobny CLAUDE.md wyłącznie dla funkcji specyficznych dla Claude Code.

Co powinno znaleźć się w AGENTS.md

Plik powinien zawierać informacje, których nie da się wywnioskować z samego kodu:

• Opis projektu - czym jest, kto jest odbiorcą, w jakim kontekście biznesowym powstaje
• Struktura katalogów - gdzie znajduje się kod aplikacji, gdzie testy, gdzie konfiguracja
• Konwencje kodowania - używany język, framework, styl nazewnictwa, preferowane wzorce
• Komendy buildowe i testowe - jak uruchomić dev server, jak zbudować produkcję, jak sprawdzić jakość kodu
• Kluczowe pliki konfiguracyjne - gdzie są zmienne środowiskowe, gdzie definicje schematu bazy danych
• Zewnętrzne zależności i usługi - jakie API jest wykorzystywane, gdzie monitoring, gdzie logi

Różnica między AGENTS.md a README.md

README.md jest przeznaczony dla ludzi odwiedzających repozytorium - ma sprzedać projekt, pokazać demo, zaprosić do kontrybucji. AGENTS.md jest przeznaczony dla agentów AI - ma dać im pełen kontekst potrzebny do efektywnej pracy. Te dwa pliki się uzupełniają, nie dublują.

SKILL.md - opis możliwości usługi lub capability

SKILL.md opisuje co Twoja usługa lub API faktycznie robi. W przeciwieństwie do dokumentacji technicznej, która opisuje, jak wywołać endpoint, SKILL.md skupia się na tym, jakie operacje biznesowe są dostępne, jakich danych wymagają i jakie mają ograniczenia.

Format SKILL.md pochodzi bezpośrednio z specyfikacji Agent Skills ogłoszonej przez Anthropic w grudniu 2025 roku jako open standard. OpenAI adoptowało ten sam format dla Codex CLI i ChatGPT, dzięki czemu SKILL.md stał się portable, cross-platformowy standard definiowania capability AI.

Agent Skills to format open-source opublikowany przez Anthropic w grudniu 2025 roku. Każdy skill składa się z folderu zawierającego plik SKILL.md z frontmatter YAML (name, description) oraz opcjonalnych podfolderów scripts/, references/ i assets/. Claude ładuje frontmatter od razu, a resztę zawartości na żądanie - co utrzymuje niskie zużycie tokenów do czasu, aż zadanie faktycznie wymaga szczegółów.

Struktura SKILL.md

Plik zawiera:

• Frontmatter YAML z wymaganymi polami name (lowercase z myślnikami) i description (co robi skill i kiedy go użyć)
• Sekcję Required Inputs z listą wszystkiego, co użytkownik musi dostarczyć
• Sekcję Capabilities z opisami poszczególnych operacji i ich rezultatów
• Sekcję Constraints z ograniczeniami technicznymi i biznesowymi
• Sekcję Documentation Links kierującą do pełnej dokumentacji

Przykład struktury SKILL.md dla usługi B2B

Na stronie FactorAI SKILL.md opisuje między innymi:

• Audyt GEO za 790 zł - wymagane dane: URL strony klienta, branża, konkurenci; czas realizacji: 5-7 dni; rezultat: raport około 30-stronicowy
• Pakiet START 1500 zł/mc - wymagane dane: brief, dostęp do GA4 i Google Search Console; rezultat: 4 artykuły + 8 postów social; warunki: month-to-month
• Pakiety BIZNES i WZROST - szczegółowo z rezultatami, czasem realizacji i warunkami
• Strony internetowe - wycena indywidualna, czas realizacji 4-8 tygodni

Taki opis pozwala ChatGPT lub Claude wygenerować precyzyjną odpowiedź typu "FactorAI oferuje audyt GEO za 790 zł z dostawą w 5-7 dni roboczych", zamiast ogólnikowego "FactorAI to agencja zajmująca się GEO".

agent-permissions.json - reguły dostępu dla automatów

Trzeci plik to agent-permissions.json umieszczany w katalogu publicznym strony. Jego rolą jest jawne deklarowanie reguł, na jakich automatyczne systemy mogą konsumować Twoją treść. W odróżnieniu od AGENTS.md i SKILL.md plik ten nie jest jeszcze sformalizowanym standardem - funkcjonuje jako emerging convention promowana między innymi przez narzędzie agentic-seo Addy'ego Osmaniego.

Równocześnie trwają prace formalne - IETF AIPref Working Group rozwija standardową, maszynowo czytelną specyfikację preferencji AI, która prawdopodobnie zdefiniuje protokół w wersji końcowej. Do czasu jej publikacji agent-permissions.json pełni rolę bogatszej alternatywy dla tradycyjnego robots.txt.

Struktura agent-permissions.json

Plik jest standardowym JSON-em z następującymi sekcjami:

• permissions - top-level deklaracja co wolno, a czego nie wolno (read, cite, summarize, train, redistribute)
• rateLimits - maksymalna liczba requestów na minutę, godzinę i dzień dla domyślnych i zaufanych agentów
• interactions - zasady atrybucji, maksymalna długość cytatu, wymóg linku źródłowego
• agents - indywidualne reguły dla konkretnych agentów (ClaudeBot, GPTBot, PerplexityBot, CCBot)
• excludedPaths - ścieżki wykluczone z dostępu automatów (np. /api/, /admin/)

Dlaczego warto mieć ten plik, nawet jeśli reguły są pozwalające

Trzy powody. Po pierwsze, jawnie deklarujesz warunki - jeśli w przyszłości pojawi się spór prawny o niewłaściwe wykorzystanie Twoich treści, ten plik stanowi dowód oczekiwań. Po drugie, sygnalizujesz profesjonalizm - strony z agent-permissions.json wyglądają wiarygodniej dla AI oraz dla klientów oceniających Twoją znajomość tematu. Po trzecie, otwierasz drzwi do jawnej współpracy - zaufani agenci z wyższymi rate limits mogą stać się źródłem stałych poleceń Twojej firmy w AI.

Jak te trzy pliki współpracują

Najlepszym sposobem zrozumienia jest prześledzenie ścieżki agenta AI trafiającego na Twoją stronę.

Krok 1 - agent pobiera robots.txt i sprawdza, czy ma w ogóle wstęp. Jeśli tak, czyta llms.txt, żeby poznać strukturę treści i priorytetowe dokumenty.

Krok 2 - agent czyta AGENTS.md, żeby zrozumieć kontekst projektu. Dowiaduje się, że ta strona to agencja content marketingowa z Polski, specjalizująca się w GEO, z pakietami od 1500 zł.

Krok 3 - agent pobiera SKILL.md, żeby poznać konkretne możliwości usługi. Dowiaduje się, że można zamówić audyt GEO za 790 zł z dostawą w 5-7 dni lub pakiet miesięczny bez długoterminowych zobowiązań.

Krok 4 - agent sprawdza agent-permissions.json, żeby upewnić się, że wolno mu cytować treść. Dowiaduje się, że cytowanie jest dozwolone z wymogiem linku zwrotnego do factorai.pl.

Krok 5 - agent formułuje odpowiedź użytkownikowi, cytując Twoją firmę z pełnym kontekstem, poprawną atrybucją i precyzyjnymi danymi.

Bez tych czterech plików (włącznie z llms.txt) agent musiałby parsować HTML strony, zgadywać ceny z fragmentów tekstu i wymyślać atrybucję. Efekt byłby albo ogólnikowy, albo niepoprawny.

Implementacja na FactorAI - case study

W kwietniu 2026 roku wdrożyliśmy wszystkie trzy pliki na własnej stronie factorai.pl. Przed wdrożeniem audyt agentic-seo pokazał ocenę D 53/100 w kategorii agent-readiness. Po wdrożeniu ocena wzrosła do A 97/100 - maksymalnego wyniku osiągalnego w tym narzędziu.

Kluczowe elementy wdrożenia:

AGENTS.md w katalogu głównym zawiera około 90 linii. Opisuje projekt, strukturę katalogów Next.js 14, konwencje kodowania (TypeScript, Tailwind, React 18), informacje o trackingu analitycznym (Google Tag Manager, Meta Pixel, GA4) oraz instrukcje buildowe.

SKILL.md w formacie zgodnym ze specyfikacją Anthropic Agent Skills zawiera pełen opis wszystkich pakietów FactorAI, wymaganych inputów od klienta, czasu realizacji i ograniczeń (np. maksymalnie 8 nowych klientów miesięcznie).

agent-permissions.json w katalogu publicznym zawiera szczegółowe reguły dla 9 konkretnych agentów AI (ClaudeBot, GPTBot, ChatGPT-User, PerplexityBot, Google-Extended, CCBot i innych), rate limits 30-60 requestów na minutę w zależności od agenta oraz wymogi atrybucji przy cytowaniu.

Jak zacząć u siebie

Kolejność wdrożenia ma znaczenie. Zacznij od najprostszych kroków i stopniowo dodawaj kolejne warstwy.

Tydzień 1 - AGENTS.md. Napisz 50-100 linii opisujących Twój projekt. Skup się na informacjach, których nie da się wywnioskować z kodu.

Tydzień 2 - SKILL.md. Opisz swoje usługi z perspektywy klienta. Co konkretnie dostaje, ile to kosztuje, jakie są terminy, jakich danych potrzebujesz od niego.

Tydzień 3 - agent-permissions.json. Zdefiniuj reguły dostępu. Zacznij od szerokich uprawnień z wymogiem atrybucji, później zawęź je na podstawie rzeczywistego ruchu.

Tydzień 4 - audyt. Odpal npx agentic-seo --url https://twoja-strona.pl i sprawdź wynik. Jeśli widzisz obszary do poprawy, iteruj.

Przyszłość protokołu

AGENTS.md i SKILL.md są już uznanymi standardami branżowymi - pierwszy stewardowany przez Linux Foundation, drugi opublikowany przez Anthropic jako open standard i adoptowany przez OpenAI. agent-permissions.json pozostaje emerging convention, z formalną specyfikacją rozwijaną przez IETF AIPref Working Group. Prawdopodobnie w 2026 i 2027 zobaczymy dalszą ewolucję tych formatów - pojawią się kolejne pola oraz formalne zatwierdzenie protokołu uprawnień.

Kluczowa obserwacja jest jednak inna. Strony internetowe przestają być wyłącznie dokumentami przeznaczonymi dla ludzi. Stają się interfejsami API dla automatów - strukturalnymi, opisanymi, wersjonowanymi, z jawnie deklarowanymi regułami. Firmy, które to rozumieją i wdrażają, już dziś zdobywają przewagę w odpowiedziach ChatGPT, Claude i Perplexity. Firmy, które tego nie robią, stają się niewidzialne dla rosnącej populacji użytkowników korzystających z asystentów AI.