Czym są skille (Agent Skills) i jak napisać taki, który agent faktycznie odpali

Skill to folder, nie prompt

Najczęstsze nieporozumienie brzmi tak: „skill to taki dłuższy prompt zapisany w pliku“. Nie. Prompt piszesz raz i wysyłasz. Instrukcja siedzi w kontekście zawsze. Skill to folder, który agent ładuje dopiero wtedy, gdy uzna, że jest potrzebny — i to jedno zdanie tłumaczy całą resztę mechaniki.

Minimalny skill to katalog z jednym plikiem:

my-skill/
├── SKILL.md          # Wymagane: metadane + instrukcje
├── scripts/          # Opcjonalnie: kod do uruchomienia
├── references/       # Opcjonalnie: dokumentacja
└── assets/           # Opcjonalnie: szablony, zasoby

Format nie jest wymysłem GitHuba. Agent Skills to otwarty standard (agentskills.io), pierwotnie opracowany przez Anthropic i wypuszczony jako specyfikacja. Ten sam folder działa dziś w Copilocie, Claude Code, Cursorze, Codeksie, Gemini CLI, OpenCode, Goose i kilkudziesięciu innych klientach. To realna przenośność, a nie marketingowa — piszesz raz, używasz wszędzie.

Mechanizm, który musisz zrozumieć: progressive disclosure

Agent nie wczytuje wszystkich twoich skilli do kontekstu. Robi to na trzy raty:

Konsekwencje są dwie i obie są praktyczne.

Pierwsza: możesz mieć zainstalowanych czterdzieści skilli i płacić kontekstem tylko za czterdzieści opisów. Dlatego skille skalują się tam, gdzie instrukcje przestają — plik copilot-instructions.md rozdęty do 400 linii je kosztuje w każdej pojedynczej wiadomości.

Druga, ważniejsza: description to jedyna część skilla, którą model widzi zawsze. To nie jest opis dla ludzi w README. To jest cały interfejs twojego skilla. Jeśli opis nie mówi wprost, kiedy sięgnąć po ten skill, skill nie odpali się nigdy — będzie leżał w katalogu, a ty będziesz się zastanawiał, dlaczego „AI go ignoruje“.

Anatomia SKILL.md

Plik markdown z frontmatterem YAML. Wymagane są dwa pola:

Dwa ostatnie pola są niedoceniane.

disable-model-invocation: true zamienia skill w narzędzie wyłącznie ręczne. Sensowne wszędzie tam, gdzie automatyczne odpalenie byłoby szkodliwe — deploy, migracja, cokolwiek z efektem ubocznym. Agent go nie tknie, dopóki nie wpiszesz /nazwa.

context: fork to odpowiedź na problem, o którym pisałem przy higienie context window. Skill, który przeszukuje trzydzieści plików, żeby wypluć jeden akapit wniosku, zaśmieca ci główną rozmowę trzydziestoma plikami. Z fork cała ta robota dzieje się w osobnym kontekście subagenta, a do rozmowy wraca wynik. Używaj do skilli, które dużo czytają, a mało zwracają.

description, który się odpala

To jest ta część, na której ludzie tracą najwięcej — dlatego konkretnie.

Źle:

description: Pomaga z testami

Model dostaje trzy słowa i musi zgadnąć, czy „napisz test do tej klasy“ to trafienie. Czasem zgadnie, częściej nie.

Dobrze:

description: >
  Tworzenie i debugowanie testów E2E w Playwright.
  Użyj przy pisaniu nowych testów przeglądarkowych, naprawianiu
  niestabilnych testów i konfiguracji infrastruktury testowej
  w nowym projekcie.

Reguła jest jedna: opis ma zawierać wyzwalacze, nie definicję. Nie „co to jest“, tylko „w jakiej sytuacji po to sięgnąć“. Wpisz w opis słowa, których użyje developer w prompcie — nazwy narzędzi, technologii, typów zadań. Jeśli twój skill dotyczy EF Core, w opisie muszą paść EF Core, LINQ, migracja, DbContext. Model dopasowuje semantycznie, ale nie czyta w myślach.

Kompletny przykład z dokumentacji VS Code:

---
name: webapp-testing
description: Guide for testing web applications using Playwright. Use this when asked to create or run browser-based tests.
---

# Web Application Testing with Playwright

## When to use this skill

Use this skill when you need to:
- Create new Playwright tests for web applications
- Debug failing browser tests
- Set up test infrastructure for a new project

## Creating tests

1. Review the [test template](./test-template.js) for the standard test structure
2. Identify the user flow to test
3. Create a new test file in the `tests/` directory
4. Use Playwright's locators to find elements (prefer role-based selectors)
5. Add assertions to verify expected behavior

