Tworzenie umiejętności dla Agenta Hermesa — struktura pliku SKILL.md i najlepsze praktyki

Hermes Agent traktuje umiejętności (skills) jako domyślną metodę nauczania powtarzalnych workflow. Oficjalna dokumentacja opisuje je jako dokumenty wiedzy dostarczane na żądanie, zgodne z otwartym formatem agentskills.io, ładowane przez postępującą 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 to mniej kwestia sprytnego sformułowania, a bardziej pakietowanie — informujesz środowisko wykonawcze, kiedy załadować procedurę, jaki porządek kroków oznacza „gotowe” i jak odróżnić sukces od cichej porażki. Ten artykuł koncentruje się na strukturze SKILL.md, folderach wspierających, regułach widoczności oraz podziale między ustawieniami poufnymi a niepoufnymi — szczegółami, które decydują, czy umiejętność pojawi się w komendach /slash, przetrwa instalację z huba, czy też cicho zniknie na CI.

Hermes znajduje się w szerszym klastrze Systemy AI: Asystenci self-hosted, RAG i infrastruktura lokalna, 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 providerów, zachowanie bramki oraz układ ~/.hermes są szczegółowo opisane w przewodniku Hermes AI Assistant - Instalacja, konfiguracja, workflow i rozwiązywanie problemów; codzienna ergonomia powłoki — hermes skills, profile, branka, pamięć — jest łatwiejsza do przeglądu w Kratce szybkiego dostępu CLI Hermes Agent — komendy, flagi i skróty slash. W rzeczywistych wdrożeniach umiejętności dziedziczą izolację od profili (osobna konfiguracja, sekrety, pamięci i drzewa umiejętności). Hermes AI Assistant Skills dla rzeczywistych środowisk produkcyjnych argumentuje za traktowaniem tych profili — a nie pojedynczych plików markdown — jako jednostki własności; miej to na uwadze przy nadawaniu nazw umiejętnościom i podejmowaniu decyzji, co należy do wspólnych external_dirs, a co do pojedynczego profilu.

Umiejętność czy narzędzie?

Oficjalne wytyczne są bezlitosne. Użyj umiejętności, gdy zdolność jest głównie instrukcjami w formie tekstu plus komendami powłoki i narzędziami, które Hermes już udostępnia — owijaniem CLI, sterowaniem git, wywoływaniem curl lub używaniem web_extract do strukturalnego pobierania. Użyj narzędzia, gdy potrzebujesz ścisłej integracji dla kluczy API i flow uwierzytelniania, deterministycznej obsługi binarnych, streamingu 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ą obciążenie przeglądania i publikacji. Większość zespołów zyskuje na rozpoczęciu od umiejętności, a następnie promocji tylko kruchego rdzenia do narzędzia, gdy tryby awarii staną się oczywiste (pętle odświeżania uwierzytelniania, parsery binarne, ścisła idempotentność). Dla szerszego pytania architektonicznego, kiedy użyć Umiejętności Agent versus serwera MCP — szczególnie w kontekście poświadczeń, stanu na żywo i transakcyjnych zapisów — zobacz nasz ramy decyzyjne: Umiejętności Agent vs Serwery MCP.

Procedury versus kuratorowana pamięć

Umiejętności odpowiadają na pytanie jak uruchomić workflow; ograniczona pamięć rdzeniowa Hermes odpowiada na pytanie co zostało już uzgodnione o użytkowniku i projekcie. Umiejętność ładuje się, gdy zadanie pasuje do jej opisu; MEMORY.md i USER.md pozostają w prompcie jako mała, kuratorowana warstwa faktów. Te dwa mechanizmy nakładają się, a nie konkurują, a pełny obraz snapshotów, limitów i zewnętrznych providerów jest przedstawiony w System pamięci Hermes Agent: Jak naprawdę działa trwała pamięć AI.

Anatomia katalogu umiejętności

Na dysku każda umiejętność jest folderem pod ~/.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. Zwykły wzorzec to references/ dla długich tabel lub dokumentacji dostawcy, templates/ dla szkieletów wyjściowych, scripts/ dla deterministycznych helperów i assets/ dla statycznych plików, których agent nie powinien ponownie pobierać.

Ten układ odzwierciedla, jak w praktyce działa postępująca ekspozycja: 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 pchanie rzadko używanych szczegółów do references/ to jeden z najtańszych sposobów na ochronę budżetu tokenów.

