Przejdź do głównej zawartości
AI Developer Toolkit

Polecenia niestandardowe i skille w Claude Code

Polecenie niestandardowe w Claude Code to plik Markdown, który staje się poleceniem slash: starsza forma .claude/commands/NAZWA.md albo obecna: skill w .claude/skills/NAZWA/SKILL.md z plikami pomocniczymi, kontrolą wywołania i automatycznym ładowaniem. Obie przyjmują argumenty i frontmatter, a plik w repozytorium daje zespołowi ten sam przepływ /NAZWA. Poniżej NAZWA to nazwa polecenia, PODKATALOG podkatalog repozytorium, a KATALOG_PLUGINU główny katalog pluginu.

Ta strona jest dla programistów, którzy raz po raz wklejają do Claude Code tę samą checklistę, i dla tech leadów, którzy chcą, żeby ta checklista działała tak samo u ośmiu osób. Sytuacja jest znajoma: procedura jednej osoby przed otwarciem PR-a wyłapuje brakujący test i niesparametryzowane zapytanie, procedury pozostałych nie, a różnica wychodzi dopiero w code review.

Strona zakłada, że Claude Code działa już w twoim repozytorium (zobacz konfigurację Claude Code). Jeśli chcesz instalować skille napisane przez innych, a nie pisać własne, zacznij od instalowania skilli i zarządzania nimi.

Co daje zespołowa biblioteka poleceń

Dział zatytułowany „Co daje zespołowa biblioteka poleceń”
  • Skill /pre-pr, który uruchamia bramki jakości przed merge’em i zwraca werdykt z dowodami, gotowy do commita.
  • Skill /fix-issue, który przyjmuje numer zgłoszenia jako nazwany argument.
  • Regułę, kto może uruchomić każde polecenie: ty, Claude czy obaj.
  • Zasady pierwszeństwa, które rozstrzygają, które /nazwa się wykona przy kolizji nazw, łącznie z pułapką /review.
  • 30-liniowy test w CI, który łapie błędy we frontmatterze ignorowane przez Claude Code bez ostrzeżenia.
  • Sposób, by wykazać, że polecenie robi swoje, bez czytania każdego transkryptu.

Plik polecenia czy skill: co pisać?

Dział zatytułowany „Plik polecenia czy skill: co pisać?”

Wszystko nowe pisz jako skill. Dokumentacja skilli Claude Code mówi, że polecenia niestandardowe „have been merged into skills”: .claude/commands/deploy.md i .claude/skills/deploy/SKILL.md tworzą to samo /deploy, a istniejące pliki poleceń nadal działają (sprawdzone na v2.1.283).

.claude/commands/NAZWA.md.claude/skills/NAZWA/SKILL.md
Wywołanie/NAZWA; podkatalog dodaje prefiks z dwukropkiem, więc commands/test/unit.md to /test:unit/NAZWA albo pole name z frontmattera
FrontmatterTe same pola co skill oprócz name i pathsWszystkie pola
Pliki pomocnicze (skrypty, szablony, dokumentacja)NieTak, w katalogu skilla
Ta sama nazwa co w drugiej formiePrzegrywaWygrywa
Przenośność do innych agentówNieUkład SKILL.md to otwarty standard Agent Skills; kontrola wywołania, context: fork i wstrzykiwanie !`polecenie` to rozszerzenia Claude Code

Skille ładują się tanio: do momentu uruchomienia w kontekście jest tylko description, potem cała treść wchodzi do rozmowy i zostaje w niej na kolejne tury. Każda linia treści to powracający koszt w tokenach, więc pisz stałe instrukcje, a nie narrację.

Gdzie leżą polecenia i które się wykona

