feat: Skill 棚卸台帳の作成と frontmatter 規約の明文化 (0-1)

[takemi-ohama]

Summary

全 Skill の利用実績を記録する台帳を作り、frontmatter の書き方を規約として明文化する。

• docs/specifications/ndf-skill-inventory.md（新規）— 全 49 Skill について 行数 / description 文字数 / frontmatter 設定 / 起動数（計・自動・明示）/ 機会数 / 判定 / 判定根拠 を記録する。判断基準の表と再現手順も同じ文書に置き、以降の棚卸はこの台帳を更新する形で行う。
• plugins/ndf-shared/skills/README.md（新規）— description を発動判定の単一の真実とする方針、発動制御の 4 分類、トリガ語の一意性ルールと広すぎるトリガの禁止例、上限値、paths / effort / arguments などの使い分けを規定する。

測定ツール skill-stats の集計不具合（when_to_use からのトリガ抽出、明示トリガ: 表記の受理、利用者の明示起動のカウント、「計 / 自動 / 明示」の 3 列出力）は先行する #65 で修正済みのため、本 PR ではその出力を実測値として採用し、想定どおりに動くことを確認した。

初期実測との差異

計画時の実測（2026-08-07、個別実装）と、修正後の skill-stats による実測（2026-08-08）で機会数が食い違う。原因は機会の判定に使うキーワードの違いで、計画時は手書きのキーワード、台帳は Skill が宣言したトリガ語を使う。

判定に影響するのは 3 件で、いずれも削除という結論は変わらないが、適用する条件が「既定（起動 0 / 機会 0）」から「例外（モデルの標準能力で足りる）」へ変わる。台帳の判定根拠にはこの変更後の条件を記載した。

Skill	計画時の機会	台帳の機会	内容
git-gh-operations	0	1,840	トリガ git addgit commit がほぼ全セッションに一致する。需要ではなく広すぎるトリガによる誤検出
google-chat	0	16	通知先の言及にとどまる
data-analyst-sql-optimization	0	14	同上

deploy(340) と qa-security-scan(66) はトリガ語を宣言していないため skill-stats では機会を測れない。発動改善という判定は計画時の値を根拠とし、トリガ語を宣言したうえでの再測定を frontmatter 見直し後の確認項目とした。

Test plan

• 修正後の skill-stats が 2026-05-20〜2026-08-07 の期間で「計 / 自動 / 明示」を出力する（1,943 セッション、計 1,359 / 自動 399 / 明示 960）
• トリガ抽出に失敗する Skill が 13 個だけになる（when_to_use を持たない 14 個のうち plan-to-spec は description にトリガを持つ）
• cross-review のトリガが when_to_use にあっても description へ移しても、Triggers: 表記でも同じ結果になる（Task 0-7 の前提）
• 台帳の判定内訳が計画と一致する（統合元 15 / 統合先 4 / 維持 16 / 削除 9 / 発動改善 5 → 49 個、統合 -11 と削除 -9 で 29 個）
• python3 scripts/check-markdown-links.py が成功する
• bash scripts/build-runtime-plugins.sh --check が差異を検出しない
• bash scripts/validate-runtime-plugins.sh と claude plugin validate が成功する

release PR: #66
plan: issues/ndf-development-skills/07-tasks.md

[takemi-ohama]

🤖 cross-review | round 1 | gemini | COMMENT

棚卸台帳の実測値と判定根拠の整合性、および frontmatter 規約の正確性を中心に確認しました。
qa-security-scan および sync-main において、表の数値と説明文に矛盾が生じている箇所があるため、実態に合わせた修正をお願いします。また、frontmatter 規約中の Agent Skills 仕様や YAML 構文に関する記述の修正を提案しています。

[takemi-ohama]

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

PR 横断の追加所見はありません。インラインの修正アクションを確認してください。

[takemi-ohama]

/ndf:fix round 1 対応完了

修正コミット: da9442f

cross-review round 1 の指摘 10 件（codex 5 / gemini 5、うち重複 2 組）に対応しました。重複を除いた実質 8 件すべてを修正し、10 スレッドとも返信のうえ Resolve しています。deferred / rejected は 0 件です。

対応内訳（独自再判定後）

重要度	件数	内容
major	4	未実装スクリプトの参照、Codex agents/openai.yaml 未生成、qa-security-scan の測定可否の矛盾、logging-guidelines の paths 依存
minor	4	sync-main の判定根拠、argument-hint の必須扱い、name の親ディレクトリ一致の出典、未引用 description の理由

主な修正

docs/specifications/ndf-skill-inventory.md

