スキルシステム Skills

源码版本v2026.7.20

職務

Skill は Tool より高階な能力単位:再利用可能で、frontmatter を持つフロー(agentskills.io 規範に準拠)であり、ドメイン別に skills/<category>/ に配置される。ツール (tool) の「静的関数」と異なり、スキルは学習ループによって作成・書き換え・精製可能で、agent が「使うほど賢くなる」媒体となる。スキルは skills_tool 経由で主ループに露出する。

設計動機

なぜスキルをフラットではなく category 別のディレクトリに分けるのか? スキル数は利用とともに増える(ユーザーが足した、hub から同期した、学習ループが生成した、すべてが ~/.hermes/skills/ に入る)。フラットにすると skills_list が返すリストはすぐノイズになる。category を使うと、progressive disclosure の第一層は「research スキルが一組あります」という見え方になり、50 行の個別スキル名を並べずに済む。各 SKILL.md は単ファイルで定義(frontmatter 付き)で、skills/<category>/<skill>/references/ のサブファイルでオンデマンド読み込みを行い、token を一気に食いつぶさない。

bundle はもう一層のラップだ。複数のスキルを一つの slash コマンドで読み込む。「バックエンド開発」のようなシナリオでは code review、TDD、PR の三スキルを同時に掛けたいが、いちいち /skill するのは細かすぎる。

主要ファイル

skills/ ディレクトリ — ドメイン別グループ(apple、computer-use、research、software-development、yuanbao…)。各スキルは次の形をとる。

skills/
├── my-skill/
│   ├── SKILL.md           # 主指令(必須)
│   ├── references/        # 補助ドキュメント
│   │   ├── api.md
│   │   └── examples.md
│   ├── templates/         # 出力テンプレート
│   └── assets/            # 添付(agentskills.io 標準)
└── category/
    └── another-skill/
        └── SKILL.md

SKILL.md の冒頭は YAML frontmatter(name/description/version/platforms/prerequisites…)で、以下が本文の指令。name は 64 文字、description は 1024 文字まで。この二つが progressive disclosure の第一層 skills_list が返す唯一の内容で、token を保つ。

skills_tool — スキルをツールとして主ループに露出する。二つのツールを登録する。

python

registry.register(
    name="skills_list",
    toolset="skills",
    schema=SKILLS_LIST_SCHEMA,
    handler=lambda args, **kw: skills_list(
        category=args.get("category"), task_id=kw.get("task_id")
    ),
    check_fn=check_skills_requirements,
    emoji="📚",
)

registry.register(
    name="skill_view",
    toolset="skills",
    schema=SKILL_VIEW_SCHEMA,
    handler=_skill_view_with_bump,
    check_fn=check_skills_requirements,
    emoji="📚",
)

skills_list は name + description + category だけを返す(progressive disclosure の第一層)。skill_view は完全な SKILL.md を読み込む(第二層)。reference/template などの補助ファイルはオンデマンドで skill_view(name, file_path="references/api.md") で引く(第三層)。_skill_view_with_bump は成功後に bump_view / bump_use を呼んで使用計数を更新し、curator の stale タイマーが使われていないスキルを片付ける。

skill_manager_tool — スキル管理(一覧/閲覧/有効化)
skills_hub — スキルハブ同期(agentskills.io 互換)
skills_sync — ローカルとリモートのスキル同期
skill_bundles — スキル束のパッケージ化、プロンプト (prompt) に注入。bundle は ~/.hermes/skill-bundles/*.yaml の小さなファイルだ。

yaml

name: backend-dev
description: Backend feature work — code review, testing, PR workflow.
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Optional extra guidance to inject above the skill bodies.

/<bundle-name> が build_bundle_invocation_message を呼び、すべてのメンバースキルの SKILL.md を一つの user message にまとめる。bundle と skill が同名のときは bundle が優先する——ユーザーがわざわざ同名にしたのは、たまたま同名だったスキルを上書きしたいからだ。欠落しているメンバースキルはエラーを出さず、結果に「どれがスキップされたか」を付記するだけ。

skill_preprocessing — スキル内容の前処理。${HERMES_SKILL_DIR} / ${HERMES_SESSION_ID} のテンプレート変数を置換し、!date +%Y-%m-%d`` のようなインライン shell snippet を実行する。インライン shell が失敗したときは例外を投げず [inline-shell error: ...] マーカーを返し、一つの壊れた snippet がスキルメッセージ全体を道連れにしない。
スキルノードと辺:125-193 — build_skill_nodes / build_edges、スキルを学習グラフに構成

データフロー

起動期 skill_preprocessing(agent/skill_preprocessing.py)が skills/<category>/ を走査し、frontmatter を読む。
skill_bundles(agent/skill_bundles.py)が関連スキルを束ねて、build_turn_context:268 経由でこのラウンドのプロンプト (prompt) に注入する。
provider がスキル呼び出しを決める → tool_call skills → tools/skills_tool.py が当該スキルのフローを読み込んで実行する。
実行結果を主ループに戻す。
学習ループがこのラウンドをバックグラウンドで審視し、次のことが起きうる:
- 新スキル作成(learning_mutations)
- 新スキルを学習グラフ agent/learning_graph.py:125 に登録
- tools/skills_sync.py 経由でスキルハブへ同期

境界と失敗

パストラバーサル:skill name は ~/.hermes/skills/ に繋いでファイルを探す。_skill_lookup_path_error は .. セグメント、絶対パス、Windows ドライブレターを拒否する。さもないと name="../outside" で skills ディレクトリの外のファイルが読めてしまう。
prompt injection:SKILL.md の内容に「ignore previous instructions」「system prompt:」「]]>」といったパターンがあると _INJECTION_PATTERNS がフラグを立てる。サードパーティのスキル(hub から同期したもの)は信頼できない内容で、主ループが読み込むときに sanitize する。
bundle のメンバー欠落:build_bundle_invocation_message は欠落/無効化されたメンバースキルを missing / disabled リストに記録するだけでエラーにしない——bundle は寛容に読み込み、何個か足りなくても残りのスキルに影響しない。
キャッシュの陳腐化:skills/ の走査は O(#dirs) stat で、署名はディレクトリ mtime + disabled 集合 + プラットフォームを含む。しかし単一ファイル SKILL.md のその場編集は自身の mtime しか bump せず、ディレクトリ署名からは見えない。だから 30s TTL の安全網を追加している。

まとめ

スキル = 進化可能な高階フロー。frontmatter で記述し、ファイルがそのまま定義になり、学習ループが書き換える。ツールとの関係:ツールはスキルフロー内で呼ばれる原子、スキルは「どうツールを組み合わせて一種のタスクをこなすか」の知識。スキルの進化機構は学習ループを参照。

スキルシステム Skills ​

職務 ​

設計動機 ​

主要ファイル ​

データフロー ​

境界と失敗 ​

まとめ ​

スキルシステム Skills

職務

設計動機

主要ファイル

データフロー

境界と失敗

まとめ