OPUBLIKOWANO: 11 lutego 2026
Pierwsze tygodnie z agentem AI są zawsze piękne: wszystko da się „dogadać w rozmowie”. A potem robisz to samo trzeci raz i zaczyna się firmowy klasyk: „gdzie jest zapisane, jak to robimy?”, „gdzie był ten endpoint?”, „czemu raz działa, a raz agent zapomina?”.
W OpenClaw masz dwa mechanizmy porządkowania wiedzy, które z zewnątrz wyglądają podobnie, ale służą do zupełnie innych celów:
- Skills – reużywalne procedury „jak to robić” (playbooki dla agenta).
- TOOLS.md – lokalna ściąga „jakie mam środowisko i gdzie to jest” (ścieżki, linki, identyfikatory, konwencje).
Jeśli pomylisz te role, kończysz z agentem, który jest albo mądry, ale chaotyczny, albo uporządkowany, ale niepraktyczny. Poniżej dostajesz prosty model decyzyjny i przykłady, które pomagają utrzymać porządek bez rozdmuchiwania kontekstu.
- TL;DR: różnica w jednym zdaniu
- Skills: procedury i zasady bezpieczeństwa (SOP dla agenta)
- TOOLS.md: lokalna ściąga (parametry środowiska)
- Prosty model decyzyjny: gdzie co trzymać
- Przykład: publikacja wpisów – skill vs TOOLS.md
- Dobre praktyki, które działają po miesiącu pracy
TL;DR: różnica w jednym zdaniu
- Skill odpowiada na pytanie: „jak agent ma to robić krok po kroku?”
- TOOLS.md odpowiada na pytanie: „co mam skonfigurowane i gdzie to jest?”
Czyli: Skills = procedury. TOOLS.md = ściąga.
Skills: procedury i zasady bezpieczeństwa (SOP dla agenta)
Skill w OpenClaw to katalog z plikiem SKILL.md i (opcjonalnie) skryptami, przykładami oraz zasobami. Dobrze napisany skill działa jak SOP (Standard Operating Procedure): narzuca kolejność kroków, format wyniku i ogranicza „kreatywność” modelu w miejscach, w których ma być deterministycznie.
To jest kluczowe, gdy wchodzisz w akcje write: publikacja, edycja, usuwanie, wysyłka. Skill powinien wtedy zawierać zasady bezpieczeństwa, np. „nie publikuj bez potwierdzenia”, „nie loguj sekretów”, „jeśli brakuje danych – zadaj maksymalnie 2 pytania”.
Drugą ważną rolą skilli jest wymuszanie formatu outputu. Jeśli agent ma działać w pipeline (np. workflow/n8n), zwykle chcesz JSON albo listę kontrolną, a nie esej. Skill to najlepsze miejsce, żeby to narzucić.
| Sygnał | Dlaczego | Przykład |
| Powtarzalny proces | Chcesz stabilności i szybkości | Publikacja wpisów, triage ticketów |
| Ryzyko write/destructive | Potrzebujesz zasad bezpieczeństwa | Usuwanie, zmiany w systemach |
| Wymagany format outputu | Pipeline potrzebuje schematu | Zwróć JSON: score/recommendation/nextStep |
TOOLS.md: lokalna ściąga (parametry środowiska)
TOOLS.md to plik utrzymywany przez Ciebie w workspace. Jego sens jest prosty: przechowuje informacje o tym, jak wygląda Twoje środowisko. To nie jest miejsce na długie procedury. To miejsce na fakty, które agent ma szybko znaleźć.
Co warto trzymać w TOOLS.md:
- ścieżki do plików credentials (bez wklejania sekretów),
- nazwy urządzeń, profili i zasobów,
- linki do dashboardów i repo,
- konwencje zespołu („używaj tego jednego wątku do komunikacji z agentem X”).
Czego nie warto: wielostronicowych instrukcji krok po kroku. TOOLS.md szybko puchnie, a każdy dodatkowy akapit to koszt kontekstu i szum.
Prosta zasada: jeśli procedura działa tak samo na każdym serwerze – to Skill. Jeśli zależy od lokalnego środowiska (ścieżki, porty, tokeny) – to TOOLS.md. Skill to SOP, TOOLS.md to ściąga.
Prosty model decyzyjny: gdzie co trzymać
Zadaj sobie cztery pytania.
- Czy to jest reużywalne i powtarzalne?
- Tak → skill.
- Nie → TOOLS.md.
- Czy ma działać dla innych agentów / na innych maszynach?
- Tak → skill (wspólny).
- Nie → TOOLS.md.
- Czy to dotyczy akcji write lub ryzyka?
- Tak → skill + zasady bezpieczeństwa + często human-in-the-loop.
- Czy to zależy od obecności binarki/env/config?
- Tak → skill powinien mieć gating (żeby nie był aktywny bez wymagań).
Przykład: publikacja wpisów – skill vs TOOLS.md
Załóżmy, że agent ma publikować wpisy przez API.
W TOOLS.md trzymasz „co masz”:
- gdzie jest klucz API (ścieżka do pliku
.env), - jaki jest base URL,
- jak wygląda autoryzacja (nagłówek, nazwa sekretu).
W skillu trzymasz „jak robić”:
- pełną procedurę: GET/PUT/POST, walidacje, zasady slugów,
- obsługę edge case’ów (duplikaty, prefixy),
- bezpieczeństwo: publikuj jako draft domyślnie, nie loguj sekretów, potwierdzenie przed publikacją.
Różnica jest krytyczna: TOOLS.md ma być krótką ściągą środowiska, a skill ma być playbookiem procesu.
Dobre praktyki, które działają po miesiącu pracy
TOOLS.md:
- trzymaj krótko i konkretnie,
- zero sekretów w treści (zapisuj tylko ścieżki i nazwy),
- traktuj jak README środowiska.
Skills:
- pisz jak SOP: krok po kroku,
- dodawaj zasady bezpieczeństwa dla write,
- wymuszaj format outputu,
- używaj gatingu, gdy zależy od env/binariów.
Jeśli trzymasz ten podział, agent przestaje „kombinować” i zaczyna dowozić.
Chcesz uporządkować pracę z agentami AI?