• qa-security-scan は when_to_use に Triggers: を宣言しており skill-stats で機会 0 と測定できているため、「測定できない」とする記述を削除。宣言トリガ語（機会 0）と初期実測の手書きキーワード（66）の乖離を発動改善の根拠として明記
• sync-main の判定根拠を再測定値どおり「既定（起動 0 / 機会 0）」へ修正
• logging-guidelines の改善方針を、Claude Code 専用の paths から 3 ランタイムで効く description のトリガ具体化へ変更

plugins/ndf-shared/skills/README.md

• 未実装の scripts/check-skill-frontmatter.py の参照を、現行 CI の実行内容と Task 0-7 での追加予定へ差し替え
• Codex の agents/openai.yaml は配布物に未生成のため分類表を「現状は制御手段なし」とし、Task 0-8 で生成処理を追加する旨を注記
• 明示指示専用の条件から argument-hint の必須扱いを外す
• 未引用 description の問題を YAML 構文エラーとして説明（Kiro issue は実例として残置）
• name と親ディレクトリ名の一致を Agent Skills 仕様から分離し、プロジェクト規約として記載

検証

• 実測値は skill-stats.py --plugin-root plugins/ndf-shared --from 2026-05-20 --to 2026-08-07 --format json を再実行して確認
• python3 scripts/check-markdown-links.py --root . — PASS
• bash scripts/validate-runtime-plugins.sh — PASS
• push 前の CI（0181731）は 6 チェックすべて SUCCESS

再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 2 | codex | COMMENT

frontmatter 規約のランタイム横断説明について、実装差が誤読される箇所だけコメントしました。

[takemi-ohama]

🤖 cross-review | round 2 | gemini | REQUEST_CHANGES

棚卸台帳の実測値と判定根拠の整合性を確認しました。一部の Skill において、表上の「機会」の実測値と「判定根拠」の前提が矛盾している箇所があるため修正を提案します。

[takemi-ohama]

/ndf:fix round 2 対応完了

修正コミット: 80c9b8b

cross-review round 2 の未 Resolve 指摘 3 件（codex 2 / gemini 1）すべてを修正し、3 スレッドとも返信のうえ Resolve しました。deferred / rejected は 0 件です。

対応内訳（独自再判定後）

重要度	件数	内容
major	1	機会が測定不能な Skill の判定根拠を「機会 0」と断定していた矛盾
minor	2	allowed-tools のランタイム差、disable-model-invocation の挙動が Claude Code 固有である旨の明記

主な修正

docs/specifications/ndf-skill-inventory.md

• 「判断基準」節に、機会 —（トリガ語未宣言で測定不能）の Skill は機会数を 0 と断定せず、起動 0 かつ機会が測定不能なものは需要を示す実測値が得られていないものとして削除の既定を準用する旨を追記
• knowledge-reorg / mcp-builder / sync-main の判定根拠を「既定を準用（起動 0 / 機会は測定不能）」へ修正。削除の結論は変わらない

plugins/ndf-shared/skills/README.md

• Agent Skills 仕様 6 項目を表へ分割し、「共通に解釈され発動判定に効く（name / description）」「解釈されるが発動に関与しない（license / compatibility / metadata）」「実装差があり保証されない（allowed-tools、仕様上 experimental）」の 3 段階で記載
• disable-model-invocation: true で description がコンテキストへ載らないのは Claude Code の挙動である旨を明記し、Codex / Kiro では description 自体へ明示指示専用である旨を残す必要があることを併記

検証

• 実測値は skill-stats.py --plugin-root plugins/ndf-shared --from 2026-05-20 --to 2026-08-07 --format json を再実行し、3 件が triggers_source: none / invocations: 0 であることを確認
• allowed-tools の Experimental 表記は docs/claude-code-skills-official-reference.md の Agent Skills 仕様表で確認。Kiro installer が allowed-tools を参照していないことも grep で確認
• python3 scripts/check-markdown-links.py --root . — PASS
• bash scripts/validate-runtime-plugins.sh — PASS
• bash scripts/build-runtime-plugins.sh --check — PASS
• push 前の CI（da9442f）は 6 チェックすべて SUCCESS

再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 3 | codex | APPROVE

修正必須の追加指摘はありません。

[takemi-ohama]

🤖 cross-review | round 3 | gemini | REQUEST_CHANGES

• when_to_use フィールドに関する仕様誤認があり、各ランタイムの暗黙起動が意図通りに動作しなくなる致命的な問題があります（Claude Code も公式ドキュメント上 when_to_use を認識しません）。
• 1% / 8,000 文字のコンテキスト予算や 250 文字の短縮仕様は Claude Code のものであり、Codex の仕様として誤って記述されています。

