Wspólne skills — firmowe repo + bootstrap + onboarding hook

Pytanie 6 (Wspólna infrastruktura): Czy zespół dzieli się skills?

Odpowiedź na maksa: Repo + bootstrap script + onboarding hook, który auto-instaluje.

Dlaczego to ważne: Skills to sposób, w jaki seniorzy pakują wiedzę instytucjonalną. Repo skills zmienia “umie zrefaktorować nasz auth” w one-liner, który każdy może odpalić.

Dlaczego to ma znaczenie w 2026

Największym predyktorem tego, ile wartości organizacja inżynierska wyciąga w 2026 z Claude Code, Codex czy Cursora, nie jest to, za który model płacisz — tylko czy milcząca wiedza w głowach Twoich seniorów została zapakowana w coś, co junior (albo agent) potrafi odpalić. Po to są skills. SKILL.md to wiedza proceduralna z progresywnym disclosure (“tak refaktorujemy auth”, “tak shippujemy fix do webhooka Polara”) zbundlowana ze skryptami, promptami i referencjami, których agent potrzebuje.

Anthropic opublikował SKILL.md jako otwarty standard pod agentskills.io pod koniec 2025, a do Q2 2026 działa już w Claude Code, Codex, Cursorze, Gemini CLI i Copilocie. Format wygrał szybko, bo rozwiązał problem, który każdy zespół niezależnie napotkał: seniorzy w kółko odtwarzali te same instrukcje w wątkach Slacka, w .claude/rules/, w prywatnych notatkach — i nic z tego nie skalowało się poza autora.

Odpowiedź na maksa w Q6 zamyka tę lukę. Jedno repo gita trzyma wszystkie skills. Bootstrap script symlinkuje folder skills/ do ~/.claude/skills/ każdego developera (plus odpowiedniki Cursora i Codexa). SessionStart hook na każdej nowej sesji sprawdza wersję repo i auto-pulluje, jeśli kolega coś wypchnął. Kiedy senior wystawia PR z nowym skillem, następna sesja agenta każdego developera już go ma załadowanego — bez DM-a, bez ogłoszenia, bez manualnej instalacji.

Zespoły bez tego setupu płacą rekurencyjny podatek “wyjaśnij, jak robimy X”. Zespoły z nim zamykają lukę między top performerem a medianą, bo wiedza top performera jest teraz w repo. Strukturalna przewaga, która kompounduje się każdy sprint.

Jak wygląda “max score” w praktyce (repo + bootstrap script + onboarding hook auto-install)

Trzy komponenty, każdy robi jedną rzecz:

1. Firmowe repo skills. Zwykłe repo gita (acme/agent-skills), jeden folder per skill. Każdy folder ma SKILL.md plus scripty, prompty i referencje. Repo jest wersjonowane, reviewowane przez PR i ownowane przez nazwany zespół — jak Twoja wspólna konfiguracja lintera czy design tokens.

2. Bootstrap script. Jedna komenda (./bootstrap.sh, npx @acme/agent-skills install), która wpina repo w maszynę developera. Klonujesz do ~/.acme-agent-skills/ i symlinkujesz każdy folder skillowy do ~/.claude/skills/, ~/.cursor/skills/, ~/.codex/skills/. Symlinki (nie kopie) sprawiają, że jeden git pull aktualizuje każde narzędzie jednocześnie.

3. Onboarding hook, który auto-instaluje. SessionStart hook w ~/.claude/settings.json sprawdza przy każdej nowej sesji: “czy lokalne repo skillsów jest aktualne z origin?”. Jeśli nie — pulluje. Jeśli nie jest jeszcze sklonowane — klonuje. Pierwszy raz, kiedy nowy hire otwiera Claude Code w Twojej organizacji, dostaje wszystkie firmowe skills, nigdy nie wiedząc, że to się stało.

Czysty layout plików:

acme/agent-skills/                          # repo
├── bootstrap.sh                            # script instalujący (idempotentny)
├── version.json                            # { "version": "2026.05.21", "min_claude": "1.4.0" }
├── README.md                               # dla ludzi
└── skills/
    ├── refactor-auth/
    │   ├── SKILL.md                        # sam skill
    │   ├── scripts/migrate.sh
    │   └── references/policies.md
    ├── ship-polar-webhook-fix/
    │   └── SKILL.md
    ├── audit-worker-cost/
    │   ├── SKILL.md
    │   └── scripts/cost-diff.ts
    └── ...

Pierwsza sesja terminala nowego hire’a od początku do końca:

# Dzień 1, po setupie laptopa
$ curl -fsSL https://acme.dev/agent-skills/install | bash
$ claude
> /skills
# Wszystkie 47 firmowych skillsów już wylistowanych.