## Best practices

- Use data-testid attributes for dynamic content
- Keep tests independent and atomic
- Use Page Object Model for complex pages

Zwróć uwagę na strukturę ciała: sekcja „kiedy używać“, potem ponumerowana procedura, na końcu zasady. To nie jest przypadek — skill ma być procedurą do wykonania, nie esejem o dobrych praktykach. Jeśli twój SKILL.md czyta się jak artykuł, przepisz go na listę kroków.

Pliki towarzyszące

Tu jest przewaga skilla nad każdą inną formą customizacji: skill może wieźć ze sobą kod i zasoby.

.github/skills/
└── webapp-testing/
    ├── SKILL.md
    ├── test-template.js
    ├── scripts/
    │   └── seed-test-db.sh
    └── examples/
        └── page-object.md

Copilot wykrywa wszystkie pliki w katalogu skilla i udostępnia je obok instrukcji. Ale załadowane zostaną tylko te, na które wskażesz — zwykłym relatywnym linkiem markdown:

Zacznij od [szablonu testu](./test-template.js), a strukturę
Page Object weź z [przykładu](./examples/page-object.md).

To trzeci etap progressive disclosure w praktyce. Plik, którego nie zalinkujesz, nie kosztuje cię ani jednego tokena. Możesz więc trzymać w skillu obszerną referencję i płacić za nią tylko wtedy, gdy jest potrzebna.

Gdzie kłaść skille

Dwa poziomy, kilka akceptowanych ścieżek:

Trzy ścieżki projektowe istnieją dla zgodności między narzędziami: .claude/skills czytają zarówno Claude Code, jak i Copilot. Jeśli w zespole część osób siedzi na Claude Code, a część na Copilocie, jeden katalog obsłuży obie grupy.

Kolejność ładowania to first-found-wins: projekt przed katalogami osobistymi, katalogi osobiste przed skillami z pluginów. Przy konflikcie nazw wygrywa pierwszy znaleziony, a pozostałe znikają bez ostrzeżenia. Pisałem o tym szerzej przy pluginach do Copilot CLI — to ta sama pułapka, tylko widziana z drugiej strony.

Gdzie skille działają

To jest argument, który zwykle przekonuje sceptyków w zespole. Ten sam katalog obsługują:

• Copilot w VS Code i JetBrains (agent mode)
• Copilot CLI — w terminalu
• Copilot cloud agent — agent pracujący na issue w chmurze
• Copilot code review — od lipca 2026 GA, skille z .github/skills/ wpływają na automatyczny review PR-ów, a komentarze oznaczają, że powstały z użyciem skilla
• GitHub Copilot App

I dalej, poza ekosystemem GitHuba, bo to otwarty standard: Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Goose, Kiro, Roo Code i wiele innych.

Ostatni punkt z tej listy jest niedoceniany strategicznie. Skill spisany raz przeżyje zmianę narzędzia. Instrukcje w formacie .github/copilot-instructions.md i prompt files są specyficzne dla VS Code i GitHuba — przy migracji zespołu na inne narzędzie po prostu przepadają.

Instalowanie cudzych skilli: gh skill

Nie wszystko musisz pisać sam. GitHub CLI ma od kwietnia 2026 osobny zestaw komend:

gh skill search mcp-apps                                   # szukaj
gh skill preview github/awesome-copilot documentation-writer   # zajrzyj przed instalacją
gh skill install github/awesome-copilot                    # przeglądaj repo interaktywnie
gh skill install github/awesome-copilot documentation-writer
gh skill install github/awesome-copilot documentation-writer@v1.2.0
gh skill install OWNER/REPO SKILL --agent claude-code --scope user
gh skill update --all                                      # aktualizuj wszystko
gh skill publish --fix                                     # waliduj i opublikuj własne

Warto znać --pin:

gh skill install github/awesome-copilot documentation-writer --pin abc123def

Pinowanie do commita albo tagu daje powtarzalne instalacje. Przy skillach z zewnętrznych repozytoriów traktuj to jako domyślne — o tym za chwilę.

Sensowne źródła na start: github/awesome-copilot i anthropics/skills. Na tym blogu opisywałem trzy konkretne, których używam: Impeccable do frontendu, Taste Skill jako anty-slopowy fundament i Ponytail do wymuszania najprostszego rozwiązania.

Skill, instrukcja, prompt file czy własny agent?

Pytanie, które dostaję najczęściej. Tabela decyzyjna:

Praktyczna heurystyka:

• Instrukcje — reguły, które mają obowiązywać zawsze: „używamy Result<T> zamiast wyjątków“, „testy w xUnit“. Jeśli to zdanie ma sens przy każdym zadaniu, to instrukcja. Szczegóły: instrukcje w GitHub Copilot.
• Skill — wiedza sytuacyjna z procedurą: „jak u nas robi się migrację bazy“, „jak wygląda review komponentu React“. Potrzebna w 5% zadań, ale wtedy potrzebna w całości.
• Prompt file — powtarzalna komenda, którą odpalasz świadomie: „wygeneruj changelog z ostatnich commitów“.
• Custom agent — kiedy chcesz zmienić nie wiedzę, tylko zachowanie i uprawnienia: agent od review bez prawa zapisu, agent od dokumentacji bez dostępu do terminala. Więcej: własny agent Copilot w VS Code.

Najczęstszy błąd, jaki widzę: wpychanie do copilot-instructions.md wszystkiego, łącznie z procedurami potrzebnymi raz na miesiąc. Plik rośnie, koszt rośnie w każdej wiadomości, a jakość spada, bo model dostaje ścianę tekstu, z której 90% jest nieistotne dla bieżącego zadania. Wszystko, co jest sytuacyjne, powinno być skillem.

Bezpieczeństwo: allowed-tools i markdown, który jest kodem

Dwie rzeczy, na które trzeba uważać.

Pierwsza: allowed-tools. To pole zdejmuje potwierdzenie przed użyciem narzędzia. Wpisanie tam shell albo bash oznacza, że skill uruchamia polecenia w terminalu bez pytania. Dokumentacja GitHuba mówi o tym wprost: wstępne zatwierdzenie powłoki pozwala skillowi kontrolowanemu przez atakującego lub prompt injection wykonać dowolne polecenie.

Reguła: allowed-tools tylko dla narzędzi odczytu (view, glob, rg). Zapis i shell zostawiaj za potwierdzeniem, chyba że skill jest w pełni twój i wiesz, co robi każda linijka.

Druga: skill to kod wykonywalny, mimo że to markdown. Agent czyta SKILL.md jako instrukcje i według nich działa — z twoim repozytorium i twoim terminalem. Instalując cudzy skill, instalujesz cudze instrukcje dla agenta z dostępem do twojej maszyny. Stąd gh skill preview przed instalacją i --pin do konkretnego commita zamiast do ruchomej gałęzi.

Jeśli myślisz o rozdaniu skilli całemu zespołowi, cała ta tematyka jest szerzej rozłożona w artykule o dystrybucji skilli w firmowym środowisku.

Pierwszy skill w dziesięć minut

Weź procedurę, którą tłumaczyłeś komuś w zespole więcej niż dwa razy. To najlepszy kandydat — jeśli trzeba ją było tłumaczyć, agent też jej nie zna.

1. mkdir -p .github/skills/nazwa-skilla
2. W środku SKILL.md: name = nazwa katalogu, description = jedno zdanie „co“ plus jedno „kiedy“, z konkretnymi słowami-wyzwalaczami.
3. Ciało: sekcja „kiedy używać“, potem ponumerowana procedura. Krótko. Skill to instrukcja obsługi, nie artykuł.
4. Dorzuć szablon albo skrypt, jeśli procedura go używa, i zalinkuj relatywnie.
5. Sprawdź: /skills list w Copilot CLI albo /skills w VS Code.
6. Test właściwy: zadaj pytanie, przy którym skill powinien się odpalić — ale nie wpisuj jego nazwy. Jeśli się nie odpalił, problem jest w description, nie w treści.

Krok szósty jest tym, który wszyscy pomijają. Skill wywołany ręcznie przez /nazwa zawsze zadziała — to nie dowodzi niczego. Dowodem jest odpalenie automatyczne.

Wniosek

Skill to najtańsza forma trwałej wiedzy dla agenta: kosztuje jeden opis w kontekście, dopóki nie jest potrzebny, a kiedy jest — wnosi całą procedurę razem ze skryptami. To odwrotność instrukcji, które płacisz w każdej wiadomości niezależnie od tego, czy są istotne.

Trzy rzeczy warte zapamiętania: description to interfejs, nie dokumentacja. Ciało to procedura, nie esej. A test polega na tym, że skill odpala się sam — jeśli musisz go wołać po nazwie, właśnie zbudowałeś prompt file z dodatkowymi krokami.

Kiedy skilli zrobi się kilka i zaczniesz je rozdawać dalej, następny krok to spakowanie ich w plugin do Copilot CLI. A jeśli wolisz przejść to z ćwiczeniami, mam o tym osobną lekcję w kursie.

Źródła: About agent skills, Agent Skills w VS Code, Adding agent skills for Copilot CLI, Copilot CLI plugin reference, Manage agent skills with GitHub CLI, Copilot code review: agent skills GA, specyfikacja Agent Skills. Stan: sierpień 2026.