Kurs vibe coding z Claude Code · Moduł 15: Claude Code dla zaawansowanych

Własna załoga: subagenci, skille i pluginy

7 min czytania
W tej lekcji9

Przed każdym commitem w Treasure Map prosisz Claude o to samo: przejrzyj trasy API pod kątem bezpieczeństwa. Raz piszesz "zerknij na sesję", raz "czy ktoś zapisze pin na cudzej tablicy", a raz zapominasz zapytać o walidację. Za każdym razem przegląd wygląda trochę inaczej i za każdym razem umyka coś innego. Procedura, którą powtarzasz z pamięci innymi słowami, to procedura, której nie masz.

Co już umiesz

W lekcji 9_5 zleciłeś subagenta video-reviewer z tools: Read, Grep, Glob i model: sonnet, a w lekcji 5_4 wysłałeś na zwiad wbudowanego Explore. Skille znasz z lekcji 6_1, a w lekcji 10_5 skill /deploy z disable-model-invocation: true zostawił decyzję o wdrożeniu Tobie. Z lekcji 5_10 wiesz, że subagent kosztuje tokeny i nie myśli mądrzej, tylko pracuje w osobnym kontekście. Teraz składasz te części w jedną procedurę dla załogi: recenzenta, skill, który go wzywa, i plugin, w którym zabierzesz oba do innych projektów.

Polecenie dla Claude Code

Recenzenta i skill zamawiasz jednym poleceniem, bo skill ma wołać tego recenzenta po nazwie:

Utwórz subagenta projektu .claude/agents/security-reviewer.md, który tylko czyta
(Read, Grep, Glob) i sprawdza trasy w app/api: sesję, właściciela danych, schemat Zod
i treść błędów. W description napisz, kiedy go używać. Potem utwórz skill
.claude/skills/przed-commitem/SKILL.md: testy, lint i ten subagent dla plików
z poczekalni, a na końcu tabela z werdyktem. Tylko ja uruchamiam ten skill.
Nie zmieniaj kodu aplikacji.

Polecenie mówi nie tylko, co recenzent ma robić, ale też czego mu nie wolno. Ostatnie zdanie chroni przed "przy okazji poprawiłem".

Co napisał Claude: recenzent

Otwórz w Cursorze .claude/agents/security-reviewer.md. Na górze stoi frontmatter, czyli ustawienia agenta:

---
name: security-reviewer
description: Recenzent bezpieczeństwa tras API Treasure Map. Używaj przed każdym commitem, który zmienia pliki w app/api albo lib/session.ts. Dostaje listę plików i tylko czyta kod.
tools: Read, Grep, Glob
model: sonnet
---

description mówi Claude, kiedy delegować, więc konkretne foldery działają lepiej niż "recenzuje kod". tools to lista dozwolonych narzędzi. Gdy pole pominiesz, agent dostaje wszystkie narzędzia rozmowy, a disallowedTools: Write, Edit zostawia mu Bash i narzędzia MCP, więc dla recenzenta wybierasz krótką listę. model: sonnet bierze tańszy model do rutyny. Bez tego pola subagent pracuje na modelu rozmowy, a dokumentacja dodaje, że Claude może przy wywołaniu podać inny model. Pod frontmatterem stoi treść, która staje się promptem systemowym agenta:

Jesteś recenzentem bezpieczeństwa. Dostajesz listę zmienionych plików.
Dla każdej trasy w app/api sprawdź:
1. czy trasa zmieniająca dane woła getCurrentUserId() i zwraca 401 bez sesji;
2. czy sprawdza właściciela tablicy albo pinu i zwraca 403 dla cudzych danych;
3. czy dane wejściowe przechodzą przez schemat Zod;
4. czy odpowiedź błędu nie ujawnia szczegółów bazy.

Niczego nie poprawiaj. Odpowiedz listą: plik:linia | problem | propozycja.
Gdy nic nie znajdziesz, napisz: Brak uwag.

Subagent nie widzi Twojej rozmowy: dostaje ten prompt i zadanie od Claude. Cztery pytania to sedno, bo przegląd za każdym razem sprawdza to samo, niezależnie od tego, jak dziś sformułujesz prośbę. Format odpowiedzi znasz z lekcji 14_1, a każdą linię porównasz z diffem.

Co napisał Claude: skill /przed-commitem

Teraz .claude/skills/przed-commitem/SKILL.md. Nagłówek skilla ma cztery pola:

---
name: przed-commitem
description: Raport przed commitem: testy, lint i recenzja bezpieczeństwa zmian w poczekalni.
disable-model-invocation: true
allowed-tools: Bash(npm run test *) Bash(npm run lint)
---

disable-model-invocation: true znasz z /deploy: skill uruchamiasz tylko Ty, a jego opis nie zajmuje kontekstu. allowed-tools zatwierdza te dwie komendy bez pytania, ale tylko w turze, w której skill działa, i niczego nie zabiera. Dokumentacja dodaje ostrzeżenie: Claude Code stosuje allowed-tools skilla z repozytorium nawet w przebiegu -p w folderze, któremu nie zaufałeś. Skille w cudzym repozytorium czytasz więc jak skrypty. Pod nagłówkiem stoją kroki:

## Pliki w poczekalni
!`git diff --cached --name-only`

## Kroki
1. Uruchom `npm run test -- --run` i zapisz wynik.
2. Uruchom `npm run lint` i zapisz wynik.
3. Przekaż subagentowi security-reviewer listę plików z poczekalni.
4. Niczego nie poprawiaj. Na koniec pokaż tabelę: testy, lint, recenzja, a pod nią werdykt "gotowe do commita" albo "do poprawy" z listą powodów.

Linia z wykrzyknikiem to wstrzyknięcie: Claude Code uruchamia komendę, zanim Claude przeczyta skill, i wkleja jej wynik w miejsce linii. To nie ozdobnik. Recenzent z Read, Grep, Glob nie uruchomi git diff sam, więc listę plików musi dostać w zadaniu. Kroki nie przerywają się na pierwszym błędzie, bo przed commitem chcesz pełnego obrazu.

Próba: /przed-commitem

W sesji wpisujesz /przed-commitem. My puściliśmy to samo przez claude -p "/przed-commitem", z lib/pinInput.ts z lekcji 14_1 w poczekalni. Skrót wyniku:

| Testy | 3 nie przechodzą z 64 |
| Lint | 2 błędy |
| Recenzja bezpieczeństwa | 1 wysoka, 1 średnia, 3 niskie uwagi |
Wysoka, linia 9: z.union([startsWith("/pins/"), z.url()]) przepuszcza dowolny URL
Werdykt: do poprawy

W JSON przebiegu pole subagent_stats pokazało jednego uruchomionego subagenta typu security-reviewer. Recenzent znalazł tę samą dziurę co szybka recenzja z potoku w lekcji 14_1, ale teraz znajdzie ją każdy z załogi tą samą komendą.

Przegląd kapitana

  1. Narzędzia recenzenta. We frontmatterze stoi tylko Read, Grep, Glob. Typowy błąd agenta: dopisuje Edit i Write "na wszelki wypadek, żeby recenzent mógł od razu poprawić". Wtedy recenzent w tle zmienia kod, którego diffu nie czytałeś, a recenzja przestaje być niezależna. Rozpoznasz to po linii tools albo po jej braku.
  2. Opis z warunkiem. description mówi, kiedy użyć agenta. Bez tego Claude sam po niego nie sięgnie i będziesz go wołać po imieniu.
  3. Kto uruchamia skill. disable-model-invocation: true musi tu być, bo raport kończy się decyzją o commicie.
  4. Sprawdzenie. Wpisz @ i wybierz recenzenta z podpowiedzi, a /skills pokaże skill na liście. Folder .claude/agents/ założony w trakcie sesji wymaga restartu sesji, a nowy .claude/skills/ komendy /reload-skills, jak w lekcji 6_1.

Pluginy: załoga w jednej skrzyni

Pliki w .claude/agents/ i .claude/skills/ jadą z repozytorium Treasure Map. A gdy tego samego recenzenta chcesz w klonie Spotify? Plugin to katalog ze skillami, agentami, hookami i serwerami MCP, który Claude Code instaluje i ładuje jako całość. Cudze pluginy przeglądasz komendą /plugin: zakładka Discover pokazuje pluginy z Twoich marketplace'ów, czyli katalogów pluginów. Oficjalny marketplace Anthropic, claude-plugins-official, Claude Code dodaje sam przy pierwszej sesji w terminalu. Instalacja zaczyna się od podglądu:

/plugin install commit-commands@claude-plugins-official

