Skill to nie jeden plik. To folder, repo i kultura zespołu.

Co kilka tygodni ktoś pyta mnie: „mamy gotowy bash skrypt, który robi X — czy to już skill?”. Nie jest. To skrypt. Skill, w sensie w jakim używają tego pojęcia Claude Code, Cursor i pochodne, to coś więcej — to katalog, w którym żyje skrypt, dokumentacja kiedy go uruchamiać, przykłady, czasem testy oraz manifest, dzięki któremu asystent AI sam znajduje skill w odpowiednim momencie.

Ta różnica nie jest semantyczna. Jeśli traktujesz skill jak gist, dostajesz wąski, kruchy kawałek automatyzacji — który jutro odpali junior, ale za pół roku już nikt. Jeśli traktujesz skill jak mały moduł — dostajesz wielokrotnie używaną dźwignię, którą da się recenzować, ulepszać i dzielić.

Anatomia skilla, który nie zawodzi

Minimalny przyzwoity skill to mniej-więcej tyle:

my-skill/
├── SKILL.md            # manifest + opis "kiedy używać" + instrukcje dla AI
├── scripts/
│   ├── run.sh          # główne wejście
│   └── helpers.py      # to, co trzeba odpalić bezpośrednio
├── references/
│   └── docs.md         # dokumentacja narzędzi zewnętrznych, na które wołamy
├── examples/
│   └── invoice.json    # realne przykłady wejścia/wyjścia
└── tests/
    └── smoke.sh        # 1–2 sanity testy, które ktoś za rok odpali

SKILL.md to serce. Tam zaczyna asystent: opis, kiedy skill jest właściwy (i kiedy NIE jest), jakie pliki są w środku, jak je wywołać. Bez tego AI nie wie, czy ma sięgać po Twój skill, czy improwizować — improwizacja zwykle wygrywa, a Twój skrypt nigdy się nie uruchomi.

scripts/ to wszystko, co rzeczywiście coś robi — bash, Python, Node, mieszane. Nie hostuj jednego mega-pliku. Rozbij na wywoływalne kawałki, dodaj --help, dodaj komentarze nad funkcjami. Asystent AI traktuje Twój kod jak czytelnik — im czytelniej, tym lepsze decyzje podejmie.

references/ to gotowe odpowiedzi dla asystenta na pytania, których nie chcesz, żeby zadawał użytkownikowi. „Czy ten endpoint wymaga Authorization: Bearer?”. „Jak wygląda format daty w odpowiedzi?”. Spisz to raz, AI nie zgaduje.

examples/ to disambiguator. Pokazujesz jak wygląda dobry input i dobry output. Jeden konkretny przykład wart jest pięciu paragrafów dokumentacji.

tests/ to siatka bezpieczeństwa. Nie potrzebujesz unit-test framework. Wystarczy smoke.sh, który odpala skill na przykładzie z examples/ i porównuje z oczekiwanym wyjściem. Po pół roku jak ktoś z biura zmieni API, ten test zaświeci na czerwono i skill da się naprawić.

Wersjonowanie i semver

Skill ewoluuje. Jeśli zmieniasz wejście, którego inne skille albo agenty oczekują w określonym kształcie — to breaking change. SKILL.md powinien mieć wersję, np. version: 1.4.0. Patch dla bugfixów, minor dla nowych opcji bez breakage, major dla zmian niekompatybilnych.

To samo, co robisz z każdą biblioteką wewnętrzną. Tu nie ma magii, tylko żelazna dyscyplina.

Firmowe repo skilli

Najczęstszy błąd: każdy zespół ma swoje skille w prywatnych folderach na laptopach. Wiedza zostaje u jednej osoby. Ktoś odchodzi — skill znika.

Rozwiązanie:

• Jedno repo typu internal-skills/ (GitHub / GitLab / wewnętrzny Gitea, obojętne).
• Po jednym katalogu na skill w korzeniu repo (internal-skills/extract-invoice/, internal-skills/run-jira-report/).
• PR-based contribution — nowy skill albo zmiana = PR, code review jak przy normalnym kodzie. Recenzent sprawdza SKILL.md, examples i smoke testy.
• CODEOWNERS — każdy skill ma właściciela (osoba lub team). Bez właściciela skill jest „bezdomny” i pierwszą rzeczą, która rdzewieje.
• CI odpalający tests/smoke.sh na każdy PR. Nawet 30 sekund testu chroni przed regresją.
• Changelog per skill — krótki CHANGELOG.md w katalogu skilla. Co się zmieniło, kiedy, dlaczego.

W większej firmie warto dorzucić per-domena katalogi: internal-skills/finance/, internal-skills/devops/, internal-skills/customer-support/. Łatwiej znaleźć, łatwiej zarządzać własnościami.

Dlaczego to się opłaca

• Mnożnik produktywności, nie sumator. Jeden senior, który pisze dobry skill raz, daje wszystkim juniorom tę samą dźwignię na zawsze.
• Onboarding nowych — nowa osoba wchodzi do internal-skills/ i widzi, co firma faktycznie automatyzuje. Mapa kompetencji w jednym miejscu.
• Audytowalność — w branżach regulowanych łatwiej wytłumaczyć compliance, że automatyzacja AI jest wersjonowana, recenzowana i testowana niż że „każdy ma swoją magiczną komendę w README”.
• Migracja narzędzi — gdy firma przeskakuje z Cursor na Claude Code (albo odwrotnie), 90% logiki zostaje w skillach, zmienia się tylko warstwa adaptera.

Anty-wzorce, których spotykam najczęściej

1. „Skill = jeden bash plik” — patrz wstęp. Dorzuć katalog z SKILL.md, examples i smoke test. Cała robota: 30 minut.
2. „Skill bez SKILL.md” — AI nie wie, kiedy go używać. Skutek: skill istnieje, ale nigdy się nie uruchamia.
3. „Skill bez przykładów” — asystent halucynuje wejście. Wynik: błędne wywołania, frustracja, użytkownik wraca do pisania ręcznie.
4. „Skill, którego nikt nie testował od roku” — narzędzie zewnętrzne zmienia API, skill cicho się sypie. Pojawia się dopiero, gdy ktoś nieznajomy spróbuje go odpalić w stresie.
5. „Repo skilli bez właściciela” — wszystko marnieje równo. Powierz każdy katalog konkretnej osobie i wymień to w CODEOWNERS.

Jak zacząć w swoim zespole

W tym tygodniu:

1. Wybierz jedną rzecz, którą zespół powtarza co tydzień. Skill kandydat numer jeden.
2. Stwórz repo internal-skills/, w nim katalog dla tego skilla.
3. Napisz SKILL.md w 15 linijkach: kiedy używać (1 zdanie), jak działa (3 zdania), jak wywołać (1 komenda).
4. Wrzuć skrypt, który już masz, do scripts/.
5. Dodaj jeden examples/input.json i tests/smoke.sh, który go odpala.

Pierwszy skill firmy. Drugi pójdzie szybciej — zespół zobaczy wzorzec.

---

Pracujesz nad wdrożeniem AI w organizacji i zastanawiasz się, jak ułożyć tę warstwę z głową? Porozmawiajmy.