--- title: "SKILLS.md czy SKILL.md? Umiejętności agentów AI" url: "https://majchrzycki.com/blog/skills-md-skill-md-umiejetnosci-agentow" description: "Czym jest skill agenta, jak zapisać go w SKILL.md i czym różni się od AGENTS.md oraz promptu? Przykład, ograniczenia i test w AI SDLC." --- # SKILLS.md czy SKILL.md? Umiejętności agentów AI 30 czerwca 2026· Aktualizacja: 28 września 2026·2 min czytania·Krzysztof Majchrzycki Temat: [AI SDLC](https://majchrzycki.com/blog/filar/ai-sdlc) **Skill to wielokrotnego użytku instrukcja wykonania określonego rodzaju zadania przez agenta.** Może zawierać procedurę, przykłady, skrypty i materiały referencyjne. W [otwartej specyfikacji Agent Skills](https://agentskills.io/specification) wymagany plik ma nazwę **`SKILL.md`**, w liczbie pojedynczej, i leży w katalogu danej umiejętności. Nazwa `SKILLS.md` z liczbą mnogą może być własną konwencją zespołu lub spisem umiejętności, ale nie jest tym wymaganym plikiem specyfikacji. Ta różnica ma znaczenie: agent szukający standardowego formatu może nie odkryć pliku o innej nazwie. ## Co znajduje się w katalogu skilla? Minimalny układ wygląda tak: ``` sprawdz-migracje-bazy/ ├── SKILL.md ├── scripts/ │ └── compare-schema.py └── references/ └── zasady-migracji.md ``` `SKILL.md` zaczyna się od frontmatter YAML z polami `name` i `description`. Pierwsze określa nazwę, drugie mówi agentowi, kiedy umiejętności użyć. Treść Markdown opisuje kroki, kryteria wyniku oraz sytuacje wyjątkowe. Dodatkowe katalogi są opcjonalne. Skrypt może wykonać powtarzalny pomiar, a plik referencyjny przechować dłuższą dokumentację ładowaną dopiero wtedy, gdy jest potrzebna. Specyfikacja nazywa to stopniowym ujawnianiem kontekstu. ``` --- name: sprawdz-migracje-bazy description: Sprawdź plan migracji schematu PostgreSQL przed wdrożeniem. --- ``` Po frontmatter warto podać sekwencję pracy: odczytaj zmianę schematu, zidentyfikuj blokady i operacje nieodwracalne, uruchom test na kopii danych, przedstaw ryzyko i plan wycofania. Skill nie powinien obiecywać, że każdy skrypt zadziała bez zależności; wymagane środowisko należy opisać. Kod i instrukcje podlegają zwykłemu przeglądowi bezpieczeństwa. ## Czym skill różni się od AGENTS.md i specyfikacji zadania? Artefakt Zakres Przykład [AGENTS.md](https://majchrzycki.com/blog/agents-md-instrukcje-agentow-ai-sdlc) Stałe zasady repozytorium lub jego podkatalogu „Uruchom test kontraktu przed zmianą API”. `SKILL.md` Powtarzalna metoda dla określonej klasy zadań „Jak przeprowadzić bezpieczną migrację bazy”. [Specyfikacja funkcji](https://majchrzycki.com/blog/github-spec-kit-specyfikacja-ai-sdlc) Wymagania jednej zmiany „Dodaj pole statusu do formularza zamówienia”. Skill może działać w kilku repozytoriach. `AGENTS.md` pomaga dopasować go do lokalnych ograniczeń. Specyfikacja funkcji mówi, co ma powstać w tym konkretnym zadaniu. Mieszanie tych warstw prowadzi do konfliktów: gdy niezmienne zasady projektu schowamy w skillu wywoływanym tylko czasem, agent może ich nie zobaczyć; gdy całą procedurę umieścimy w głównym `AGENTS.md`, obciążymy każde zadanie niepotrzebnym kontekstem. ## Dlaczego to pomaga w AI SDLC? Agent kodujący często dobrze realizuje zadanie, ale pomija jeden krok odbioru: test regresji, aktualizację dokumentacji albo sprawdzenie uprawnień. Skill może utrwalić sprawdzony przebieg. Na przykład „przygotuj PR” może wymagać odczytu stanu Git, wykonania odpowiednich testów, streszczenia ryzyka i wskazania zmian w danych. Dzięki temu zespół porównuje wyniki różnych agentów na tej samej procedurze. W suwerennym stosie katalog skilli można wersjonować we własnym repozytorium i przenosić między środowiskami. Nie oznacza to pełnej przenośności automatycznej: agenci różnią się obsługą narzędzi, sposobem aktywacji i uprawnieniami. Trzeba sprawdzić zgodność w docelowym kliencie oraz to, czy materiały dodatkowe są rzeczywiście odczytywane. ## Jak bezpiecznie ocenić skill? Przygotuj zadanie kontrolne z prawidłowym wejściem, brakującą zależnością i próbą wymuszenia niedozwolonej akcji. Uruchom je z aktywnym skillem oraz bez niego. Sprawdź, czy agent wybrał właściwą metodę, zgłosił brak, nie przekroczył uprawnień i przedstawił wynik możliwy do odtworzenia. Szczególnie uważaj na skrypty pobrane z obcego repozytorium: opis „skill” nie jest przeglądem ich kodu. Jeżeli zespół chce utrzymywać plik `SKILLS.md` jako katalog odsyłaczy do umiejętności, może to zrobić, ale każdą umiejętność zgodną z Agent Skills powinien nadal umieścić w jej własnym katalogu z `SKILL.md`. Taki podział daje czytelny spis dla ludzi i rozpoznawalny format dla agentów. Gdy kilka skilli i połączeń MCP trzeba instalować oraz aktualizować razem, zobacz [porównanie pluginów Claude, ChatGPT, Codex i innych agentów](https://majchrzycki.com/blog/pluginy-agentow-claude-chatgpt-codex-copilot). - Agenci AI ## Przełóż temat na projekt w Twojej firmie Zobacz zakres współpracy: od rozpoznania procesu i danych po projekt rozwiązania AI. [Zobacz współpracę](https://majchrzycki.com/wspolpraca) ## Czytaj dalej - [Pluginy agentów AI: Claude, ChatGPT, Codex i Copilot](https://majchrzycki.com/blog/pluginy-agentow-claude-chatgpt-codex-copilot) - [AGENTS.md: stałe instrukcje dla agentów kodujących](https://majchrzycki.com/blog/agents-md-instrukcje-agentow-ai-sdlc) - [GitHub Spec Kit: specyfikacja przed kodowaniem z AI](https://majchrzycki.com/blog/github-spec-kit-specyfikacja-ai-sdlc) - [Umiejętności SKILL.md w Microsoft 365 Copilot Cowork](https://majchrzycki.com/blog/microsoft-copilot-cowork-umiejetnosci-skill-md)