W sesji ta komenda jeszcze niczego nie instaluje: otwiera szczegóły z listą tego, co plugin doda, i pyta o zakres. Zakres projektu zapisuje plugin w .claude/settings.json, ale każdy z załogi i tak instaluje go u siebie. Plugin działa z Twoimi uprawnieniami, więc czytasz go jak każdy cudzy kod.

Własną załogę pakujesz tak samo. Dokumentacja opisuje przeniesienie gotowego folderu .claude/ do pluginu o takim układzie:

treasure-crew/
├── .claude-plugin/plugin.json      # nazwa i opis pluginu
├── agents/security-reviewer.md
└── skills/przed-commitem/SKILL.md

claude plugin validate ./treasure-crew sprawdza manifest i frontmattery, a claude --plugin-dir ./treasure-crew ładuje plugin na jedną sesję. Skill dostaje wtedy prefiks: /treasure-crew:przed-commitem. Dwie różnice warto znać. Subagent z pluginu ignoruje pola hooks, mcpServers i permissionMode, a każdy włączony plugin wnosi opisy swoich skilli i agentów do każdej tury, także gdy z nich nie korzystasz. Polecam prostą zasadę: jeden projekt to .claude/ w repozytorium, kilka projektów to plugin.

MCP dla załogi

Serwery MCP dla całej załogi już znasz: w lekcji 11_4 --scope project zapisało Sentry w .mcp.json, a w lekcji 13_7 dołożyłeś Supabase tylko do odczytu i regułę ask na mcp__supabase__*. Dorzuć do tego jedną rzecz: w .mcp.json możesz napisać ${API_KEY} zamiast tokenu, a Claude Code podstawi zmienną środowiskową z komputera każdego marynarza, więc sekret nie trafi do repozytorium. Rada z lekcji 11_4 wciąż obowiązuje: gdy system ma CLI, na przykład gh dla GitHuba, zacznij od niego, a MCP zostaw dla systemów bez CLI.

Następny krok

Dołóż do procedury sprawdzenie typów:

Dopisz do skilla /przed-commitem krok npx tsc --noEmit przed lintem
i dodaj Bash(npx tsc --noEmit) do allowed-tools. Recenzenta nie zmieniaj.

Uruchom /przed-commitem jeszcze raz i poproś o commit, na przykład "Recenzent bezpieczeństwa i skill przed commitem". W edytorze obok wkleisz frontmatter subagenta albo skilla i zobaczysz, czego Claude Code nie wczyta, jakie narzędzia dostanie recenzent i kto może uruchomić skill.

Pamiętaj: załogę werbujesz raz, a procedura pracuje w każdym rejsie.

Kod do tej lekcji: App.tsx
// Kontrola frontmattera: co Claude Code zrobi z plikiem subagenta albo skilla
import { useState } from 'react';

export type Kind = 'agent' | 'skill';
export type Level = 'ok' | 'warn' | 'error';

export interface Finding {
  level: Level;
  text: string;
}

export interface Parsed {
  hasFrontmatter: boolean;
  fields: Record<string, string>;
  body: string;
}

const BT = String.fromCharCode(96);

export function parseFrontmatter(src: string): Parsed {
  const lines = src.split('\n');
  if (lines[0] !== '---') return { hasFrontmatter: false, fields: {}, body: src };
  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
  if (end === -1) return { hasFrontmatter: false, fields: {}, body: src };
  const fields: Record<string, string> = {};
  for (const line of lines.slice(1, end)) {
    const m = /^([A-Za-z_-]+):\s*(.*)$/.exec(line);
    if (m) fields[m[1]] = m[2].trim();
  }
  return { hasFrontmatter: true, fields, body: lines.slice(end + 1).join('\n') };
}

export function toolList(value: string | undefined): string[] {
  if (!value) return [];
  return value.split(/[,\s]+/).filter(Boolean);
}

const AGENT_FIELDS = ['name', 'description', 'tools', 'disallowedTools', 'model', 'permissionMode', 'maxTurns', 'skills', 'mcpServers', 'hooks', 'memory', 'background', 'effort', 'isolation', 'color'];
const MODELS = ['sonnet', 'opus', 'haiku', 'fable', 'inherit'];
const WRITERS = ['Edit', 'Write', 'Bash', 'NotebookEdit'];

