Agent skills — instaluj z marketplace i pisz własne

Pytanie ze scorecardu: Jak używasz agent skills (SKILL.md)? Max odpowiedź (3 pkt): Piszę też własne skille w ~/.claude/skills/, .cursor/skills/ lub ~/.agents/skills/.

Dlaczego to ma znaczenie w 2026

Skille to najbardziej niedoceniana funkcja Tier 1 w całym stosie agentów na 2026. To wielokrotnego użytku, wywoływane przez model playbooki: folder z plikiem SKILL.md (plus opcjonalne skrypty, szablony i pliki referencyjne), który model sam ładuje gdy sytuacja pasuje do opisu — bez slash commanda, bez ręcznego importu, bez MCP servera, bez subagenta. W grudniu 2025 Anthropic opublikował specyfikację Agent Skills jako otwarty standard na agentskills.io, a w ciągu kilku tygodni OpenAI przyjął ten sam format SKILL.md w Codex CLI i ChatGPT, za nimi Cursor z folderem .cursor/skills/. W maju 2026 format jest naprawdę cross‑tool: ten sam SKILL.md działa bez zmian w Claude Code, Codex CLI, Cursor Agents i Gemini CLI. Ta standaryzacja zmieniła skille z claude‑only ciekawostki w najwyżej dźwigniowy prymityw rozszerzalności we wszystkich czterech głównych agentach — i dopiero ona sprawiła, że marketplace’y są naprawdę użyteczne, bo jeden skill ląduje wszędzie naraz.

Powód, dla którego Q8 oddziela setup za 2 pkt od setupu za 3 pkt, jest taki, że instalowanie skilli w 2026 to baza; pisanie ich samemu to ruch, który procentuje. Skille z marketplace są świetne na natychmiastowe level‑upy w domenach, które ktoś już zmapował (integracja Stripe, audyty dostępności, użycie rejestru shadcn, triage Sentry). Ale najcenniejsze są te, które kodują lekcje, których twoje przyszłe ja uczy się w kółko — kroki migracji dla twojego konkretnego setupu Drizzle + D1, sposób, w jaki twój zespół pisze server endpointy w Astro, dokładną repro harness dla tego flaky E2E testu. Nikt inny tych skilli za ciebie nie napisze, a za każdym razem kiedy agent ogarnia je od zera, palisz tokeny i tury, których nie musiałeś. Pisanie własnych to sposób, by przestać płacić ten sam podatek drugi raz.

Jak naprawdę wygląda “max score”

Setup za max punkty na Q8 ma obie połowy podpięte. Masz 10–30 skilli z marketplace zainstalowanych z jednego z rejestrów (LobeHub Skills, SkillsMP, SkillHub lub mcpmarket.com/tools/skills), pokrywających uniwersalne rzeczy — code review, audyty SEO, testy Stripe / Polar, wysyłanie maili Resend, shadcn UI, typografia webowa, pętle Sentry. Leżą w ~/.claude/skills/ (i w symlinkowanym lub zduplikowanym .cursor/skills/ oraz ~/.agents/skills/, żeby wszystkie trzy narzędzia je widziały). Masz też 3–10 własnych skilli w tych samych katalogach: co najmniej jeden per aktywne repo dla specyfiki projektu, co najmniej jeden osobisty skill dla workflowu, który robisz w wielu projektach (np. “wyślij PR i pilnuj review loop”, “rebase na main i rozwiąż typowe konflikty”) i co najmniej jeden zespołowy skill dla nieoczywistego wewnętrznego patternu.

Kiedy sesja potrzebuje skilla, nie wzywasz go — model sam go wywołuje, bo opis w twoim SKILL.md pasuje do prośby. W transkrypcie zobaczysz linie typu Loading skill: stripe-best-practices albo Reading skills/your-repo-conventions/SKILL.md bez wpisywania czegokolwiek. Rewidujesz skille w miarę nauki: kiedy sesja ujawni nową pułapkę, nie tylko naprawiasz problem na teraz, dopisujesz zdanie do odpowiedniego SKILL.md, żeby następna sesja na nim nie wyłożyła. Ta pętla zwrotna jest różnicą między “mam skille” (2 pkt) a “skille to mój sposób na łapanie i recykling własnej wiedzy” (3 pkt).