Żadnego “zapytaj na Slacku, które skills zainstalować”. Żadnego “poczekaj, aż kumpel cię wprowadzi”. Agent wchodzi z każdym kawałkiem wiedzy instytucjonalnej, który firma raczyła spisać.

Aktualny krajobraz (zweryfikowany web-searchem)

Struktura repo skills (folder per skill z SKILL.md)

Konwencja 2026, ustawiona przez referencję Anthropica i wzmocniona przez openai/skills i VoltAgent awesome-agent-skills, to jeden folder per skill, jeden SKILL.md per folder. Plik używa YAML frontmattera (name, description, when_to_use), po którym idzie ciało. Loader skanuje katalog, czyta frontmatter i ładuje pełne ciało do kontekstu dopiero, gdy skill pasuje do intencji usera — to “progresywne disclosure” powstrzymujące skills przed rozsadzeniem context window.

Minimalny firmowy skill:

---
name: refactor-auth
description: Zrefaktoruj handler BetterAuth + Polar.sh. Użyj, kiedy user prosi
  "zrefaktoruj auth", "popraw auth", "przerób signin" albo modyfikuje plik
  w src/lib/auth/** lub src/pages/api/auth/**.
---

# Refactor auth (Acme)

## Model myślowy
- BetterAuth ownuje sesje i flow OTP.
- Polar.sh ownuje stan subskrypcji, zapisywany przez webhook do
  `subscription_access_tokens`.
- Zalogowany user bez aktywnej subskrypcji dostaje 402 z gated route'ów.

## Kroki
1. Przeczytaj `src/lib/auth/config.ts`; potwierdź opcje BetterAuth.
2. Odpal `npm run db:check-migrations` przed jakąkolwiek zmianą schemy.
3. Pierwsza linia każdego gated handlera: `await auth.api.getSession({ headers })`.
4. Po zmianach odpal `./scripts/auth-smoke.sh` (w folderze tego skilla).

## Częste pułapki
- Bridge webhooka Polara jest async — nie sprawdzaj stanu subskrypcji
  natychmiast po checkoucie; polluj z backoffem.
- Nie rób własnego sprawdzania sesji. Zawsze przez `auth.api.*`.

Każdy skill jest reviewowalny. PR-y dodające albo zmieniające skill przechodzą przez ten sam code review co każda inna zmiana. O to chodzi — wiedza instytucjonalna staje się artefaktem pierwszej klasy.

Bootstrap script (symlink ~/.claude/skills/* do klonu repo)

Wzorzec bootstrapu, który utknął w community templates (netresearch/skill-repo-skill, Anthropic Skill-Creator), to:

#!/usr/bin/env bash
set -euo pipefail

REPO_DIR="${HOME}/.acme-agent-skills"
SKILLS_DIR="${REPO_DIR}/skills"

# 1. Sklonuj albo zaktualizuj repo
if [ ! -d "${REPO_DIR}" ]; then
  git clone https://github.com/acme/agent-skills "${REPO_DIR}"
else
  git -C "${REPO_DIR}" pull --ff-only
fi

# 2. Upewnij się, że istnieją docelowe katalogi
mkdir -p ~/.claude/skills ~/.cursor/skills ~/.codex/skills

# 3. Symlinkuj każdy skill do skills dira każdego narzędzia
for skill in "${SKILLS_DIR}"/*/; do
  name="$(basename "${skill}")"
  ln -sfn "${skill}" ~/.claude/skills/"${name}"
  ln -sfn "${skill}" ~/.cursor/skills/"${name}"
  ln -sfn "${skill}" ~/.codex/skills/"${name}"
done

# 4. Zarejestruj SessionStart hook (tylko przy pierwszym odpaleniu)
HOOK_FILE="${HOME}/.claude/hooks/acme-skill-sync.sh"
if [ ! -f "${HOOK_FILE}" ]; then
  mkdir -p "${HOME}/.claude/hooks"
  cat > "${HOOK_FILE}" <<'EOF'
#!/usr/bin/env bash
git -C "${HOME}/.acme-agent-skills" fetch --quiet origin main || exit 0
LOCAL="$(git -C "${HOME}/.acme-agent-skills" rev-parse HEAD)"
REMOTE="$(git -C "${HOME}/.acme-agent-skills" rev-parse origin/main)"
[ "$LOCAL" != "$REMOTE" ] && "${HOME}/.acme-agent-skills/bootstrap.sh" >/dev/null
EOF
  chmod +x "${HOOK_FILE}"
  # Zarejestruj hook w settings.json (zobacz krok 4 w następnej sekcji).
fi

echo "Zainstalowano $(ls "${SKILLS_DIR}" | wc -l) skillsów."

Liczą się trzy właściwości:

Idempotentny. Odpal go pięć razy z rzędu — nic nie pęknie. Symlinki re-tworzone, git pull fast-forward-only, hook pisany tylko jeśli go nie ma.
Multi-tool. Symlinki rozchodzą się z jednego źródła do każdego narzędzia w zespole. Skill napisany raz pojawia się wszędzie.
Read-only po stronie developera. Developerzy nigdy nie edytują plików w ~/.claude/skills/ bezpośrednio — edytują w repo, składają PR, symlink łapie zmianę. To zabija tryb awarii “drift”, gdzie każdy developer ma subtelnie inną kopię.

Auto-install onboarding hook (SessionStart hook sprawdzający wersję)

SessionStart hook w Claude Code (z odpowiednikami w Cursorze i Codexie) odpala script za każdym razem, gdy startuje nowa sesja. Bez niego senior shippujący skill o 16:00 dociera do zespołu dopiero jak każdy inny developer ręcznie pullnie. Z hookiem następna sesja każdego developera auto-synchronizuje się.

Wzorzec w ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": ".*",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/acme-skill-sync.sh" }
        ]
      }
    ]
  }
}

Hook powinien być szybki (poniżej sekundy) i cichy na happy path. Loguje tylko, jeśli faktycznie pullnął — jednolinijkowy komunikat “Updated to 2026.05.21 (3 skills changed)” mówi developerowi, co nowego, nie przerywając flow.

Część zespołów dorzuca miękki check wersji: hook czyta version.json z repo i porównuje z min_skills_version w AGENTS.md projektu. Jeśli repo jest starsze niż projekt wymaga, hook marudzi, żeby zaktualizować — projekt zależny od nowszego skilla nigdy cicho nie pęka na nieświeżej maszynie.

Discovery + zarządzanie wersjami

Dwa problemy operacyjne pojawiają się, gdy skills już istnieją: discovery (“czy skill na to istnieje?”) i wersjonowanie (“gdy skill się zmienił, czy ktoś to zauważył?”).

Discovery. /skills w Claude Code listuje każdy załadowany skill z opisem z frontmattera. Dla większości zespołów wystarczy, ale te najlepiej działające publikują wewnętrzny indeks — Notion, README.md w repo albo wpis w Backstage’u — pogrupowany po domenie (auth/, infra/, payments/, frontend/) z ownerem per wpis.

Wersjonowanie. Dwie taktyki w 2026: semantyczne wersjonowanie repo (tagi typu v2026.05.21), więc bootstrap może pinować albo trackować main, oraz CHANGELOG.md aktualizowany każdym PR-em, żeby seniorzy łapali nakładające się albo breaking zmiany. Sparuj to z jobem CI, który pinguje ownera na PR-ach zmieniających skills/<name>/SKILL.md — i skill nigdy cicho nie zmienia zachowania pod ownerem.

Krok po kroku: rollout firmowego repo skills

Stwórz repo i zasiej trzema skillsami, które możesz shipnąć dzisiaj.

Wybierz trzy kawałki wiedzy, które obecnie wyjaśniasz na Slacku przynajmniej raz na sprint — “jak refaktorujemy handler route’a”, “jak dodajemy migrację D1”, “jak shippujemy fix do webhooka Polara”. Spisz każdy jako skills/<name>/SKILL.md z frontmatterem, modelem myślowym, krokami, pułapkami. Trzy wystarczą do udowodnienia formatu; reszta pójdzie sama.
Napisz bootstrap script i najpierw przedogfoodzuj go sam.

Odpal na własnym laptopie, otwórz Claude Code, wpisz /skills, potwierdź, że Twoje trzy zasiane skille się pokazują. Potem zepsuj coś specjalnie — usuń symlink, edytuj plik bezpośrednio — i odpal bootstrap ponownie. Jeśli nie naprawia stanu idempotentnie, popraw to, zanim oddasz komukolwiek innemu.
Dodaj SessionStart hook i zweryfikuj auto-sync.

Zarejestruj hook w ~/.claude/settings.json, pushnij małą zmianę do repo z innej maszyny, otwórz nową sesję Claude Code, potwierdź, że hook się odpalił i lokalny checkout się zaktualizował. Pierwszy raz, kiedy widzisz “Updated to 2026.05.21” samo z siebie, to moment, w którym system staje się prawdziwy.
Rolluj najpierw do jednego zespołu, nie do całej organizacji.

Wybierz pięciu do dziesięciu inżynierów i usiądź z nimi, gdy odpalają bootstrap.sh. Patrz, co pęka — korporacyjne dotfile managery, fish vs. zsh, niedomyślne lokalizacje ~/.claude/. Popraw bootstrap, aż jest turnkey dla tego zespołu. Dopiero potem skaluj.
Promuj przynajmniej jeden skill na sprint z “tribalnego” do “repo-nego”.

