Tworzenie umiejętności agenta Hermes — struktura pliku SKILL.md i najlepsze praktyki

Hermes Agent traktuje umiejętności (skills) jako domyślny sposób nauczania powtarzalnych procesów. Oficjalna dokumentacja opisuje je jako dokumenty wiedzy dostępne na żądanie, zgodne z otwartym schematem agentskills.io, ładowanymi poprzez stopniową ekspozycję (progressive disclosure), dzięki czemu model widzi najpierw mały indeks i pobiera pełne instrukcje dopiero wtedy, gdy zadanie ich faktycznie wymaga.

Tworzenie umiejętności ma mniej wspólnego z chwytliwym sformułowaniem, a więcej z pakowaniem – informujesz środowisko wykonawcze, kiedy ma załadować procedurę, jaki ciąg kroków uznaje się za „ukończony” i jak odróżnić sukces od cichej niepowodzenia. Ten artykuł koncentruje się na strukturze pliku SKILL.md, folderach wspierających, zasadach widoczności oraz podziale między ustawieniami tajnymi a nietajnymi – szczegółach, które decydują o tym, czy umiejętność pojawi się w komendach /slash, przetrzy instalację z huba, czy też cicho zniknie w środowisku CI.

Hermes znajduje się w szerszym klastrze Systemy AI: Asystenci Samochostowani, RAG i Lokalna Infrastruktura, gdzie asystenci są traktowani jako systemy zbudowane z wnioskowania, odzyskiwania, pamięci i narzędzi, a nie jako pojedynczy interfejs czatu. Ścieżki instalacji, konfiguracja dostawców, zachowanie bramki (gateway) oraz układ folderu ~/.hermes są szczegółowo opisane w przewodniku Asystent Hermes AI - Instalacja, Konfiguracja, Procesy i Rozwiązywanie Problemów; codzienna ergonomia powłoki – hermes skills, profile, bramka, pamięć – są łatwiejsze do przeglądania w Ściągnicy CLI Asystenta Hermes – komendy, flagi i skróty slash. W rzeczywistych wdrożeniach umiejętności dziedziczą izolację z profili (oddzielna konfiguracja, sekrety, pamięci i drzewa umiejętności). Umiejętności Asystenta Hermes AI dla Prawdziwych Środowisk Produkcyjnych argumentuje, że należy traktować te profile – a nie pojedyncze pliki markdown – jako jednostkę odpowiedzialności; miej to na uwadze, nazywając umiejętności i decydując, co należy do wspólnych external_dirs, a co do pojedynczego profilu.

Umiejętność czy narzędzie?

Oficjalne wytyczne są bezpośrednie. Użyj umiejętności, gdy zdolność polega głównie na instrukcjach tekstowych oraz komendach powłoki i narzędziach, które Hermes już udostępnia – opakowywanie CLI, sterowanie git, wywoływanie curl lub używanie web_extract do strukturalnego pobierania danych. Użyj narzędzia, gdy potrzebujesz ścisłej integracji dla kluczy API i przepływów uwierzytelniania, deterministycznej obsługi binarnych danych, strumieniowania lub Pythona, który musi wykonywać się identycznie za każdym razem.

Ta granica ma znaczenie w praktyce, ponieważ umiejętności są dostarczane bez zmiany kodu agenta, podczas gdy narzędzia niosą ze sobą koszty przeglądania i wydawania. Większość zespołów korzysta z rozpoczęcia od umiejętności, a następnie promowania tylko kruchej rdzeniowej części do narzędzia, gdy tryby awarii staną się oczywiste (pętle odświeżania autoryzacji, parsery binarne, ścisła idempotentność).

Procedury versus kurated memory

Umiejętności odpowiadają na pytanie jak uruchomić proces; ograniczona pamięć rdzeniowa Hermes odpowiada na pytanie co zostało już ustalone dotyczące użytkownika i projektu. Umiejętność ładuje się, gdy zadanie pasuje do jej opisu; pliki MEMORY.md i USER.md pozostają w prompcie jako mała, kurated warstwa faktów. Te dwa mechanizmy nakładają się na siebie, a nie konkurują, a pełny obraz snapshotów, limitów i zewnętrznych dostawców jest przedstawiony w System Pamięci Asystenta Hermes: Jak Działa Trwała Pamięć AI.

Anatomia katalogu umiejętności

Na dysku każda umiejętność jest folderem pod ścieżką ~/.hermes/skills/, często zagnieżdżonym pod kategorią taką jak devops/ lub research/. Hermes oczekuje SKILL.md na liście; wszystko inne to opcjonalna struktura, którą dodajesz, gdy instrukcje w przeciwnym razie by się rozlały. Typowym wzorcem jest references/ dla długich tabel lub dokumentacji dostawców, templates/ dla szkieletów wyjściowych, scripts/ dla deterministycznych pomocników oraz assets/ dla plików statycznych, których agent nie powinien ponownie pobierać.

