# Jak pisać i testować wzorce dla SKILL.md: kompletny przewodnik inżynierski

> Profesjonalny przewodnik po tworzeniu umiejętności (skills) dla agentów AI: 4 obowiązkowe sekcje w SKILL.md, synchronizacja Codex i Claude Code, wzorce kompozycji, 5 obowiązkowych testów oraz ochrona przed regresjami.

## 1. Architektura i obowiązkowe sekcje pliku SKILL.md

Plik **SKILL.md** to narzędzie inżynierskie, które przekształca uniwersalny model językowy w wyspecjalizowanego inżyniera zdolnego do wykonania jednego, ściśle zdefiniowanego typu zadań. Nie dubluje on globalnych invariantów projektu, lecz dodaje do nich wąskie, wysoko specyficzne wiedzę proceduralną.

Zanim utworzysz skill dla własnego repozytorium, koniecznie zapoznaj się z ogólnym plikiem konfiguracyjnym reguł projektu (`AGENTS.md` lub `CLAUDE.md`). Te dokumenty systemowe są absolutnym źródłem prawdy dla krytycznych zasad bezpieczeństwa oraz komend budowania. Zadaniem samego Skilla jest nauczenie agenta struktury i kolejności kroków poprzez odwoływanie się do reguł systemowych, a nie kopiowanie ich.

```mermaid
flowchart TD
    subgraph Structure ["Чотири обов'язкові компоненти якісного SKILL.md"]
        F["1. Description у Frontmatter<br><i>(Формулюється строго як УМОВА, а не тема)</i>"]
        T["2. When to Trigger<br><i>(Точні контекстні критерії та ключові слова)</i>"]
        P["3. Procedure<br><i>(Нумеровані кроки з реальними командами й шляхами)</i>"]
        Pit["4. Pitfalls & Anti-Patterns<br><i>(Дія + Наслідок + Точне виправлення)</i>"]
    end

    F --> T --> P --> Pit
```

### Szczegółowa analiza obowiązkowych sekcji

1. **Description we Frontmatter:** Jedyny blok tekstu, który agent odczytuje przed podjęciem decyzji o załadowaniu skilla. Należy go formułować jako predykatowy warunek aktywacji („Użyj, gdy...”), a nie abstrakcyjną nazwę tematu.
2. **When to trigger (Kiedy aktywować):** Rozbudowana lista bezpośrednich zapytań, błędów w logach lub operacji w git, przy których skill musi zostać uruchomiony.
3. **Procedure (Procedura regulaminowa):** Numerowany algorytm działań z dokładnymi nazwami lokalnych komend i zwalidowanymi ścieżkami do plików.
4. **Pitfalls (Pułapki):** Katalog zarejestrowanych w przeszłości awarii. Każdy wpis konstruowany jest według wzorca: *Konkretna błędna czynność* → *Dokładna awaria techniczna* → *Przepis na naprawę*.

> [!NOTE]
> Jeśli skill kończy się procedurą release’u lub deployu, nie dubluj samego pipeline’u wewnątrz skilla. Zamiast tego zakończ algorytm wskazówką: „Uruchom skill ship-pipeline”.

---

## 2. Struktura rozmieszczenia: synchronizacja między Codex a Claude Code

W nowoczesnych procesach roboczych deweloperzy często korzystają jednocześnie z kilku klientów (np. **OpenAI Codex** w terminalu lub IDE oraz **Claude Code**). Oba runtime’y wspierają otwartą specyfikację skills, ale oczekują ich obecności w różnych katalogach projektu.

![Ścieżki rozmieszczenia plików skills dla runtime’ów Codex i Claude Code](/api/guides-media/ai_agents/testing-and-writing-skill-md-patterns-guide/images/testing-and-writing-skill-md-patterns-guide-extra-01.webp)

### Macierz ścieżek dla runtime’ów

| Runtime / Agent | Docelowa ścieżka pliku SKILL.md | Cechy detekcji |
| :--- | :--- | :--- |
| **OpenAI Codex** | `.agents/skills/<name>/SKILL.md` | Odczytywane przez agenta Codex podczas skanowania lokalnych narzędzi |
| **Anthropic Claude Code** | `.claude/skills/<name>/SKILL.md` | Odczytywane przez Claude Code podczas inicjalizacji środowiska sesji |

