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 (Формулюється строго як УМОВА, а не тема)"] T["2. When to Trigger (Точні контекстні критерії та ключові слова)"] P["3. Procedure (Нумеровані кроки з реальними командами й шляхами)"] Pit["4. Pitfalls & Anti-Patterns (Дія + Наслідок + Точне виправлення)"] end F --> T --> P --> Pit

Szczegółowa analiza obowiązkowych sekcji

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.
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.
Procedure (Procedura regulaminowa): Numerowany algorytm działań z dokładnymi nazwami lokalnych komend i zwalidowanymi ścieżkami do plików.
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ę.

Uwaga

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 Збільшити

Ścieżki rozmieszczenia plików skills dla runtime’ów Codex i Claude Code

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

Ważne

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 (Розмитий опис, копії правил, абстрактні кроки)"] --> 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.

Wskazówka

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 Збільшити

Macierz budowania i rozmieszczenia różnych typów skills w systemie

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

Ostrzeżenie

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 (3 позитивні + 2 негативні запити)"] --> T2["2. Procedure Walk-Through (Наскрізний запуск на реальному репозиторії)"] T2 --> T3["3. Pitfall Audit (Перевірка формули: Дія + Збій + Фікс)"] T3 --> T4["4. Scope Test (Перевірка єдиної відповідальності одним реченням)"] T4 --> T5["5. Staleness Check (Звірка команд і шляхів з актуальним репозиторієм)"] T5 --> Ready["Схвалено до коміту"]

Szczegóły protokołu testowego

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.
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.
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.
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.
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.