Dział zatytułowany „Gdzie leżą polecenia i które się wykona”
LokalizacjaŚcieżkaŁaduje się w
Enterprise.claude/skills/NAZWA/SKILL.md w katalogu managed settingsNa każdym komputerze zarządzanym przez organizację
Osobista~/.claude/skills/NAZWA/SKILL.mdWe wszystkich twoich projektach na tym komputerze; nie w sesjach w chmurze ani w rutynach (Routines)
Projektowa.claude/skills/NAZWA/SKILL.mdW tym repozytorium, u każdego, kto je sklonuje
ZagnieżdżonaPODKATALOG/.claude/skills/NAZWA/SKILL.mdW sesjach uruchomionych w PODKATALOG albo gdy Claude dotknie tam pliku
PluginKATALOG_PLUGINU/skills/NAZWA/SKILL.mdTam, gdzie plugin jest włączony, jako /NAZWA_PLUGINU:NAZWA

Gdy dwie definicje mają tę samą nazwę, wykonuje się (według dokumentacji skilli, v2.1.283):

  • Enterprise wygrywa z osobistą, a osobista z projektową. Skill deploy w ~/.claude/skills/ przesłania zespołowy .claude/skills/deploy/, ale tylko na twoim komputerze. Reszta zespołu uruchamia wersję projektową, a ty nie.
  • Skill wygrywa z plikiem polecenia o tej samej nazwie.
  • Twój skill zastępuje wbudowany skill, ale nie jego aliasy. Projektowy skill code-review zastępuje /code-review, ale /review, wbudowany alias /code-review, nigdy nie uruchomi twojego skilla. Nie nazywaj zespołowego polecenia review; nazwij je /team-review albo /pre-pr, żeby nikt nie musiał zgadywać, co się właściwie wykonało.
  • Skille z pluginów nigdy nie kolidują, bo poprzedza je nazwa pluginu.

Zbuduj polecenie /pre-pr krok po kroku

Dział zatytułowany „Zbuduj polecenie /pre-pr krok po kroku”

Poniższe polecenie nie prosi Claude’a o opinię o twoim diffie. Uruchamia te same bramki co CI i raportuje kod wyjścia każdej z nich, więc osoba otwierająca pull request czyta dowody, a nie prozę.

  1. Utwórz katalog skilla w głównym katalogu repozytorium:

    Okno terminala
    mkdir -p .claude/skills/pre-pr

  2. Zapisz to jako .claude/skills/pre-pr/SKILL.md, dopasowując trzy skrypty npm run do nazw bramek w twoim projekcie:

    ---
    description: Runs this repository's merge gates on the current branch and reports evidence. Use before opening a pull request.
    disable-model-invocation: true
    allowed-tools: Bash(git diff *) Bash(npm run *)
    ---
    

    ## Branch under check
    

    !`git diff --stat origin/main...HEAD`
    

    ## Instructions
    

    1. Run these gates in order and record the exact command and exit code of each:
       `npm run typecheck`, `npm run lint`, `npm run test`.
    2. If a gate fails, show the first error with its file and line. Do not edit code.
    3. For each changed file under `src/`, name the test that exercises it, or list the file as untested.
    4. Reply in exactly this shape and nothing else:
    

       VERDICT: READY or BLOCKED
       | Gate | Command | Exit code |
       Untested files: <list or "none">
       Look here first: at most three file:line locations with one reason each

    Linia !`git diff --stat origin/main...HEAD` wykonuje się, zanim Claude zobaczy skill, więc instrukcje docierają z prawdziwym diffem w środku. Zamień origin/main na domyślną gałąź swojego repozytorium; jeśli taka referencja nie istnieje, wstrzyknięcie się nie powiedzie i przerwie polecenie. allowed-tools z góry zatwierdza wstrzyknięty git diff i polecenia bramek tylko na tę turę; bez tego wstrzyknięte polecenie, które wymaga zgody, przerywa całe wywołanie poza trybem auto.

  3. Uruchom Claude Code w repozytorium i wywołaj polecenie:

    /pre-pr

    Claude Code obserwuje istniejące katalogi skilli, więc zmiana w SKILL.md działa bez restartu. Jeśli katalog .claude/skills/ powstał dopiero w trakcie sesji, najpierw uruchom /reload-skills.

  4. Zatwierdź skill w repozytorium (commit), żeby cały zespół dostał /pre-pr po najbliższym git pull:

    Okno terminala
    git add .claude/skills/pre-pr/SKILL.md
    git commit -m "Add /pre-pr merge-gate command"

