Praktyczny workflow dla developerów: Współdzielenie Skills i Agents między Codex, Claude Code i innymi narzędziami AI.

Coraz więcej developerów używa lokalnych agentów AI takich jak Codex, Claude Code czy OpenCode. Początkowo wszystko wygląda prosto, jednak problem pojawia się bardzo szybko, gdy zaczynamy budować własne Skills, role agentów i instrukcje projektowe.

W praktyce każde narzędzie chce przechowywać konfigurację w trochę innym miejscu. W efekcie developerzy zaczynają kopiować te same pliki między katalogami, utrzymywać kilka wersji tych samych promptów albo trzymać konfigurację w katalogu domowym użytkownika.

Dlatego w tym poradniku pokażę prosty i bardzo praktyczny wzorzec organizacji katalogów, dzięki któremu możesz współdzielić Skills między różnymi narzędziami AI bez kopiowania plików i bez trzymania konfiguracji w katalogu domowym użytkownika.

Jeżeli pracujesz z narzędziami typu Codex, Claude Code albo innymi agentami AI uruchamianymi z terminala, to bardzo szybko pojawia się praktyczny problem:

Współdzielenie Skills i Agents – Gdzie trzymać własne instrukcje, skille i role agentów, żeby nie kopiować ich między narzędziami?

Najprostszy i jednocześnie najbardziej praktyczny wzorzec wygląda tak:

• trzymasz źródło prawdy w katalogu ai/,
• wystawiasz je Codexowi przez lokalny katalog .agents/,
• wystawiasz je Claude Code przez lokalny katalog .claude/,
• wszystko jest zapisane w projekcie, a nie w katalogu domowym użytkownika.

Dzięki temu konfiguracja jest:

• przenośna,
• czytelna,
• wersjonowana w Git,
• współdzielona przez cały zespół,
• niezależna od lokalnego środowiska programisty.

Docelowa struktura współdzielenia Skills i Agents

Chcemy uzyskać taki układ:

my-project/
├── ai/
│   ├── agents/
│   │   ├── architect.md
│   │   ├── incident-commander.md
│   │   └── reviewer.md
│   └── skills/
│       ├── api-review/
│       │   └── SKILL.md
│       ├── frontend-qa/
│       │   └── SKILL.md
│       └── security-check/
│           └── SKILL.md
├── .agents/
│   ├── agents -> ../ai/agents
│   └── skills -> ../ai/skills
└── .claude/
    ├── agents -> ../ai/agents
    └── skills -> ../ai/skills

Katalog ai/ zawiera prawdziwe pliki.

Katalogi .agents/ i .claude/ zawierają jedynie symlinki, czyli techniczne wskaźniki do tych samych plików.

W praktyce oznacza to, że ten sam skill, np.:

ai/skills/security-check/SKILL.md

może być widoczny jednocześnie dla Codexa i Claude Code.

Krok 1: utwórz katalog ai

Wejdź do katalogu projektu:

cd /sciezka/do/my-project

mkdir -p ai/agents
mkdir -p ai/skills

ai/
├── agents/
└── skills/

touch ai/agents/architect.md

# Architect

Jesteś software architectem w tym projekcie.

Twoje zadania:

- oceniasz decyzje architektoniczne,
- wskazujesz ryzyka techniczne,
- proponujesz proste rozwiązania zamiast nadmiarowych abstrakcji,
- dbasz o granice modułów, kontrakty API i utrzymywalność kodu.

Zanim zaproponujesz zmianę, sprawdź istniejące wzorce w repozytorium.
Nie wprowadzaj nowych frameworków ani dużych refaktorów bez wyraźnego powodu.

touch ai/agents/reviewer.md

# Reviewer

Jesteś seniorem robiącym code review.

Priorytety:

- błędy logiczne,
- regresje,
- problemy bezpieczeństwa,
- brakujące testy,
- niezgodność ze stylem projektu,
- niepotrzebna złożoność.

Odpowiadaj jak w prawdziwym code review:
najpierw konkretne problemy, potem krótkie uzasadnienie i sugestia poprawki.

touch ai/agents/incident-commander.md

# Incident Commander

Jesteś incident commanderem dla systemów produkcyjnych.

Pomagasz w:

- triage awarii,
- ustalaniu wpływu na użytkowników,
- analizie logów i metryk,
- formułowaniu hipotez,
- planowaniu rollbacku albo hotfixa,
- pisaniu krótkiego postmortem.