Aktualny stan rynku (zweryfikowany web searchem)

Ekosystem skilli w 2026 stoi na trzech filarach: otwarty format (SKILL.md plus YAML frontmatter), garść publicznych marketplace’ów i oficjalne repo Anthropic jako kanoniczna implementacja referencyjna. Wszystkie trzy narzędzia (Claude Code, Codex CLI, Cursor Agents) czytają ten sam format ze swoich katalogów skilli — nie potrzebujesz już osobnych ekosystemów wtyczek per narzędzie.

Marketplace skilli (LobeHub Skills, SkillsMP, SkillHub) w 2026

W praktyce liczą się cztery marketplace’y. LobeHub Skills jest największy pod względem jakości curation — celuje wprost w Claude Code, Codex CLI i ChatGPT, a każdy wpis to plik SKILL.md (nie prompt, nie MCP server). Kategorie obejmują workflow, design, marketing, dev tooling i integracje; strona główna ma planszę “Top 20 All Skills”, która jest sensownym punktem startowym, jeśli nie wiesz co zainstalować. SkillsMP to katalog o największym wolumenie, około 30 000+ wpisów w maju 2026, ale lista miesza czyste skille z promptami, agentami i MCP serverami, więc trzeba filtrować po “Skill”. SkillHub siedzi pośrodku, z 7 000+ skilli ocenionych przez AI, otagowanych pod Claude, Codex, Gemini i OpenCode — jego kolumna z oceną przydaje się do filtrowania słabych wpisów. Katalog Skills w MCP Market jest najmniejszy, ale linkuje każdy skill do powiązanych MCP serverów, co jest przydatne, kiedy chcesz skill i integrację pod nim jednym zamachem. Tekst Claude Skills Marketplace Comparison 2026 na openaitoolshub.org porównuje sześć platform obok siebie i warto go przeczytać, zanim się gdzieś osiądziesz.

Flow instalacji jest taki sam we wszystkich czterech: ściągnij folder skilla (albo git clone), wrzuć do ~/.claude/skills/<name>/, następna sesja agenta go widzi. Dla Cursor Agents — zmirroruj do .cursor/skills/<name>/ (per‑projekt) albo ~/.cursor/skills/<name>/ (globalnie, tam gdzie wspierane). Dla Codex CLI i innych narzędzi kompatybilnych z AGENTS.md konwencją jest ~/.agents/skills/<name>/. Wielu użytkowników symlinkuje jeden kanoniczny katalog do wszystkich trzech lokalizacji, żeby utrzymywać go tylko raz.

Oficjalne skille Anthropic (anatomia SKILL.md)

Repo anthropics/skills na GitHubie to kanoniczna implementacja referencyjna i miejsce, do którego warto zajrzeć, żeby nauczyć się patternów na przykładach. Wysyła ze sobą skill skill-creator — tak, meta‑skill, który uczy Claude’a pisać pliki SKILL.md — plus kilkadziesiąt produkcyjnych przykładów pokrywających code review, audyty designu, frontend design, autorstwo promptów i więcej.

Struktura prawdziwego SKILL.md jest mała i sztywna. YAML frontmatter na górze z dwoma wymaganymi polami (name, description) i kilkoma opcjonalnymi (version, tools, model). Potem markdown body z właściwymi instrukcjami, opcjonalnie pogrupowanymi pod ## When to use, ## Steps, ## Examples, ## Gotchas. Opcjonalne pliki obok (skrypty, szablony, JSON z danymi referencyjnymi) referencjonuje się z markdown ścieżkami względnymi i ładuje leniwie — tylko kiedy body skilla każe agentowi je przeczytać.