ドキュメントの主張が読者（Skill 開発者）の判断を誤らせ、発動しない Skill を作らせてしまうため、全体的な仕様の確認と修正が必要です。

[takemi-ohama]

/ndf:fix round 3 対応完了

修正コミット: fe17e36

cross-review round 3 の未 Resolve 指摘 6 件（gemini のみ。codex は同ラウンドで指摘なしの APPROVE）を精査しました。4 件を修正して Resolve、2 件は事実確認の結果 rejected（Resolve せず返信のみ）です。deferred は 0 件です。

重要度の再判定

gemini は critical 4 件 / major 2 件としていましたが、本 PR はドキュメント 4 ファイルのみでコード変更がなく、セキュリティ・データ破損・本番障害のいずれにも該当しません。内容で判定し直した結果は次のとおりです。

箇所	元ラベル	判定	対応
skills/README.md L29（when_to_use は全 3 ランタイムで読まれない）	critical	事実誤認	rejected
skills/README.md L46（短縮するのは Codex でなく Claude Code）	critical	minor（記述不足）	一部修正
skills/README.md L114（2% / 8,000 は Claude Code の仕様）	critical	minor（記述不足）	一部修正
skills/README.md L123（when_to_use へ逃がすと暗黙起動不可）	major	major（理由は別）	修正
ndf-skill-inventory.md L69（implementation-plan の評価根拠）	major	事実誤認	rejected
ndf-skill-inventory.md L80（plan-to-spec の改善方針）	critical	major（理由は別）	修正

rejected 2 件の根拠

いずれも「Claude Code は when_to_use を読まない」という共通の前提に基づく指摘ですが、この前提は実測で否定されました。

本 PR を作業している Claude Code セッション自身の Skill 一覧が、description と when_to_use を - で連結した文字列になっていることを確認しています。

• codex（when_to_use あり）→ 一覧は Delegate coding, review, or research to Codex CLI. - 外部 AI へコード生成 / レビュー / 調査を委譲したいとき。Triggers: 'codexで調査', ... と両項目が連結されて表示される
• plan-to-spec / ndf-policies（when_to_use なし）→ description のみが表示され、連結部分が現れない

when_to_use を持つ Skill にだけ連結部分が現れるため、Claude Code が when_to_use を初期一覧へ読み込んでいることは確定します。したがって「Claude Code 独自項目であり、Codex と Kiro では description だけで発動が判定される」という本文の記述は正しく、変更していません。

implementation-plan についても、description は英語 43 文字でトリガ語を含まず、日本語トリガ語は when_to_use 側にのみ存在します。日本語の依頼文に対して起動 24 回が全数自動起動という実測と、現在の判定根拠は整合しています。

修正 4 件

plugins/ndf-shared/skills/README.md

• 上限値表に Claude Code の初期一覧予算（コンテキストウィンドウの 1%、不明時 8,000 文字、1 項目 250 文字で切り詰め）の行を追加。従来は Codex の予算しか載っておらず、予算を持つのが Codex だけと読めた
• トリガ語を先頭へ置く根拠を、Codex の短縮だけでなく Claude Code の 250 文字切り詰めも併記する形へ変更
• 予算超過分の逃がし先を配布先ごとに分割。when_to_use は Codex / Kiro では読まれないため、3 ランタイムへ配布する Skill のトリガ語をそこへ移すと当該ランタイムで暗黙起動に効かなくなる点を明記

docs/specifications/ndf-skill-inventory.md

• plan-to-spec（配布 CXK）の発動改善方針を「要点を when_to_use へ移す」から「トリガ語は description に残したまま重複した言い換えを削って要約する」へ変更。round 1 の logging-guidelines / paths と同じ「3 ランタイムで効く方針にする」判断に揃え、同表の cross-review とも向きが一致

なお Codex の 2% / 8,000 文字は issues/ndf-development-skills/02-skill-inventory.md に Build skills（2026-08-07 取得）を出典として記録済みの値であり、Claude Code の 1% とは別物です。混同ではないため Codex 行の値と出典は維持しています。

検証

• python3 scripts/check-markdown-links.py --root . — PASS
• bash scripts/validate-runtime-plugins.sh — PASS
• bash scripts/build-runtime-plugins.sh --check — PASS
• push 前の CI（80c9b8b）は 6 チェックすべて SUCCESS

再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 4 | gemini | APPROVE

指摘事項はありません。

[takemi-ohama]

🤖 cross-review | round 4 | codex | REQUEST_CHANGES

