Codee Skills: własne repozytorium dla AI Skills

Pracując w projektach z pomocą AI zauważyłem dwa realne problemy. Pierwszy to bezpieczeństwo. Nie chcę i nie będę kopiował do projektu "skilli", których nie sprawdziłem, ściąganych z przypadkowych repozytoriów, co do których nie mam pewności. Drugi to aktualizacje. Kiedy buduję własne skille, chcę je sprawnie aktualizować w jednym miejscu. Nie kopiować ich tam i z powrotem za każdym razem, gdy zmieniłem jedno słowo albo dopisałem dwa zdania.

Z tych dwóch potrzeb powstało narzędzie, które opisuję w tym wpisie. Napisałem własne CLI i własne repozytorium skilli, żeby trzymać je w jednym, zaufanym miejscu i instalować do projektu jednym poleceniem. Działa z Claude Code i z Codex.

Z tego wpisu dowiesz się:

1. Dlaczego kopiowanie skilli między projektami się nie sprawdza
2. Czym jest repozytorium Codee Skills i jak jest zbudowane
3. Co dają globalne skille, niezależnie od frameworka
4. Jak wygląda praca z CLI ags na co dzień

Problem: agent zaczyna od zera w każdym projekcie

Agent AI nie pamięta Twoich konwencji. W każdym nowym projekcie startuje bez wiedzy o tym, jak piszesz kod, jak nazywasz pliki, jak formułujesz teksty interfejsu czy specyfikacje. Naturalny odruch to przekleić mu instrukcje do katalogu .claude/ albo innych folderów, w zależności od wybranego narzędzia, i działać dalej.

To podejście psuje się na dwa sposoby.

Pierwszy to zaufanie. W internecie jest pełno gotowych skilli, ale skill to instrukcja, którą agent wykonuje na Twoim kodzie i w Twoim środowisku. Wklejenie czegoś, czego nie przeczytałeś linijka po linijce, jest dokładnie tym samym ryzykiem, co uruchomienie cudzego skryptu bez sprawdzenia. Dlatego u mnie do projektu trafiają tylko skille, które sam napisałem albo zweryfikowałem.

Drugi to utrzymanie. Kiedy podczas pracy zauważam, że skill warto poprawić, dopisać regułę albo doprecyzować przykład, ta zmiana powstaje w jednym projekcie i reszta projektów o niej nie wie. Po kilku tygodniach mam pięć wersji tego samego skilla, każda trochę inna, i żadnej pewności, która jest aktualna. Kopiowanie plików ręcznie nie skaluje się przy zmianie jednego słowa.

Czym jest Codee Skills

Codee Skills to repozytorium AI Skills. Jedno miejsce, w którym trzymam wszystkie skille, i z którego instaluję je do konkretnych projektów. Repozytorium jest źródłem prawdy. Kopia w projekcie zawsze pochodzi stąd i stąd jest aktualizowana.

Skille dzielą się na dwie grupy:

codee-skills/
  general/                     # skille niezależne od stacku
    code-style/
    project-organization/
    skill-creator/
    spec-writing/
    ui-copy/
    writing-questions/
  frameworks/                  # skille pod konkretne technologie
    medusa/
    payload/

general/ - przydają się w każdym projekcie, niezależnie od technologii.

frameworks/ - to wiedza specyficzna dla konkretnego narzędzia, na przykład konwencje Payload albo Medusa.js.

Każdy skill to zwykły katalog z plikiem SKILL.md. Jedna ważna zasada: skille muszą być prawdziwymi katalogami, nie symlinkami, bo narzędzie instalujące je pomija.

Instalacja zawsze trafia do dwóch lokalizacji naraz: .claude/skills/ dla Claude Code i .agents/skills/ dla Codex. Dzięki temu nie obchodzi mnie, którego agenta akurat używam w danym projekcie. Oba widzą te same, aktualne skille.

Globalne skille, czyli co działa w każdym projekcie