Pole description to najważniejsza linia w całym skillu, bo to jedyne, co model widzi na starcie. Przy boocie sesji agent pre‑ładuje tylko nazwę i opis każdego zainstalowanego skilla — nic więcej. Czyta body SKILL.md dopiero, kiedy opis pasuje do requestu użytkownika, a referowane podpliki dopiero, kiedy body każe. To się nazywa progressive disclosure i to jest powód, dla którego setup z 50 skillami nie rozsadza ci okna kontekstu: na boocie płacisz może 2 KB metadanych, a nie 200 KB pełnej treści skilli.

Pisanie własnych (struktura katalogu, description dla discovery, kiedy się wywołuje)

Własny skill to po prostu folder. Minimalny przykład dla użytkownika Claude Code:

~/.claude/skills/my-repo-conventions/
├── SKILL.md          # playbook (wymagane)
├── examples/         # opcjonalne: przykłady kodu, do których skill się odwołuje
│   └── astro-endpoint.ts
└── scripts/          # opcjonalne: skrypty pomocnicze, które skill może odpalić
    └── run-tests.sh

Dla Cursora — zmirroruj do .cursor/skills/my-repo-conventions/ (projekt) albo ~/.cursor/skills/ (globalnie). Dla Codex CLI / Gemini CLI / innych narzędzi AGENTS.md: ~/.agents/skills/my-repo-conventions/.

Działający SKILL.md wygląda tak:

---
name: my-repo-conventions
description: Konwencje repo developer-toolkit — Astro server endpointy na Cloudflare Workers z D1 + Drizzle, paywall w /public/paywall-inline.js, treść EN/PL pod src/content/docs/{en,pl}. Wywołuj zawsze przy edycji API routes, MDX docs, paywalla albo schematu DB w tym repo.
version: 1.0.0
---

# Konwencje repo Developer Toolkit

## When to use

Wywołuj ten skill zawsze, kiedy user pracuje w repo `developer-toolkit`
(lub w dowolnym worktree pod `.claude/worktrees/`). Konkretnie:

- Edycja `src/pages/api/**.ts` (API routes)
- Edycja `src/content/docs/{en,pl}/**.mdx` (Starlight docs)
- Edycja `/public/paywall-inline.js` (paywall UI)
- Dotykanie `src/lib/db/schema.ts` albo `scripts/schema.sql` (schemat DB)

## Steps

1. API routes idą do `src/pages/api/`. Zawsze ciągnij bindingi z
   `locals.runtime.env` (D1 = `DB`, KV = `KV`, sesja = `SESSION`).
2. Docs idą parami — EN w `src/content/docs/en/<section>/<slug>.mdx`
   i PL w `src/content/docs/pl/<section>/<slug>.mdx`. Nie wysyłaj
   jednego bez drugiego.
3. Zmiany paywalla — tylko vanilla JS w `/public/paywall-inline.js`.
   Nie wprowadzaj do tego pliku TypeScripta ani frameworka.
4. Po każdej zmianie schematu DB zaktualizuj zarówno
   `src/lib/db/schema.ts`, jak i `scripts/schema.sql`, potem dodaj
   migrację pod `migrations/<timestamp>-<slug>.sql`.

## Gotchas

- `npm run deploy` jest tylko do CI — nigdy nie odpalaj lokalnie poza
  `--dry-run`. CI deployuje na push do master.
- Submoduły pod `src/content/docs/` są prywatne — pull przez
  `npm run submodule:pull`, nie przez `git submodule update` wprost.

Co sprawia, że ten opis działa: jest konkretny (wymienia faktyczny stack, ścieżki, nazwy plików), wylicza eksplicytne warunki triggera (“zawsze przy edycji API routes, MDX docs, paywalla albo schematu DB w tym repo”) i jest lekko pushy — własny przewodnik po pisaniu skilli od Anthropic wprost ostrzega, że Claude ma tendencję do under‑triggerowania skilli, więc opisy powinny iść raczej w stronę “tak, wywołaj mnie” niż “może mnie rozważ”. Body potem jest krótkie, używa progressive disclosure (referuje pliki tylko gdy trzeba) i wyjaśnia dlaczego w gotchas, żeby model mógł generalizować poza dosłowną listę.