Najpierw stabilizuj system.
Dopiero potem szukaj pełnej przyczyny źródłowej.

mkdir -p ai/skills/api-review
touch ai/skills/api-review/SKILL.md

# API Review

Używaj tego skilla, gdy oceniasz endpointy REST, GraphQL albo kontrakty między usługami.

Sprawdź:

- czy nazwy endpointów i pól są spójne,
- czy statusy HTTP są poprawne,
- czy błędy mają stabilny format,
- czy API jest kompatybilne wstecznie,
- czy paginacja, filtrowanie i sortowanie są przewidywalne,
- czy dane wrażliwe nie wyciekają w odpowiedziach,
- czy kontrakt da się łatwo testować.

W odpowiedzi podaj konkretne ryzyka i przykładowe poprawki.

mkdir -p ai/skills/security-check
touch ai/skills/security-check/SKILL.md

# Security Check

Używaj tego skilla przy zmianach związanych z autoryzacją, logowaniem,
danymi użytkownika, integracjami zewnętrznymi i konfiguracją infrastruktury.

Sprawdź:

- brakujące kontrole uprawnień,
- możliwość IDOR,
- niebezpieczne logowanie sekretów,
- zbyt szerokie tokeny lub scope'y,
- podatności na injection,
- brak walidacji danych wejściowych,
- problemy z konfiguracją CORS,
- ryzyka przy webhookach i callbackach.

Nie ograniczaj się do ogólnych porad.
Odnoś się do konkretnych plików, funkcji i przepływów danych.

Skill: Frontend QA

mkdir -p ai/skills/frontend-qa
touch ai/skills/frontend-qa/SKILL.md

Przykładowa zawartość:

# Frontend QA

Używaj tego skilla przy sprawdzaniu interfejsu użytkownika.

Sprawdź:

- responsywność na mobile i desktopie,
- czy tekst nie wychodzi poza przyciski i karty,
- czy stany loading, empty, error i success są obsłużone,
- czy formularze mają walidację i czytelne komunikaty,
- czy elementy interaktywne są dostępne z klawiatury,
- czy hierarchia wizualna pasuje do funkcji ekranu,
- czy UI nie wygląda jak przypadkowy landing page,
  gdy powinien być narzędziem pracy.

Jeżeli projekt ma istniejący design system,
trzymaj się jego wzorców.

Chcesz więcej takich workflowów AI dla developerów?

Pobrałem i opisałem praktyczne wzorce pracy z agentami AI, Claude Code, Codexem i automatyzacją developmentu w darmowym poradniku: https://ewolucjadevelopera.pl/poradnik/

Krok 4: utwórz lokalne katalogi dla narzędzi

Teraz tworzymy lokalne katalogi, z których mogą korzystać narzędzia uruchamiane w projekcie.

Dla Codexa:

mkdir -p .agents

Dla Claude Code:

mkdir -p .claude

To nadal są katalogi lokalne w projekcie.

Nie konfigurujemy niczego w:

~/.claude
~/.codex

ani innych katalogach domowych użytkownika.

Krok 5: dodaj symlinki dla Codexa

Podepnij ai/agents i ai/skills do .agents:

ln -sfn ../ai/agents .agents/agents
ln -sfn ../ai/skills .agents/skills

Co oznaczają te flagi?

• ln — tworzy link,
• -s — tworzy symlink,
• -f — nadpisuje istniejący link,
• -n — traktuje istniejący symlink jak plik.

Po tym kroku:

.agents/agents -> ../ai/agents
.agents/skills -> ../ai/skills

Krok 6: dodaj symlinki dla Claude Code

Claude Code potrafi korzystać z lokalnego katalogu .claude w projekcie.

Podpinamy do niego te same katalogi źródłowe:

ln -sfn ../ai/agents .claude/agents
ln -sfn ../ai/skills .claude/skills

Po tym kroku Claude Code widzi dokładnie te same agenty i skille, które widzi Codex.

Nie kopiujemy plików.

Oba narzędzia wskazują na to samo źródło:

ai/agents
ai/skills

Krok 7: sprawdź konfigurację Codexa

Uruchom:

ls -la .agents

Powinieneś zobaczyć:

agents -> ../ai/agents
skills -> ../ai/skills

Sprawdź też zawartość:

ls .agents/agents
ls .agents/skills

Krok 8: sprawdź konfigurację Claude Code

Uruchom:

ls -la .claude

Powinieneś zobaczyć:

agents -> ../ai/agents
skills -> ../ai/skills

