CaseYwY/skills — プロジェクトスキル管理

manage-project-skills — プロジェクトスキルの選択と監査

0. ルール階層（最初に読むこと）

1. 許可（最優先、例外なし）: インストール/更新/削除、明示的なユーザー承認なしでのプロジェクトファイルへの書き込みは禁止。例外：承認された台帳への書き込み。承認 = 特定のスキル + ソース + スコープ。「スキルを管理して」という指示は個別のスキルを承認しない。
2. プロセス: 選択されたモード（T0/T1/T2/監査）に従う。「禁止」されたステップは効率化のためにスキップしない。
3. ガイダンス: ローカルファースト、抑制的。逸脱は理由を明示した場合のみ許可。

核心：不足は誤インストールに勝る — 引き戻しは約1分。誤インストールは永続的なコンテキストとトリガー競合を引き起こす。抑制、必須の正当化、ローカルファースト。

1. モード

要件が不明確 ⇒ ニーズ全体が把握不可能 ⇒ キックオフ時点での一括インストールはしない。

• T0 · 起動時インベントリ（読み取り専用）: ステップ1〜2とチャットレポート（「カバー済み / インストールしない」）。インストール/書き込みゼロ。台帳の初期化は別途承認された書き込み。カバレッジマトリックス = スタックから推測可能なニーズのみ。高速パス：台帳が存在し、スキルに関する言及がない場合 ⇒ 台帳のみを読む。再インベントリ条件：スキルディレクトリ / AGENTS.md / ロックファイル / エージェントが変更された場合、または台帳 ≠ ディスクの状態、またはユーザーの要求があった場合。
• T1 · ギャップ駆動型（タスク途中）: まず分類する。一回限りの回答（API詳細、単一コマンド）⇒ 調べる、インストールしない。再利用可能（このリポジトリが再度遭遇するワークフロー/標準/ツールチェーン）⇒ 1つのスキルをプル ⇒ 記録する。エントリはAGENTS.mdのルールに依存し（MAINTENANCE.md参照）、モデルの自己評価には依存しない。
• T2 · 計画確定後: 一括インストール。各候補は確定した計画によって正当化される。完全なステップ1〜7を実行。
• 監査: ユーザーがレビュー/トリミング/クリーンアップを要求 ⇒ 末尾を参照。

すべてのモードでプロジェクト台帳 .agents/skills-rationale.md を共有する（承認されている場合）。最初に読むこと。

2. フロー

1. プロジェクトのプロファイリング

存在する場合は読む（推測しない）：マニフェスト（package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj）。レイアウト + モノレポのシグナル（workspaces, turbo.json）。インフラ（.github/workflows, Dockerfile, vercel.json, wrangler.toml）。READMEの冒頭、docs/agents/。

2. カバレッジのインベントリ（ローカルファースト、プル前に重複排除）

順序：プロジェクトにインストール済み → グローバル → レジストリ。2つのクラス：

• 個人スキル: グローバル、クロスプロジェクト。プロジェクトに重複させない。対象エージェントを記録。グローバルに存在しても、宣言されたプロジェクト依存関係ではない。
• プロジェクトクリティカル: ワークフロー/デリバリーが依存するもの。ソース + バージョン/コミット + 復元パスを記録 — グローバルにインストールされていても実施。新しいマシンはグローバルを継承しない。

スキャン：プロジェクトディレクトリ（.agents/skills, .opencode/skills, .claude/skills = 一般的な例、各エージェントのドキュメントで確認。到達不能 ⇒ 「未確認」、決して「スキルなし」としない）。グローバル：npx skills ls -g でスキャン。ソースマニフェストと skills-lock.json（存在する場合は同期）。

出力：カバレッジマトリックス（ニーズ → 充足済み / ギャップ）。

3. 信頼できるソースからギャップを埋める

信頼レベル：ベンダー公式（anthropics/skills, openai/skills, supabase/agent-skills）> 原著者（mattpocock/skills, cursor/plugins）> コミュニティ > 検証不可能（精査を強化）。それ以外は npx skills find <kw> — インストール数は参考であり、信頼性ではない。何も該当しない ⇒ その旨を伝え、skill-creatorを提案。ニアミス的なハックはしない。

4. 予算：ハードキャップなし、ニーズ駆動

• 各候補には1つの具体的な理由が必要（「プロジェクトにXがあるためYが必要」）。理由がない ⇒ ドロップ。
• 候補が約10を超える ⇒ 分析バグ。ステップ1〜2を再監査。
• わずかに有益なものは「延期」リストへ（引き戻しは容易）。
• 重複排除 ≠ 自動削除：説明が重複する場合 ⇒ 候補グループ化 ⇒ トリガー/IO/副作用/依存関係/バージョンを比較 ⇒ 置き換えの証拠とユーザー承認がある場合のみマージ/削除。それ以外は両方を保持し、「比較対象」とマーク。

