hermes-agent-skill-authoring

Name: hermes-agent-skill-authoring
Author: nousresearch

github.com/nousresearchエージェントワークフロー258.1k528 回インストール今日更新

リポジトリ

hermes-agent-skill-authoring について

hermes-agent リポジトリ内のスキルを作成・保守するための手順書です。階層の選択、執筆規約、検証、テスト、ドキュメント更新を扱います。

主な機能

01標準・オプション階層の指針
02フロントマターと説明の規約
03プラットフォームと容量の要件
04作成・編集の手順
05検証・テスト・ドキュメント生成

活用シーン

01hermes-agent に再利用可能なスキルを追加
02リポジトリ内のスキルを編集
03PR 提出前にスキルを確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/nousresearch/hermes-agent --skill hermes-agent-skill-authoring

インストール後、Claude Code で/hermes-agent-skill-authoringを入力して読み込まれたか確認します。

詳細

Hermes-Agent スキルの作成（リポジトリ内）

概要

SKILL.md を配置できる場所は 2 つあります。

ユーザーのローカル: ~/.hermes/skills/<maybe-category>/<name>/SKILL.md — 個人用で、共有されません。skill_manage(action='create') で作成します。
リポジトリ内（このスキルではこちらを扱います）: hermes-agent リポジトリ内の skills/<category>/<name>/SKILL.md または optional-skills/<category>/<name>/SKILL.md — コミットされ、パッケージに同梱されます。write_file と git add を使用します。skill_manage(action='create') はこのツリーを対象にしません。

リポジトリ内のスキルは、リポジトリの厳格な作成基準を満たす必要があります（AGENTS.md の「Skill authoring standards (HARDLINE)」を参照してください。このセクションが基準の正式な参照元であり、このスキルは実践的な手順を説明します）。基準に違反する PR はレビュアーに却下されるため、後から修正するより、最初から基準を満たすほうが手間がかかりません。

使用するタイミング

ユーザーから「このブランチ／リポジトリ／コミットに」スキルを追加するよう依頼された場合
hermes-agent に同梱する再利用可能なワークフローをコミットする場合
skills/ または optional-skills/ 内の既存スキルを編集する場合（小規模な編集には patch、書き直しには write_file を使用します。skill_manage はリポジトリ内のスキルへのパッチにも使えますが、create には使えません）
使用しない場合：~/.hermes/skills/ 内の個人用スキル（skill_manage を使用してください）

まずティアを決める：バンドル対象かオプションか

バンドル対象（skills/<category>/） — 日常的に使われ、幅広いユーザーに役立ち、フットプリントが小さいもの。厳しい基準として、「ユーザーは月に 5 回以上のセッションでこれを読み込む」と自信を持って言えることが必要です。
オプション（optional-skills/<category>/） — ニッチなもの、特定分野向けのもの（ブロックチェーン、ゲーム、金融、特定のアプリなど）、繰り返し発生する仕事やタスク向けのスキル、または容量の大きいもの。hermes skills install official/<category>/<skill> でインストールします。

迷ったらオプションにしてください。 後から昇格させるのは簡単ですが、降格は余計な作業になります。「必要になる人なら誰にとっても役立つ」は、バンドル対象ではなくオプションの根拠です。

カテゴリーは、ツールがどのようなものかに基づいて選び、どう感じられるかで選ばないでください（AI エージェントの CLI は、「生産性向上向け」に感じられても autonomous-ai-agents/ に分類します）。search_files(pattern='*', target='files', path='skills') で既存のカテゴリーを確認し、安易に新しいトップレベルカテゴリーを作らないでください。

ルーター／インデックス／ハブとなるスキルは禁止です。 中核となる内容が兄弟スキルを指すルーティングテーブルであるスキルは、余計な中継を生み、兄弟スキル自身の「使用するタイミング」の条件を重複させます。「代わりにスキル X を読み込む」という案内がなければ内容が空になるようなスキルは作らないでください。カタログと各兄弟スキルの条件で、すでにその役割を果たしています。

必須のフロントマター

バリデーターの正式な参照元：tools/skill_manager_tool.py::_validate_frontmatter。バリデーターの必須要件：