Przekaż argumenty do polecenia

Dział zatytułowany „Przekaż argumenty do polecenia”

$ARGUMENTS rozwija się do wszystkiego, co wpisano po nazwie polecenia. $0, $1 i kolejne wybierają argumenty pozycyjne, z cudzysłowami jak w powłoce dla wartości wielowyrazowych. W poleceniu, którego będą używać inni, zadeklaruj nazwane argumenty w arguments i dodaj argument-hint, żeby autouzupełnianie pokazywało, czego polecenie oczekuje:

---
description: Fix a GitHub issue test-first. Use when given an issue number to fix.
argument-hint: "[issue-number]"
arguments: [issue]
disable-model-invocation: true
allowed-tools: Bash(gh issue view *)
---


Fix GitHub issue #$issue.


1. Run `gh issue view $issue --comments` and restate the expected behaviour in one sentence.
2. Write a failing test that reproduces it. Run it and show that it fails.
3. Make the smallest change that turns the test green, then run the full test suite.
4. Stop without committing. Report the test name, the suite result and the files changed.

Zapisz to jako .claude/skills/fix-issue/SKILL.md i uruchom /fix-issue 482. Dwa zachowania warto znać: symbol indeksowany bez pasującego argumentu, na przykład $1, gdy podałeś jedną wartość, zostaje w tekście dosłownie jako $1, a symbol nazwany rozwija się do pustego ciągu. Jeśli żaden symbol nie odbierze danych, Claude Code dopisze je na końcu jako ARGUMENTS: WARTOŚĆ, gdzie WARTOŚĆ to wpisany tekst.

Zdecyduj, kto może uruchomić polecenie

Dział zatytułowany „Zdecyduj, kto może uruchomić polecenie”

Domyślnie skill mogą wywołać zarówno ty, jak i Claude: ty wpisujesz /nazwa, a Claude ładuje go, gdy prośba pasuje do description. Zmieniają to dwa pola:

FrontmatterTy możesz wywołaćClaude może wywołaćZastosowanie
(domyślnie)TakTakChecklisty i procedury, które można bezpiecznie uruchomić zawsze, gdy pasują
disable-model-invocation: trueTakNieWszystko ze skutkami ubocznymi: commit, push, deploy, wysłanie wiadomości, /pre-pr
user-invocable: falseNieTakWiedza w tle, np. skill api-conventions albo legacy-billing-context

Skill z disable-model-invocation znika też całkowicie z kontekstu Claude’a, co oszczędza miejsce na liście skilli. Jeśli Claude mimo to spróbuje go uruchomić, Claude Code zablokuje wywołanie.

Dwa pola łatwo źle odczytać:

  • allowed-tools nadaje uprawnienia, a nie ogranicza. Z góry zatwierdza wymienione narzędzia na turę, w której wywołano skill, i wygasa przy twojej następnej wiadomości. Każde inne narzędzie pozostaje dostępne według zwykłych reguł uprawnień. Żeby usunąć narzędzia na czas działania skilla, użyj disallowed-tools; żeby zablokować je wszędzie, użyj reguł deny.
  • allowed-tools nie zależy od zaufania do katalogu roboczego. Uprawnienia ze skilla projektowego działają nawet w claude -p w folderze, któremu nigdy nie zaufałeś. Przejrzyj allowed-tools w .claude/skills/ każdego repozytorium, zanim uruchomisz w nim Claude Code, a przy skillach instalowanych z zewnątrz zajrzyj do bezpieczeństwa łańcucha dostaw skilli. Wstrzykiwanie !`polecenie` dla skilli użytkownika, projektu i pluginów wyłącza ustawienie "disableSkillShellExecution": true; organizacja umieszcza je w managed settings, gdzie użytkownik nie może go nadpisać.