Krok po kroku: budowanie skilla

Zaudytuj, co tłumaczysz w kółko. Otwórz transkrypty z ostatniego tygodnia (Claude Code: ~/.claude/projects/<repo>/transcripts/; Codex CLI: ~/.codex/sessions/). Znajdź trzy rzeczy, które wpisałeś więcej niż dwa razy. To twój pierwszy backlog skilli: każde powtarzane tłumaczenie to skill, który powinieneś był napisać.
Zainstaluj 5–10 skilli z marketplace, zanim napiszesz pierwszy. Wybierz z LobeHub Skills, SkillHub albo SkillsMP. Sensowny zestaw startowy: code-review, jeden stack‑specific (np. nextjs-best-practices albo astro-best-practices), jeden designowy (refactoring-ui), jeden opsowy (sentry-fix-issues) i meta‑skill skill-creator z anthropics/skills. Czytanie cudzych plików SKILL.md to najszybszy sposób na zinternalizowanie formatu.
Stwórz katalog. mkdir -p ~/.claude/skills/<nazwa-skilla>/. Pod cross‑tool sharing utwórz też ~/.cursor/skills/ i ~/.agents/skills/ i zsymlinkuj ten sam folder do obu. (ln -s ~/.claude/skills/<name> ~/.cursor/skills/<name> itp.)
Napisz najpierw YAML frontmatter. Dwa pola są wymagane: name (małe litery z myślnikami, musi zgadzać się z nazwą folderu) i description (jedno zdanie, konkretne, lista warunków triggera, lekko pushy). Spędź więcej czasu nad opisem niż nad body — to dosłownie jedyne, co model widzi na boocie. Jeśli opis jest generyczny (“pomaga z kodem”), skill nigdy się nie wywoła.
Napisz body w trzech sekcjach. ## When to use listuje konkretne warunki triggera, pliki albo typy zadań. ## Steps to właściwy playbook — numerowany, wykonalny, opiniodawczy. ## Gotchas listuje pułapki z powodem dla każdej (to dlaczego pozwala modelowi generalizować). Trzymaj cały plik poniżej ~300 linii; jeśli rośnie, rozbij na podpliki i referuj je z body, żeby ładowały się leniwie.
Testuj zapraszając go. Otwórz nową sesję agenta w odpowiednim repo i opisz zadanie, które powinno triggerować skill. Patrz w transkrypt: czy model załadował skill sam? Jeśli tak — v1 gotowy. Jeśli nie — opis był zbyt ogólny, dodaj konkretniejsze warunki triggera i spróbuj jeszcze raz. Nie polegaj na “powiedz modelowi, żeby użył skilla” — to wywala cały sens model‑invoked designu.
Iteruj na każdej sesji. Za każdym razem, kiedy sesja ujawni coś, co skill powinien był wiedzieć, a nie wiedział, dopisz zdanie (albo gotchę) do SKILL.md. Wrzuć skill do osobistego repo dotfiles albo zespołowego repo skills/, żeby przeżył zmiany maszyn i był współdzielony. Do trzeciego miesiąca będziesz miał 5–10 skilli, które procentują — każdy obniża tę samą klasę błędów do zera.

Najczęstsze pułapki