> [!IMPORTANT]
> **Wymóg dualnej synchronizacji:** Jeśli skill został dodany tylko w `.claude/skills/`, będzie całkowicie niewidoczny dla agentów Codex i odwrotnie. Zawsze twórz i utrzymuj skill w obu katalogach lub skonfiguruj dowiązania symboliczne (symlinks).

---

## 3. Kryteria gotowości i walidacja szkicu skilla

Zanim przekażesz skill do repozytorium zespołu, oceń go według standaryzowanej inżynierskiej skali jakości:

- **Falsyfikowalność triggera:** Możesz wskazać co najmniej 2 pokrewne zapytania w tej samej dziedzinie, przy których skill **NIE** powinien się uruchamiać.
- **Audyt komend:** Każda wykonywalna komenda w procedurze istnieje w sekcji Local Commands systemowego pliku `AGENTS.md`.
- **Faktograficzne pułapki:** Każdy punkt w sekcji Pitfalls opisuje rzeczywisty incydent z praktyki, a nie ogólne ostrzeżenie typu „bądź ostrożny”.
- **Kompaktowość kontekstu:** Przeczytanie tekstu skilla zajmuje nie więcej niż 2–3 minuty (do 500 linii).
- **Zero duplikacji:** Żaden akapit nie kopiuje ogólnych reguł z `AGENTS.md`.

```mermaid
flowchart LR
    Draft["Чорновий Skill<br><i>(Розмитий опис, копії правил, абстрактні кроки)</i>"] --> Review{"Валідація чернетки"}
    Review -->|Виявлено недоліки| Fix["Виправлення формулювань і команд"]
    Fix --> Review
    Review -->|Всі критерії виконано| Prod["Production-Ready Skill"]
```

---

## 4. Wzorce kompozycji: dyspozytory, referencje i łańcuchy

Rzeczywiste procesy robocze rzadko są izolowane w obrębie jednego pliku. Próba opisanie wszystkiego w jednym monolitycznym `SKILL.md` prowadzi do rozrostu kontekstu i spadku uwagi modelu. Stosuj trzy sprawdzone wzorce architektoniczne:

### Wzorzec 1: Entry Router (Skill-dyspozytor)
Jeden ogólny skill pełni rolę mapy routingu. Analizuje intencję użytkownika i deleguje zadanie wyspecjalizowanym sub-skills:

```text
Zapytanie: „Zoptymalizuj wydajność zapytań do bazy danych”
  └── db-router (Entry Router)
        ├── Kieruje do: neon-migrations (jeśli wymagane są zmiany struktury)
        └── Kieruje do: drizzle-index-optimizer (jeśli wymagane są indeksy)
```

### Wzorzec 2: Pliki Reference
Główny plik `SKILL.md` zawiera jedynie wysokopoziomowy algorytm, a złożone szczegóły, tabele i gramatyki przenoszone są do katalogu `references/`:

```text
.claude/skills/fleet-coordinator/
├── SKILL.md                   # Krótki pipeline orkiestracji
└── references/
    ├── agent-roles.md         # Opis specjalizacji i macierz ról
    └── file-ownership.md      # Zasady zapobiegania konfliktom przy zapisie
```

### Wzorzec 3: Skill Chain (Łańcuch skills)
Skills odnoszą się do siebie nawzajem jako do następnego logicznego etapu poprzez pole `relatedPaths` lub dyrektywę tekstową:

```markdown
> Po pomyślnym przejściu walidacji schematu bezwzględnie uruchom umiejętność drizzle-migration-runner.
```

---

## 5. Strategie refaktoryzacji: kiedy dzielić, a kiedy łączyć skills

Wybór między podziałem a konsolidacją skills determinuje stabilność Twojego systemu automatyzacji.