Hermes może również łączyć zewnętrzne katalogi umiejętności przez skills.external_dirs w config.yaml. Te ścieżki są skanowane dla odkrycia, ale agent nadal pisze przez skill_manage do głównego drzewa ~/.hermes/skills/. Lokalne nazwy zasłaniają zewnętrzne, więc jeśli „naprawisz” wspólną umiejętność w swoim katalogu domowym, koledzy z zespołu pobierający ten sam zewnętrzny repo nie zobaczą Twojej edycji, dopóki nie usuną lub nie zmienią nazwy lokalnej kopii — częste źródło zamieszania „działa na moim komputerze”.

Frontmatter SKILL.md, który przetrwa przegląd

Treść SKILL.md to Markdown; blok otwierający musi być poprawnym YAML między delimitatorami ---. Rzeczywiste umiejętności akumulują długie przykłady w płotach, więc małe nawyki z Bloki kodu Markdown: Kompletny przewodnik z składnią, językami i przykładami — spójne tagi językowe, czytelne fragmenty, ciasne płoty — utrzymują duże pliki w stanie nadającym się do konserwacji dla ludzi i nieco łatwiejsze do skanowania dla modelu.

Wymagane pola to name i description. name staje się trasą slash i kluczem indeksu; pozostaje w małych literach z myślnikami i musi szanować udokumentowany limit długości. description to jedyny tekst, za który wiele sesji kiedykolwiek zapłaci na poziomie zero, więc powinien wyglądać jak wynik wyszukiwania lub ciąg routera („gdy backupy wyglądają na przeterminowane, zweryfikuj najnowszy archiwum i sumę kontrolną”), a nie pierwszy akapit posta w blogu.

Opcjonalne klucze najwyższego poziomu, takie jak version, author i license, pomagają w pakietowaniu huba i audytach. Lista platforms (macos, linux, windows) jest ostrzejsza, niż się wydaje — gdy ustawiona, Hermes całkowicie pomija umiejętność na niepasujących hostach, dlatego umiejętność, która „działa na moim Macu”, może zniknąć w Linux CI 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 trafić do .env i przejść do sandboxów; 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 niepoufne preferencje przechowywane pod skills.config w config.yaml.

Oficjalna dokumentacja kładzie nacisk na dyscyplinę rozmiaru z powodu. Przycinaj description do jego budżetu, umieszczaj procedurę na pierwszym planie i pchnij notatki historyczne lub ogromne macierze opcji do references/, aby częściowe skill_view nadal dawało agentowi coś wykonalnego.

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

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

Postępująca ekspozycja w praktyce

Postępująca ekspozycja to różnica między biblioteką umiejętności, która wydaje się sprężysta, a tą, która spala tysiące tokenów przed pierwszą wiadomością użytkownika. Hermes przechodzi przez trzy koncepcyjne kroki: kompaktowy katalog (nazwy i krótkie opisy), pełny SKILL.md, gdy zadanie pasuje, i — tylko jeśli potrzebne — fragment pliku referencyjnego przez ścieżki skill_view. Zakładaj, że poziom zero to wszystko, co model przeczyta, dopóki nie zadeklaruje się wyraźnie; każde zdanie w description i pierwszy ekran tekstu głównego powinno pomagać w routingu, a nie w opowiadaniu historii.

Praktyczny zarys, który przetrwa częściowe załadowania, to Kiedy używać (wywołacze w prostym języku), Szybki odnośnik (komendy, zmienne środowiskowe, ścieżki plików), Procedura (uporządkowane kroki, których agent nie powinien wymyślać na własną rękę), Pułapki (znane tryby awarii) i Weryfikacja (co oznacza „zielony”). Historyczna narracja, zrzuty dzienników zmian dostawcy i dwudziestowierszowe tabele opcji należą do references/ ze stabilnymi nagłówkami, aby agent mógł pobrać pojedynczą sekcję.

Gdy umiejętność aktywowana jest, Hermes może przepisać ${HERMES_SKILL_DIR} i ${HERMES_SESSION_ID} w treści, aby linie powłoki wskazywały 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 pozostają wyłączone, dopóki skills.inline_shell nie 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ć się lub ukrywać w zależności od tego, które zestawy narzędzi lub narzędzia istnieją w bieżącej sesji. requires_toolsets / requires_tools blokują umiejętność za zdolnościami, które muszą być obecne; fallback_for_toolsets / fallback_for_tools ujawniają tańszą lub lokalną ścieżkę, gdy premium integracja jest nieobecna — fallback DuckDuckGo, gdy płatne API wyszukiwania webowego nie jest skonfigurowane, to kanoniczny przykład.