Najwięcej wartości na co dzień dają mi skille z general/, bo nie są przypisane do żadnej technologii.
Na ten moment mam dodane kilka moich skilli, z których korzystam codziennie:

• code-style - pomaga w analize kodu czyli kiedy komentować, jak nazywać, jak organizować pliki. Agent przestaje zgadywać mój styl i od razu pisze tak, jak piszę ja.
• spec-writing - pomaga przy tworzeniu specyfikacji dla konkretnego modułu czy funkcjonalności. Najpierw szkielet i lista otwartych pytań, które trzeba domknąć, zanim powstanie reszta dokumentu. Dopiero potem architektura i rozbicie pracy na małe, testowalne kroki. Dopiero gdy skończymy pracę nad specyfikacją, to zaczynamy wdrożenie. Ważne są tutaj umiejętności techniczne, ponieważ ten skill pomaga zbudować taką specyfikację, ale to jak chcemy to zbudować, w jakim kierunku, decyduje już autor.
• ui-copy - reguły pisania tekstów interfejsu: etykiet, nagłówków, komunikatów błędów, pustych stanów. Spójny język bez tłumaczenia tego za każdym razem.
• writing-questions - to format zadawania pytań. Krótko, w pierwszej osobie.
• project-organization - generuje dokument PROJECT-ORGANIZATION.md dla nowego projektu: zespół, narzędzia, workflow, sprinty.
• skill-creator - pomaga zbudować nowy skill z gotowego szkieletu, żeby każdy kolejny powstawał w tej samej strukturze.

To jest sedno pomysłu. Raz spisana wiedza o tym, jak pracujemy, jest dostępna w każdym projekcie i dla każdego agenta, zamiast siedzieć w głowie jednej osoby albo w jednym repozytorium.

Jak to działa w praktyce: CLI ags

Do zarządzania skillami napisałem małe CLI. Pod spodem instalacją zajmuje się npx skills od Vercel Labs. Nie przepisywałem tego, co już działa. Moje ags opakowuje to narzędzie tak, żeby pasowało do jednego repozytorium i dwóch agentów naraz. Dokładam trzy rzeczy:

• Samo znajduje źródło. Nie podaję ścieżki do repozytorium przy każdej komendzie, bo ags odczytuje ją z własnej lokalizacji.
• Instaluje od razu dla obu agentów. Każda instalacja leci z flagami dla Claude Code i Codex w trybie kopii, więc skille trafiają jako prawdziwe katalogi do .claude/skills/ i .agents/skills/. Nie jestem przywiązany do tych dwóch. npx skills obsługuje też inne narzędzia, więc dołożenie kolejnego modelu to tylko jedna flaga i kolejna lokalizacja, do której trafia ten sam skill.
• Wybór czyta opisy skilli. Lista z ags skills add grupuje skille po folderach i pokazuje opis z SKILL.md, więc wybierasz świadomie, a nie po samej nazwie.

Komendy w pigułce

Nie wszystkie komendy są tak samo „moje". Część to cienkie przekazanie do npx skills, część dokłada logikę, a dwie nie dotykają npx w ogóle.

Repozytorium nie musi być moje. ags skills add przyjmuje też adres URL, więc skille można pobrać wprost z cudzego repozytorium na GitHubie. Twórcy frameworków robią to już oficjalnie: Payload i Medusa.js utrzymują własne zestawy skilli, które podpinasz jednym poleceniem i aktualizujesz tak samo jak własne. Z jednym zastrzeżeniem spójnym z tym, od czego zacząłem: zewnętrzny skill najpierw czytam, a dopiero potem dodaję. push-skill zostaje wtedy poza grą, bo zwrot zmian działa tylko dla repozytoriów, które mam u siebie lokalnie.

Jak zacząć w 3 krokach

Najpierw klonujesz swoje (albo moje) repozytorium:

git clone git@github.com:codee-sh/codee-skills.git