先頭に --- があること（先行する空行なし）。
本文の前に \n---\n で閉じられていること。
YAML マッピングとして解析できること。
name フィールドがあること。
description フィールドがあること（バリデーターの上限は 1024 文字ですが、以下のリポジトリの厳格な基準はさらに厳しいものです）。
閉じる --- の後に空でない本文があること。

リポジトリ標準の形式（バリデーターが必須としていない場合でも、すべてのフィールドが必要です）：

---
name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
description: Concise capability statement, under sixty chars.
version: 0.1.0                    # semver; new skills start at 0.1.0
author: Real Name (github-handle), Hermes Agent
license: MIT
platforms: [linux, macos, windows]   # audit, don't guess — see Platform Gating
metadata:
  hermes:
    tags: [Short, Descriptive, Tags]
    related_skills: [other-in-repo-skill]
---

`description` のルール（厳守 — バリデーターの 1024 は基準ではありません）

60 文字以内。 1 文にします。ピリオドで終わります。
実装ではなく機能を記載し、スキル名やカテゴリ名を繰り返さないでください（インデックスでは、スキルの上にカテゴリが表示されます）。
マーケティング用語（「強力な」「包括的な」「シームレスな」「高度な」）は使わないでください。
システムプロンプトのスキルインデックスに表示される幅は 60 文字です。skill_manage は新規または変更後の説明がこれを超えると拒否し、インデックスは長い既存の説明を単語の切れ目で省略します。
説明に : が含まれる場合は、二重引用符で囲んでください。そうしないと YAML がマッピングとして解析し、ドキュメント生成ツールがクラッシュします。引用符は 60 文字に含めません。

良い例：重要なニュースを出典付きダイジェストで追跡します。 悪い例：ユーザーが指定した競合他社や企業の製品発表、価格変更、資金調達などの監視を依頼した場合に使用します。（240 文字 — レビューで却下）

`author` のルール

まず人間を記載し、次に二次的な協力者として「Hermes Agent」を記載します：Ben Barclay (benbarclay), Hermes Agent。
提供されたスキルで author: Hermes Agent だけにすることは禁止です。エージェントが文章を作成した場合でも（特にその場合）、ツールではなく人間をクレジットしてください。
メンテナーが作成したスキル：Teknium (teknium1), Hermes Agent。

`related_skills` のルール

すべての項目は、PR と同じリポジトリの状態に存在するリポジトリ内のスキルを参照する必要があります。計画段階のスキル、別の PR にあるスキル、~/.hermes/skills/ にしか存在しないスキルは参照しないでください。
各項目を検証してください：search_files(pattern='<name>', target='files', path='skills')（および optional-skills/）。

プラットフォームの制約：鵜呑みにせず監査する

platforms: はホスト OS による読み込みを制限します。スキルの説明文とスクリプトが実際に呼び出すものに基づいて設定してください：

スキルが使用するもの…	`platforms:`
Hermes ツール＋Python 標準ライブラリ＋クロスプラットフォーム CLI のみ	`[linux, macos, windows]`
bash パイプライン、`grep`／`awk`／`sed` の連結、ヒアドキュメント	`[linux, macos]`
`osascript`、`defaults`、`pmset`	`[macos]`
`apt`／`systemctl`／`/proc`	`[linux]`

scripts/ 内で検索する POSIX 専用の兆候：fcntl、termios、pty、os.fork、os.killpg、signal.SIGKILL、os.kill(pid, 0) による生存確認、ハードコードされた /tmp /proc /etc。まずはクロスプラットフォーム対応にするのが原則です（tempfile.gettempdir()、pathlib.Path、psutil.pid_exists）。依存関係が実際に特定プラットフォームに限定される場合にのみ、より限定的な設定を行い、その理由を ## Pitfalls に記載してください。

サイズ制限

