# Codex Skills dla początkujących: jak zautomatyzować scenariusze pracy agenta AI > Praktyczny przewodnik po tworzeniu i korzystaniu z funkcji Skills w Codex: struktura pliku SKILL.md, aktywacja jawna i automatyczna, różnice między umiejętnościami (skills), skryptami a narzędziami (tools), API Skills oraz konfiguracja limitów bezpieczeństwa. ## 1. Czym jest Codex Skill: przejście od jednorazowych promptów do powtarzalnych scenariuszy Podczas regularnej pracy z **Codex** inżynierowie często powtarzają ten sam zestaw instrukcji wejściowych: które pliki sprawdzić, według jakich kryteriów przeprowadzać audyt, jakich zasad architektury przestrzegać oraz w jakim formacie zwracać wynik. Konieczność ponownego wpisywania tych wymagań w każdej sesji obniża produktywność i prowadzi do losowych błędów. **Codex Skill (umiejętność)** to zapisany, wielokrotnie używany scenariusz roboczy dla konkretnego typu zadań. Tworzenie umiejętności nie polega na fine-tuningu modelu: wagi sztucznej inteligencji pozostają bez zmian. Zamiast tego agent otrzymuje jasny protokół proceduralny, który dynamicznie ładuje do swojego okna kontekstowego dokładnie wtedy, gdy pojawia się odpowiednie zadanie. ```mermaid flowchart LR subgraph AdHoc ["Традиційний підхід (Ручний промптинг)"] User1["Користувач"] -->|Щоразу вводить довгі правила| Prompt["Великий разовий промпт"] Prompt --> Agent1["Codex"] end subgraph Modular ["Підхід на основі Skills"] User2["Користувач"] -->|Короткий запит: $code-review| Agent2["Codex"] SkillsDir["Репозиторій Skills (SKILL.md)"] -->|Автоматичне підвантаження інструкцій| Agent2 Agent2 --> Output["Стандартизований результат"] end ``` > [!NOTE] > W oficjalnym ekosystemie OpenAI umiejętności są już standardem automatyzacji. Na przykład, przy migracji bazy kodu na nowe modele OpenAI udostępnia gotowy Skill `openai-docs`, który zna wszystkie niuanse aktualnego SDK, eliminując konieczność ręcznego ładowania dokumentacji. --- ## 2. Kryteria wyboru: kiedy potrzebny jest Skill, a kiedy wystarczy zwykły prompt Skill jest przeznaczony przede wszystkim dla procesów charakteryzujących się wyraźną powtarzalnością, stabilną sekwencją działań lub surowymi wymaganiami dotyczącymi formatu danych wyjściowych. | Kryterium | Zwykły prompt | Codex Skill | | :--- | :--- | :--- | | **Częstotliwość użycia** | Jednorazowe unikalne zadanie | Regularny scenariusz (codziennie lub przed każdym releasem) | | **Złożoność procesu** | 1–2 proste kroki | Wielokrokowy, uregulowany pipeline z walidacją | | **Dodatkowe pliki** | Niepotrzebne | Wymaga skryptów pomocniczych, referencji lub checklistów | | **Wymagania co do formatu** | Dowolna odpowiedź | Ścisła struktura raportu (np. JSON lub stała tabela) | | **Uprawnienia i ograniczenia** | Bieżące ustawienia sesji | Jasno określone dozwolone i zabronione działania | ### Typowe scenariusze tworzenia umiejętności - **Przedrelease’owa weryfikacja repozytorium:** Uruchomienie linterów, wyszukiwanie pozostałego kodu debugującego (`console.log`, `TODO`), sprawdzenie kompatybilności typów. - **Standaryzowane code review:** Weryfikacja zgodności z wewnętrznymi regułami architektonicznymi zespołu bez wprowadzania samodzielnych zmian. - **Generowanie notatek release’owych:** Ekstrakcja listy scalonych PR-ów, ich kategoryzacja oraz aktualizacja `CHANGELOG.md`. - **Migracja komponentów:** Krok po kroku refaktoryzacja przestarzałych wzorców zgodnie z wcześniej zatwierdzonym szablonem. > [!TIP] > **Praktyczna zasada inżyniera:** Jeśli złapiesz się na tym, że trzeci raz wyjaśniasz Codex tę samą sekwencję kroków („najpierw przeczytaj ten plik, potem uruchom ten test, nic nie zmieniaj, wypisz w formie tabeli”) – najwyższy czas zapakować ten workflow w osobny Skill. --- ## 3. Mechanika aktywacji: jawne wywołanie przez $name vs automatyczne dopasowanie Codex wspiera dwa uzupełniające się sposoby aktywacji umiejętności w sesji: bezpośrednie, deterministyczne wywołanie przez użytkownika oraz automatyczne rozpoznawanie semantyczne. ### Jawne wywołanie (Explicit Invocation) Użytkownik bezpośrednio wskazuje nazwę wymaganej umiejętności za pomocą prefiksu dolara `$`: ```bash $code-review перевір останні зміни у гілці feature/auth ``` Ta metoda gwarantuje 100% przewidywalność: Codex natychmiast aktywuje wskazany Skill, przyjmuje jego instrukcje jako podstawę zachowania i stosuje je do argumentów Twojego zapytania. ### Automatyczna aktywacja (Semantic Auto-Match) Jeśli prefiks `$name` nie został podany, Codex analizuje zapytanie użytkownika i porównuje je z polami `description` wszystkich podłączonych umiejętności: ```mermaid flowchart TD Req["Запит: 'Підготуй релізні нотатки для v2.1.0'"] --> Router{"Аналіз семантичного збігу"} Router -->|Match: description release-notes| LoadSkill["Підвантаження .codex/skills/release-notes/SKILL.md"] Router -->|No Match| Standard["Звичайний діалог без підвантаження навичок"] LoadSkill --> Exec["Виконання регламентованого сценарію"] ``` ```text Skuteczny opis (wysokie prawdopodobieństwo trafnego dopasowania): description: Weryfikuje zmodyfikowane pliki projektu pod kątem regresji, błędów typowania oraz stylu przed wydaniem wersji. Używaj podczas audytu PR. Nieskuteczny opis (rozmyte granice zastosowania): description: Pomaga programiście lepiej pisać kod. ``` --- ## 4. Anatomia umiejętności i struktura SKILL.md: metadane, zasady i zasoby Minimalny Skill składa się tylko z jednego pliku — `SKILL.md`. Bardziej dojrzałe umiejętności mogą zawierać osadzone skrypty automatyzacji, podręczniki referencyjne oraz szablony. ```text project-review/ ├── SKILL.md # Plik główny (metadane + instrukcje) ├── scripts/ └── check-deps.sh # Wykonywalny skrypt do szybkich sprawdzeń ├── references/ └── styleguide.md # Przewodnik: wewnętrzny styl kodu zespołu └── templates/ └── report-template.md # Szablon raportu podsumowującego ``` ### Struktura pliku `SKILL.md` Plik dzieli się na dwie funkcjonalne części: blok YAML Frontmatter na początku oraz instrukcje w formacie Markdown. ```markdown --- name: project-review description: Przeprowadza kompleksowy audyt kodu przed wydaniem, sprawdza typy i generuje raport o błędach bez wprowadzania zmian. --- Instrukcje dotyczące audytu: 1. Uruchom „npm run typecheck”, aby wykryć błędy TypeScript. 2. Przeanalizuj git diff względem gałęzi main. 3. Pogrupuj znalezione uwagi według kategorii: Critical (Krytyczne), Warning (Ostrzeżenia), Suggestion (Sugestie). 4. Nie zmieniaj niczego automatycznie w kodzie źródłowym. 5. Przedstaw podsumowujący raport zgodnie z templates/report-template.md. ``` > [!IMPORTANT] > **Zasada zwięzłości:** Nie przeciążaj `SKILL.md` długimi filozoficznymi wyjaśnieniami. Im krótszy i bardziej precyzyjny tekst, tym mniej cennego miejsca zajmuje w oknie kontekstowym modelu i tym rygorystyczniej agent przestrzega regulaminu. --- ## 5. Obszary przechowywania: umiejętności projektowe vs osobiste globalne Codex rozróżnia umiejętności w dwóch zakresach widoczności w zależności od ich przeznaczenia: ```mermaid flowchart TD subgraph GlobalScope ["Глобальні навички (~/.codex/skills/)"] G1["Особистий стиль комітів"] G2["Швидкий генератор ліцензій"] end subgraph ProjectScope ["Проєктні навички (.codex/skills/)"] P1["Архітектурний лінтер проєкту"] P2["Генератор DTO та міграцій БД"] P3["Чек-лист релізу сервісу"] end Dev["Розробник"] -->|Власні уподобання| GlobalScope Team["Команда в Git"] -->|Спільні стандарти| ProjectScope ``` ### Umiejętności projektowe (`.codex/skills/` lub `.agents/skills/`) Przechowywane w katalogu głównym repozytorium projektu i wersjonowane w Git. - **Przeznaczenie:** Standaryzacja procesów dla całego zespołu deweloperskiego. - **Zaleta:** Każdy inżynier (lub runner CI/CD), który klonuje repozytorium, od razu otrzymuje identyczny zestaw agentic skills. ### Umiejętności osobiste (`~/.codex/skills/`) Umieszczone w katalogu domowym bieżącego użytkownika systemu operacyjnego. - **Przeznaczenie:** Indywidualne narzędzia specyficzne dla konkretnego developera (np. osobisty asystent do formatowania notatek deweloperskich). - **Zaleta:** Dostępne w dowolnym terminalu niezależnie od aktywnego projektu. --- ## 6. Praktyczny warsztat: tworzenie umiejętności weryfikacji kodu za pomocą $skill-creator Najprostszym i najszybszym sposobem na utworzenie nowej umiejętności jest skorzystanie z wbudowanego w Codex systemowego meta-narzędzia `$skill-creator`. ### Krok 1. Inicjalizacja kreatora W oknie dialogowym Codex wywołujemy komendę: ```bash $skill-creator ``` Następnie opisujemy pożądany workflow językiem naturalnym: ```text Utwórz dla mnie skill projektowy o nazwie "pr-validator". Cel: sprawdzenie zmodyfikowanych plików w bieżącym pull request. Zasady: 1. Uruchom npm run lint oraz npm test. 2. Sprawdź, czy do nowych modułów dodano testy jednostkowe (unit tests). 3. Zabroń agentowi samodzielnego naprawiania wykrytych defektów. 4. Wynik przedstaw w formie tabeli z kolumnami: Plik, Linia, Problem, Poziom ryzyka. ``` ### Krok 2. Weryfikacja wygenerowanego artefaktu Kreator utworzy katalog `.codex/skills/pr-validator/` i wygeneruje plik `SKILL.md`: ```markdown --- name: pr-validator description: Validates pull request changes by running lint and test suites, checking test coverage for new modules, and returning an issue table without modifying code. --- Execution Steps: 1. Identify modified files using git diff against the target branch. 2. Execute "npm run lint" and capture any linter warnings or errors. 3. Execute "npm test" to ensure regression safety. 4. Verify whether newly created source files in src/ have corresponding test files in tests/. 5. Strict constraint: Do NOT modify any project files under any circumstances. 6. Present the audit findings in a markdown table: | File | Line | Issue | Severity | ``` ### Krok 3. Testowanie utworzonej umiejętności w rzeczywistej sesji Otwórz nową sesję Codex i przetestuj działanie utworzonej umiejętności: ```bash $pr-validator перевір мою поточну гілку перед відкриттям PR ``` Upewnij się, że agent uruchomił linter, nie próbował edytować plików źródłowych i zwrócił tabelę z wynikami. --- ## 7. Triada możliwości agenta: Skill, Script i Tool Początkujący często mylą pojęcia umiejętności, skryptu i narzędzia (Tool / MCP). Uzupełniają się one nawzajem, ale rozwiązują zasadniczo różne problemy inżynierskie. ```mermaid flowchart TD subgraph Triad ["Тріада архітектури автономного агента"] Skill["SKILL (Навичка)
'Мозок і регламент'
Пояснює послідовність, контекст та логіку"] Script["SCRIPT (Скрипт)
'Точний алгоритм'
Виконує детерміновану операцію на диску"] Tool["TOOL (Інструмент / MCP)
'Органи чуття та руки'
Надає доступ до API, терміналу, баз даних"] end Skill -->|Керує викликом| Script Skill -->|Використовує| Tool Script -->|Викликається через| Tool ``` ### Macierz porównawcza triady | Komponent | Rola w systemie | Jak jest wykonywany | Przykład | | :--- | :--- | :--- | :--- | | **Skill (Umiejętność)** | **Regulamin i myślenie** | Odczytywana i interpretowana przez model | Instrukcja przeprowadzania audytu bezpieczeństwa | | **Script (Skrypt)** | **Deterministyczne działanie obliczeniowe** | Uruchamiany w OS przez terminal | Bash script parsujący tagi git | | **Tool (Narzędzie)** | **Interfejs dostępu do środowiska** | Wywoływany przez mechanizm Tool Calling | Serwer MCP do łączenia z GitHub API | > [!NOTE] > Skill mówi agentowi, **co** i **w jakiej kolejności** należy zrobić. Skrypt szybko i gwarantowanie wykonuje operację matematyczną lub plikową. Narzędzie daje uprawnienia do interakcji ze światem zewnętrznym. --- ## 8. Programistyczne zarządzanie przez Skills API i wersjonowanie Poza lokalną pracą z plikami, OpenAI udostępnia wyspecjalizowane **Skills API** do programistycznego zarządzania umiejętnościami w aplikacjach chmurowych i systemach backendowych. ```bash # Створення нової навички через HTTP API curl https://api.openai.com/v1/skills \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "schema-migrator", "description": "Автоматична валідація та створення міграцій бази даних", "instructions": "Перевір схему Prisma, переконайся у відсутності drop column..." }' ``` ### Po co potrzebne wersjonowanie Skills 1. **Niezmienność środowiska produkcyjnego (Immutability):** Każda aktualizacja umiejętności tworzy nową wersję (`v1`, `v2`). Pipeline’y produkcyjne przypinają się do konkretnej, zamrożonej wersji, uniemożliwiając niespodziewane awarie przez przypadkowe zmiany. 2. **Bezpieczne cofnięcie (Rollback):** Jeśli zaktualizowany opis doprowadził do regresji lub pogorszenia jakości generowanego kodu, zespół może natychmiast przywrócić poprzedni numer wersji. 3. **Testy A/B instrukcji:** Możliwość jednoczesnego porównywania wydajności dwóch alternatywnych redakcji umiejętności na rzeczywistych zadaniach. --- ## 9. Bezpieczeństwo, granice autonomii i zasady potwierdzania działań Skill bezpośrednio wpływa na to, jakie operacje agent wykonuje w Twoim systemie. Dlatego w treści umiejętności muszą być jasno rozgraniczone działania autonomiczne i kontrolowane. ```mermaid flowchart LR Action["Дія агента"] --> Decision{"Тип операції"} Decision -->|Безпечна: Read-Only| Auto["Автономне виконання без пауз
(Читання коду, запуск лінтера)"] Decision -->|Критична: Write / Network| Confirm["Запит підтвердження в інженера
(Видалення файлів, деплой)"] ``` ### Macierz poziomów zaufania :::tabs @tab Dozwolone bez potwierdzenia - Odczyt plików źródłowych i dokumentacji. - Analiza logów buildu i błędów w terminalu. - Uruchamianie izolowanych unit-testów w trybie read-only. - Generowanie raportów analitycznych i tabel. @tab Wymaga obowiązkowego potwierdzenia - Modyfikacja plików konfiguracji globalnej (`package.json`, `.env`). - Usuwanie lub nadpisywanie plików w repozytorium. - Wykonywanie zapytań sieciowych lub wysyłanie danych do zewnętrznych API. - Tworzenie commitów lub push zmian do zdalnego repozytorium Git. ::: > [!WARNING] > **Nie dubluj zakazów wielokrotnie:** Unikaj wielokrotnego powtarzania fraz typu „nic nie zmieniaj” w każdym punkcie. Wystarczy raz na początku sekcji ograniczeń jasno określić zabronione operacje; w przeciwnym razie agent stanie się nadmiernie pasywny i zacznie pytać o zgodę nawet przed odczytem zwykłego pliku. --- ## 10. Podsumowująca ściągawka i checklist tworzenia niezawodnego Skill Zapisz ten checklist i korzystaj z niego podczas projektowania każdej nowej umiejętności. ### Szybka ściągawka inżyniera ```bash # ─── Робота з навичками в Codex ────────────────────────────────── $skill-creator # Запуск вбудованого майстра створення навичок $ <ваше завдання> # Явний детермінований виклик навички /skills # Перегляд списку доступних навичок у сесії # ─── Файлова структура проєкту ─────────────────────────────────── .codex/skills//SKILL.md # Проєктна навичка (для всієї команди) ~/.codex/skills//SKILL.md # Персональна навичка (для поточної машини) ``` ### Checklist gotowości umiejętności do releasu - [ ] **Jasna nazwa:** Do 64 znaków, małe litery alfabetu łacińskiego, rozdzielone dywidem (`kebab-case`). - [ ] **Informatyczny opis:** Pole `description` zawiera jasną formułę „co robi umiejętność” oraz „kiedy ją uruchamiać”. - [ ] **Zwięzła treść:** Tekst nie przekracza optymalnej długości, zachowując klarowność instrukcji.