121 lines
7.1 KiB
Markdown
121 lines
7.1 KiB
Markdown
# Agent Skills を Workflow として ingest
|
||
|
||
## 背景
|
||
|
||
[agentskills.io](https://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 側の意味論には手を入れない
|
||
|
||
## 方針
|
||
|
||
### ロードソース
|
||
|
||
- **`$user/skills/<name>/SKILL.md`** — `$XDG_CONFIG_HOME/insomnia/skills/` 配下。**デフォルトで有効**
|
||
- **`$workspace/skills/`** — **デフォルトで無効**。manifest の `[skills]` セクションで明示指定したパスのみ ingest する
|
||
|
||
```toml
|
||
[skills]
|
||
directories = [".claude/skills", ".cursor/skills"]
|
||
```
|
||
|
||
各パスは workspace root からの相対 or 絶対。manifest の base directory に対して resolve する（既存 path 解決と同方針）。Claude Code / Cursor 等が既に書いている `.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 が複数ソースから来た場合の優先順位:
|
||
|
||
1. `<workspace>/.insomnia/memory/workflow/<slug>.md`（内製 Workflow）
|
||
2. workspace skills（manifest 指定パス）
|
||
3. user skills（`$user/skills/`）
|
||
|
||
衝突時は上位を採用し、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 リンクで
|
||
|
||
## 完了条件
|
||
|
||
- `$user/skills/` 配下の SKILL.md が Workflow として登録され、`/<name>` で呼び出せる
|
||
- manifest で `[skills] directories = [...]` を指定した workspace では、そのパス配下の SKILL.md だけが追加で ingest される。指定しない workspace では workspace 側 skill は 0 件
|
||
- 内製 Workflow と同 slug の skill は内製優先で shadow され、Notification が発行される
|
||
- skill ディレクトリ（SKILL.md 本体・`scripts/`・`references/`・`assets/`）が scope readable に含まれ、agent が Read ツールでアクセスできる
|
||
- frontmatter 違反の skill は warn でスキップされ、他の skill / Pod 起動は影響を受けない
|
||
- 単体テストで frontmatter 検証、Workflow へのマッピング、衝突解決（内製 > workspace > user）、manifest 未指定時の workspace skip が verify される
|
||
|
||
## 実装順序
|
||
|
||
1. SKILL.md パーサと frontmatter 検証を実装。Workflow frontmatter への変換器を含めてテスト完結
|
||
2. `$user/skills/` の loader を Workflow registry に接続
|
||
3. manifest に `[skills] directories: Vec<PathBuf>` を追加し、workspace 側 ingest を実装
|
||
4. 衝突解決と Notification 発行を乗せる
|
||
5. 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
|