設計レベルの追加指摘はありません。既存計画との整合性に 1 件、修正が必要です。

[takemi-ohama]

/ndf:fix round 4 対応完了

修正コミット: ec8a18f

cross-review round 4 は gemini が指摘なしの APPROVE、codex が REQUEST_CHANGES 1 件でした。未 Resolve のスレッド 3 件（round 4 の新規 1 件 + round 3 で rejected として残していた 2 件）を処理し、3 件すべてを返信のうえ Resolve しました。

対応内訳（独自再判定後）

箇所	元ラベル	判定	対応
plugins/ndf-shared/skills/README.md L130（計画側 Task 0-7 が旧方針のまま）	major / 整合性	major（妥当）	修正
plugins/ndf-shared/skills/README.md L29（when_to_use は全 3 ランタイムで読まれない）	critical / 正確性	事実誤認	rejected（判断済みとして Resolve）
docs/specifications/ndf-skill-inventory.md L69（implementation-plan の評価根拠）	major / 正確性	事実誤認	rejected（判断済みとして Resolve）

後者 2 件は round 3 で rejected とした指摘で、round 4 では同趣旨の再提出がありませんでした（gemini は APPROVE）。同じ根拠を再掲したうえで、判断済みとして決着させています。

修正 1 件

codex の指摘どおり、本 PR で定めた「3 ランタイムへ配布する Skill のトリガ語は description に残す」という規約に対し、計画側が旧方針（when_to_use へ移す）のままで矛盾していました。次工程が旧方針で実装しないよう、プラン文書を規約へ揃えています。

issues/ndf-development-skills/07-tasks.md（Task 0-7）

• plan-to-spec の指示を「長い description は要点を残して when_to_use へ移す」から「配布が CXK で when_to_use が Codex/Kiro に効かないため、トリガ語を残したまま重複した言い換えを削って要約し、手順の説明は本文へ逃がす」へ変更

issues/ndf-development-skills/02-skill-inventory.md

• 「適用方針」の plan-to-spec の項に同じ旧方針の記述があったため、あわせて新方針へ更新
• 「Codex の初期一覧予算」節の「超過分は when_to_use と本文へ逃がす」も規約（逃がし先を配布先で選ぶ）と矛盾していたため、配布先で分ける記述へ統一

これでプラン（issues/）・台帳（docs/specifications/ndf-skill-inventory.md）・規約（plugins/ndf-shared/skills/README.md）の 3 者が同じ方針で一致しました。

rejected 2 件の根拠（再掲）

いずれも「Claude Code は when_to_use を読まない」という共通の前提に基づく指摘ですが、この前提は実測で否定されています。

本 PR を作業している Claude Code セッション自身の Skill 一覧が、description と when_to_use を - で連結した文字列になっていることを確認しました。when_to_use を持たない Skill（plan-to-spec / ndf-policies）には連結部分が現れないため、Claude Code が when_to_use を初期一覧へ読み込んでいることは確定します。

implementation-plan についても、description は英語 43 文字でトリガ語を含まず、日本語トリガ語は when_to_use 側にのみ存在します。日本語の依頼文に対して起動 24 回が全数自動起動という実測と、現在の判定根拠は整合しています。

なお、when_to_use が Codex / Kiro で読まれないことによる実害は round 3（fe17e36）で規約・台帳の両方へ反映済みで、今回の修正でプラン側にも反映しました。

検証

• python3 scripts/check-markdown-links.py --root . — PASS
• bash scripts/validate-runtime-plugins.sh — PASS
• bash scripts/build-runtime-plugins.sh --check — PASS
• push 前の CI（fe17e36）は 6 チェックすべて SUCCESS

再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 5 | codex | APPROVE

修正必須の指摘はありません。

[takemi-ohama]

🤖 cross-review | round 5 | gemini | REQUEST_CHANGES

棚卸台帳の実測値と判定ルール、および 3 ランタイムでの発動制御について、以下の整合性に関する修正を提案します。

• 棚卸台帳の判定基準に「削除の既定を覆して維持・改善する」例外条件を追加してください。
• Codex / Kiro における「常時注入のみ」Skill の自動実行リスクへの対応方針を追記してください。

[takemi-ohama]

cross-review round 5 対応サマリ

• codex: APPROVE（指摘なし）
• gemini: REQUEST_CHANGES 2 件 → いずれも妥当と判断し修正、reply 済み・Resolve 済み

commit: aed3587

1. 判断基準表と qa-security-scan の矛盾（major / 整合性）

docs/specifications/ndf-skill-inventory.md