Ten układ odzwierciedla, jak stopniowa ekspozycja działa w praktyce: agent może pozostać przy głównym pliku, dopóki nie będzie naprawdę potrzebował głębokiego dodatku. Trzymanie „szczęśliwej ścieżki” w SKILL.md i przenoszenie rzadko używanych szczegółów do references/ to jeden z najtańszych sposobów ochrony budżetu tokenów.

Hermes może również łączyć się z zewnętrznymi katalogami umiejętności poprzez skills.external_dirs w config.yaml. Te ścieżki są skanowane w celu odkrycia, ale agent nadal zapisuje przez skill_manage do głównego drzewa ~/.hermes/skills/. Lokalne nazwy przesłaniają zewnętrzne, więc jeśli „naprawisz” wspólną umiejętność w swoim katalogu domowym, koledzy z zespołu ściągający ten sam zewnętrzny repozytorium nie zobaczą Twojej edycji, dopóki nie usuną lub nie zmienią nazwy lokalnej kopii – to częłe źródło nieporozumień typu „działa na moim komputerze”.

Frontmatter SKILL.md przetrzymujący przegląd

Ciało SKILL.md to Markdown; otwierający blok musi być poprawnym YAML-em między delimitatorami ---. Prawdziwe umiejętności gromadzą długie, ogrodzone przykłady, więc małe nawyki z Bloki Kodu Markdown: Kompletny Przewodnik ze Składnią, Językami i Przykładami – spójne tagi językowe, czytelne fragmenty, ciasne ogrodzenia – utrzymują duże pliki w stanie maintainable dla ludzi i nieco łatwiejsze do skanowania dla modelu.

Wymagane pola to name i description. name staje się ścieżką slash i kluczem indeksu; pozostaje w małych literach z myślnikami i musi szanować udokumentowany limit długości. description jest jedynym tekstem, za który wiele sesji kiedykolwiek płaci na poziomie zero, więc powinna brzmieć jak wynik wyszukiwania lub string routera („kiedy kopie zapasowe wyglądają na przeterminowane, zweryfikuj najnowszy archiwum i kontrolną sumę”), a nie jak pierwszy akapit posta blogowego.

Opcjonalne klucze najwyższego poziomu, takie jak version, author i license, pomagają w pakowaniu huba i audytach. Lista platforms (macos, linux, windows) jest ostrzejsza, niż się wydaje – gdy jest ustawiona, Hermes całkowicie pomija umiejętność na niezgodnych hostach, dlatego umiejętność, która „działa na moim Macu”, może zniknąć w CI Linux bez żadnej wiadomości o błędzie poza krótszą listą umiejętności.

Specyficzne dla Hermes pokrętła znajdują się pod metadata.hermes: tags, related_skills i pola warunkowej widoczności w następnej sekcji. required_environment_variables deklaruje sekrety, które powinny znaleźć się w .env i przejść do piaskownic; required_credential_files obejmuje pliki tokenów OAuth i inne poświadczenia na dysku, które muszą być zamontowane w Dockerze lub Modal; metadata.hermes.config deklaruje nietajne preferencje przechowywane pod skills.config w config.yaml.

Oficjalne dokumenty podkreślają dyscyplinę rozmiaru z powodu. Przetnij description do jego budżetu, umieść procedurę na początku i przesunij notatki historyczne lub ogromne macierze opcji do references/, aby częściowe skill_view nadal dawało agentowi coś do wykonania.

Poniżej znajduje się minimalny SKILL.md, który możesz umieścić w ~/.hermes/skills/devops/backup-check/SKILL.md (lub dowolnym katalogu kategorii) i iterować od tamtej pory.

---
name: backup-check
description: Verify nightly backup archives exist, are non-empty, and pass a quick checksum spot-check on the latest file.
version: 1.0.0
metadata:
  hermes:
    tags: [devops, backups, shell]
    requires_toolsets: [terminal]
    config:
      - key: backup_check.archive_dir
        description: Absolute path to the directory that holds backup archives
        default: "/var/backups"
        prompt: Backup archive directory (absolute path)
---

# Backup archive spot-check

## When to use

Use when the user asks to confirm backups ran, to audit the latest archive on disk, or to catch empty or stale backup files before a restore drill.

## Quick reference

- Latest archive directory is configured under `skills.config.backup_check.archive_dir` (set via `hermes config migrate` if declared in metadata).
- Default check uses `ls` by mtime and `test -s` for non-empty files.

## Procedure