SKILL.md 全体は MAX_SKILL_CONTENT_CHARS により 100,000 文字以下に制限されていますが、目安は単純なスキルなら約 100 行、複雑なスキルなら約 200 行です。同種のスキルは 8～14k 文字です。
大量の情報や特定の分岐に関する内容は references/*.md、templates/、scripts/ に置き、SKILL.md 内には記載せず、そこから参照してください。
モデルが呼び出しのたびにパーサーや複雑なロジックをインラインで記述することを期待しないでください。ヘルパースクリプトを scripts/ に用意し、パスを参照してください。

本文の構成（現在のセクション順）

# <Skill> Skill
2-3 sentence intro: what it does, what it doesn't do, dependency stance.

## When to Use          — bulleted triggers (+ "Don't use for:" counter-triggers)
## Prerequisites        — exact env vars, installs, API key sourcing
## How to Run           — canonical invocation through the `terminal` tool
## Quick Reference      — flat command list, no narration
## Procedure            — numbered steps, each with a checkable completion criterion
## Pitfalls             — known limits, things that look broken but aren't
## Verification         — how to prove the skill worked

すべてのセクションがあらゆるスキルに当てはまるわけではありません（純粋な手順タスクのスキルには「クイックリファレンス」がない場合があります）が、「使用する場面」＋実行可能な本文＋「落とし穴」＋「検証」は最低限必要です。マーケティング的な導入、「セットアップ確認」のような何もしない項目、前提条件ですでに説明した環境変数の再説明は削除してください。

生のシェルではなく Hermes ツールを参照する

スキルで機能が必要な場合は、適切な Hermes ツールをバッククォートで囲んで記載してください：terminal、read_file、write_file、patch、search_files、web_search、web_extract、browser_exec、vision_analyze、delegate_task、cronjob。エージェントがすでにラップしているシェルユーティリティ（grep → search_files、cat → read_file、sed／awk → patch、find／ls → search_files target='files'）は記載しないでください。CLI ラッパーのスキルでは、呼び出しを terminal(command="{tool} ...", timeout=...) の形式で記載してください。「foo --version を実行する」のように、生のシェルコマンドを文章で記載するのは、レビューでブロックされる不適合です。スキルが MCP サーバーに依存する場合は、その名前を明記し、「前提条件」にセットアップ手順を記載してください。

マシン固有のパスは絶対に使用しない

リポジトリ相対パス（skills/...、tools/skill_manager_tool.py）を記述してください。/home/<you>/... のパスがコミット済みのスキルに埋め込まれていると、ほかのユーザーが使えなくなり、レビューで即座に問題として指摘されます。

執筆品質の原則

スキルは、エージェントのプロセスをより予測可能にするためのものです。エージェントが、同じ有用な規律に確実に従うようにします。

プロセスの予測可能性を最適化する。 動作を変えない行は削除してください。
適切なコンテキスト量を選ぶ。 説明文は毎ターン参照されるため、詳細は本文またはリンク先の参考資料に記載してください。
各手順の最後に完了基準を示す。 確認可能で、必要に応じて網羅的な基準にします。「変更したファイルをすべて説明する」より「変更したファイルがすべて明記されている」のほうが適切です。
ルールは、それが適用される概念と同じ場所に記載する。
長い説明を繰り返すより、冒頭に力強い言葉を使う（「短い反復サイクル」「根本原因」「回帰テスト」など）。
重複と何もしない指示を削る。 「注意する」「ベストプラクティスに従う」ではモデルの動作は変わりません。確認可能な基準に置き換えるか、削除してください。

テストとドキュメント（リポジトリスキルでは必須）

テストは tests/skills/test_<skill>_skill.py に配置します。使用できるのは stdlib、pytest、unittest.mock のみで、実際のネットワーク接続は禁止です。次のコマンドで実行します：scripts/run_tests.sh tests/skills/test_<skill>_skill.py -q。（汎用テスト tests/tools/test_skill_manager_tool.py が通っても、あなたのスキルを検証したことにはなりません。）
ドキュメントの再生成： python website/scripts/generate-skill-docs.py を実行し、対象範囲を厳守してください。ジェネレーターはすべての自動生成ページを書き換えます。git checkout -- で自分の変更以外を元に戻してください。最終差分には、自分の SKILL.md、自分のスキル専用ドキュメントページ、カタログの1行、website/sidebars.ts への1行の挿入だけが含まれている必要があります（search_files(pattern='<your-slug>', path='website/sidebars.ts') で確認してください。ヒットは1件だけでなければなりません。そうでない場合、そのページは孤立しています）。
.env.example（スキルで新しい環境変数が必要な場合のみ）：コメントで明確に区切ったブロックを1つ追加してください。ファイル内のほかの箇所は変更しないでください。

ワークフロー

対象カテゴリの類似スキルを search_files(target='files') で調査し、類似する SKILL.md を2～3件読んで、文体と構成を合わせます。狭い用途の姉妹スキルを新たに作るより、既存スキルの拡張を優先してください。
階層とカテゴリを決めます（上記を参照）。迷った場合は任意扱いとし、デフォルトで進めず、プッシュする前に確認してください。
write_file で skills/<category>/<name>/SKILL.md（または optional-skills/...）に下書きを作成します。

ローカルで検証します：

import re, pathlib
from ruamel.yaml import YAML
content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
assert content.startswith("---")
m = re.search(r'\n---\s*\n', content[3:])
fm = YAML(typ="safe").load(content[3:m.start()+3])
assert "name" in fm and "description" in fm
assert len(fm["description"]) <= 60, f"description {len(fm['description'])} chars — hardline is 60"
assert fm["description"].endswith(".")
assert "platforms" in fm
assert len(content) <= 100_000

また、すべての related_skills エントリがリポジトリ内に存在することを確認してください。

（前のセクションのとおり）テストを追加し、ドキュメントを再生成します。
アクティブなブランチで Git に追加してコミットし、PR を作成します。
注意： 現在のセッションのスキルローダーはキャッシュされています。新しいセッションを開始するまで、skill_view / skills_list には新しいスキルが表示されません。これは想定された動作であり、バグではありません。

リポジトリ内の既存スキルの編集

小さな修正： リポジトリ内のスキルには skill_manage(action='patch', ...) も patch も使用できます。
大幅な書き換え： write_file で SKILL.md 全体を書き込みます。
補助ファイル： スキルディレクトリ内の references/、templates/、scripts/ に write_file で書き込みます。
必ずコミットする： リポジトリ内のスキルはソースであり、ランタイム状態ではありません。frontmatter を変更した場合は、ドキュメントジェネレーターを再実行してください。

よくある落とし穴

リポジトリ内のスキルに skill_manage(action='create') を使う。 ~/.hermes/skills/ に書き込まれ、リポジトリのツリーには書き込まれません。write_file を使ってください。
バリデーターの制限を標準だと思い込む。 バリデーターでは説明文が1024文字まで許可されますが、レビューでは60文字を超えるものは却下されます。バリデーターは platforms:、作者の形式、テスト、ドキュメントを確認しませんが、レビューでは確認します。
コントリビュートしたスキルに author: Hermes Agent を設定する。 まず人間の貢献者をクレジットしてください。
--- の前に空白を入れる。 先頭に空行または BOM があると、バリデーションに失敗します。
説明が漠然としすぎている、またはトリガーが57文字目より後ろに埋もれている。
related_skills がリポジトリ内に存在しないスキルを指している（ユーザーのローカル環境にある、作成予定、または兄弟 PR にあるスキル）。
同等のスキルを重複して作成する。 まずカテゴリを調査し、同等のスキルを作るのではなく拡張してください。
ドキュメント生成ツールの実行を省略する、または無関係な差分を含めてプッシュする。 どちらも適切ではありません。再生成しないと、ドキュメントページのない孤立したスキルになります。無条件に再生成すると、ほかのスキルの差分が大量に含まれた膨れ上がった差分になります。
現在のセッションで新しいスキルを確認できると思い込む。 ローダーはセッション開始時に初期化されます。
スキルに古い記述を堆積させる。 ルールを追加するときは、それによって置き換えられる古い記述を削除してください。

検証チェックリスト

Markdown 対応

ログインしてコメント

基本情報

作者: nousresearch
リポジトリ: nousresearch/hermes-agent
カテゴリ: エージェントワークフロー
インストール数: 528
GitHub スター: 258,061

問題を報告