8.1 KiB
Agent Skills を Workflow として ingest
背景
agentskills.io の "Agent Skills" は Anthropic 発のオープン標準で、Claude Code / Cursor / OpenCode / Gemini CLI / Goose / OpenHands など主要な coding agent 群が採用している。ユーザーが既に書いた skill を insomnia に持ち込めるようにすることで、他ツールと能力資産を共有できる。
insomnia 側の一級概念は Workflow (/<slug>、tickets/workflow.md)。SKILL.md 形式は Workflow と意味的にほぼ同型（procedural な指示本体 + メタデータ + 付随リソース）であり、別経路として並列管理するより Workflow にマップして ingest する方が呼び出し UX (/<slug>) と内部経路を一本化できる。
docs/plan/memory.md が「SKILL.md 形式は採用しない」と書いているのは Knowledge (#<slug>) の表現形式としての話で、本チケットの「Workflow への ingest 経路」とは矛盾しない。
Skill の骨格 (仕様要旨)
skill-name/
├── SKILL.md # 必須: YAML frontmatter + Markdown 本体
├── scripts/ # 任意: 実行コード
├── references/ # 任意: 詳細ドキュメント
└── assets/ # 任意: テンプレート等の静的資産
SKILL.md frontmatter:
| フィールド | 必須 | 制約 |
|---|---|---|
name |
○ | 1-64 chars, [a-z0-9-]+, ディレクトリ名と一致 |
description |
○ | 1-1024 chars, 非空 |
license |
自由文 | |
compatibility |
1-500 chars | |
metadata |
任意の key-value map | |
allowed-tools |
experimental |
前提チケット
tickets/workflow.md— Workflow loader //<slug>resolve /model_invokation注入の本実装。本チケットはその ingest 経路を増やすだけで、Workflow 側の意味論には手を入れない
方針
ロードソース
skill は manifest の [skills] directories で明示指定したパスのみ ingest する。$config_dir/skills/ の自動ロードや builtin skills は持たない — manifest に書かれていないディレクトリは決して読まれない。
[skills]
directories = ["~/skills", ".claude/skills", ".cursor/skills"]
各パスは manifest の base directory に対して resolve する（既存 scope.allow.target 等と同方針）。絶対パスでも相対パスでもよく:
- user manifest layer (
$config_dir/manifest.toml) に書けば全 workspace 共通で使う skill 集を持てる - project manifest layer に書けば workspace 固有の
.claude/skills/.cursor/skills/をそのまま流用できる
ビルトイン $insomnia/skills/ は不要になるまで作らない（前ガイドラインのまま）。
SKILL → Workflow マッピング
| SKILL.md frontmatter | Workflow frontmatter | 備考 |
|---|---|---|
name |
（ファイル名 = slug として扱う） | name がディレクトリ名と一致することは仕様上の不変。slug としてはディレクトリ名を使用 |
description |
description |
そのまま |
| — | model_invokation |
true 固定。agentskills の progressive disclosure（メタデータ常時注入）と整合 |
| — | user_invocable |
true 固定 |
| — | requires |
空配列。SKILL 側に概念がない |
license / compatibility / metadata |
— | 保持はするが Workflow 実行には影響しない |
allowed-tools |
— | permission-extension-point.md が Permission 層を整備するまで tracing::warn! して無視 |
Workflow 本文には SKILL.md 本体（frontmatter 直下の Markdown）をそのまま使う。
scripts / references / assets
skill ディレクトリ全体（SKILL.md 本体だけでなく scripts/ references/ assets/）を Pod の Scope に permission = read で自動 union する。scripts/ の実行は Bash ツール + Permission 層（permission-extension-point.md）が整うまで Read 経由の閲覧に留める。
衝突解決
同一 slug が複数ソースから来た場合の優先順位:
<workspace>/.insomnia/memory/workflow/<slug>.md（内製 Workflow）- manifest
[skills] directoriesの各エントリ（列挙順で解決。先に書かれたディレクトリが上位）
衝突時は上位を採用し、shadow した側について Event::Notification を発行する。「明示的に書かれた内製 Workflow が外部資産より強い」順に並べる。
検証
- frontmatter は SKILL 仕様通り検証。
name↔ ディレクトリ名一致、description長さ、nameの文字種制約を hard error - 検証エラーは個別 skill 単位で skip +
tracing::warn!。一個の壊れた SKILL が Pod 起動を止めない（内製 Workflow とは違う扱い: 外部資産は緩く受ける） - 未知フィールドは無視
範囲外
allowed-toolsの実効化 →permission-extension-point.md待ち- skill 専用の実行機構（
scripts/の自動実行）— Bash ツールと Permission 層で自然に扱う - skill の自動生成（Hermes 風 Skill Library）— memory 系チケットで別途、本チケットの ingest 経路を再利用する側
- ビルトイン skill (
$insomnia/skills/) — 必要になるまで追加しない - skill 間依存の解決 — 独立単位、相互参照は本体の Markdown リンクで
完了条件
- manifest の
[skills] directories = [...]で指定したパス配下の SKILL.md が Workflow として登録され、/<name>で呼び出せる [skills]セクションが無い manifest では skill 由来の Workflow は 0 件 ($config_dir/skills/等の暗黙ロードはしない)- 内製 Workflow と同 slug の skill は内製優先で shadow され、Notification が発行される
- skill ディレクトリ（SKILL.md 本体・
scripts/・references/・assets/）が scope readable に含まれ、agent が Read ツールでアクセスできる - frontmatter 違反の skill は warn でスキップされ、他の skill / Pod 起動は影響を受けない
- 単体テストで frontmatter 検証、Workflow へのマッピング、衝突解決（内製 > skill）、manifest 未指定時の skill 0 件が verify される
実装順序
- SKILL.md パーサと frontmatter 検証を実装。Workflow frontmatter への変換器を含めてテスト完結
- manifest に
[skills] directories: Vec<PathBuf>を追加し、ingest 経路を実装 - 衝突解決と Notification 発行を乗せる
- skill ディレクトリの Scope union（read 自動 allow）
各ステップ終了時点でビルド通過・既存テスト合格を維持する。
参照
- 仕様本体: https://agentskills.io/specification
- 採用状況: https://agentskills.io/home
- Anthropic 公式サンプル: https://github.com/anthropics/skills
- 検証 CLI: https://github.com/agentskills/agentskills/tree/main/skills-ref
- 前提:
tickets/workflow.md - 関連:
tickets/permission-extension-point.md（allowed-tools実効化の受け皿）、docs/plan/workflow.md、docs/plan/memory.md、docs/ref/memory-systems.md§Skill Library
Review
- 状態: Approve (Round 2)
- レビュー詳細: ./agent-skills.review.md
- 経緯:
- 2026-05-04: 初回レビュー Approve (旧仕様: 2 ソース構成)
- 2026-05-05:
$config_dir/skills/の自動 ingest を廃止、skill ロードソースを manifest[skills] directoriesのみに統合する設計変更。実装もWorkflowSource::WorkspaceSkill/UserSkill2 バリアントから単一のSkill { dir }に簡略化済み - 2026-05-04: Round 2 レビュー Approve。新設計の完了条件をすべて満たし、Round 1 で挙げた user_skills_dir 関連の懸念は設計変更で構造的に解消。non-blocking として manifest crate の stale doc コメント (
crates/manifest/src/lib.rs:47-62) と受け皿チケット (tickets/permission-extension-point.md:61) の旧バリアント名参照が残るのみ