• 判断基準表の列名を「例外として削除する条件」→**「例外として判定を覆す条件」**へ変更し、削除方向以外の例外も表現できる形にした。各行の例外に覆した後の判定（削除 / 発動改善 / 削除または統合）を明記
• 「起動 0 / 機会 0」の行に、別の測定で需要が確認できるときは削除せず発動改善とする例外を追加
• 機会 — で削除の既定を準用する場合にも同じ例外が適用されることを追記
• qa-security-scan の判定根拠に、例外を適用した旨と根拠（初期実測の機会 66、宣言トリガ語が実際の発話と乖離）を記載

同じ状況の Skill を台帳全体から機械的に洗い出し（起動 0 かつ機会が 0 または — で判定が削除・統合元以外）、deploy が該当したため同様に修正した（機会は測定不能だが初期実測 340 のため既定を準用せず発動改善）。ndf-policies も該当するが、既に「判定対象外」と明記済みのため変更なし。

判定そのものは変えていないため「判定の内訳」の個数に変更はない。

2. 「常時注入のみ」の Codex / Kiro 制約（major / 仕様整合性）

plugins/ndf-shared/skills/README.md

実態確認の結果、ndf-policies は manifest 3 種すべて（claude-skills.txt / codex-skills.txt / kiro-skills.txt）に含まれ、その description は "Apply core NDF project policies." のみで「実行しない」旨の記載がないことを確認した。

「発動制御の 4 分類」表の下に次を追記した。

• Codex / Kiro は user-invocable: false を解釈せず、この分類の Skill も通常の Skill として扱われる（Codex では暗黙起動されうる）
• したがってこの分類の Skill は description に「知識として参照する。手順として実行しない」旨を明記する
• Kiro は Skill として配らず .kiro/steering/ へ常時指示として置き換えることで回避する（Task 0-9）

あわせて issues/ndf-development-skills/07-tasks.md の Task 0-10（ndf-policies/SKILL.md を対象ファイルに含む）へ、description の追記を変更内容として追加した。SKILL.md 自体の書き換えは本 PR の範囲外のため Task 0-10 で実施する。

検証

検査	結果
python3 scripts/check-markdown-links.py --root .	PASS
bash scripts/validate-runtime-plugins.sh	PASS（build --check / manifest / plugin validate / marketplace validate / link check すべて PASS）
gh pr checks 67（修正前時点）	6 件すべて SUCCESS

[takemi-ohama]

🤖 cross-review | round 6 | gemini | APPROVE

3 ランタイムの仕様差と棚卸台帳の実測値の整合性を確認しました。仕様矛盾や計算・論理の破綻は見当たらず、修正すべき点はありません。

[takemi-ohama]

🤖 cross-review | round 6 | codex | REQUEST_CHANGES

台帳と frontmatter 規約の整合性を 1 点修正してください。

[takemi-ohama]

cross-review round 6 対応サマリ

• 対応: 1 件（major 1 / critical 0 / minor 0 / nit 0）
• deferred: 0 件
• rejected: 0 件
• 修正コミット: 0654a2c
• gemini (round 6): APPROVE / 指摘なし

対応内容

指摘	対応
docs/specifications/ndf-skill-inventory.md:79 [major / 仕様整合性] ndf-policies の判定根拠が user-invocable: false のみを前提としており、同 PR で追記した「Codex / Kiro は同項目を解釈しない」制約と矛盾	判定根拠をランタイム差分込みへ修正。Claude Code は常時注入、Kiro は Task 0-9 で .kiro/steering/ へ移設、Codex は Task 0-10 で description に「知識として参照する。手順として実行しない」旨を明記、と記載し 07-tasks.md へリンク

あわせて skill-stats も確認しました。配布が —（manifest 3 種のいずれにも不在）かつ frontmatter が 常時注入 ではないためランタイム差分は生じませんが、同じ疑問が生じないよう判定根拠へその旨を明記しています。

検証

• python3 scripts/check-markdown-links.py --root . → Markdown local links are valid
• bash scripts/validate-runtime-plugins.sh → runtime plugin validation passed
• push 前の CI (aed3587 時点): 6 チェックすべて SUCCESS

変更は docs/specifications/ndf-skill-inventory.md の 2 行のみで、コード・生成物への影響はありません。再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 7 | codex | APPROVE

指摘すべき修正事項はありません。

[takemi-ohama]

🤖 cross-review | round 7 | gemini | APPROVE

台帳の実測値・判定ロジック・3ランタイムの仕様差異・計数ともに矛盾なく整合していることを確認しました。指摘事項はありません。