Zbyt ogólny description. “Pomaga z TypeScriptem” albo “Skill do code review” — to nigdy się nie wywoła, bo każde zadanie luźno dotyczy TypeScripta albo code review. Opis musi wymieniać konkretne warunki triggera (“zawsze przy edycji plików pod src/pages/api/”, “kiedy user wspomina Stripe webhooks albo PaymentIntent”). Jeśli nie umiesz wyartykułować, kiedy ma się odpalić — model też nie da rady.
Brak warunków triggera, tylko kroki. SKILL.md z samą sekcją ## Steps i bez bloku ## When to use mówi modelowi co zrobić, ale nie kiedy. Efekt: skill ładuje metadane na boocie i drzemie wiecznie, bo opis nie podpiął się do żadnego konkretnego sygnału.
Brak testu, czy skill się wywołuje. Autorzy piszą skill, widzą go w ~/.claude/skills/ i zakładają, że działa. Może nie działać. Otwórz świeżą sesję, opisz pasujące zadanie bez nazywania skilla i potwierdź w transkrypcie, że model go załadował. Jeśli nie — opis jest zepsuty, napraw zanim pójdziesz dalej.
Jeden mega‑skill na wszystko. SKILL.md na 2 000 linii, który pokrywa całe repo, konwencje zespołu, ulubione biblioteki i workflow debugowania, jest bezużyteczny. Model ładuje go raz dla “dowolnego zadania w tym repo” i pali tokeny na nieistotne sekcje. Rozbij na skupione skille (jeden na API routes, jeden na schemat DB, jeden na docs), żeby model ładował tylko to, co istotne.
Pominięcie kroku z marketplace. Autorzy, którzy piszą skille przed zainstalowaniem czegokolwiek, czują się jakby wymyślali format od zera. Zainstaluj najpierw 5–10 skilli z marketplace, przeczytaj ich pliki SKILL.md, dopiero potem pisz własne. Zaoszczędzisz godziny na konwencjach i odkryjesz pattern (progressive disclosure, lekko‑pushy opisy, blok ## When to use), które nie są oczywiste z samej spec.
Niezmirrorowanie między narzędziami. Jeśli wrzucisz skille tylko do ~/.claude/skills/, twoje sesje Codex CLI i Cursor Agents ich nie zobaczą. Albo zsymlinkuj katalog do wszystkich trzech lokalizacji (~/.cursor/skills/, ~/.agents/skills/), albo trzymaj jeden kanoniczny folder ~/skills/ i symlinkuj go wszędzie. Bez tego twoje własne skille działają tylko w jednym narzędziu, co podcina cały sens otwartego formatu.

Jak zweryfikować, że jesteś na miejscu

Masz 10+ skilli z marketplace zainstalowanych w ~/.claude/skills/ (albo odpowiedniku dla głównego narzędzia) — nie zero, nie trzy.
Masz 3+ autorskie skille, w tym co najmniej jeden projektowy i jeden osobisty/workflowowy.
Każdy twój skill ma description z konkretnymi warunkami triggera, a nie generycznym one‑linerem.
Twoje skille są zmirrorowane lub zsymlinkowane między ~/.claude/skills/, .cursor/skills/ i ~/.agents/skills/, żeby wszystkie trzy narzędzia je widziały.
W ostatnim transkrypcie potrafisz wskazać linię, w której model auto‑załadował skill (Loading skill: <name> albo Reading skills/<name>/SKILL.md) bez tego, że nazwałeś skill w prompcie.
Kiedy sesja ujawni pułapkę albo powtarzane tłumaczenie, dopisujesz to do odpowiedniego SKILL.md zanim zamkniesz pętlę — nie “później”, nie “w jakimś doc”.
Twoje skille żyją pod kontrolą wersji (osobiste repo dotfiles albo zespołowe repo skills/), a nie jako efemeryczne pliki w ~/.claude/.

Dalsza lektura

Q7 · Własne slash commands Skille są wywoływane przez model; slash commands przez usera. Używaj obu.

Q9 · Liczba MCP 3–5 dobrze dobranych MCP to sweet spot — paruj je ze skillami.

Q11 · Budowanie MCP Kiedy napisać skill, a kiedy własny MCP server pod integrację.

Zrób Developer Scorecard Sprawdź, gdzie stoisz w 25 pytaniach.