diff --git a/docs/specifications/README.md b/docs/specifications/README.md index 54052561..f3c64bd8 100644 --- a/docs/specifications/README.md +++ b/docs/specifications/README.md @@ -6,5 +6,6 @@ |---|---| | [issues-derived-specifications.md](issues-derived-specifications.md) | `issues/` 配下の完了済み issue / plan / report 由来仕様の索引 | | [ndf-knowledge-and-kiro.md](ndf-knowledge-and-kiro.md) | NDF 知識構造、Serena 分離、Kiro CLI 対応 | +| [ndf-skill-inventory.md](ndf-skill-inventory.md) | Skill ごとの利用実績と、維持・統合・削除・発動改善の判定 | Skill の挙動仕様はここに置かない。Skill に関する詳細は対象 Skill の `SKILL.md` を参照する。 diff --git a/docs/specifications/ndf-skill-inventory.md b/docs/specifications/ndf-skill-inventory.md new file mode 100644 index 00000000..4cc4bb02 --- /dev/null +++ b/docs/specifications/ndf-skill-inventory.md @@ -0,0 +1,169 @@ +# NDF Skill 棚卸台帳 + +Skill ごとの実測値と、維持・統合・削除・発動改善の判定を記録する。判定の基準そのものは +[frontmatter 規約](../../plugins/ndf-shared/skills/README.md) ではなく本書の「判断基準」節に置き、 +以降の棚卸もこの表を更新する形で行う。 + +- 測定日: 2026-08-08 +- 測定範囲: 2026-05-20 〜 2026-08-07 の会話ログ 1,943 セッション +- 測定ツール: `/ndf:skill-stats`（`plugins/ndf-shared/skills/skill-stats/scripts/skill-stats.py`） + +再現手順: + +```bash +python3 plugins/ndf-shared/skills/skill-stats/scripts/skill-stats.py \ + --plugin-root plugins/ndf-shared --from 2026-05-20 --to 2026-08-07 --format json +``` + +## 用語 + +| 列 | 意味 | +| --- | --- | +| 配布 | 配布先ランタイム。`C` = Claude Code / `X` = Codex / `K` = Kiro。`plugins/ndf-shared/manifests/` の内容 | +| 行数 | `SKILL.md` の行数。運用上限は 500 行 | +| desc | `description` の文字数。運用目標は 300 文字以内 | +| frontmatter 設定 | `明示専用` = `disable-model-invocation: true` / `常時注入` = `user-invocable: false` / `wtu` = `when_to_use` あり / `引数` = `argument-hint` あり / `tools` = `allowed-tools` あり | +| 計 | 起動数の合計（自動 + 明示） | +| 自動 | エージェントが `Skill` ツールで自動起動した回数 | +| 明示 | 利用者がスラッシュコマンドで起動した回数 | +| 機会 | 利用者の発話に Skill の宣言トリガ語が含まれた回数。トリガ語を宣言していない Skill は測定できないため `—` | + +## 判断基準 + +機能が他 Skill と重複するものは、起動数にかかわらず統合の対象とし、内容は統合先へ残す。 +統合対象を除いた Skill には、起動数と機会数の 2 軸で次の判定を適用する。 + +| 起動数 | 機会数 | 既定の判定 | 例外として判定を覆す条件 | +| ---: | ---: | --- | --- | +| 0 | 0 | 削除 | 別の測定で需要が確認できるとき、削除せず**発動改善**とする。宣言トリガ語が実際の発話と乖離しているだけで、初期実測など本台帳以外の測定では機会があるものが該当する | +| 0 | 1 以上 | 発動改善 | 手順の中身が現在のモデルの標準能力で足り、Skill 固有の知識が残らないとき、**削除**する | +| 1 以上 | 問わない | 維持 | 起動が 1 回にとどまり、機能が他 Skill または単一のコマンドで代替できるとき、**削除または統合**する | + +例外を適用したものは、判定根拠の列に適用した条件を記載する。 + +機会が `—`（トリガ語を宣言しておらず測定できない）の Skill は、機会数を 0 と断定しない。 +起動 0 かつ機会が測定不能なものは、需要を示す実測値が得られていないものとして削除の既定を +準用し、判定根拠の列に「既定を準用」と記載する。準用した既定にも「起動 0 / 機会 0」の行の +例外を同じく適用し、別の測定で需要が確認できるものは削除せず発動改善とする。 + +## 台帳 + +| Skill | 配布 | 行数 | desc | frontmatter 設定 | 計 | 自動 | 明示 | 機会 | 判定 | 判定根拠 | +| --- | --- | ---: | ---: | --- | ---: | ---: | ---: | ---: | --- | --- | +| `branch-fix-strategy` | CXK | 87 | 41 | wtu | 4 | 4 | 0 | 341 | 統合元 | `cherry-pick-pr` とトリガ語が完全重複 | +| `browser-test` | CK | 159 | 37 | 明示専用 / 引数 / tools | 0 | 0 | 0 | — | 統合元 | ブラウザ自動テストのスクリプト作成と実行工程へ集約 | +| `cherry-pick-pr` | CXK | 120 | 48 | 明示専用 / 引数 / tools | 16 | 1 | 15 | — | 統合先 | `branch-fix-strategy` を吸収。起動 16 回で、実行コマンド側の名前を残す | +| `clean` | CXK | 20 | 40 | 明示専用 / tools | 0 | 0 | 0 | — | 統合元 | 初期実測の機会 251 が `merged` の起動数とほぼ一致し、ブランチ整理は実態として `merged` で行われている | +| `codex` | CK | 473 | 50 | wtu | 4 | 4 | 0 | 51 | 統合元 | 本文の大半が共通。`external-ai` へ統合し、ツール差分を `references/` へ分離 | +| `cross-review` | CXK | 478 | 42 | wtu / 引数 / tools | 286 | 14 | 272 | 1473 | 維持 | 起動 286 回。`description` が 42 文字で発動条件を含まず 254 文字の `when_to_use` に依存しているため、明示トリガの要点を `description` へ移す | +| `data-analyst-export` | — | 64 | 57 | wtu / tools | 0 | 0 | 0 | 54 | 削除 | 例外（モデルの標準能力で足りる）。出力形式の指定のみで Skill 固有の知識が残らない | +| `data-analyst-sql-optimization` | — | 48 | 49 | wtu | 0 | 0 | 0 | 14 | 削除 | 例外（モデルの標準能力で足りる）。機会 14 と少なく、48 行の内容はデータ分析エージェントの定義に直接書ける | +| `deepwiki-transfer` | — | 144 | 45 | 明示専用 / wtu / tools | 1 | 0 | 1 | 0 | 削除 | 例外（起動 1 回・代替あり）。最終利用 2026-05-21。取り込み手順は汎用の取得コマンドで代替できる | +| `deploy` | CXK | 114 | 55 | 明示専用 / 引数 / tools | 0 | 0 | 0 | — | 発動改善 | 例外（別の測定で需要を確認）。機会は測定不能だが初期実測の手書きキーワードでは 340 あり、削除の既定を準用せず発動改善とする。破壊的操作のため明示指示専用は維持し、`description` の改善と周知を行う | +| `docker-container-access` | CXK | 76 | 55 | wtu / tools | 6 | 6 | 0 | 33 | 維持 | 起動 6 回 | +| `fix` | CXK | 303 | 34 | wtu / 引数 / tools | 300 | 236 | 64 | 0 | 統合先 | `review-pr-comments` と `resolve-pr-comments` を吸収。起動 300 回で最多 | +| `gemini` | C | 444 | 51 | wtu | 1 | 1 | 0 | 4 | 統合元 | 本文の大半が共通。`external-ai` へ統合し、ツール差分を `references/` へ分離 | +| `git-gh-operations` | CXK | 228 | 44 | wtu / tools | 0 | 0 | 0 | 1840 | 削除 | 例外（モデルの標準能力で足りる）。機会 1,840 は `git add` `git commit` という広すぎるトリガによる誤検出で需要ではない。一般的な Git 操作に Skill 固有の知識が残らない | +| `google-auth` | — | 173 | 29 | wtu / tools | 4 | 4 | 0 | 157 | 維持 | 起動 4 回 | +| `google-chat` | — | 153 | 37 | wtu / tools | 0 | 0 | 0 | 16 | 削除 | 例外（モデルの標準能力で足りる）。機会 16 は通知先の言及にとどまり、手順は汎用の HTTP 呼び出しで代替できる | +| `google-drive` | — | 111 | 55 | wtu / tools | 1 | 1 | 0 | 104 | 維持 | 起動 1 回だが、認証情報の取り回しに Skill 固有の知識がある | +| `implementation-plan` | CXK | 98 | 43 | wtu | 24 | 24 | 0 | 344 | 維持 | 起動 24 回が全数自動起動。現在の `when_to_use` が機能している | +| `investigation-rules` | CXK | 105 | 54 | wtu | 25 | 25 | 0 | 1271 | 維持 | 起動 25 回が全数自動起動。ただしトリガ `調査` が広すぎるため具体化する | +| `issue-plan-strategy` | CXK | 358 | 52 | wtu / 引数 / tools | 141 | 38 | 103 | 142 | 維持 | 起動 141 回 | +| `knowledge-reorg` | — | 269 | 46 | 明示専用 / 引数 / tools | 0 | 0 | 0 | — | 削除 | 既定を準用（起動 0 / 機会は測定不能） | +| `logging-guidelines` | CXK | 112 | 43 | wtu | 0 | 0 | 0 | 112 | 発動改善 | 機会 112 に対し起動 0。`paths` は Claude Code 専用で配布先 3 種のうち Codex/Kiro に効かないため、`description` のトリガ語を `logger` `logging` からログ設計の依頼を表す語へ具体化して 3 ランタイム共通で絞る | +| `markdown-writing` | CXK | 203 | 76 | wtu / tools | 40 | 21 | 19 | 874 | 維持 | 起動 40 回 | +| `mcp-builder` | — | 236 | 31 | — | 0 | 0 | 0 | — | 削除 | 既定を準用（起動 0 / 機会は測定不能） | +| `merged` | CXK | 29 | 30 | 明示専用 / 引数 / tools | 248 | 0 | 248 | — | 統合先 | `clean` を吸収。起動 248 回。改名しない | +| `ml-model-structure` | — | 152 | 55 | wtu / tools | 2 | 0 | 2 | 94 | 維持 | 起動 2 回。`paths` で `analysis/**` に限定する | +| `ndf-policies` | CXK | 10 | 32 | 常時注入 | 0 | 0 | 0 | — | 維持 | Claude Code では `user-invocable: false` により説明のみが常時注入される。Codex / Kiro は同項目を解釈せず通常の Skill として扱うため、Kiro は [Task 0-9](../../issues/ndf-development-skills/07-tasks.md) で `.kiro/steering/` へ移して回避し、Codex は [Task 0-10](../../issues/ndf-development-skills/07-tasks.md) で `description` に「知識として参照する。手順として実行しない」旨を明記する。いずれのランタイムでも自然文からの発動を前提としないため判定対象外 | +| `official-skills-autoloader` | — | 121 | 51 | wtu / tools | 0 | 0 | 0 | 97 | 発動改善 | 機会 97 に対し起動 0。各ランタイムの公式 Skill 提供状況を確認したうえで発動条件を見直す | +| `plan-to-spec` | CXK | 182 | 401 | tools | 0 | 0 | 0 | 2 | 発動改善 | 機会 2 と少なく運用に組み込まれていない。`description` が 401 文字と最長だが、配布が `CXK` で `when_to_use` は Codex/Kiro に効かないため、トリガ語は `description` に残したまま重複した言い換えを削って要約する | +| `playwright-browser-connect` | — | 484 | 49 | wtu / tools | 5 | 5 | 0 | 48 | 統合元 | ブラウザ自動テストのスクリプト作成と実行工程へ集約 | +| `playwright-evidence-drive` | — | 190 | 43 | wtu / tools | 0 | 0 | 0 | 3 | 統合元 | ブラウザ自動テストの証跡とレポート工程へ集約 | +| `playwright-execution` | X | 101 | 51 | wtu / tools | 3 | 3 | 0 | 94 | 統合元 | ブラウザ自動テストのスクリプト作成と実行工程へ集約 | +| `playwright-kit-ops` | X | 119 | 56 | wtu / tools | 2 | 2 | 0 | 22 | 維持 | 実行環境ディレクトリとスクリプトを持つため他へ吸収せず単独で残す | +| `playwright-report` | X | 55 | 40 | wtu / tools | 0 | 0 | 0 | 111 | 統合元 | ブラウザ自動テストの証跡とレポート工程へ集約 | +| `playwright-scenario-test` | — | 68 | 52 | wtu / tools | 3 | 0 | 3 | 23 | 統合元 | ブラウザ自動テストのテスト計画工程へ集約 | +| `playwright-script-creation` | X | 108 | 48 | wtu / tools | 0 | 0 | 0 | 16 | 統合元 | ブラウザ自動テストのスクリプト作成と実行工程へ集約 | +| `playwright-test-planning` | X | 97 | 39 | wtu / tools | 1 | 1 | 0 | 233 | 統合元 | ブラウザ自動テストのテスト計画工程へ集約 | +| `pr` | CXK | 161 | 39 | 明示専用 / 引数 / tools | 173 | 2 | 171 | — | 維持 | 起動 173 回。`disable-model-invocation` を外して自然文から発動させる | +| `pr-tests` | CXK | 31 | 38 | 明示専用 / 引数 / tools | 2 | 0 | 2 | — | 維持 | 起動 2 回。`disable-model-invocation` を外して自然文から発動させる | +| `problem-solving` | CXK | 162 | 62 | wtu | 3 | 3 | 0 | 229 | 維持 | 起動 3 回。バグ・障害対応の判断基準として保持 | +| `python-execution` | CXK | 86 | 44 | wtu / tools | 0 | 0 | 0 | 1207 | 削除 | 例外（モデルの標準能力で足りる）。実行環境の検出はモデルが自力で行える。トリガ `python` `スクリプト` が広すぎ他 Skill の発動を埋もれさせている | +| `qa-security-scan` | — | 56 | 34 | wtu | 0 | 0 | 0 | 0 | 発動改善 | 例外（別の測定で需要を確認）。宣言トリガ語での機会は 0 だが、初期実測の手書きキーワードでは 66 あり、宣言トリガ語が実際の発話と乖離している。削除せず、`description` に発動条件を含めたうえでトリガ語を実態へ寄せる | +| `resolve-pr-comments` | CXK | 146 | 39 | 明示専用 / 引数 / tools | 0 | 0 | 0 | — | 統合元 | 分類・修正・返信が 3 分割されており、`fix` の一連の流れに含まれる | +| `review` | CXK | 337 | 48 | 明示専用 / 引数 / tools | 58 | 1 | 57 | — | 統合先 | `review-branch` を吸収し `--branch` 引数で切り替える。起動 58 回 | +| `review-branch` | CXK | 129 | 46 | wtu / 引数 / tools | 3 | 3 | 0 | 150 | 統合元 | 対象がローカル差分かの違いのみで、レビュー観点は `review` と同一 | +| `review-pr-comments` | CXK | 110 | 44 | wtu / 引数 / tools | 0 | 0 | 0 | 0 | 統合元 | 分類・修正・返信が 3 分割されており、`fix` の一連の流れに含まれる | +| `skill-stats` | — | 103 | 49 | wtu / tools | 0 | 0 | 0 | 1 | 維持 | 測定ツール自体。自然文からの発動を前提としないため判定対象外。配布先がなく（`常時注入` も未指定）ランタイム差分は生じない | +| `statusline` | CK | 51 | 47 | 明示専用 / wtu / tools | 3 | 0 | 3 | 16 | 維持 | 起動 3 回 | +| `sync-main` | CXK | 48 | 44 | 明示専用 / tools | 0 | 0 | 0 | — | 削除 | 既定を準用（起動 0 / 機会は測定不能）。Git 操作 1 コマンドに 48 行を割いており `merged` で代替できる | + +## 判定の内訳 + +| 判定 | 個数 | 意味 | +| --- | ---: | --- | +| 維持 | 16 | そのまま残す。frontmatter の見直しは行う | +| 統合先 | 4 | 他 Skill を吸収する側 | +| 統合元 | 15 | 統合先へ内容を移して削除する側 | +| 削除 | 9 | 内容ごと削除する | +| 発動改善 | 5 | 残したうえで `description` などの発動条件を見直す | + +統合元 15 個は 4 個の統合先と、新設する `external-ai` および 3 個のブラウザ自動テスト +Skill へ集約されるため、統合による減少は 11 個になる。削除 9 個とあわせて 49 → 29 となる。 + +## 測定ツールの修正 + +初回の実測は `skill-stats` が使えず個別実装で行った。以降の計測をツールへ一本化するため、 +次の 2 点を修正した（[#65](https://github.com/devbasex/ai-plugins/pull/65)）。 + +| 不具合 | 原因 | 修正 | +| --- | --- | --- | +| 49 個中 48 個でトリガ抽出に失敗し、ヒット率が算出されない | 抽出対象が `description` に限られ、トリガ語を列挙している `when_to_use` を読まなかった。加えて抽出パターンが `Triggers:` 表記に限られ、`明示トリガ:` と書いている `cross-review` を拾えなかった | 抽出対象に `when_to_use` を加え、見出し語として `Triggers:` `明示トリガ:` `トリガ:` を受ける。両フィールドは独立に走査する | +| 利用者の明示起動を数えず、`cross-review` を 14 と報告する | 明示起動は `` を含む利用者メッセージとして残るが、これをシステム由来の記述として除外していた | `` から明示起動を数え、`Skill` ツール呼び出しと合算して「計 / 自動 / 明示」の 3 列で出力する。トリガ一致の判定からは従来どおり除外する（明示起動は機会ではない） | + +修正後にトリガ抽出へ失敗するのは、トリガ語を宣言していない 13 個だけになる。 + +```text +browser-test, cherry-pick-pr, clean, deploy, knowledge-reorg, mcp-builder, +merged, ndf-policies, pr, pr-tests, resolve-pr-comments, review, sync-main +``` + +`when_to_use` を持たない Skill は 14 個あるが、そのうち `plan-to-spec` は `description` に +トリガ語を宣言しているため抽出に成功する。 + +## 初期実測との差異 + +初期実測（2026-08-07、個別実装）と本台帳（2026-08-08、`skill-stats`）で値が異なる。 +差異の要因は 3 つあり、いずれも既知である。 + +| 要因 | 影響 | +| --- | --- | +| 測定日が 1 日ずれている | 対象セッションが 1,938 → 1,943 件に増え、起動数が数件増減している | +| 機会の判定に使うキーワードが異なる | 初期実測は手書きのキーワード、本台帳は Skill が宣言したトリガ語を使う | +| トリガ語を宣言していない Skill の機会を測れない | 初期実測が値を持っていた `deploy`(340) `clean`(251) は本台帳では `—` になる | + +判定に影響する差異は次の 3 件で、いずれも削除の結論は変わらないが、適用する条件が +「既定（起動 0 / 機会 0）」から「例外（モデルの標準能力で足りる）」へ変わる。 + +| Skill | 初期実測の機会 | 本台帳の機会 | 影響 | +| --- | ---: | ---: | --- | +| `git-gh-operations` | 0 | 1,840 | トリガ `git add` `git commit` がほぼ全セッションに一致する。需要ではなく広すぎるトリガによる誤検出であり、削除の理由は変わらない | +| `google-chat` | 0 | 16 | 通知先の言及にとどまる | +| `data-analyst-sql-optimization` | 0 | 14 | 同上 | + +`deploy` はトリガ語を宣言しておらず機会を測定できないため、発動改善の判定は初期実測の値 +（340）を根拠とする。 + +`qa-security-scan` はトリガ語を宣言しており機会 0 と測定できている。初期実測の手書きキーワード +では 66 だったため、この差は宣言トリガ語（`security scan` `OWASP` など）が実際の発話と乖離して +いることを示す。発動改善の判定はこの乖離を根拠とする。 + +`deploy` へのトリガ語宣言と `qa-security-scan` のトリガ語見直しののち再測定することを、 +frontmatter 見直し後の確認項目とする。 + +## 参照 + +- 棚卸の計画: [issues/ndf-development-skills/02-skill-inventory.md](../../issues/ndf-development-skills/02-skill-inventory.md) +- frontmatter 規約: [plugins/ndf-shared/skills/README.md](../../plugins/ndf-shared/skills/README.md) diff --git a/issues/ndf-development-skills/02-skill-inventory.md b/issues/ndf-development-skills/02-skill-inventory.md index e3e65876..e3ba18ee 100644 --- a/issues/ndf-development-skills/02-skill-inventory.md +++ b/issues/ndf-development-skills/02-skill-inventory.md @@ -204,7 +204,7 @@ when_to_use: "Claude Code 向けの追加トリガのみ" - `merged`(247) / `pr`(171) / `review`(57) / `pr-tests`(2) から `disable-model-invocation` を外し、`description` に発動条件を含める。いずれも明示指示でしか使えていない - `deploy` は環境ブランチへ書き込む破壊的操作のため明示指示専用を維持する。起動ゼロだが機会が 340 あるため、発動改善の対象として `description` を改善する - `when_to_use` は Claude Code 向けの追加トリガが要る Skill にだけ付与する。主要トリガは `description` に置くため、未設定であること自体は不備とせず、一律付与もしない（[03-runtime-conformance.md](03-runtime-conformance.md)） -- `plan-to-spec` は `description` が 401 文字あるため、要点を残して残りを `when_to_use` へ移す。`cross-review` は逆に `description` が 42 文字で発動条件を含まず、254 文字の `when_to_use` に依存しているため、明示トリガの要点を `description` へ移す +- `plan-to-spec` は `description` が 401 文字あるが、配布が `CXK` で `when_to_use` は Codex/Kiro に効かないため、トリガ語は `description` に残したまま重複した言い換えを削って要約する。`cross-review` は逆に `description` が 42 文字で発動条件を含まず、254 文字の `when_to_use` に依存しているため、明示トリガの要点を `description` へ移す - 広すぎるトリガを具体化する（`'python'` → `'uv run'` `'venv が見つからない'`、`'git add'` → `'fatal:'` `'non-fast-forward'`、`'調査'` → `'調査レポートを書く'`） - frontmatter に `<` と `>` を含めない。Agent Skills 仕様がシステムプロンプトへの注入リスクとして警告している - `description` は二重引用符で囲む。Kiro はコロンを含む未引用の `description` を持つ Skill を検出対象から落とす（[kirodotdev/Kiro#8329](https://github.com/kirodotdev/Kiro/issues/8329)） @@ -240,7 +240,7 @@ Codex は起動時に Skill の `name` と `description` に加えてファイ `description` を 1 個あたり 300 文字で運用しても、この総量予算には収まらない。最終構成の 38 個（「Skill 総数の推移」）に 300 文字を割り当てると 11,400 文字となり、`name` とファイルパスを加える前の時点で 8,000 文字を超える。コンテキストウィンドウが判明している場合の 2% は 8,000 文字より厳しくなることがあり、たとえばコンテキストウィンドウが 272,000 のモデルでは 5,440 文字となる。 -したがって 300 文字は**1 個あたりの上限**であって全 Skill に一律で使ってよい枠ではない。実際の配分は総量が予算へ収まることを条件に決め、超過分は `when_to_use` と本文へ逃がす。あわせて、短縮されても暗黙起動が働くよう `description` の先頭に主要な用途とトリガ語を置く（適用方針の先頭トリガ規約）。この 2 点は [07-tasks.md](07-tasks.md) Task 0-7 の検査項目として機械的に検査する。 +したがって 300 文字は**1 個あたりの上限**であって全 Skill に一律で使ってよい枠ではない。実際の配分は総量が予算へ収まることを条件に決め、超過分を逃がす。逃がし先は配布先で選ぶ。Claude Code だけに配布する Skill は `when_to_use` へ移してよいが、`when_to_use` は Codex と Kiro では読まれないため、3 ランタイムへ配布する Skill はトリガ語を `description` に残したまま要約し、手順の説明を本文へ逃がす。あわせて、短縮されても暗黙起動が働くよう `description` の先頭に主要な用途とトリガ語を置く（適用方針の先頭トリガ規約）。この 2 点は [07-tasks.md](07-tasks.md) Task 0-7 の検査項目として機械的に検査する。 ### 未使用項目の導入 diff --git a/issues/ndf-development-skills/07-tasks.md b/issues/ndf-development-skills/07-tasks.md index a30a3371..b4280554 100644 --- a/issues/ndf-development-skills/07-tasks.md +++ b/issues/ndf-development-skills/07-tasks.md @@ -46,7 +46,7 @@ - `merged` / `pr` / `review` / `pr-tests` から `disable-model-invocation` を外し、`description` に発動条件を含める - `deploy` と `cherry-pick-pr` 相当の破壊的操作は明示指示専用を維持する - 主要トリガは `description` に入れる。`when_to_use` は Claude Code 向けの追加トリガが要る Skill にだけ付与し、`description` で足りるものには付けない（[03-runtime-conformance.md](03-runtime-conformance.md)） - - `plan-to-spec` の長い `description` は要点を残して `when_to_use` へ移す。`cross-review` は逆に、`when_to_use` に置いた明示トリガの要点を `description` へ移す + - `plan-to-spec` は配布が `CXK` で `when_to_use` が Codex/Kiro に効かないため、401 文字の `description` はトリガ語を残したまま重複した言い換えを削って要約し、手順の説明は本文へ逃がす。`cross-review` は逆に、`when_to_use` に置いた明示トリガの要点を `description` へ移す - 広すぎるトリガを具体化する - `description` の先頭に主要な用途とトリガ語を置き、合計を Codex の初期一覧予算へ収める（[02-skill-inventory.md](02-skill-inventory.md)「Codex の初期一覧予算」） - `paths` / `effort` / `arguments` / `license` / `metadata` を導入方針に従って付与する @@ -106,6 +106,7 @@ - **変更内容:** - 統合と整理の結果を manifest 3 種すべてへ反映する - `ndf-policies` に旧 Skill 名から新 Skill 名への対応表を記載する + - `ndf-policies` の `description` に「知識として参照する。手順として実行しない」旨を追記する。Codex には `user-invocable: false` の相当機能がなく、通常の Skill として暗黙起動されうるため - バージョンを 5.0.0 へ上げる。版数は `plugin.json` 以外にも散在しており、実測で次の箇所にある | ファイル | 記載箇所 | diff --git a/plugins/ndf-shared/README.md b/plugins/ndf-shared/README.md index 3401d84b..11599ebf 100644 --- a/plugins/ndf-shared/README.md +++ b/plugins/ndf-shared/README.md @@ -18,6 +18,7 @@ bash scripts/build-runtime-plugins.sh --check ## Layout - `skills/` - shared Skill implementations. +- `skills/README.md` - frontmatter conventions for Skill authoring. - `scripts/` - shared helper scripts copied into runtime plugins. - `manifests/claude-skills.txt` - Claude Code published Skill set. - `manifests/codex-skills.txt` - Codex published Skill set. diff --git a/plugins/ndf-shared/skills/README.md b/plugins/ndf-shared/skills/README.md new file mode 100644 index 00000000..50c36bae --- /dev/null +++ b/plugins/ndf-shared/skills/README.md @@ -0,0 +1,166 @@ +# Skill 執筆規約 + +`plugins/ndf-shared/skills/` は 3 ランタイム（Claude Code / Codex / Kiro）へ配布する Skill の +編集元である。ここでは frontmatter の書き方を規約として定める。本文の書き方は各 `SKILL.md` +に委ね、規約は発動と配布に関わる部分だけを扱う。 + +frontmatter の機械検査は未実装である。現在の継続的インテグレーションは +`scripts/build-runtime-plugins.sh --check` / `scripts/validate-runtime-plugins.sh` / +`scripts/check-markdown-links.py` を実行しており、本規約はそれまで人手で確認する。検査スクリプト +`scripts/check-skill-frontmatter.py` の追加は +[棚卸の計画](../../../issues/ndf-development-skills/07-tasks.md) の Task 0-7 で行う。 + +利用実績と維持・統合・削除の判定は +[docs/specifications/ndf-skill-inventory.md](../../../docs/specifications/ndf-skill-inventory.md) +に記録する。 + +## `description` を単一の真実とする + +3 ランタイムに共通する土台は Agent Skills 仕様の 6 項目（`name` / `description` / `license` / +`compatibility` / `metadata` / `allowed-tools`）である。ただし共通に効く度合いは項目ごとに異なる。 + +| 項目 | 3 ランタイムでの扱い | +| --- | --- | +| `name` / `description` | いずれも解釈する。発動判定に効くのは `description` | +| `license` / `compatibility` / `metadata` | 解釈されるが発動には関与しない | +| `allowed-tools` | 仕様上 experimental。Claude Code は解釈するが、Kiro は frontmatter 一覧に載せておらず解釈は保証されない。ツール制限は実装差がある前提で書く | + +`when_to_use` は Claude Code 独自の項目で、Codex と Kiro は文書化していない。仕様は未知の項目を +無視すると定めているため壊れはしないが、**両ランタイムでは `description` だけで発動が判定される**。 + +したがって **発動判定に必要な情報はすべて `description` に入れる**。Claude Code 独自項目は +その上乗せとして扱う。 + +```yaml +--- +name: review +description: "Review a PR or local branch diff and post an approve/changes verdict. Use when asked to review a PR, check a diff before merge, or self-review a branch (レビューして / PR確認 / マージ前チェック)." +when_to_use: "Claude Code 向けの追加トリガのみ。description で足りるなら付けない" +--- +``` + +規則: + +- `description` は「何をするか」と「いつ使うか」の両方を書く +- **主要な用途とトリガ語を最初の 1 文に置く。** Claude Code は一覧の 1 項目あたり 250 文字を + 超えた分を切り詰め、Codex は初期一覧が予算を超えると `description` を先頭から残して短縮する。 + どちらも後半へ置いたトリガ語は暗黙起動の判定に届かない +- `description` は二重引用符で囲む。`:` に空白が続く文字列を未引用で書くと YAML はマッピングと + 解釈して構文エラーになり、Kiro はその Skill を検出対象から落とす + （[kirodotdev/Kiro#8329](https://github.com/kirodotdev/Kiro/issues/8329)） +- frontmatter に `<` と `>` を含めない。Agent Skills 仕様がシステムプロンプトへの注入リスクと + して警告している +- `when_to_use` は Claude Code 向けの**追加**トリガが要る Skill にだけ付ける。`description` の + 言い換えにしない。未設定であること自体は不備ではない + +## 発動制御の 4 分類 + +| 分類 | Claude Code | Codex | Kiro | 対象 | +| --- | --- | --- | --- | --- | +| 自動発動（既定） | 追加トリガがあれば `when_to_use` を併記 | 既定で暗黙起動可 | 自動ロード | 知識・判断基準・ワークフロー | +| パス限定自動発動 | 上記 + `paths` | `paths` 無効 | `paths` 無効 | 特定ディレクトリでのみ意味を持つもの | +| 明示指示専用 | `disable-model-invocation: true`（引数を取るなら + `argument-hint`） | 現状は制御手段なし。`description` に明示指示専用である旨を記載する | 制御手段なし。`description` に「利用者が明示的に指示したときのみ実行する」と記載 | 破壊的操作・外部への書き込み | +| 常時注入のみ | `user-invocable: false` | 相当機能なし | 相当機能なし | `ndf-policies` | + +- Codex には `/agents/openai.yaml` の `policy.allow_implicit_invocation: false` という + 相当機能があるが、現在の `plugins/ndf-codex` 配布物はこのファイルを生成していないため利用でき + ない。生成処理の追加は + [棚卸の計画](../../../issues/ndf-development-skills/07-tasks.md) の Task 0-8 で行う +- 「常時注入のみ」に相当する機能は Codex と Kiro にない。両ランタイムは `user-invocable: false` + を解釈せず、この分類の Skill も通常の Skill として扱う。唯一の対象である `ndf-policies` は + 3 ランタイムすべてへ配布している（`plugins/ndf-shared/manifests/`）ため、Codex では暗黙起動 + されうる。したがってこの分類の Skill は `description` に**「知識として参照する。手順として + 実行しない」旨を明記する**。Kiro は Skill として配らず `.kiro/steering/` へ常時指示として + 置き換えることで回避する（[棚卸の計画](../../../issues/ndf-development-skills/07-tasks.md) + の Task 0-9）。`description` の書き換えは同計画の Task 0-10 で行う +- **Claude Code では** `disable-model-invocation: true` の Skill は `description` がコンテキスト + へ載らず、`user-invocable: false` は載る。Codex と Kiro にはこのキーがなく `description` は + 常に読まれるため、明示指示専用にする Skill は `description` 自体へ「利用者が明示的に指示した + ときのみ実行する」と書き残す +- 明示指示専用にしてよいのは、実行してしまうと取り消しが難しい操作に限る。日常的に自然文で + 依頼される Skill に付けると、エージェントは Skill を使わず独自手順で実行する +- `disable-model-invocation: true` と `user-invocable: false` を同時に指定しない。誰も起動 + できなくなる + +## トリガ語の規則 + +### 一意であること + +トリガ語は Skill 間で重複させない。重複すると、同じ依頼に対して複数の Skill が起動を競い、 +どちらが選ばれるかが依頼文の細部に左右される。 + +重複を見つけたら、次のどちらかで解消する。 + +1. 機能が重複しているなら Skill 自体を統合する +2. 機能が異なるなら、区別できるところまでトリガ語を具体化する + +### 広すぎるトリガを置かない + +ほぼ全セッションに一致するトリガ語は、その Skill を発動させる代わりに他 Skill の発動を +埋もれさせる。実測では次の例が問題になった。 + +| Skill | 問題のあるトリガ | 機会 | 具体化した例 | +| --- | --- | ---: | --- | +| `python-execution` | `python`、`スクリプト` | 1,207 | `uv run`、`venv が見つからない` | +| `git-gh-operations` | `git add`、`git commit` | 1,840 | `fatal:`、`non-fast-forward` | +| `investigation-rules` | `調査` | 1,271 | `調査レポートを書く` | + +目安として、**その語が出たときに必ずその Skill を使ってほしいか**を基準にする。「使うことも +ある」程度の語はトリガにしない。 + +## 上限値 + +| 項目 | 上限 | 根拠 | +| --- | --- | --- | +| `name` | 64 文字。小文字英数とハイフンのみ。先頭末尾ハイフン不可、連続ハイフン不可 | Agent Skills 仕様（必須） | +| `name` と親ディレクトリ名 | 一致させる | プロジェクト規約。仕様上は任意（Claude Code は `name` 省略時にディレクトリ名を使う） | +| `description` | 1,024 文字。運用目標は 300 文字以内 | 仕様上限 / 運用目標 | +| `description` + `when_to_use` | 1,536 文字 | Claude Code。超えると一覧で切り詰められる | +| `compatibility` | 500 文字 | Agent Skills 仕様 | +| `SKILL.md` 行数 | 500 行。超えるものは補助ファイルへ分割 | 仕様の推奨、コンパクション対策 | +| `SKILL.md` 本文 | 5,000 トークン | 仕様の推奨 | +| Claude Code の初期 Skill 一覧の合計 | コンテキストウィンドウの 1%。不明な場合は 8,000 文字。1 項目あたり 250 文字で切り詰め | Claude Code 公式ドキュメント | +| Codex の初期 Skill 一覧の合計 | コンテキストウィンドウの 2%。不明な場合は 8,000 文字 | Codex 公式ドキュメント | + +運用目標の 300 文字は仕様上限より厳しい。全 Skill 分の `description` が常時注入されるため、 +仕様上限は 1 個で使い切ってよい量ではない。 + +Codex は起動時に全 Skill の `name` と `description` とファイルパスを一覧として読み込み、この +一覧に総量予算を設けている。予算を超えると Codex はまず `description` を短縮し、それでも +収まらない場合は一部の Skill を一覧から省略して警告を表示する。**300 文字は 1 個あたりの +上限であって、全 Skill に一律で使ってよい枠ではない。** 総量が予算へ収まることを条件に配分し、 +超過分を逃がす。 + +逃がし先は配布先で選ぶ。Claude Code だけに配布する Skill は `when_to_use` へ移してよい。 +一方 `when_to_use` は Codex と Kiro では読まれないため、この 2 ランタイムへも配布する Skill の +トリガ語を `when_to_use` へ移すと、そのランタイムでは一覧に載らず暗黙起動に効かなくなる。 +3 ランタイムへ配布する Skill はトリガ語を `description` に残したまま要約し、手順の説明を +本文へ逃がす。 + +Claude Code のコンパクション後は、呼び出し済み Skill の先頭 5,000 トークンのみが再添付され、 +全体で 25,000 トークンの共通予算を新しい順に消費する。480 行級の Skill は圧縮後に後半が +失われるため、500 行上限は推奨ではなく必須条件として扱う。 + +## 項目の使い分け + +| 項目 | 使いどころ | +| --- | --- | +| `paths` | 特定ディレクトリを扱うときだけ意味を持つ Skill。Claude Code 独自 | +| `context: fork` + `background: false` | 長時間実行をメインコンテキストから隔離したい Skill。`background: false` がないと結果が非同期で返る。組み込みの `/goal` と併用する Skill には使わない（セッション単位の Stop フックとして動く評価器が分離実行では働かない） | +| `effort: high` | 判断の質が結果を大きく左右する設計レビュー系 | +| `arguments` | `argument-hint` を持つ Skill。引数の手動解析を名前付き引数に置き換える | +| `license` / `metadata` | 上流の Skill を参考にした場合に、参照元名・固定コミット・ライセンスを記録する | + +## 配布先を広げる際の制約 + +`when_to_use` / `argument-hint` / `arguments` / `disable-model-invocation` / `user-invocable` / +`paths` は Claude Code 独自である。仕様準拠のランタイムは未知の項目を無視するが、claude.ai への +アップロードや Skills API 経由では `Unexpected key(s) in SKILL.md frontmatter` のエラーになる。 +現在の配布先 3 種では問題にならないが、配布先を広げる際の制約として記録する。 + +## 参照 + +- [Agent Skills Specification](https://agentskills.io/specification) +- [Claude Code — Skills](https://code.claude.com/docs/en/skills) +- [Codex — Build skills](https://learn.chatgpt.com/docs/build-skills) +- [Kiro — Skills](https://kiro.dev/docs/skills/)