5. セキュリティゲート：インストール前にユーザー承認

SKILL.mdだけでなくパッケージ全体をレビュー：

1. SKILL.md全文 + 参照されているすべてのファイル/スクリプト/設定/依存関係を読む。各スクリプトで確認：実行 / ネットワーク / 書き込み / 認証情報。
2. スキャン証拠を記録：スキャナー + 判定 + 一致したバージョン + 日付。スキャンなし = 不明、安全ではない。スキャナー間で意見が一致しない場合 ⇒ リストアップし、平均化しない。
3. プライベートソースでスキャンなし ⇒ 手動による全ファイルレビューでゲートを代替し、「未スキャン」とマーク。
4. 中リスク以上または説明不能な動作 ⇒ ユーザーが決定。不明なままインストールしない。

6. インストール

# エージェントを自動検出（検出結果をユーザーに報告）。マルチエージェントマシン：--agent を渡す
npx skills add <owner/repo>@<skill> --copy -y

• チャネル2 — バージョン固定 / npm 到達不能時のフォールバック：gh skill install <owner/repo> <skill[@version]> --agent opencode（プレビュー。ファイルをコピーし、skills-lockは更新しない ⇒ 台帳にソース+バージョンを記録。常に --agent を渡す — 非インタラクティブのデフォルトは github-copilot）。スキルごとに1チャネル — 混在させない。
• --copy = スナップショット分離、バージョン固定ではない：アップストリームとの同期なし、バージョンIDなし、再インストールで変更される。再現性 ⇒ 台帳に記録：ソース + パス + バージョン/コミット（+ハッシュ）。
• プロジェクトクリティカルなワークフロースキル：--copy、決してシンボリックリンクにしない（シンボリックリンクはアップストリームを追跡する）。
• skills-lock.json が生成される ⇒ コミットする（復元：npx skills experimental_install）。.agents/ が gitignore されていないことを確認。
• 効果はエージェントによる：OpenCodeはホットリロード（確認済み）。その他のエージェントは再起動が必要な場合あり ⇒ ユーザーに再起動と再検証を促す。
• GitHub に到達不能 ⇒ 報告し、ローカルキャッシュを提案。決して黙ってスキップしない。

7. 検証と記録（4つのレイヤー、欠けているレイヤーは「未検証」）

• ファイル：存在、パスが正しい、参照が完全
• マニフェスト：npx skills ls がロックファイルおよびディスクと一致（見える ≠ ロード可能）
• ロード：対象エージェントが実際にスキルをロードする
• 動作：1つの代表的な正のタスクが機能する
• 決定事項を書き込む（何を/なぜ/延期/検証済み） → .agents/skills-rationale.md
• 削除：npx skills remove <name> -y を推奨（パラメータは npx skills --help を参照）。決して単にディレクトリを削除しない（ロックファイルの不整合が発生）。削除前にソース+バージョンを記録。復元不可能な場合はバックアップ。削除後、4つのレイヤーを再チェック。

3. 監査モード

このスキル自身も含む。レポート → ユーザー承認 → 実行。チェック項目：

1. 重複：説明をクラスタリング ⇒ 候補グループ ⇒ トリガー/IO/副作用/依存関係/バージョンを比較。置き換えの証拠と承認 ⇒ マージ/削除。それ以外は両方保持（比較対象）。類似性だけで削除しない。
2. 競合：同一シナリオでの矛盾 ⇒ 引用とスコープを記録 ⇒ ユーザーが裁定。
3. 肥大化：使用テレメトリなし — 「トリガーされたことがない」 = ユーザー情報源。測定可能：説明の肥大化 vs 機能、より高頻度のスキルとの重複。ダウングレード ⇒ 状態復元パス。
4. デッドリファレンス：必須入力（欠落=ブロッカー）/ オプション依存（不在=スキップ）/ 期待される出力（ランタイム作成、不在≠エラー）。デッドリファレンス ⇔ 必須入力が欠落し、回復手段がない。

レポート：証拠 → 推奨 → 影響 → 承認。削除前：復元可能性を確認（npx skills find）。復元不可能 ⇒ バックアップ + 確認。結果 → 台帳。

4. メンテナンスと強制

AGENTS.md ルールテンプレート、トリガー失敗診断ループ、15シナリオテストセット、リリースフロー → MAINTENANCE.md — このスキルを編集する前後に実行すること。