Budowanie i publikowanie własnych skilli
Własny skill agenta to folder z plikiem SKILL.md: frontmatter YAML z polami name i description, a pod nim instrukcje, które Claude Code, Codex i Cursor wczytują, gdy zadanie pasuje do opisu. Dobry skill powstaje w czterech krokach: szkielet, opis, który uruchamia się precyzyjnie, walidacja formatu i eval dowodzący, że skill wypada lepiej niż przebieg bez niego.
Twój zespół nigdy nie edytuje migracji, która już trafiła na produkcję, numeruje nowe po kolei i uzupełnia każdą kolumnę NOT NULL. Ta reguła żyje w głowach dwóch seniorów, więc w zeszłym tygodniu agent „poprawił literówkę” w 003_init.sql i wdrożenie padło. Ta strona jest dla programisty, który zamienia taką regułę w skill, i dla tech leada, który odpowiada za wspólne repozytorium skilli i potrzebuje dowodu, że skill działa, zanim zainstaluje go osiem osób.
Co wyniesiesz z budowania własnego skilla
Dział zatytułowany „Co wyniesiesz z budowania własnego skilla”- Kompletny, zgodny ze specyfikacją skill
db-migration:SKILL.md, checklistę przeglądu wreferences/i skrypt pomocniczy - Polecenie tworzące szkielet dla każdej ścieżki:
npx skills init,claude plugin initoraz skillskill-creatorw Claude Code, Codeksie i Cursorze - Procedurę weryfikacji zamiast „przeczytaj skill i miej nadzieję”:
claude plugin validate --strict, walidator referencyjny,claude plugin evalz przebiegiem bazowym bez skilla i odczyt kosztu kontekstu - Polecenia do publikowania i przypinania wersji dla repozytoriów publicznych i prywatnych oraz job CI i regułę akceptacji, które pilnują, żeby skill nadal robił to, co deklaruje
Polecenia, przy których zaznaczamy, że uruchomiliśmy je w teście, zostały wykonane na Claude Code 2.1.283 (kanał latest z 2026-09-26), codex-cli 0.157.1 i CLI skills 1.7.0 w tymczasowym katalogu domowym. Cursor nie ma CLI w środowisku testowym, więc jego kroki pochodzą z tabeli agentów CLI skills i nie były uruchamiane.
Skill, plik reguł, wtyczka czy serwer MCP?
Dział zatytułowany „Skill, plik reguł, wtyczka czy serwer MCP?”Skill to właściwa jednostka dla procedury, której agent potrzebuje tylko czasami. Nazwa i opis kosztują tokeny w każdej sesji, a treść wczytuje się dopiero wtedy, gdy zadanie pasuje. Wybierz według tego, co pakujesz:
| Twoja sytuacja | Zbuduj |
|---|---|
Reguła obowiązująca w każdym zadaniu w repozytorium („używaj pnpm”, „nigdy nie commituj .env”) | Linijkę w AGENTS.md lub CLAUDE.md, nie skill |
| Wieloetapowa procedura dla jednego rodzaju zadań (migracje, wydania, notatki z incydentów) | Skill |
| Procedura, która działa tylko z hookiem albo serwerem MCP obok | Wtyczkę, która zawiera skill |
| Stałe połączenie z wewnętrznym API lub bazą danych | Serwer MCP |
Reguły obowiązujące zawsze należą do plików kontekstu opisanych w artykułach o optymalizacji AGENTS.md w Codeksie i systemie pamięci Claude Code. Przeniesienie ich do skilla czyni je warunkowymi i agent pomija je w zadaniach, do których opis nie pasuje.
Co zawiera folder skilla?
Dział zatytułowany „Co zawiera folder skilla?”Specyfikacja Agent Skills wymaga jednego pliku, SKILL.md, w folderze o nazwie zgodnej z polem name. Cała reszta jest opcjonalna i wczytuje się na żądanie.
acme-agent-skills/ # repozytorium skilli zespołu├── .claude-plugin/plugin.json # opcjonalne: pozwala Claude Code walidować, ewaluować i mierzyć├── skills/│ └── db-migration/ # nazwa folderu == name we frontmatterze│ ├── SKILL.md # wymagane: frontmatter + instrukcje│ ├── references/checklist.md # wczytywane tylko, gdy SKILL.md do niego odsyła│ └── scripts/next-number.sh # uruchamiany przez agenta, nigdy nie trafia do kontekstu├── evals/ # przypadki dla claude plugin eval└── README.md # dla ludzi: co robi każdy skill, polecenie instalacjiReguły frontmattera pochodzą ze specyfikacji; walidator referencyjny z następnej sekcji odrzuca plik, który je łamie:
| Pole | Wymagane | Reguła |
|---|---|---|
name | Tak | 1–64 znaki, małe litery, cyfry i pojedyncze myślniki; bez myślnika na początku i końcu; musi być identyczne z nazwą folderu |
description | Tak | 1–1024 znaki; mówi, co skill robi i kiedy go użyć |
license, compatibility, metadata | Nie | compatibility ma najwyżej 500 znaków i opisuje wymagania środowiska („Requires git and jq”) |
allowed-tools | Nie | Eksperymentalne; lista zatwierdzonych z góry narzędzi rozdzielona spacjami; obsługa zależy od agenta |
Specyfikacja określa też budżet. Około 100 tokenów nazwy i opisu wczytuje się przy starcie dla każdego zainstalowanego skilla. Treść wczytuje się przy aktywacji; zalecane jest mniej niż 5000 tokenów i SKILL.md poniżej 500 linii. Pliki w references/, scripts/ i assets/ wczytują się tylko w razie potrzeby, więc przenieś tam dłuższe materiały i linkuj je z SKILL.md najwyżej jeden poziom w głąb.
Oto gotowy skill. Bloki kodu w środku są częścią pliku.
---name: db-migrationdescription: Creates and reviews SQL schema migrations in migrations/. Use when the user asks to add, drop, rename or alter a table, column or index, or says "write a migration". Do not use for seed data, ad-hoc queries or editing application code.---
# Database migrations
## Rules
1. Never edit a file in `migrations/` that exists on the default branch. Applied migrations are immutable: write a new migration that corrects the old one.2. Name the file `NNN_short_description.sql`. Get NNN by running `scripts/next-number.sh` from the repository root. Do not guess the number.3. One schema change per file.4. A new `NOT NULL` column needs a `DEFAULT` or a backfill `UPDATE` in the same file.5. After writing the file, run `npm run db:migrate -- --dry-run` and include its output in your reply.
## Before you finish
Go through [the review checklist](references/checklist.md) and state which items you checked.
## Example
Request: "Add a last_login_at timestamp to users."Existing files end at `013_add_orders_status.sql`.Result: a new file `migrations/014_add_users_last_login_at.sql` containing
```sqlALTER TABLE users ADD COLUMN last_login_at TEXT;```
and no change to any existing migration.Checklista, do której odsyła SKILL.md, trzyma punkty przeglądu poza treścią skilla, dopóki agent nie dojdzie do ostatniego kroku:
# Migration review checklist
- [ ] No file that exists on the default branch was modified- [ ] The new file number is the output of scripts/next-number.sh- [ ] The file contains exactly one schema change- [ ] Every new NOT NULL column has a DEFAULT or a backfill UPDATE- [ ] The dry-run output is included in the replySkrypt pomocniczy zamienia regułę 2 z decyzji wymagającej osądu w zwykłe polecenie, dlatego reguła zabrania agentowi zgadywania:
#!/usr/bin/env bash# skills/db-migration/scripts/next-number.sh — wypisuje numer następnej migracjiset -euo pipefaillast=$(ls migrations/ | grep -E '^[0-9]{3}_' | sort | tail -1 | cut -c1-3)printf '%03d\n' $((10#${last:-0} + 1))Jak napisać opis, na który agent naprawdę reaguje
Dział zatytułowany „Jak napisać opis, na który agent naprawdę reaguje”Opis to jedyna część skilla, którą agent widzi, zanim zdecyduje się go wczytać. Pisz go jak regułę dopasowania, a nie streszczenie:
- Wymień frazy i obiekty, które go uruchamiają. „add, drop, rename or alter a table, column or index” pasuje do tego, jak ludzie formułują prośby. „Helps with databases” nie pasuje niezawodnie do niczego.
- Podaj wykluczenia. „Do not use for seed data” sprawia, że skill nie włącza się przy pokrewnych zadaniach i nie zużywa tam tokenów na wczytanie swojej treści.
- Zacznij od czasownika. „Creates and reviews SQL schema migrations” mówi agentowi, co dostaje.
W treści pisz reguły, które agent może sprawdzić: jedna na linię, z uzasadnieniem tam, gdzie reguła nie jest oczywista. „Follow best practices for migrations” nie da się sprawdzić. „Never edit a file that exists on the default branch” — da się.
Jak utworzyć szkielet skilla w swoim narzędziu
Dział zatytułowany „Jak utworzyć szkielet skilla w swoim narzędziu”Trzy ścieżki dają ten sam folder. npx skills init zapisuje goły SKILL.md dla dowolnego agenta. claude plugin init tworzy osobisty skill Claude Code, który Claude Code potrafi zwalidować, ocenić i zmierzyć. Skill skill-creator przeprowadza z tobą wywiad i pisze szkic treści.
Ścieżka przenośna działa wszędzie tak samo (polecenie uruchomione w teście):
cd acme-agent-skills/skillsnpx skills init db-migration # tworzy db-migration/SKILL.md z opisem TODODla osobistego skilla utwórz wtyczkę typu skills-dir — sprawdziliśmy to poleceniem:
claude plugin init db-migration --description "Schema migration rules" --author "Acme Platform Team"# √ Created plugin "db-migration" at ~/.claude/skills/db-migration# It will auto-load next session as db-migration@skills-dir. Run /reload-plugins to load it now.Polecenie zapisuje ~/.claude/skills/db-migration/SKILL.md oraz .claude-plugin/plugin.json. Dodaj --with skills agents hooks, żeby utworzyć foldery kolejnych komponentów. Skill projektowy umieść w .claude/skills/db-migration/ i zacommituj.
Jeśli chcesz, żeby agent napisał i przetestował skill, zainstaluj skill-creator od Anthropic. Pisze skill, uruchamia testowe prompty z nim i bez niego, porównuje wyniki i dostraja opis pod kątem trafności uruchamiania.
claude plugin install skill-creator@claude-plugins-officialcodex-cli 0.157.1 ma wbudowany skill systemowy o nazwie skill-creator, więc nic nie trzeba instalować. Wywołaj go w sesji przez $skill-creator. To własny skill OpenAI, a nie kopia skilla Anthropic: tworzy szkielet skryptem scripts/init_skill.py i sprawdza wynik skryptem scripts/quick_validate.py. Domyślnie zapisuje do ${CODEX_HOME:-$HOME/.codex}/skills, więc wskaż katalog docelowy, jeśli chcesz skill w repozytorium:
$skill-creator Create a skill named db-migration in .agents/skills/ from the rules in docs/migrations.md.Codex czyta skille projektowe z .agents/skills/. codex-cli 0.157.1 nie ma polecenia, które ocenia skill; przetestuj go evalem Claude Code opisanym niżej albo przebiegiem kontrolnym codex exec.
Ta strona nie potwierdziła wbudowanego kreatora skilli w Cursorze (jego dokumentacja skilli, ostatnio sprawdzona 2026-08-28, żadnego nie wymienia). Zainstaluj skill-creator od Anthropic przez CLI skills, które dla Cursora zapisuje do .agents/skills/:
npx skills add anthropics/skills --skill skill-creator -a cursorPotem poproś agenta na czacie, żeby użył skill-creator do utworzenia db-migration. Porównanie „ze skillem i bez” w tym skillu zakłada subagentów, a krok optymalizacji opisu uruchamia claude -p, więc sprawdzenie zachowania z następnej sekcji wykonaj z Claude Code, a test kontrolny w Cursorze — ręcznie.
Na dzień 2026-09-26 skill-creator od Anthropic ma na skills.sh 391 071 instalacji od początku istnienia według zewnętrznego zrzutu LinklyAI/best-skills z tego dnia (źródło wtórne; sam skills.sh był nieosiągalny). Jego repozytorium źródłowe, anthropics/skills, miało tego samego dnia 178 380 gwiazdek na GitHubie.
Jak udowodnić, że skill działa, zanim ktoś go zainstaluje
Dział zatytułowany „Jak udowodnić, że skill działa, zanim ktoś go zainstaluje”Nikt nie powinien czytać skilla linijka po linijce, żeby mu zaufać. Dowód opiera się na formacie, zachowaniu w porównaniu z przebiegiem bazowym, koszcie kontekstu i teście kontrolnym w każdym narzędziu.
-
Zwaliduj format dwoma walidatorami.
claude plugin validate --strictsprawdza manifest i frontmatter każdego skilla i kończy się kodem1przy każdym ostrzeżeniu. Walidator referencyjny z bibliotekiskills-refsprawdza reguły nazewnictwa, które Claude Code przepuszcza. Sprawdziliśmy to poleceniami:./acme-agent-skills/skills/db-migration claude plugin validate --strict ./acme-agent-skillsuvx --from skills-ref==0.1.1 agentskills validate ./acme-agent-skills/skills/db-migrationW wersji 2.1.283
validate --strictodrzucił skill bez opisu i plik bez frontmattera, ale przepuściłname: Bad_Name. Walidator referencyjny go odrzucił: „Skill name ‘Bad_Name’ must be lowercase”. READMEskills-refnazywa bibliotekę „intended for demonstration purposes only”, więc traktuj ją jak linter, a nie bramkę, na której polegasz. -
Daj Claude Code manifest, który da się ocenić.
claude plugin evaluruchamia przypadki ze skillem i bez niego i raportuje różnicę. Potrzebuje wtyczki, więc repozytorium zawiera minimalny.claude-plugin/plugin.json:{"name": "acme-agent-skills","version": "0.1.0","description": "Acme platform team skills","author": { "name": "Acme Platform Team" },"skills": ["./skills/"]}Ustaw
skillsna./skills/, a nie./. Świeży szkielet zclaude plugin initdeklaruje"skills": ["./"]i wtedyclaude plugin eval initodmawia zapisu, boevals/nachodziłoby na ścieżkę komponentu. -
Napisz przypadki evala.
claude plugin eval init --bare new-columntworzyevals/new-column/prompt.md(zadanie,max_turns,allowed_tools) ievals/new-column/graders/criteria.md(definicję sukcesu ocenianą przez LLM). Wypełnij przypadek, który musi uruchomić skill:---max_turns: 10allowed_tools: [Read, Glob, Grep, Skill]---The migrations/ directory contains 001_init.sql through 013_add_orders_status.sql.Add a last_login_at timestamp column to the users table. Show the file you would create.---type: llmweight: 1---The response proposes a new file named 014_*.sql containing one ALTER TABLE statement,and does not propose any change to an existing migration.Ten przypadek sprawdza tylko plik zaproponowany przez agenta, dlatego
allowed_toolscelowo pomija Bash i agent nie może w trakcie evalu wykonać reguł 2 i 5. Jeśli chcesz sprawdzić także skrypt numerujący, zostaw Bash w przypadku i przyznaj go w poleceniu evalu flagą--allow-tools Bash, która uruchamia prawdziwe polecenia powłoki na twojej maszynie.Dodaj drugi przypadek z niezwiązaną prośbą („rename the heading in README.md”), którego kryteria mówią, że nie powstaje żaden plik migracji. Wyłapuje opis, który uruchamia się zbyt szeroko.
-
Uruchom eval z przebiegiem bazowym. Eval wywołuje model na twoich poświadczeniach, więc uruchamiaj go lokalnie albo w osobnym jobie, który ma klucz:
Okno terminala claude plugin eval ./acme-agent-skills --runs 3 --threshold 0.8 --no-publishPolecenie kończy się kodem
1, gdy którykolwiek przypadek ma wynik poniżej progu. Domyślne--ablation with-withoutdodaje przebieg bez skilla. Skill, który nie wypada lepiej niż przebieg bazowy, nic nie wnosi. Dodaj gradertool_used: Skilloznaczony jako with-only, aby raport pokazywał osobno od wyniku, czy skill się uruchomił;claude plugin eval --helpw wersji 2.1.286 opisuje takie gradery jako wskaźnik uruchomienia wtyczki w trybiewith-without. Eval uruchamia wtyczkę na twojej maszynie z twoimi uprawnieniami, więc--trust-pluginpodawaj tylko dla skilli, które sam napisałeś. -
Odczytaj koszt kontekstu. Wczytaj kopię roboczą flagą
--plugin-diri odczytaj, ile skill dokłada do każdej sesji i ile kosztuje przy uruchomieniu. Bez--plugin-dirpolecenieplugin detailswidzi tylko zainstalowane wtyczki i zgłaszaPlugin "acme-agent-skills" not found. Sprawdziliśmy to poleceniami:Okno terminala claude --plugin-dir ./acme-agent-skills plugin details acme-agent-skills# Source: acme-agent-skills@inline# Projected token cost# Always-on: ~98 tok added to every sessionWartość zależy od opisu: ~98 tokenów to opis
db-migrationpokazany wyżej. Opis, który rozrośnie się ponad kilka zdań, zobaczysz tu najpierw. -
Zrób test kontrolny w każdym wspieranym narzędziu. Zainstaluj kopię roboczą w Codeksie i Cursorze, wczytaj ją do Claude Code flagą
--plugin-diri raz uruchom prompt pozytywny w każdym z nich. Bez--plugin-dirclaude -pdziała bez skilla i może przejść test na samym przebiegu bazowym:Okno terminala npx skills add ./acme-agent-skills --skill db-migration -a codex -a cursor -ycodex exec --sandbox read-only "Add a last_login_at column to users. Show the migration file you would create."claude -p --plugin-dir ./acme-agent-skills --permission-mode plan "Add a last_login_at column to users. Show the migration file you would create."W Cursorze wklej ten sam prompt do czatu agenta. Test przechodzi, gdy każde narzędzie proponuje
014_…i nie rusza istniejących plików.
Kto akceptuje: właściciel skilla, wpisany w CODEOWNERS dla skills/db-migration/, zatwierdza zmianę tylko wtedy, gdy walidatory przechodzą, a różnica w evalu nie spadła. Recenzenci czytają diff reguł, wyniki evala i linijkę kosztu, a nie wynik agenta z każdego przebiegu.
Jak opublikować, przypiąć i wdrożyć skill
Dział zatytułowany „Jak opublikować, przypiąć i wdrożyć skill”Wypchnięte publiczne repozytorium od razu nadaje się do instalacji; nic nie wymaga zatwierdzenia:
npx skills add acme/agent-skills --skill db-migration -a claude-code -a codex -a cursorPrzypnij wydanie. Otaguj repozytorium i instaluj z taga przez fragment #. W skills 1.7.0 zapis acme/agent-skills@v1.2.0 robi coś innego: część po @ jest traktowana jako nazwa skilla.
git tag v1.2.0 && git push origin v1.2.0npx skills add acme/agent-skills#v1.2.0 --skill db-migration -a claude-codeRepozytoria prywatne używają tego samego polecenia. CLI próbuje twoich poświadczeń git, potem zalogowanego GitHub CLI, potem SSH, i przyjmuje też GitLab, Azure DevOps oraz dowolny URL git przez HTTPS lub SSH. Anonimowa telemetria instalacji wysyła identyfikatory repozytorium i skilla tylko dla repozytoriów, które GitHub potwierdza jako publiczne, ale dla innych hostów może je wysłać, więc przy instalacji z wewnętrznego serwera git ustaw DISABLE_TELEMETRY=1.
Tylko jedno repozytorium? Zacommituj folder do .claude/skills/ i .agents/skills/ i pomiń CLI. Cała organizacja? Opakuj skille we wtyczkę i rozprowadzaj ją z prywatnego marketplace’u zespołu, który daje wersjonowane aktualizacje i ustawienia zarządzane centralnie.
Wyszukiwanie. npx skills find przeszukuje indeks skills.sh. Nie dało się sprawdzić 2026-09-26, jak skills.sh wybiera i szereguje repozytoria, bo serwis był nieosiągalny ze środowiska testowego; zanim obiecasz komuś obecność na liście, sprawdź to na samym skills.sh.
Jak zmiana skilla przechodzi przez pętlę dostarczania
Dział zatytułowany „Jak zmiana skilla przechodzi przez pętlę dostarczania”Traktuj skill jak kod z własnymi testami. Pętla, która utrzymuje go w zgodzie z rzeczywistością:
-
Zmieniaj konwencję i skill w jednym pull requeście. Gdy zespół przechodzi na nowy format migracji, ten sam PR edytuje
SKILL.mdi dodaje przypadek evala dla nowej reguły. -
CI uruchamia bramkę formatu.
claude plugin validate --strictnie potrzebuje modelu ani klucza API, więc działa na każdym PR:.github/workflows/skills.yml name: skillson: pull_requestpermissions:contents: readjobs:validate:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v7 # w swoim repozytorium przypnij pełny SHA commitawith:persist-credentials: false- run: npx -y @anthropic-ai/claude-code@2.1.283 plugin validate --strict .- run: pipx run --spec skills-ref==0.1.1 agentskills validate skills/db-migration -
Właściciel uruchamia eval przed scaleniem i wkleja do PR wyniki ze skillem i bez niego.
-
Otaguj wydanie po scaleniu i przenieś na nie zespół przez
npx skills updatealbo nową przypiętą instalację.
Gdy własny skill się nie uruchamia albo działa źle
Dział zatytułowany „Gdy własny skill się nie uruchamia albo działa źle”Skill w ogóle się nie wczytuje. Opis nie pasuje do tego, jak ludzie formułują zadanie. Uruchom przypadki pozytywny i niezwiązany z evala; jeśli pozytywny ma ten sam wynik ze skillem i bez niego, przepisz opis, używając czasowników z prawdziwych próśb zespołu, i uruchom eval ponownie. skill-creator od Anthropic ma do tego osobny krok optymalizacji opisu.
Skill uruchamia się przy niezwiązanych zadaniach. Opis jest za szeroki. Dodaj zdanie „Do not use for…” i przypadek evala dla sąsiedniego zadania, które skill błędnie przechwycił.
Agent naśladuje przykład, ale łamie regułę. Agenci kopiują przykłady dosłownie. Sprawdź, czy każdy przykład w SKILL.md spełnia każdą regułę, a decyzje wymagające oceny przenieś do skryptu, tak jak next-number.sh robi to z numeracją.
Działa w Claude Code, ale nie w Codeksie ani Cursorze. Pliki leżą w złym katalogu. Instalacje projektowe trafiają do .claude/skills/ dla Claude Code i do .agents/skills/ dla Codeksu i Cursora; globalne do ~/.claude/skills/, ~/.codex/skills/ i ~/.cursor/skills/. Uruchom npx skills list: pokazuje ścieżkę każdego skilla i agentów, którzy go czytają.
Członkowie zespołu dostają różne zachowanie z tego samego skilla. Ktoś ma nieaktualną kopię albo osobisty skill z nakładającym się opisem. Przypnij instalację zespołową do taga i uruchom Dr. Skill, żeby znaleźć nakładające się skille i serwery MCP.
Skill spoza zespołu zachowuje się dziwnie. Skill może zawierać skrypty, które agent uruchamia z twoimi uprawnieniami. Zanim zainstalujesz cudze skille we wspólnym repozytorium, przeczytaj o bezpieczeństwie łańcucha dostaw skilli.