Kiedy senior odpowiada na pytanie, które padło wcześniej, odpowiedź staje się PR-em ze skillem przed końcem dnia. Egzekwuj na retrach: “wyjaśnialiśmy X trzy razy — czyje nazwisko jest na PR-ze skill-ifującym to?”. Prędkość bije polish. Zaniedbany skill, który istnieje, bije perfekcyjny, którego nie ma.
Dodaj metadane discovery i ownershipu.

Po tuzinie skillsów dodaj README.md pogrupowany po domenie z ownerami, plus CODEOWNERS, żeby PR-y na skills/auth/** auto-requestowały review od zespołu auth. Bez ownershipu skille szybko gniją.
Wepnij bootstrap w doc onboardingowy.

Setup script nowego hire’a (Homebrew, klucze SSH, monorepo) powinien też odpalać curl -fsSL .../agent-skills/install | bash. To moment, w którym przechodzisz z “mamy repo skills” do “każdy nowy hire wchodzi z każdym skillem załadowanym” — stan max-score dla Q6.
Audytuj kwartalnie.

Co kwartał audytuj repo. Wykasuj skille, których nikt nie używa (Claude Code loguje załadowania — wyciągnij liczby). Zmerguj bliskie duplikaty. Awansuj skille, które powinny być regułami projektowymi, do .claude/rules/. Repo to żyjący kod, nie wysypisko.

Typowe pułapki

Skille napisane przez jedną osobę, których nikt inny nie używa. Klasyczny tryb awarii. Senior pisze skill, shipuje, zakłada, że zespół go używa — ale nikt nie wie, że istnieje, albo opis frontmattera jest tak mglisty, że agent go nigdy nie ładuje. Fix jest dwustronny: bezlitosne description: odzwierciedlające, jak teammate faktycznie prosi (“kiedy user mówi ‘fix auth’ albo ‘refaktoryzuj signin’”), plus discovery pass na standupie (“shipnęliśmy te trzy skille w tym sprincie, oto co robią”).

Brak wersjonowania, brak review. Repo bez CHANGELOG-a, bez review PR-ów i bez ownerów rozpada się w chaos w ciągu kwartału. Skille się nakładają, zaprzeczają sobie i odwołują do scriptów, które już nie istnieją. Traktuj repo jak każdy inny artefakt produkcyjny — PR-y, CODEOWNERS, CI checks. Jeśli regułą jest “każdy może pushnąć na main”, seniorzy przestaną pisać skille, bo nie ufają stanowi.

Kopiowanie zamiast symlinkowania. Część zespołów kopiuje do ~/.claude/skills/ zamiast symlinkować. Pierwszy update nigdy nie dociera do nikogo. Zawsze symlinkuj (albo użyj Stow). Cały sens jest taki, że jeden git pull aktualizuje każde narzędzie.

Brak SessionStart hooka. Bez auto-install hooka wracasz do “pamiętaj, żeby pullnąć repo” — co znaczy, że nikt tego nie robi. Hook przekształca to z “rzeczy, którą zespół ma” w “rzecz, której zespół używa, nawet o tym nie myśląc”.

Skille, które powinny być regułami. Krótka reguła “używaj podwójnych cudzysłowów w JSON” należy do .claude/rules/style.md, nie do osobnego skilla. Skille są do proceduralnej, wielokrokowej wiedzy “jak robimy X”. Reguły są do zawsze-aktywnych konwencji. Mieszanie rozdyma powierzchnię discovery.

Skille zależne od lokalnego stanu. Skill mówiący “najpierw zrób cd do monorepo” jest kruchy. Skill odpalający git rev-parse --show-toplevel i działający z dowolnego miejsca jest odporny. Pisz skille tak, jakby miały odpalać się na świeżo onboardowanej maszynie — z SessionStart hookiem często będą.

Osobiste skille pomieszane z firmowymi. Developerzy piszą też swoje (~/.claude/skills/<my-skill>/). Trzymaj symlinki firmowego repo w namespace (np. ~/.claude/skills/acme-<name>/), żeby osobisty eksperyment nigdy nie nadpisał firmowego skilla i odwrotnie.

Pozwalanie repo na rozrost. 200 skillsów jest gorsze od 20. Większość nie będzie używana; te, które będą — będą zakopane. Ustaw kwartalny cull jako prawdziwe wydarzenie w kalendarzu. Skille, które się nie załadowały przez dwa kwartały, idą do archiwum (do skills/.archive/, nie kasowane).

Jak zweryfikować, że jesteś na poziomie

Dalsza lektura

Q5 · Wspólne reguły agenta Companion do skillsów — managed CLAUDE.md policy + per-repo rules w całej organizacji.

Q18 · Governance hooków Ten sam playbook zastosowany do hooków: repo + auto-install + podpisane scripty.

Q19 · Czas onboardingu Skills to jedna z sześciu rzeczy, które sub-day onboarding script auto-instaluje.

Zrób CTO Scorecard 25 pytań, ~12 minut. Ocena tier + plan 30/60/90 + risk register.