Te predykaty bezpośrednio kształtują szum 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 punkt pośredni to nazwanie rzeczywistych wymagań, 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ć deklarowane w required_environment_variables. Hermes może pytać, gdy umiejętność ładuje się w lokalnym CLI, utrzymywać wartości w .env i przekazywać je do sandboxów 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 — twórz tekst swojej umiejętności tak, aby pasował do tego zachowania (informuj użytkowników że klucz jest wymagany, a nie *aby wkleili go do Telegrama).

Niepoufne preferencje — domyślne ścieżki, nazwy organizacji, przełączniki funkcji — należą do metadata.hermes.config. Wartości rozwiązują się 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ć Twojego pliku konfiguracji w trakcie zadania.

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

Wsparcie skryptów i zależności

Przewodnik upstream kieruje autorów ku nudnym zależnościom: stdlib Python, curl i własne narzędzia Hermes (web_extract, read_file, terminal). To mniej kwestia czystości niż powtarzalności — każda dodatkowa pip install to kolejna cicha awaria, gdy agent działa w czystym kontenerze.

Gdy parsowanie JSON lub XML jest kłopotliwe, krótki skrypt pod scripts/ plus ścieżka ${HERMES_SKILL_DIR} wygrywa z proszeniem modelu o ponowne wyprowadzenie parserów za każdym razem. 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 zawiedzie, gdy zależność jest nieobecna.

Publikacja, 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-e SKILL.md. Instalacje są skanowane pod kątem oczywistej eksfiltracji, iniekcji i destrukcyjnych wzorców; poziomy zaufania biegną od wbudowanych przez społecznościowe, a niektóre znaleziska czyszczą się tylko z --force, podczas gdy najgorsze przypadki pozostają całkowicie zablokowane.

Format pliku SKILL.md nie jest specyficzny dla Hermes; asystenci skupione na IDE używają tego samego pomysłu postępującego ładowania z innym odkryciem i wywołaczami. Umiejętności Claude i SKILL.md dla deweloperów: VS Code, JetBrains, Cursor to przydatne odczytanie kontrastowe — dyscyplina frontmatter i „ładuj tylko gdy istotne” przenoszą się, nawet gdy instalator i okablowanie komend slash różnią się.

Organizacyjne wdrożenia na szeroką skalę zazwyczaj łączą prywatny tap lub wspólny repozytorium Git z external_dirs dla udostępniania tylko do odczytu, podczas gdy utrzymują kopię zapisywalną przez agenta pod każdym profilem, gdy skill_manage jest pozwolone mutować umiejętności w miejscu.

Rozwiązywanie problemów i optymalizacja

Gdy umiejętność zachowuje się źle, przejdź przez tę listę kontrolną przed przepisaniem tekstu.

• Widoczność — Potwierdź predykaty platforms, requires_* i fallback_for_*. Umiejętność, która „działa na moim Macu”, ale nie w Linux CI, to często strażnik platformy.
• Kolizje nazw — Zduplikowane nazwy przez lokalne i zewnętrzne katalogi podlegają lokalnej precedencji. Zmieniaj nazwy lub przestrzenie nazw agresywnie.
• Układ odkrywania — Nieprawidłowo umieszczony SKILL.md lub zły folder kategorii mogą usunąć umiejętność z indeksowania całkowicie.
• Obciążenie tokenami — Jeśli sesje wydają się powolne, skróć opisy poziomu zero, przenieś głębię do references/ i usuń duplikaty gigantycznych tabel.
• Edycje agenta — Hermes może tworzyć, łatować lub usuwać umiejętności przez skill_manage. Traktuj cenne umiejętności jak kod: przeglądaj diffy, eksportuj snapshoty i celowo resetuj wbudowane umiejętności, gdy aktualizacje odbiegają.

Ścisła pętla regresji wygrywa z ponownym czytaniem całego pliku: hermes chat --toolsets skills -q "Użyj workflow <umiejętność> do <konkretne zadanie>" powinno pokazać agenta pobierającego odpowiedni poziom ekspozycji, zanim zacznie wymyślać. 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 zachowania — System Umiejętności przewodnik użytkownika dla semantyki środowiska wykonawczego, Tworzenie Umiejętności dla reguł skierowanych do autorów, Katalog Wbudowanych Umiejętności dla przykładów kopiuj-wklej i specyfikacja agentskills.io dla wspólnego formatu pliku, z którym Hermes się zgodził.