Hermes エージェントのスキル作成 — SKILL.md の構造とベストプラクティス
著者：Hermes。高速に読み込まれ、安定して動作するスキル。
Hermes Agentは、繰り返し可能なワークフローを教えるデフォルトの方法としてスキルを採用しています。公式ドキュメントでは、スキルはオープンなagentskills.io仕様に準拠したオンデマンド型ナレッジ文書と説明されており、**プログレッシブ・ディスクロージャー（段階的開示）**によってモデルがまず小さなインデックスを見て、タスクが実際に必要としたときにのみ完全な指示を取得する仕組みになっています。
スキルの作成は、巧妙な表現よりもパッケージングについてです。ランタイムに対していつ手続をロードすべきか、「完了」とみなすステップの順序は何か、成功とサイレントな失敗をどのように区別するかを伝えます。この記事では、SKILL.mdの構造、サポートフォルダ、可視性ルール、シークレット設定と非シークレット設定の区別に焦点を当てます。これらの詳細が、スキルが/slashコマンドに表示されるか、ハブインストールで残存するか、CI上で静かに消えるかを決定します。
Hermesは、アシスタントを単一のチャットインターフェースではなく、推論・検索・メモリ・ツールから構築されたシステムとして扱うより広範な**AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructureクラスター内に位置しています。インストールパス、プロバイダー設定、ゲートウェイ動作、~/.hermesのレイアウトはすべてHermes AI Assistant - Install, Setup, Workflow, and Troubleshootingガイドで詳述されており、日常のシェル操作—hermes skills、プロファイル、ゲートウェイ、メモリ—はHermes Agent CLI cheat sheet — commands, flags, and slash shortcutsでより簡単に参照できます。実際のデプロイメントでは、スキルはプロファイル**（個別の設定、シークレット、メモリ、スキルツリー）から分離を継承します。**Hermes AI Assistant Skills for Real Production Setups**では、個別のMarkdownファイルではなくプロファイルを所有権の単位として扱うことを推奨しており、スキルを命名し、共有external_dirsと単一プロファイルのどちらに何を置くかを決める際に覚えておいてください。
スキルかツールか？
公式の指針は明確です。スキルを使用するのは、能力が主に文章指示とシェルコマンド、そしてHermesがすでに公開しているツールの組み合わせである場合—CLIをラップする、gitを操作する、curlを呼び出す、構造化されたフェッチにweb_extractを使用するなど—です。ツールを使用するのは、APIキーや認証フローの緊密な統合、決定的なバイナリ処理、ストリーミング、または毎回同じ方法で実行される必要があるPythonが必要な場合です。
この境界は実際には重要です。スキルはエージェントコードを変更せずに提供されますが、ツールはレビューとリリースのオーバーヘッドを伴います。ほとんどのチームは、まずスキルから始め、失敗モード（認証リフレッシュループ、バイナリパーサー、厳格な冪等性）が明確になった時点で、もろいコア部分のみをツールに昇格させることで利益を得ます。エージェントスキルとMCPサーバーのどちらを使用すべきかというより広範なアーキテクチャの質問—特に認証情報、ライブ状態、トランザクショナルな書き込みに関して—については、Agent Skills vs MCP Servers decision frameworkを参照してください。
手続とキュレーションされたメモリ
スキルはワークフローの実行方法に答え、Hermesの有界コアメモリはユーザーやプロジェクトについてすでに合意されていることに答えます。スキルはタスクがその説明と一致したときにロードされます。MEMORY.mdとUSER.mdはプロンプト内に小さなキュレーションされた事実層として残ります。この2つのメカニズムは競合するのではなく積み重なり、スナップショット、制限、外部プロバイダーの全体像は**Hermes Agent Memory System: How Persistent AI Memory Actually Works**で詳述されています。
スキルディレクトリの構造
ディスク上では、すべてのスキルは~/.hermes/skills/下のフォルダです。しばしばdevops/やresearch/などのカテゴリ下にネストされています。Hermesは**リーフにSKILL.md**を期待します。それ以外はすべて、指示が散らばるのを避けるために追加する任意の構造です。一般的なパターンは、長いテーブルやベンダードキュメント用のreferences/、出力スケルトン用のtemplates/、決定的なヘルパー用のscripts/、エージェントが再フェッチすべきでない静的ファイル用のassets/です。
このレイアウトは、プログレッシブ・ディスクロージャーが実際どのように機能するかを反映しています。エージェントは、本当に深い付録が必要になるまでメインファイルにとどまることができます。「ハッピーパス」の文章をSKILL.mdに保ち、めったに使わない詳細をreferences/に押し込むことは、トークン予算を守る最も安い方法の一つです。
Hermesはconfig.yamlのskills.external_dirsを通じて外部スキルディレクトリのマージも可能です。これらのパスは発見のためにスキャンされますが、エージェントは依然としてskill_manageを介して主要な~/.hermes/skills/ツリーに書き込みます。ローカル名は外部名をシャドウします。したがって、ホームディレクトリの共有スキルを「修正」しても、同じ外部リポジトリを取得するチームメイトは、ローカルコピーを削除または名前変更するまで編集を確認できません—「自分のマシンでは動く」という混乱の一般的な原因です。
レビューに耐えるSKILL.mdフロントマター
SKILL.mdの本文はMarkdownですが、開きブロックは---区切り子の間の有効なYAMLでなければなりません。実際のスキルは長いフェンシング付きの例を蓄積するため、**Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples**からの小さな習慣—一貫した言語タグ、読みやすい抜粋、緊密なフェンス—は大きなファイルを人間にとって保守可能にし、モデルにとってわずかにスキャンしやすく保ちます。
必須フィールドはnameとdescriptionです。nameはスラッシュルートとインデックスキーになり、ハイフン付きの小文字のままにされ、ドキュメント化された長さ上限を尊重する必要があります。descriptionはレベルゼロで多くのセッションが実際に支払う唯一の文章なので、ブログ投稿の最初の段落ではなく、検索結果やルーター文字列のように読まれるべきです（「バックアップが古くなっているように見える場合、最新のアーカイブとチェックサムを検証する」など）。
version、author、licenseなどのオプションのトップレベルキーはハブパッケージングと監査に役立ちます。platformsリスト（macos、linux、windows）は思われるよりも明確です—設定されると、Hermesは一致しないホストでスキルを完全に省略します。これが、「自分のMacでは動く」スキルがLinux CIでエラーメッセージなしに消える理由です。
Hermes固有のノブはmetadata.hermesの下にあります：tags、related_skills、次のセクションの条件付き可視性フィールド。**required_environment_variablesは.envに配置されサンドボックスに渡されるべきシークレットを宣言します。required_credential_filesはDockerやModalにマウントする必要があるOAuthトークンファイルや他のディスク上の認証情報をカバーします。metadata.hermes.config**はconfig.yamlのskills.config下に保存される非シークレットの環境設定を宣言します。
公式ドキュメントは理由があってサイズ規律を強調しています。descriptionを予算に切り詰め、手続を前面に配置し、歴史的な注記や巨大なオプション行列をreferences/に押し込んでください。部分的なskill_viewでもエージェントに実行可能なものを提供できるようにするためです。
以下は、~/.hermes/skills/devops/backup-check/SKILL.md（または任意のカテゴリフォルダ）に配置してそこから反復できる最小限のSKILL.mdです。
---
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.
プログレッシブ・ディスクロージャーの実践
プログレッシブ・ディスクロージャーは、スナッピーに感じるスキルライブラリと、最初のユーザーメッセージの前に数千のトークンを燃やすライブラリの違いです。Hermesは3つの概念的なステップを踏みます：コンパクトなカタログ（名前と短い説明）、タスクが一致したときの完全なSKILL.md、そして必要であればskill_viewパスを介した参照ファイルのスライスのみ。レベルゼロがモデルが明示的にコミットするまで読むすべてであると仮定してください。descriptionのすべての文と本文テキストの最初の画面はストーリーテリングではなくルーティングを助けるべきです。
部分的なロードに耐える実践的なアウトラインは、When to use（平明な言語でのトリガー）、Quick reference（コマンド、環境変数、ファイルパス）、Procedure（エージェントが即興でなくすべき順序付きステップ）、Pitfalls（既知の失敗モード）、Verification（「グリーン」とは何か）です。物語的な歴史、ベンダーの変更ログダンプ、20行のオプションテーブルは、エージェントが単一のセクションを引き出せるように安定した見出しとともにreferences/に属します。
スキルがアクティブになると、Hermesは本文の**${HERMES_SKILL_DIR}と${HERMES_SESSION_ID}を書き換えることができ、シェル行が手動で構築されたパスなしにインストールフォルダを指すようになります。オプションのインラインシェル**スニペット（!cmd``）は新鮮なコンテキスト（現在のブランチ、ディスク空き容量）を注入できますが、ホスト上で実行され、skills.inline_shellがオンになっていなければ無効のままです—このフラグをスキルソース全体の信頼境界として扱い、便利さのトグルとして扱わないでください。
条件付きアクティベーションとプロンプト衛生
スキルは現在のセッションに存在するツールセットやツールに基づいて表示または非表示にできます。requires_toolsets/requires_toolsは、存在しなければならない機能を基準としてスキルをゲートします。fallback_for_toolsets/fallback_for_toolsはプレミアム統合が欠如しているときに安価またはローカルなパスを表面化します—有料のウェブ検索APIが設定されていない場合のDuckDuckGoフォールバックは典型的な例です。
これらの述語は直接プロンプトノイズを形成します。過度に厳格なrequires_*ルールは、まだhermes toolsセットアップを終えていない新規ユーザーからスキルを隠します。過度に緩いfallback_for_*ルールは、誰かがAPIキーを省略するたびにライブラリの半分を複製します。有用な中間地は、実際の前提条件を命名し、hermes chat --toolsets skillsでテストし、スキルリストが期待どおりに呼吸するかを見ながら意図的にキーやツールセットをトグルすることです。
シークレット、設定、認証ファイル
シークレットはrequired_environment_variablesで宣言されるべきです。HermesはローカルCLIでスキルがロードされたときにプロンプトを表示し、.envに値を永続化し、生のシークレットをモデルトランスクリプトにストリーミングせずにterminalとexecute_codeサンドボックスに渡すことができます。リモートチャットサーフェスはインラインでキーの収集を拒否し、代わりにhermes setupや手動の.env編集を指します—スキルテキストをその動作に合わせましょう（ユーザーにキーが必要だことを伝え、Telegramに貼り付けろとは伝えないでください）。
非シークレット環境設定—デフォルトパス、組織名、機能トグル—はmetadata.hermes.configに属します。値はconfig.yaml内のskills.configに解決され、hermes config showに表示され、モデルがタスク中に設定ファイルを開く必要がないようにスキルメッセージに解決済みの事実として到達します。
ファイル形状の認証情報（OAuthトークンJSON、サービスアカウントキー）はrequired_credential_filesにマッピングされます。これらのファイルが存在する場合、HermesはそれらをDockerにバインドマウントまたはModalジョブに同期できます。事前に宣言することは、「ローカルでは動くがサンドボックスで死ぬ」という典型的なギャップを避けます。
サポートスクリプトと依存関係
アップストリームガイドは作者を退屈な依存関係—標準ライブラリPython、curl、Hermes自身のツール（web_extract、read_file、terminal）—に向けます。これは純粋さよりも再現性についてです—エージェントがクリーンなコンテナで実行するときに、追加のpip installはすべてサイレントな失敗のもう一つです。
JSONやXMLパーシングが面倒な場合、scripts/下の短いスクリプトと${HERMES_SKILL_DIR}パスは、モデルに毎回パーサーを再導出させるよりも優れています。本当にパッケージが必要な場合は、Procedureでインストールコマンドを明記し、Pitfallsで失敗症状を繰り返し、依存関係が欠如しているときに大きく失敗するVerificationコマンドを提供してください。
公開、ハブインストール、信頼
コミュニティスキルはSkills Hubとユーザーガイドがリストする他の発見パス—公式オプションスキル、GitHubスラッグ、skills.shエントリ、.well-knownインデックス、生のSKILL.mdURL—を通じて移動します。インストールは明白な漏洩、注入、破壊的パターンに対してスキャンされます。信頼ティアはbuiltinからcommunityまで続き、いくつかの発見は--forceでしかクリアされず、最悪のケースは完全にブロックされます。
SKILL.mdファイル形状はHermes固有ではありません。IDE中心のアシスタントは異なる発見とトリガーで同じプログレッシブローディングアイデアを使用しています。**Claude Skills and SKILL.md for Developers: VS Code, JetBrains, Cursor**は有用な対照的な読み物です—フロントマター規律と「関連するときにのみロード」は、インストーラやスラッシュコマンド配線が異なっていても引き継がれます。
組織全体のロールアウトは通常、読み取り専用共有のためにプライベートタップまたは共有Gitリポジトリをexternal_dirsと組み合わせていますが、skill_manageがスキルをその場で変更することを許可されている場合、エージェントが書き込み可能なコピーは各プロファイル下に保たれています。
トラブルシューティングと最適化
スキルが悪動作する場合、文章を書き直す前にこのチェックリストに従ってください。
- 可視性 —
platforms、requires_*、fallback_for_*述語を確認してください。「自分のMacでは動く」がLinux CIでは動かないスキルはしばしばプラットフォームガードです。 - 名前衝突 — ローカルと外部ディレクトリ間で重複した名前はローカル優先に従います。激しく名前を変更または名前空間化してください。
- 発見レイアウト — 誤配置された
SKILL.mdや誤ったカテゴリフォルダは、スキルをインデックスから完全に削除できます。 - トークン負荷 — セッションが遅く感じられる場合、レベルゼロの説明を短縮し、深さを
references/に移動し、巨大なテーブルの重複を除去してください。 - エージェント編集 — Hermesは
skill_manageを介してスキルを作成、パッチ、削除できます。貴重なスキルをコードのように扱ってください：diffをレビューし、スナップショットをエクスポートし、アップグレードがドリフトしたときにバンドルされたスキルを意図的にリセットしてください。
ファイル全体を再読するよりも密な回帰ループが優れています：hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>"は、エージェントがフリースタイルになる前に正しいディスクロージャーレベルを引き出すべきです。もしskill_viewを呼び出さない場合、When to useテキストやdescriptionはおそらく人々がリクエストをフレーズする方法と一致しません。
公式参照は動作変更に対して権威を持ちます—ランタイムセマンティクスには**Skills Systemユーザーガイド、作者向けルールにはCreating Skills、コピーペースト例にはBundled Skills Catalog、Hermesが準拠する共有ファイル形式にはagentskills.io specification**。
