Przejdź do głównej zawartości

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.

  • Kompletny, zgodny ze specyfikacją skill db-migration: SKILL.md, checklistę przeglądu w references/ i skrypt pomocniczy
  • Polecenie tworzące szkielet dla każdej ścieżki: npx skills init, claude plugin init oraz skill skill-creator w Claude Code, Codeksie i Cursorze
  • Procedurę weryfikacji zamiast „przeczytaj skill i miej nadzieję”: claude plugin validate --strict, walidator referencyjny, claude plugin eval z 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 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 sytuacjaZbuduj
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 obokWtyczkę, która zawiera skill
Stałe połączenie z wewnętrznym API lub bazą danychSerwer 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.

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 instalacji

Reguły frontmattera pochodzą ze specyfikacji; walidator referencyjny z następnej sekcji odrzuca plik, który je łamie:

PoleWymaganeReguła
nameTak1–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
descriptionTak1–1024 znaki; mówi, co skill robi i kiedy go użyć
license, compatibility, metadataNiecompatibility ma najwyżej 500 znaków i opisuje wymagania środowiska („Requires git and jq”)
allowed-toolsNieEksperymentalne; 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-migration
description: 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
```sql
ALTER 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:

skills/db-migration/references/checklist.md
# 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 reply

Skrypt 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 migracji
set -euo pipefail
last=$(ls migrations/ | grep -E '^[0-9]{3}_' | sort | tail -1 | cut -c1-3)
printf '%03d\n' $((10#${last:-0} + 1))

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

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):

Okno terminala
cd acme-agent-skills/skills
npx skills init db-migration # tworzy db-migration/SKILL.md z opisem TODO

Dla osobistego skilla utwórz wtyczkę typu skills-dir — sprawdziliśmy to poleceniem:

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

Okno terminala
claude plugin install skill-creator@claude-plugins-official

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.

  1. Zwaliduj format dwoma walidatorami. claude plugin validate --strict sprawdza manifest i frontmatter każdego skilla i kończy się kodem 1 przy każdym ostrzeżeniu. Walidator referencyjny z biblioteki skills-ref sprawdza reguły nazewnictwa, które Claude Code przepuszcza. Sprawdziliśmy to poleceniami:

    ./acme-agent-skills/skills/db-migration
    claude plugin validate --strict ./acme-agent-skills
    uvx --from skills-ref==0.1.1 agentskills validate ./acme-agent-skills/skills/db-migration

    W wersji 2.1.283 validate --strict odrzucił skill bez opisu i plik bez frontmattera, ale przepuścił name: Bad_Name. Walidator referencyjny go odrzucił: „Skill name ‘Bad_Name’ must be lowercase”. README skills-ref nazywa bibliotekę „intended for demonstration purposes only”, więc traktuj ją jak linter, a nie bramkę, na której polegasz.

  2. Daj Claude Code manifest, który da się ocenić. claude plugin eval uruchamia 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 skills na ./skills/, a nie ./. Świeży szkielet z claude plugin init deklaruje "skills": ["./"] i wtedy claude plugin eval init odmawia zapisu, bo evals/ nachodziłoby na ścieżkę komponentu.

  3. Napisz przypadki evala. claude plugin eval init --bare new-column tworzy evals/new-column/prompt.md (zadanie, max_turns, allowed_tools) i evals/new-column/graders/criteria.md (definicję sukcesu ocenianą przez LLM). Wypełnij przypadek, który musi uruchomić skill:

    ---
    max_turns: 10
    allowed_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: llm
    weight: 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_tools celowo 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.

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

    Polecenie kończy się kodem 1, gdy którykolwiek przypadek ma wynik poniżej progu. Domyślne --ablation with-without dodaje przebieg bez skilla. Skill, który nie wypada lepiej niż przebieg bazowy, nic nie wnosi. Dodaj grader tool_used: Skill oznaczony jako with-only, aby raport pokazywał osobno od wyniku, czy skill się uruchomił; claude plugin eval --help w wersji 2.1.286 opisuje takie gradery jako wskaźnik uruchomienia wtyczki w trybie with-without. Eval uruchamia wtyczkę na twojej maszynie z twoimi uprawnieniami, więc --trust-plugin podawaj tylko dla skilli, które sam napisałeś.

  5. Odczytaj koszt kontekstu. Wczytaj kopię roboczą flagą --plugin-dir i odczytaj, ile skill dokłada do każdej sesji i ile kosztuje przy uruchomieniu. Bez --plugin-dir polecenie plugin details widzi tylko zainstalowane wtyczki i zgłasza Plugin "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 session

    Wartość zależy od opisu: ~98 tokenów to opis db-migration pokazany wyżej. Opis, który rozrośnie się ponad kilka zdań, zobaczysz tu najpierw.

  6. Zrób test kontrolny w każdym wspieranym narzędziu. Zainstaluj kopię roboczą w Codeksie i Cursorze, wczytaj ją do Claude Code flagą --plugin-dir i raz uruchom prompt pozytywny w każdym z nich. Bez --plugin-dir claude -p dział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 -y
    codex 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.

Wypchnięte publiczne repozytorium od razu nadaje się do instalacji; nic nie wymaga zatwierdzenia:

Okno terminala
npx skills add acme/agent-skills --skill db-migration -a claude-code -a codex -a cursor

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

Okno terminala
git tag v1.2.0 && git push origin v1.2.0
npx skills add acme/agent-skills#v1.2.0 --skill db-migration -a claude-code

Repozytoria 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ą:

  1. Zmieniaj konwencję i skill w jednym pull requeście. Gdy zespół przechodzi na nowy format migracji, ten sam PR edytuje SKILL.md i dodaje przypadek evala dla nowej reguły.

  2. CI uruchamia bramkę formatu. claude plugin validate --strict nie potrzebuje modelu ani klucza API, więc działa na każdym PR:

    .github/workflows/skills.yml
    name: skills
    on: pull_request
    permissions:
    contents: read
    jobs:
    validate:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v7 # w swoim repozytorium przypnij pełny SHA commita
    with:
    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
  3. Właściciel uruchamia eval przed scaleniem i wkleja do PR wyniki ze skillem i bez niego.

  4. Otaguj wydanie po scaleniu i przenieś na nie zespół przez npx skills update albo 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.