Oddaj ciężką pracę subagentowi przez context: fork

Dział zatytułowany „Oddaj ciężką pracę subagentowi przez context: fork”

Polecenie, które czyta pół kodu, zapycha główną rozmowę zawartością plików. Dodaj context: fork, a skill uruchomi się jako osobny subagent, który startuje wyłącznie z tekstu skilla, bez historii rozmowy, i zwraca tylko wynik:

---
description: Find every caller of a function or module and summarise how each uses it. Use before changing a public API.
argument-hint: "[symbol]"
context: fork
agent: Explore
---


Find every call site of $ARGUMENTS in this repository.
Group them by package. For each group, give the file:line of one representative call
and say whether it relies on the current return type, error behaviour or side effects.
End with the list of call sites that would break if the signature changed.

Wydzielony subagent domyślnie działa w tle, z węższym zestawem narzędzi przeznaczonym dla subagentów w tle; ustaw background: false, jeśli chcesz poczekać na odpowiedź w tej samej turze. Explore to wbudowany agent tylko do odczytu. Własne typy agentów z własnymi narzędziami, modelem i trybem uprawnień opisuje strona o własnych subagentach.

Prompty, które piszą i migrują polecenia za ciebie

Dział zatytułowany „Prompty, które piszą i migrują polecenia za ciebie”

Rzadko trzeba pisać skill ręcznie. Po sesji, w której ty i Claude wypracowaliście procedurę, poproś Claude’a, żeby ją utrwalił.

Ostatni prompt wymaga pluginu skill-creator z oficjalnego marketplace’u: najpierw uruchom w Claude Code /plugin install skill-creator@claude-plugins-official.

Skąd wiesz, że polecenie niestandardowe działa?

Dział zatytułowany „Skąd wiesz, że polecenie niestandardowe działa?”

To, że /pre-pr coś wypisało, oznacza tylko, że plik się załadował, a nie że polecenie spełnia swoje zadanie. Sprawdź cztery rzeczy; żadna nie wymaga czytania całego transkryptu.

1. Plik jest poprawny. Claude Code po cichu ignoruje pole frontmattera z literówką w nazwie, nie czyta frontmattera wcale, gdy otwierające --- nie jest w pierwszej linii, i ładuje treść z pustymi metadanymi, gdy YAML się nie parsuje. Każdy z tych błędów zamienia polecenie deploy z disable-model-invocation: true z powrotem w takie, które Claude może uruchomić sam. Dodaj ten test jako scripts/check_skills.py:

import pathlib, sys, yaml


SKILL_KEYS = {"name", "description", "when_to_use", "argument-hint", "arguments",
    "disable-model-invocation", "user-invocable", "allowed-tools", "disallowed-tools",
    "disallowedTools", "version", "model", "effort", "context", "agent", "background", "hooks", "paths", "shell",
    "metadata", "license", "compatibility"}
COMMAND_KEYS = SKILL_KEYS - {"name", "paths"}


files = [(p, SKILL_KEYS) for p in pathlib.Path(".").glob("**/.claude/skills/*/SKILL.md")
         if "node_modules" not in p.parts]
files += [(p, COMMAND_KEYS) for p in pathlib.Path(".claude/commands").rglob("*.md")]
errors = []
for path, allowed in files:
    text = path.read_text(encoding="utf-8")
    if not text.startswith("---\n"):
        errors.append(f"{path}: frontmatter must open on line 1")
        continue
    try:
        meta = yaml.safe_load(text.split("---\n", 2)[1]) or {}
    except yaml.YAMLError as exc:
        errors.append(f"{path}: YAML does not parse ({exc.problem})")
        continue
    if not isinstance(meta, dict) or not meta.get("description"):
        errors.append(f"{path}: missing description")
    else:
        for key in sorted(set(meta) - allowed):
            errors.append(f"{path}: unknown field '{key}' is ignored by Claude Code")