Sprawdź zawartość:

ls .claude/agents
ls .claude/skills

Wynik powinien być taki sam jak dla:

ls .agents/agents
ls .agents/skills

To jest sedno całego wzorca:

• Codex i Claude Code mają osobne katalogi wejściowe,
• ale realnie czytają te same pliki.

A co z Windowsem?

Na Windowsie również można używać symlinków.

W PowerShell:

New-Item -ItemType SymbolicLink -Path ".agents\agents" -Target "..\ai\agents"
New-Item -ItemType SymbolicLink -Path ".agents\skills" -Target "..\ai\skills"

New-Item -ItemType SymbolicLink -Path ".claude\agents" -Target "..\ai\agents"
New-Item -ItemType SymbolicLink -Path ".claude\skills" -Target "..\ai\skills"

W części konfiguracji może być wymagane:

• uruchomienie terminala jako Administrator,
• albo włączenie Developer Mode w Windows.

Dlaczego taki układ ma sens?

Ten wzorzec ma kilka bardzo praktycznych zalet.

1. ai/ staje się źródłem prawdy

Każdy w projekcie wie, gdzie znajdują się:

• role agentów,
• instrukcje,
• skille,
• workflowy AI.

2. Narzędzia dostają warstwę kompatybilności

Codex może czytać z:

.agents/

Claude Code może czytać z:

.claude/

Ale oba katalogi wskazują na to samo źródło.

3. Wszystko jest lokalne dla projektu

Nie trzeba zakładać, że każdy developer ma identycznie skonfigurowany katalog domowy.

Repozytorium zawiera pełną konfigurację pracy z AI.

4. Można to normalnie wersjonować w Git

Agenty i skille stają się częścią projektu:

• reviewowane,
• rozwijane,
• dokumentowane,
• utrzymywane przez zespół.

Dokładnie tak samo jak dokumentacja techniczna czy tooling developerski.

Co commitować do Gita?

Najczęściej warto commitować:

ai/agents/
ai/skills/
.agents/
.claude/

Git normalnie obsługuje symlinki.

Po sklonowaniu repozytorium na macOS albo Linuksie wszystko powinno działać od razu.

Warto tylko upewnić się, że .gitignore nie wyklucza .agents ani .claude.

Sprawdź:

cat .gitignore

Jeżeli .agents jest ignorowane:

!.agents/
!.agents/agents
!.agents/skills

!.claude/
!.claude/agents
!.claude/skills

Jeżeli w .claude trzymasz też lokalne ustawienia prywatne, np.:

settings.local.json

to nie commituj ich automatycznie.

Wtedy możesz zostawić:

.claude/*
!.claude/
!.claude/agents
!.claude/skills

Współdzielenie Skills i Agents – Najważniejsza zasada

Edytuj prawdziwe pliki tutaj:

ai/agents
ai/skills

Katalogi .agents i .claude traktuj wyłącznie jako techniczne wejścia dla narzędzi.

W praktyce oznacza to prosty podział:

• ai/ — miejsce, gdzie zespół utrzymuje instrukcje,
• .agents/ — sposób, w jaki znajduje je Codex,
• .claude/ — sposób, w jaki znajduje je Claude Code.

Jak to wygląda w praktyce? Przykład z produkcji

Tomasz Kowalski z firmy Sembot opisał dokładnie ten wzorzec w praktyce:

„Podeszliśmy do tego z perspektywy: rozbijmy ten kod na kawałeczki, czyli weryfikujmy to pod względem różnych kryteriów, wykorzystując LLMa do tego, żeby ten kod zweryfikować. Napisaliśmy sobie skille pod różne weryfikatory — spójności kodu, design systemu, podatności zero day, poprawności formularzy. Tych weryfikatorów mamy 18. Jeżeli jakikolwiek weryfikator coś znajdzie, zakłada w Gicie komentarz, opisuje problem — tak jak normalny developer.”

Podcast z Tomaszem: https://www.youtube.com/watch?v=8T-nfyxu7g4&t=1s

Podsumowanie

Jeżeli pracujesz z więcej niż jednym agentem AI, bardzo szybko pojawia się problem duplikowania promptów, skillów i instrukcji projektowych.

Trzymanie wszystkiego w:

ai/

i wystawianie tego przez symlinki do:

.agents/
.claude/

daje prosty, przenośny i zespołowy workflow.

To mały detal organizacyjny, ale w praktyce bardzo szybko porządkuje pracę z AI w realnych projektach developerskich.