SKILLS.md czy SKILL.md? Umiejętności agentów AI

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 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	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	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.