1. Resolve the archive directory from skill config or ask the user once if unset.
2. List the most recently modified file matching the expected pattern (for example `*.tar.zst`).
3. Confirm the file exists, is non-empty, and record its path and size for the reply.
4. If a checksum file exists beside the archive, verify it with the documented tool (for example `sha256sum -c`).

## Pitfalls

- Empty files can still have a recent mtime if a failed job touched the path; always check size.
- Relative paths break when the terminal cwd is not the backup host; use absolute paths in config.

## Verification

The user should see the latest archive path, byte size, and either a checksum OK line or an explicit note that no `.sha256` sidecar was found.

Stopniowa ekspozycja w praktyce

Stopniowa ekspozycja to różnica między biblioteką umiejętności, która wydaje się responsywna, a tą, która spala tysiące tokenów przed pierwszą wiadomością użytkownika. Hermes przechodzi trzy koncepcyjne kroki: katalog skrócony (nazwy i krótkie opisy), pełny SKILL.md, gdy zadanie pasuje, oraz – tylko jeśli to konieczne – fragment pliku referencyjnego poprzez ścieżki skill_view. Załaduj, że poziom zero to wszystko, co model przeczyta, dopóki nie zobowiąże się wyraźnie; każde zdanie w description i pierwszy ekran tekstu ciała powinny pomagać w routingu, a nie w opowiadaniu historii.

Praktyczny plan, który przetrzymuje częściowe ładowanie, to Kiedy używać (wywołania w prostym języku), Szybkie odniesienie (komendy, zmienne środowiskowe, ścieżki plików), Procedura (układane kroki, których agent nie powinien improwizować), Pułapki (znane tryby awarii) oraz Weryfikacja (jak wygląda „zielony” stan). Historia narracyjna, zrzuty dzienników zmian dostawców i dwudziestowierszowe tabele opcji należą do references/ ze stabilnymi nagłówkami, aby agent mógł pobrać pojedynczą sekcję.

Gdy umiejętność aktywuje się, Hermes może przepisać ${HERMES_SKILL_DIR} i ${HERMES_SESSION_ID} w ciele, więc linie powłoki wskazują na zainstalowany folder bez ręcznie budowanych ścieżek. Opcjonalne fragmenty inline shell (!cmd``) mogą wstrzykiwać świeży kontekst (aktualna gałąź, wolne miejsce na dysku), ale wykonują się na hoście i są wyłączone, chyba że skills.inline_shell jest włączone – traktuj tę flagę jako granicę zaufania dla całego źródła umiejętności, a nie jako przełącznik wygody.

Warunkowa aktywacja i higiena promptu

Umiejętności mogą pokazywać lub ukrywać się w zależności od tego, które zestawy narzędzi lub narzędzia istnieją w bieżącej sesji. requires_toolsets / requires_tools chronią umiejętność za możliwościami, które muszą być obecne; fallback_for_toolsets / fallback_for_tools eksponują tańszą lub lokalną ścieżkę, gdy brak jest płatnej integracji – przykładowym kanonicznym przykładem jest awaryjne DuckDuckGo, gdy płatne API wyszukiwania internetowego nie jest skonfigurowane.

Te predykaty bezpośrednio kształtują hałas promptu. Nadmiernie rygorystyczna reguła requires_* ukrywa umiejętność przed nowymi użytkownikami, którzy nie ukończyli jeszcze konfiguracji hermes tools; nadmiernie luźna reguła fallback_for_* duplikuje połowę Twojej biblioteki za każdym razem, gdy ktoś pominie klucz API. Przydatny środek to nazwanie prawdziwych wymogów wstępnych, przetestowanie z hermes chat --toolsets skills i celowe przełączanie kluczy lub zestawów narzędzi, obserwując, czy lista umiejętności „oddycha” w sposób, jakiego oczekujesz.

Sekrety, konfiguracja i pliki poświadczeń

Sekrety powinny być zadeklarowane w required_environment_variables. Hermes może prosić o podanie wartości, gdy umiejętność ładuje się w lokalnym CLI, utrzymywać wartości w .env i przekazywać je do piaskownic terminal i execute_code bez strumieniowania surowego sekretu z powrotem do transkryptu modelu. Zdalne powierzchnie czatu odmawiają zbierania kluczy inline i zamiast tego kierują ludzi do hermes setup lub ręcznych edycji .env – autoruj tekst swojej umiejętności tak, aby pasował do tego zachowania (powiedz użytkownikom, że klucz jest wymagany, a nie aby wkleili go do Telegrama).

Nietajne preferencje – domyślne ścieżki, nazwy organizacji, przełączniki funkcji – należą do metadata.hermes.config. Wartości rozwiązywane są do skills.config wewnątrz config.yaml, pojawiają się w hermes config show i docierają do wiadomości umiejętności jako rozwiązane fakty, więc model nie musi otwierać pliku konfiguracji w trakcie zadania.

