Własne subagenty w Claude Code: .claude/agents/*.md

O czym to jest

Claude Code potrafi przekazać część pracy subagentowi: osobnej instancji modelu z własnym oknem kontekstu. Subagent dostaje zadanie, wykonuje je swoimi narzędziami i zwraca do głównej rozmowy tylko podsumowanie. Dokumenty, które przeczytał po drodze, i wyniki poleceń zostają w jego kontekście.

Ten wpis dotyczy własnych subagentów. To pliki Markdown w katalogu .claude/agents/, w których zapisuje się stały prompt, listę dozwolonych narzędzi i model. Raz zdefiniowany „recenzent umów” czy „księgowy” jest dostępny w każdej sesji, a Claude na podstawie opisu w nagłówku sam decyduje, kiedy go użyć.

Jak wygląda definicja

Każdy subagent to osobny plik .md z nagłówkiem YAML. Przykładowy folder działu operacyjnego:

firma/
├── CLAUDE.md
├── umowy/
├── faktury/
├── raporty/
└── .claude/
    └── agents/
        ├── umowy-reviewer.md
        ├── uzgadnianie-faktur.md
        └── sprzedaz/               # podkatalog tylko dla porządku
            └── analityk.md

Przykładowa definicja:

---
name: umowy-reviewer
description: Przegląd umów z kontrahentami pod kątem ryzyk, terminów i niekorzystnych zapisów. Używaj proaktywnie, gdy użytkownik dodaje lub zmienia umowę w folderze umowy/.
tools: Read, Grep, Glob
model: opus
---

Jesteś doświadczonym specjalistą od umów handlowych.

1. Przeczytaj umowę wskazaną w zleceniu.
2. Porównaj ją z wzorcem `umowy/_wzorzec.md` i polityką `umowy/_zasady.md`.
3. Wypisz uwagi w trzech grupach: krytyczne, do negocjacji, kosmetyczne.
4. Przy każdej uwadze podaj paragraf, cytat i proponowane brzmienie.

Osobno wypisz terminy: okres wypowiedzenia, kary umowne, daty płatności, automatyczne przedłużenie.
Nie edytuj plików. Zwróć tylko raport.

Treść pod nagłówkiem to prompt systemowy subagenta. Zastępuje on prompt systemowy Claude Code: subagent dostaje tylko ten tekst i podstawowe informacje o środowisku (katalog roboczy, system). Dlatego prompt powinien opisywać rolę, kolejne kroki i format odpowiedzi, bo subagent nie odziedziczy tego z rozmowy.

Wymagane są tylko dwa pola: name i description. Plik bez name albo z błędnym nagłówkiem jest ignorowany. Plik z name, ale bez description albo z błędem składni YAML, również nie zostanie załadowany, a jedyny ślad tego zostaje w logu claude --debug. Nieznane pola są pomijane bez ostrzeżenia w interfejsie.

Gdzie mogą leżeć definicje

Z tego wynika kilka zasad:

• Tożsamość wyznacza name, a nie nazwa pliku.
• Agentów można nadpisywać. Jeśli w ~/.claude/agents/ i w .claude/agents/ jest agent o tej samej nazwie, używana jest definicja z projektu.
• Bliższy katalog wygrywa. Przy powtórzonej nazwie obowiązuje definicja położona najbliżej katalogu, w którym uruchomiono sesję.
• Zmiany działają od razu. Edycja pliku w istniejącym katalogu agents/ jest wykrywana w ciągu kilku sekund. Restart jest potrzebny w trzech przypadkach: gdy katalog agents/ dla danego zakresu powstał w trakcie sesji, gdy agent leży w katalogu dodanym przez --add-dir albo /add-dir oraz gdy sesję uruchomiono z flagą --disable-slash-commands.

Pola nagłówka

description: kiedy agent zostanie użyty

description to najważniejsze pole w pliku. Claude porównuje treść prośby z opisami wszystkich agentów i na tej podstawie wybiera, komu oddać zadanie. Opisy własnych agentów są stale obecne w kontekście głównej sesji, więc powinny być krótkie. Gdy ich łączna długość przekracza 15 000 tokenów, Claude Code wyświetla ostrzeżenie na starcie. Opis powinien mówić, co agent robi i kiedy go użyć:

description: >
  Uzgadnia wyciąg bankowy (CSV) z rejestrem faktur
  i wskazuje nieopłacone lub zdublowane pozycje.
  Używaj proaktywnie po dodaniu nowego wyciągu do folderu faktury/
  oraz gdy użytkownik pyta o zaległe płatności.

tools i disallowedTools: co agent może zrobić

Bez pola tools subagent dziedziczy narzędzia głównej sesji, także narzędzia serwerów MCP. Subagenty działające w tle (to tryb domyślny) dostają jednak węższy zestaw narzędzi wbudowanych, m.in. Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch i Skill. Narzędzia MCP zachowują w całości. Do dalszego ograniczenia służą dwa pola:

tools: Read, Grep, Glob # lista dozwolonych: agent tylko czyta dokumenty

disallowedTools: Write, Edit # lista zabronionych: wszystko poza edycją plików

# narzędzia MCP
tools: Read, mcp__crm__*           # wszystkie narzędzia serwera crm
disallowedTools: mcp__*            # bez żadnych narzędzi MCP

Niezależnie od konfiguracji subagent nie ma dostępu do kilku narzędzi, m.in. AskUserQuestion i EnterPlanMode. Nie może więc dopytać użytkownika w trakcie pracy, co jest kolejnym powodem, by prompt był kompletny. Subagent może uruchamiać własne subagenty, maksymalnie do trzech poziomów w głąb. Żeby to zablokować, wystarczy pominąć Agent w tools albo dopisać go do disallowedTools.

model: który model pracuje

Model jest ustalany w następującej kolejności (wygrywa pierwsze podane źródło):

1. Parametr model w wywołaniu narzędzia Agent.
2. Pole model w nagłówku definicji.
3. Zmienna środowiskowa CLAUDE_CODE_SUBAGENT_MODEL.
4. Model głównej rozmowy.

Jak wywołać subagenta

Subagenty uruchamiane z głównej rozmowy domyślnie działają w tle, a ich postęp widać w /tasks. Prośby o uprawnienia od subagenta działającego w tle pojawiają się w głównej sesji, oznaczone jego nazwą. Zakończonego subagenta można wznowić, pisząc np. „kontynuuj ten przegląd i sprawdź jeszcze klauzulę o poufności”. Claude wysyła wtedy wiadomość do istniejącej instancji, która zachowuje całą swoją historię.

Co subagent dostaje na starcie

Własny subagent zaczyna z czystym kontekstem. Dostaje:

• prompt z pliku definicji i informacje o środowisku,
• wiadomość, którą napisał Claude przy delegowaniu,
• pliki CLAUDE.md (chyba że omitClaudeMd: true),
• migawkę git status, jeśli folder jest repozytorium git,
• treść skilli wymienionych w polu skills.

Nie dostaje historii rozmowy ani automatycznej pamięci. Zasady, które mają obowiązywać także subagenty, najlepiej trzymać w CLAUDE.md albo w regułach (więcej: Reguły w Claude Code ).

Przykłady

Agent tylko do odczytu: analiza oferty konkurencji

---
name: analiza-konkurencji
description: >
  Zbiera ceny, pakiety i warunki ze stron konkurencji wymienionych w pliku rynek/konkurenci.md.
  Używaj, gdy użytkownik pyta o ceny konkurencji, przygotowuje cennik albo ofertę przetargową.
tools: Read, Grep, Glob, WebFetch, WebSearch
model: haiku
color: cyan
---

Analizujesz ofertę konkurencji na podstawie ich stron internetowych.

1. Wczytaj listę firm i adresów z `rynek/konkurenci.md`.
2. Dla każdej firmy pobierz stronę cennika i oferty. Jeśli adres nie działa, wyszukaj aktualną stronę.
3. Zapisz dla każdej firmy: pakiety, ceny netto, okres umowy, dodatkowe opłaty, datę sprawdzenia.

Zwróć jedną tabelę porównawczą i pod nią maksymalnie pięć wniosków. Przy każdej cenie podaj adres źródła.
Jeśli ceny nie da się ustalić, wpisz „brak danych”, nie szacuj. Nie edytuj plików.

Agent ma tylko narzędzia do czytania i pobierania stron, więc niczego nie zmieni. Treść kilkudziesięciu pobranych stron zostaje w jego kontekście, a do rozmowy wraca jedna tabela. Tani model haiku wystarcza do wyciągania cen.

Agent zapisujący wynik: uzgadnianie faktur z wyciągiem

---
name: uzgadnianie-faktur
description: >
  Uzgadnia wyciąg bankowy (CSV) z rejestrem faktur i wskazuje nieopłacone lub zdublowane pozycje.
  Używaj proaktywnie po dodaniu nowego wyciągu do folderu faktury/ oraz gdy użytkownik pyta o zaległe płatności.
tools: Read, Write, Grep, Glob
model: sonnet
maxTurns: 30
---

Uzgadniasz płatności z fakturami za miesiąc wskazany w zleceniu.

1. Wczytaj wyciąg `faktury/wyciagi/<miesiąc>.csv` i rejestr `faktury/rejestr.csv`.
2. Dopasuj przelewy do faktur po numerze faktury w tytule przelewu, a gdy go brak, po kwocie i NIP kontrahenta.
3. Zapisz wynik w `raporty/uzgodnienie-<miesiąc>.md` w trzech sekcjach:
   opłacone, nieopłacone po terminie, przelewy bez dopasowania.

Nie zmieniaj plików wyciągów ani rejestru. Dopasowania niepewne (tylko po kwocie) oznacz jako „do weryfikacji”.
Na koniec zwróć liczbę pozycji w każdej sekcji i łączną kwotę zaległości.

Agent nie ma Edit ani Bash, więc nie poprawi pojedynczych wierszy w danych ani nie uruchomi skryptów. Write pozwala jednak nadpisać każdy plik, także rejestr.csv, i przed tym chroni wyłącznie instrukcja w prompcie. Twardą blokadę daje dopiero hook PreToolUse na Write, który przepuszcza tylko ścieżki w raporty/ (mechanizm opisany w następnym przykładzie). maxTurns chroni przed zapętleniem przy wyciągu, którego nie da się uzgodnić.

Agent z hookiem: dane sprzedażowe tylko do odczytu

---
name: analityk-sprzedazy
description: >
  Odpowiada na pytania o sprzedaż, klientów i produkty na podstawie bazy dane/sprzedaz.db.
  Używaj, gdy użytkownik pyta o wyniki sprzedaży, trendy albo najlepszych klientów.
tools: Bash, Read
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/tylko-odczyt.sh"
---

Odpowiadasz na pytania o sprzedaż, wykonując zapytania `sqlite3 -readonly dane/sprzedaz.db "<zapytanie>"`. Używaj wyłącznie SELECT, jedno zapytanie na wywołanie, bez średnika na końcu.
Wynik podsumuj w kilku zdaniach i małej tabeli, nie wklejaj całych zestawień. Kwoty podawaj w PLN netto.

Pole tools nie odróżnia odczytu danych od ich usuwania: zapytania SELECT i DELETE idą przez to samo narzędzie Bash. Dlatego potrzebny jest hook. Przed każdym wywołaniem Bash Claude Code przekazuje skryptowi na standardowe wejście opis wywołania w formacie JSON, a treść polecenia jest w polu tool_input.command. Kod wyjścia 2 blokuje wywołanie, a tekst ze standardowego wyjścia błędów trafia do subagenta jako wyjaśnienie. Skrypt scripts/tylko-odczyt.sh:

#!/usr/bin/env bash
# Hook PreToolUse dla agenta analityk-sprzedazy: przepuszcza tylko odczyt bazy.

COMMAND=$(jq -r '.tool_input.command // empty')

# Dozwolone jest jedno wywołanie sqlite3 na bazie otwartej tylko do odczytu.
if [[ "$COMMAND" != "sqlite3 -readonly dane/sprzedaz.db "* ]]; then
  echo "Zablokowano: uruchamiaj wyłącznie 'sqlite3 -readonly dane/sprzedaz.db \"<zapytanie>\"'." >&2
  exit 2
fi

# Bez łączenia poleceń, potoków i podstawień powłoki.
if [[ "$COMMAND" == *[\;\&\|\`]* || "$COMMAND" == *'$('* || "$COMMAND" == *$'\n'* ]]; then
  echo "Zablokowano: polecenie może zawierać tylko jedno zapytanie, bez ; & | \` i \$(...)." >&2
  exit 2
fi

# Słowa kluczowe SQL zmieniające dane lub schemat.
if grep -qiwE 'INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|REPLACE|ATTACH|VACUUM' <<< "$COMMAND"; then
  echo "Zablokowano: dozwolone są tylko zapytania SELECT." >&2
  exit 2
fi

exit 0

Przykłady zastosowania

Jak sprawdzić, czy agent działa

Podsumowanie

• Subagent to plik .md w .claude/agents/ albo ~/.claude/agents/. Przy tej samej nazwie wygrywa projekt.
• Wymagane są name i description. Tożsamość agenta wyznacza name, nie nazwa pliku ani podkatalog.
• Treść pliku to prompt systemowy. Subagent nie widzi historii rozmowy, więc prompt musi opisywać rolę, kroki i format wyniku.
• description decyduje o automatycznym delegowaniu: powinien mówić, co agent robi i kiedy go użyć.
• tools i disallowedTools ograniczają uprawnienia, model pozwala dobrać koszt do zadania, a hooki w nagłówku kontrolują to, czego nie da się opisać listą narzędzi.
• Subagent sprawdza się tam, gdzie po drodze powstaje dużo danych (umowy, wyciągi, strony konkurencji), a w rozmowie potrzebny jest tylko wynik.