export function checkAgent(p: Parsed): Finding[] {
  const f = p.fields;
  const out: Finding[] = [];
  if (!p.hasFrontmatter || !f.name) {
    return [{ level: 'error', text: 'Bez name (albo bez --- w pierwszej linii) Claude Code uzna plik za dokumentację i go pominie.' }];
  }
  if (f.name.includes(':')) out.push({ level: 'error', text: 'name nie może zawierać dwukropka: jest zarezerwowany dla pluginów.' });
  if (!f.description) {
    out.push({ level: 'error', text: 'Jest name, ale nie ma description: Claude Code pominie plik i zapisze powód w logu --debug.' });
  } else if (!/używaj|use /i.test(f.description)) {
    out.push({ level: 'warn', text: 'description nie mówi, kiedy użyć agenta. Claude deleguje na podstawie tego opisu.' });
  } else {
    out.push({ level: 'ok', text: 'description mówi, kiedy delegować.' });
  }
  const tools = toolList(f.tools);
  if (!f.tools && f.disallowedTools) {
    out.push({ level: 'warn', text: 'disallowedTools bez tools: agent dziedziczy resztę narzędzi, także Bash i MCP.' });
  } else if (!f.tools) {
    out.push({ level: 'warn', text: 'Brak tools: agent dostaje wszystkie narzędzia rozmowy, także Edit, Write i Bash.' });
  } else {
    const writers = tools.filter((t) => WRITERS.includes(t));
    out.push(
      writers.length
        ? { level: 'warn', text: 'Recenzent z ' + writers.join(', ') + ' może zmieniać kod albo uruchamiać komendy. Do recenzji wystarczy Read, Grep, Glob.' }
        : { level: 'ok', text: 'Tylko czyta (' + tools.join(', ') + '). Listę plików musi dostać w zadaniu, bo git diff nie uruchomi.' },
    );
  }
  if (f.model) {
    const known = MODELS.includes(f.model) || f.model.startsWith('claude-');
    out.push(known ? { level: 'ok', text: 'model: ' + f.model + '.' } : { level: 'warn', text: 'Nieznany model "' + f.model + '".' });
  }
  for (const key of Object.keys(f)) {
    if (!AGENT_FIELDS.includes(key)) {
      out.push({ level: 'warn', text: 'Pole ' + key + ' nie istnieje w agencie; Claude Code zignoruje je bez błędu (pola agenta piszesz camelCase).' });
    }
  }
  return out;
}

const SKILL_FIELDS = ['name', 'description', 'when_to_use', 'argument-hint', 'arguments', 'disable-model-invocation', 'user-invocable', 'allowed-tools', 'disallowed-tools', 'model', 'effort', 'context', 'agent', 'background', 'hooks', 'paths', 'shell'];

export function checkSkill(p: Parsed): Finding[] {
  const f = p.fields;
  const out: Finding[] = [];
  if (!p.hasFrontmatter) {
    return [{ level: 'warn', text: 'Bez --- w pierwszej linii cały plik jest treścią, a skill nie ma żadnych pól.' }];
  }
  out.push(
    f.description
      ? { level: 'ok', text: 'description jest; to z niego Claude wie, do czego służy skill.' }
      : { level: 'warn', text: 'Brak description: Claude weźmie pierwszą linię treści.' },
  );
  const sideEffects = /commit|deploy|wdroż|push|npm run/i.test(p.body);
  if (f['disable-model-invocation'] === 'true') {
    out.push({ level: 'ok', text: 'Tylko Ty uruchamiasz skill; jego opis nie siedzi w kontekście.' });
  } else if (sideEffects) {
    out.push({ level: 'warn', text: 'Kroki mają skutki uboczne, a Claude może sam uruchomić skill. Dodaj disable-model-invocation: true.' });
  }
  if (f['allowed-tools']) {
    out.push({ level: 'ok', text: 'allowed-tools zatwierdza ' + f['allowed-tools'] + ' tylko w turze skilla i niczego nie zabiera. W cudzym repozytorium czytaj tę linię uważnie.' });
  }
  const injected = p.body.split('\n').filter((l) => l.startsWith('!' + BT));
  for (const line of injected) {
    out.push({ level: 'ok', text: 'Wstrzyknięcie: ' + line.slice(2, -1) + ' uruchomi się, zanim Claude przeczyta skill, a wynik zastąpi linię.' });
  }
  for (const key of Object.keys(f)) {
    if (!SKILL_FIELDS.includes(key)) {
      out.push({ level: 'warn', text: 'Pole ' + key + ' nie istnieje w skillu; Claude Code zignoruje je bez błędu (pola skilla piszesz z myślnikami).' });
    }
  }
  return out;
}