Pojedyncze poświadczenia plikowe (JSON tokenów OAuth, klucze kont usługowych) mapują się do required_credential_files. Gdy te pliki istnieją, Hermes może je zamontować (bind-mount) do Dockera lub zsynchronizować do zadań Modal; deklarowanie ich z góry unika klasycznej luki „skrypt działa lokalnie, umiera w piaskownicy”.

Skrypty wspierające i zależności

Przewodnik upstream kieruje autorów w stronę nudnych zależności: stdlib Pythona, curl i własnych narzędzi Hermes (web_extract, read_file, terminal). To mniej dotyczy czystości, a bardziej powtarzalności – każde dodatkowe pip install to kolejna cicha awaria, gdy agent działa w czystym kontenerze.

Gdy parsowanie JSON lub XML jest problematyczne, krótki skrypt pod scripts/ plus ścieżka ${HERMES_SKILL_DIR} jest lepszy niż proszenie modelu o ponowne wyprowadzanie parserów przy każdym uruchomieniu. Jeśli naprawdę potrzebujesz pakietu, podaj komendę instalacji w Procedurze, powtórz objaw awarii w Pułapkach i podaj komendę Weryfikacji, która głośno nie powiedzie się, gdy zależność jest brakująca.

Publikowanie, instalacje z huba i zaufanie

Społecznościowe umiejętności przechodzą przez Skills Hub i inne ścieżki odkrywania wymienione w przewodniku użytkownika – oficjalne opcjonalne umiejętności, slugi GitHub, wpisy skills.sh, indeksy .well-known i surowe URL SKILL.md. Instalacje są skanowane pod kątem oczywistej eksfiltracji, iniekcji i destruktywnych wzorców; poziomy zaufania biegą od wbudowanych przez społecznościowe, a niektóre znaleziska są usuwane dopiero z --force, podczas gdy najgorsze przypadki pozostają całkowicie zablokowane.

Kształt pliku SKILL.md nie jest specyficzny dla Hermes; asystenci skupione na IDE używają tej samej idei stopniowego ładowania z innym odkryciem i wyzwalaczami. Umiejętności Claude i SKILL.md dla Deweloperów: VS Code, JetBrains, Cursor to użyteczne czytanie kontrastowe – dyscyplina frontmatter i „ładuj tylko gdy to istotne” przenoszą się, nawet gdy instalator i okablowanie komend slash się różnią.

Wdrożenia w skali organizacji zazwyczaj łączą prywatny tap lub wspólny repozytorium Git z external_dirs do tylko do odczytu, podczas gdy utrzymują kopię zapisywalną przez agenta pod każdym profilem, gdy skill_manage jest dozwolone do mutowania umiejętności w miejscu.

Rozwiązywanie problemów i optymalizacja

Gdy umiejętność zachowuje się błędnie, przejdź tę listę kontrolną przed przepisywaniem tekstu.

• Widoczność — Potwierdź predykaty platforms, requires_* i fallback_for_*. Umiejętność, która „działa na moim Macu”, ale nie w CI Linux, to często strażnik platformy.
• Kolizje nazw — Duplikaty nazw w lokalnych i zewnętrznych katalogach podlegają precedencji lokalnej. Zmień nazwę lub nazwij przestrzeń nazw agresywnie.
• Układ odkrywania — Nieumiejętnie umieszczony SKILL.md lub błędny folder kategorii może całkowicie usunąć umiejętność z indeksowania.
• Obciążenie tokenami — Jeśli sesje wydają się wolne, skróć opisy poziomu zero, przenieść głębię do references/ i zdublować ogromne tabele.
• Edycje agenta — Hermes może tworzyć, łatać lub usuwać umiejętności poprzez skill_manage. Traktuj cenne umiejętności jak kod: przeglądaj diffy, eksportuj snapshoty i resetuj wbudowane umiejętności świadomie, gdy aktualizacje odbiegają.

Ciasny pętla regresji przewyższa ponowne czytanie całego pliku: hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>" powinna pokazać agenta pobierającego odpowiedni poziom ekspozycji, zanim zacznie improwizować. Jeśli nigdy nie wywołuje skill_view, Twój tekst Kiedy używać lub description prawdopodobnie nie pasuje do tego, jak ludzie formułują prośby.

Oficjalne referencje pozostają autorytatywne dla zmian zachowań – System Umiejętności przewodnik użytkownika dla semantyki środowiska wykonawczego, Tworzenie Umiejętności dla zasad skierowanych do autorów, Katalog Wbudowanych Umiejętności dla przykładów do skopiowania i wklejenia oraz specyfikacja agentskills.io dla wspólnego formatu pliku, z którym Hermes się zgodnia.