:::tabs
@tab Dzielenie skilla
- **Różne warunki triggera:** Scenariusze wymagają przeciwnych konfiguracji (np. audyt kodu bez prawa zapisu vs migracja bazy danych z bezpośrednią zmianą schemy).
- **Różne powierzchnie produktu:** Skill próbuje jednocześnie regulować landing page (kod designu, Tailwind) oraz serwer backendowy (NestJS, SQL).
- **Przeciążenie kontekstu:** Objętość tekstu przekracza 500 linii, a agent zaczyna mylić kroki.
@tab Łączenie skills
- **Nierozerwalny związek:** Dwa mikroskille nigdy nie są wywoływane osobno, a wykonanie jednego bez drugiego pozbawione jest praktycznego sensu.
- **Duplikacja kodu:** Podział prowadzi do powielania tego samego bloku walidacji w dwóch plikach.
:::

> [!TIP]
> W 90% przypadków właściwą decyzją jest właśnie **podział**. Próba stworzenia „uniwersalnego skilla dla całego backendu” nieuchronnie zamienia się w nieefektywny monolit z wysokim poziomem halucynacji.

---

## 6. Kontrakt wersjonowania i pipeline budowania flagowych skills

W złożonych bazach kodu skills dzielą się na trzy poziomy technologiczne ze względu na sposób dystrybucji i budowania:

![Macierz budowania i rozmieszczenia różnych typów skills w systemie](/api/guides-media/ai_agents/testing-and-writing-skill-md-patterns-guide/images/testing-and-writing-skill-md-patterns-guide-extra-02.webp)

| Typ skilla | Gdzie edytowany jest kod źródłowy | Pipeline budowania | Przeznaczenie |
| :--- | :--- | :--- | :--- |
| **Skill repozytorium (prywatny)** | `.agents/skills/<name>/SKILL.md` + `.claude/skills/<name>/SKILL.md` | **Nie wymagany** (odczytywany bezpośrednio) | Wewnętrzne zasady zespołu dla bieżącego projektu |
| **Publiczny flagowy (wieloplikowy)** | `skills-source/<slug>/` + metadane w skrypcie generacji | `node scripts/build-flagship-skills.mjs skills-source/` | Kompleksowe rozwiązania modułowe z plikami reference dla marketplace’u |
| **Publiczny jednoplikowy** | `baseSkills` w `lib/library/skills.ts` | **Nie wymagany** | Lekkie podstawowe skills dla katalogu platformy |

> [!WARNING]
> **Zakaz ręcznej edycji wygenerowanych plików:** Nigdy nie edytuj ręcznie skompilowanego pliku flagowego skilla. Wszelkie zmiany wprowadzaj wyłącznie w folderze źródłowym `skills-source/<slug>/` z następczym uruchomieniem skryptu kompilacji.

---

## 7. Metodologia testowania: pięć obowiązkowych kontroli jakości

Napisanie instrukcji to dopiero początek. Aby skill niezawodnie działał w produkcji, musi kolejno przejść 5 etapów testowania:

```mermaid
flowchart TD
    T1["1. Trigger Probe<br><i>(3 позитивні + 2 негативні запити)</i>"] --> T2["2. Procedure Walk-Through<br><i>(Наскрізний запуск на реальному репозиторії)</i>"]
    T2 --> T3["3. Pitfall Audit<br><i>(Перевірка формули: Дія + Збій + Фікс)</i>"]
    T3 --> T4["4. Scope Test<br><i>(Перевірка єдиної відповідальності одним реченням)</i>"]
    T4 --> T5["5. Staleness Check<br><i>(Звірка команд і шляхів з актуальним репозиторієм)</i>"]
    T5 --> Ready["Схвалено до коміту"]
```

### Szczegóły protokołu testowego