Potem dodajesz alias do ~/.zshrc, podmieniając ścieżkę na tę, gdzie sklonowałeś repozytorium:

echo 'alias ags="node /path/to/codee-skills/bin/codee-skills.js"' >> ~/.zshrc
source ~/.zshrc

Później, w katalogu projektu instalujesz skille:

ags skills add

To wszystko. ags skills add bez argumentu otwiera interaktywny wybór, w którym zaznaczasz pojedyncze skille albo cały podfolder. Możesz też podać nazwę wprost:

ags skills add code-style           # jeden skill
ags skills add frameworks/payload   # cały podfolder

Po instalacji w projekcie pojawia się plik skills-lock.json, który zapisuje źródło każdego skilla. Dzięki temu wiadomo, skąd dany skill pochodzi i kiedy był pobierany.

Aktualizacje bez kopiowania

Tu rozwiązuje się mój drugi problem. Zamiast ręcznie przeklejać pliki, uruchamiam:

ags skills update           # sprawdza wszystkie skille
ags skills update code-style   # albo jeden konkretny

Polecenie najpierw robi git pull w repozytorium źródłowym, więc zawsze porównuje projekt z najnowszą wersją z GitHuba. Jeśli któraś z lokalizacji jest nieaktualna, instaluje skill na nowo.

Praca zespołowa: push-skill

Aktualizacje działają w drugą stronę. Kiedy poprawię skill bezpośrednio w projekcie, chcę oddać tę zmianę do repozytorium, żeby reszta projektów ją dostała. Od tego jest push-skill:

ags push-skill                  # pokazuje zmienione skille
ags push-skill code-style       # konkretny skill
ags push-skill code-style --dry-run   # podgląd bez zapisu

Polecenie skanuje lokalne skille, pokazuje, które się zmieniły, sprawdza, czy w repozytorium nie ma nowszych zmian, wyświetla różnicę i prosi o potwierdzenie. Dopiero wtedy robi commit i push. Na końcu synchronizuje kopię dla drugiego agenta, więc .claude/skills/ i .agents/skills/ nie rozjeżdżają się ze sobą.

W praktyce wygląda to tak: poprawiam skill w projekcie, w którym akurat pracuję, robię ags push-skill, i od tego momentu każdy następny projekt pobiera już nową wersję przez ags skills update. Jedno repozytorium, jedna aktualna wersja, niezależnie od tego, ilu osób i projektów dotyczy.

Dobre praktyki

Kilka rzeczy, które ułatwiają życie przy tym podejściu:

• Skille jako prawdziwe katalogi. Symlinki są pomijane przez narzędzie instalujące, więc każdy skill musi być fizycznym folderem z plikiem SKILL.md.
• Jeden skill, jedna odpowiedzialność. Lepiej mieć osobno code-style i ui-copy niż jeden wielki skill o wszystkim. Granularne skille łatwiej aktualizować i wybierać do projektu.
• Świadomy podział na general i frameworks. Jeśli wiedza działa niezależnie od technologii, jej miejsce jest w general. Jeśli dotyczy konkretnego narzędzia, trafia do frameworks.

Podsumowując

Codee Skills rozwiązuje dwa konkretne problemy, które miałem przy pracy z agentami AI. Bezpieczeństwo, bo do projektu trafiają wyłącznie skille, które sam sprawdziłem oraz utrzymanie, bo aktualizacja w jedną i drugą stronę to jedno polecenie zamiast ręcznego kopiowania. Wartość rośnie z każdym kolejnym projektem, w którym te same, sprawdzone skille są od razu dostępne.

To podejście będzie miało sens dla Ciebie, jeśli pracujesz z Claude Code, Codeksem albo innym narzędziem, w więcej niż jednym projekcie i masz dość przeklejania tych samych instrukcji.

W kolejnym wpisie pokażę drugą stronę tego rozwiązania czyli skille frameworkowe. Przykładem będą Payload CMS i Medusa.js, czyli dwie technologie w których pracuję obecnie na co dzień.