export const SAMPLES: Record<string, { kind: Kind; text: string }> = {
  'Recenzent tylko do odczytu': {
    kind: 'agent',
    text: [
      '---',
      'name: security-reviewer',
      'description: Recenzent bezpieczeństwa tras API. Używaj przed każdym commitem, który zmienia app/api.',
      'tools: Read, Grep, Glob',
      'model: sonnet',
      '---',
      'Sprawdź sesję, właściciela danych i schemat Zod. Niczego nie poprawiaj.',
    ].join('\n'),
  },
  'Recenzent na wszelki wypadek': {
    kind: 'agent',
    text: [
      '---',
      'name: security-reviewer',
      'description: Recenzuje kod.',
      'tools: Read, Grep, Glob, Edit, Write',
      'disallowed-tools: Bash',
      '---',
      'Sprawdź trasy i od razu popraw, co znajdziesz.',
    ].join('\n'),
  },
  'Skill przed commitem': {
    kind: 'skill',
    text: [
      '---',
      'name: przed-commitem',
      'description: Raport przed commitem: testy, lint i recenzja bezpieczeństwa.',
      'disable-model-invocation: true',
      'allowed-tools: Bash(npm run test *) Bash(npm run lint)',
      '---',
      '## Pliki w poczekalni',
      '!' + BT + 'git diff --cached --name-only' + BT,
      '1. Uruchom npm run test -- --run.',
      '2. Przekaż listę plików subagentowi security-reviewer.',
    ].join('\n'),
  },
  'Skill bez blokady': {
    kind: 'skill',
    text: [
      '---',
      'name: przed-commitem',
      'disableModelInvocation: true',
      '---',
      'Uruchom testy i zrób commit, jeśli przejdą.',
    ].join('\n'),
  },
};

const LEVEL_CLASS: Record<Level, string> = {
  ok: 'text-emerald-400',
  warn: 'text-amber-400',
  error: 'text-rose-400',
};

export default function App() {
  const names = Object.keys(SAMPLES);
  const [kind, setKind] = useState<Kind>(SAMPLES[names[0]].kind);
  const [text, setText] = useState(SAMPLES[names[0]].text);
  const parsed = parseFrontmatter(text);
  const findings = kind === 'agent' ? checkAgent(parsed) : checkSkill(parsed);

  return (
    <div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
      <h1 className="text-xl font-bold">Kontrola załogi: subagent i skill</h1>
      <div className="flex flex-wrap gap-2">
        {names.map((n) => (
          <button
            key={n}
            type="button"
            className="rounded bg-slate-700 px-3 py-1 text-sm"
            onClick={() => {
              setKind(SAMPLES[n].kind);
              setText(SAMPLES[n].text);
            }}
          >
            {n}
          </button>
        ))}
      </div>
      <label className="block text-sm">
        Rodzaj pliku{' '}
        <select className="rounded bg-slate-800 p-1" value={kind} onChange={(e) => setKind(e.target.value as Kind)}>
          <option value="agent">.claude/agents/*.md</option>
          <option value="skill">.claude/skills/*/SKILL.md</option>
        </select>
      </label>
      <textarea
        className="h-56 w-full rounded bg-slate-900 p-2 font-mono text-xs"
        value={text}
        onChange={(e) => setText(e.target.value)}
      />
      <ul className="space-y-1 text-sm">
        {findings.map((f, i) => (
          <li key={i} className="rounded border border-slate-800 p-2">
            <strong className={LEVEL_CLASS[f.level]}>{f.level}</strong> {f.text}
          </li>
        ))}
      </ul>
    </div>
  );
}

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Subagent security-reviewer ma tylko recenzować trasy API. Co wpiszesz w jego frontmatterze?

  2. 2. Gdzie zapisać subagenta security-reviewer, żeby dostał go każdy, kto sklonuje Treasure Map?

To 2 z 4 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w poziomie

    Ułóż komendę, która sprawdza manifest i frontmattery Twojego pluginu treasure-crew, zanim dasz go załodze:

  1. PytanieQuiz: Narzędzia subagenta recenzenta
  2. PytanieQuiz: Subagent dla całej załogi
  3. Ułóż w kolejnościSortowanie: Sprawdzenie pluginu
  4. PytanieQuiz: CLI czy MCP
  5. PytanieQuiz: Wstrzyknięta lista plików w skillu

Przydatne artykuły