1. **Trigger Probe (Sprawdzenie triggera):** Sformułuj 3 zapytania, które powinny aktywować skill, oraz 2 zapytania, które powinny zostać odrzucone. Sprawdź, czy opis we frontmatter wyraźnie rozgranicza te przypadki.
2. **Procedure Walk-Through (Naturalne przejście):** Przeprowadź każdy krok ręcznie na żywym standzie. Jeśli do wykonania kroku zabrakło Ci danych wejściowych – w skillu pominięto ważny warunek.
3. **Pitfall Audit (Audyt awarii):** Upewnij się, że każda opisana pułapka rzeczywiście zdarzyła się w praktyce, a zaproponowany sposób usunięcia jest skuteczny.
4. **Scope Test (Test zakresu):** Sformułuj przeznaczenie skilla jednym prostym zdaniem. Jeśli zdanie wymaga spójnika „a także” – skill należy podzielić na dwie części.
5. **Staleness Check (Kontrola przestarzałości):** Zweryfikuj każdą komendę CLI z bieżącą konfiguracją repozytorium i aktualnymi wersjami zależności.

---

## 8. Anatomia antywzorców: jak odróżnić działający skill od szkicu

Porównanie typowych błędów pozwala szybko przeprowadzić samoaudyt przed zapisaniem skilla.

| Cecha | Szkic (Draft) | Skill gotowy do produkcji (Ready) |
| :--- | :--- | :--- |
| **Sformułowanie triggera** | Opisuje szeroki temat: *„Do pracy z bazą danych”* | Określa dokładny warunek: *„Użyj przy tworzeniu migracji Drizzle”* |
| **Opis kroków** | Rozmyte instrukcje: *„uruchom linter w razie potrzeby”* | Jasne komendy: *„uruchom npm run lint:fix”* |
| **Opis zagrożeń** | Ogólne życzenie: *„bądź ostrożny z plikami”* | Konkretna awaria: *„git add nieistniejącej ścieżki przerwie staging”* |
| **Źródła reguł** | Kopiuje tekst z `AGENTS.md` do swojej zawartości | Zawiera bezpośrednie odwołanie do sekcji w `AGENTS.md` |
| **Synchronizacja** | Utworzono tylko w `.claude/skills/` | Zsynchronizowano w `.agents/` oraz `.claude/` jednocześnie |

---

## 9. Zapobieganie pułapkom: rezygnacja z dublowania AGENTS.md

Najpodstępniejszą pułapką przy rozwoju skills jest dublowanie globalnych invariantów projektu (np. zasady unikania długich myślników, wymogi dotyczące zaokrąglonych rogów w CSS lub zakaz bezpośredniego pusha do main).

```text
Dlaczego duplikacja niszczy system:
1. Inżynier kopiuje regułę z AGENTS.md do treści SKILL.md.
2. Miesiąc później komitet architektoniczny aktualizuje regułę w AGENTS.md.
3. Wewnątrz SKILL.md pozostaje przestarzałe sformułowanie.
4. Agent otrzymuje dwa sprzeczne sygnały systemowe i zaczyna halucynować.
```

### Bezpieczne indeksowanie zmian w Git

Podczas wykonywania procedur commitu wewnątrz skills zawsze stosuj sprawdzenie istnienia ścieżek przed dodaniem do staging:

```bash
# Небезпечно (якщо файл відсутній, вся команда переривається з помилкою):
git add src/generated/schema.ts src/types/db.ts

# Безпечно (додаються лише реально існуючі файли):
[ -e src/generated/schema.ts ] && git add src/generated/schema.ts
[ -e src/types/db.ts ] && git add src/types/db.ts
```

---

## 10. Podsumowujący checklist gotowości do produkcji

Przed zatwierdzeniem utworzonego skilla w Git zweryfikuj wykonanie każdego punktu:

- [ ] Skill jest zsynchronizowany w obu katalogach: `.agents/skills/<name>/SKILL.md` oraz `.claude/skills/<name>/SKILL.md`.
- [ ] Pole `description` zaczyna się od słów „Użyj, gdy...” i definiuje jasne granice aktywacji.
- [ ] Wszystkie 5 etapów protokołu testowego (Trigger, Procedure, Pitfall, Scope, Staleness) zostało pomyślnie ukończonych.
- [ ] W tekście brak fraz-markersów niepewności („w razie potrzeby”, „odpowiednio”).
- [ ] Wszystkie komendy konsolowe zostały przetestowane w żywym terminalu projektu.
- [ ] Globalne inwarianty sformułowano jako odwołania do `AGENTS.md`.