print("\n".join(errors) or f"{len(files)} files OK")
sys.exit(1 if errors else 0)

Lista pól odpowiada dokumentacji frontmattera skilli dla v2.1.283, uzupełnionej o pisownię disallowedTools i pole version, które parser v2.1.283 także czyta; zaktualizuj ją, gdy Claude Code doda nowe pole. Wzorzec obejmuje katalog .claude/skills/ najwyższego poziomu i zagnieżdżone; skille z pluginów sprawdza claude plugin validate, opisane niżej. Uruchamiaj test w każdym pull requeście, który dotyka .claude/:

.github/workflows/skills-lint.yml
name: skills-lint
on:
  pull_request:
    paths: [".claude/**"]
permissions:
  contents: read
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-python@v7
        with:
          python-version: "3.12"
      - run: pip install pyyaml
      - run: python scripts/check_skills.py

Job nie potrzebuje żadnego sekretu i nie uruchamia agenta. claude plugin validate go nie zastąpi. W naszym teście na v2.1.283 claude plugin validate --strict . uruchomione w głównym katalogu repozytorium wykryło SKILL.md bez frontmattera albo z pustą pierwszą linią, ale przepuściło literówkę disable-model-invokation: true i YAML, który się nie parsuje, a wskazane bezpośrednio na .claude/skills nie sprawdziło ani jednego pliku. Traktuj je jako drugi krok, a gdy spakujesz skille jako plugin, uruchamiaj też claude plugin validate --strict KATALOG_PLUGINU na samym pluginie.

2. Polecenie coś zmienia. Uruchom trzy realistyczne prośby w świeżych sesjach ze skillem włączonym i ponownie z wyłączonym, a potem porównaj wyniki. Świeża sesja jest ważna, bo kontekst pozostały po pisaniu skilla maskuje luki w jego instrukcjach. Prompt ze skill-creator powyżej automatyzuje to porównanie; dla skilli dostarczanych w pluginie claude plugin eval wykonuje to samo porównanie z pluginem i bez niego na przypadkach z katalogu evals/ pluginu (dla każdego przypadku case.yaml albo prompt.md plus graders/*.md) i kończy się kodem niezerowym, gdy któryś przypadek wypadnie poniżej --threshold (domyślnie 1.0, sprawdzone na v2.1.283). W CI dodaj --trust-plugin i realistyczny próg, na przykład --threshold 0.8.

3. Wynik da się sprawdzić. Polecenie, które kończy się stałym formatem, na przykład VERDICT z tabelą bramek i kodami wyjścia, pozwala recenzentowi potwierdzić wynik jednym ponownym uruchomieniem zamiast czytania sesji. Polecenie, które zwraca swobodną prozę, traktuj jako niedokończone.

4. Biblioteka nie kosztuje za dużo. Opis każdego skilla zajmuje kontekst w każdej turze. Uruchom /skill-doctor, żeby zobaczyć koszt każdego skilla w kontekście i częstotliwość użycia, i wyłącz te, których nikt nie wywołuje.

Kto zatwierdza: obejmij .claude/ wpisem w CODEOWNERS dla tech leada albo właściciela platformy. Zespołowe polecenie zmienia zachowanie agenta u każdego członka zespołu, a jego allowed-tools nadaje uprawnienia, więc zasługuje na taki sam przegląd jak zmiana workflow w CI. Tym samym wpisem obejmij .github/ i scripts/check_skills.py, a w ochronie gałęzi wymagaj przeglądu code ownera: przy wyzwalaczu pull_request GitHub uruchamia workflow i skrypt z samego pull requesta, więc bez tego przeglądu pull request może osłabić lint w tym samym diffie, który dodaje skill.

Udostępnij polecenia poza jednym repozytorium

Dział zatytułowany „Udostępnij polecenia poza jednym repozytorium”

Katalog .claude/skills/ w repozytorium obsługuje jedno repozytorium. Dwa przypadki wymagają więcej:

  • Sesje w chmurze i rutyny nie czytają ~/.claude/skills/. Rutyna, która wywołuje skill istniejący tylko na twoim laptopie, zgłosi, że skilla nie znaleziono. Zatwierdź skill w repozytorium albo włącz go dla swojego konta claude.ai.
  • Kilka repozytoriów potrzebuje tych samych poleceń. Spakuj je jako plugin i opublikuj przez zespołowy marketplace; zobacz budowanie pluginów i zespołowy marketplace pluginów. Skille z pluginów mają przestrzeń nazw, więc nigdy nie przesłaniają poleceń samego repozytorium.

Ta sama treść SKILL.md działa w innych agentach, które implementują Agent Skills. Strona budowanie i publikowanie własnych skilli pokazuje układ międzynarzędziowy dla Codex i Cursora; przy przenoszeniu usuń pola dostępne tylko w Claude Code.

Gdy polecenia niestandardowe zawodzą

Dział zatytułowany „Gdy polecenia niestandardowe zawodzą”
ObjawPrawdopodobna przyczynaNaprawa
Brak /nazwa w menu /Skill leży w zagnieżdżonym .claude/skills/, który jeszcze się nie załadował, albo katalog skilli powstał w trakcie sesjiUruchom /add-dir PODKATALOG lub /reload-skills; /skills pokaże, co się załadowało
Frontmatter nic nie zmieniaOtwierające --- nie w pierwszej linii, YAML, który się nie parsuje, albo literówka w nazwie polaUruchom scripts/check_skills.py; wystartuj Claude Code z --debug, żeby zobaczyć błąd parsowania
/deploy u kolegi działa inaczej niż u ciebieOsobisty skill o tej samej nazwie przesłania projektowy na jednym komputerzeZmień nazwę albo usuń osobistą kopię w ~/.claude/skills/; osobisty wygrywa z projektowym
/review ignoruje twoje polecenie/review to alias wbudowanego /code-review, a aliasy nigdy nie uruchamiają twojego skillaZmień nazwę polecenia, na przykład na /team-review
Claude sam uruchamia polecenie ze skutkami ubocznymiBrak disable-model-invocation: true albo literówka w tym poluDodaj pole i pilnuj go lintem w CI
Polecenie przerywa się z Shell command failed for patternWstrzyknięte !`polecenie` zakończyło się kodem niezerowym, a każdy błąd przerywa całe wywołanieDopisz || true do poleceń, które zwracają 1 przy znaleziskach; w pozostałych przypadkach napraw polecenie
Polecenie przerywa się z Shell command permission check failedWstrzyknięte polecenie trafiło na regułę deny albo wymagało zgody poza trybem autoDodaj pasującą regułę do allowed-tools; reguły deny i tak wygrywają
Pod koniec długiej sesji skill przestaje wpływać na zachowanie Claude’aPo kompaktowaniu Claude Code zachowuje tylko pierwsze 5000 tokenów każdego ponownie dołączonego skilla, łącznie do 25 000 tokenów, zaczynając od najnowszychWywołaj skill ponownie; pisz krótkie treści; twarde reguły przenieś do hooków
Przy dziesiątkach skilli Claude przestaje wybierać właściwyOpisy są obcinane, żeby zmieścić się w budżecie listy (1% okna kontekstu), zaczynając od najrzadziej używanychZaczynaj każdy opis od zastosowania, rzadko używane skille ustaw na "name-only" w skillOverrides i wyłącz nieużywane wskazane przez /skill-doctor

Dokąd dalej z poleceniami niestandardowymi

Dział zatytułowany „Dokąd dalej z poleceniami niestandardowymi”

Autor:

Zobacz co nowego na platformie.

Polityka prywatności Regulamin Ustawienia cookie