project-skill-audit

プロジェクトスキルの監査

概要

スキルを提案する前に、プロジェクトで実際に繰り返されているワークフローを監査します。一般的なアイデア出しよりも、メモリ、ロールアウトの要約、既存のスキルフォルダー、現在のリポジトリの規約に基づく証拠を優先します。

既存のプロジェクトスキルが必要な動作にすでに近い場合は、新しいスキルを作成する前に更新を提案します。

ワークフロー

1. 現在のプロジェクトの範囲を把握します。 リポジトリのルートを特定し、まず AGENTS.md、README.md、ロードマップ／台帳ファイル、ワークフローや検証要件を定めたローカルドキュメントなど、プロジェクトに関する最も重要なガイダンスを読みます。

2. まずメモリ／セッションのパスを構築します。 メモリのベースパスは、$CODEX_HOME が設定されている場合はその値を使用し、それ以外の場合は ~/.codex をデフォルトとします。 次の場所を使用します。

   • メモリインデックス：$CODEX_HOME/memories/MEMORY.md または ~/.codex/memories/MEMORY.md
   • ロールアウトの要約：$CODEX_HOME/memories/rollout_summaries/
   • 生のセッション：$CODEX_HOME/sessions/ または ~/.codex/sessions/

3. 過去のプロジェクトセッションを次の順序で読みます。 ランタイムプロンプトにメモリの要約がすでに含まれている場合は、そこから始めます。 次に MEMORY.md で以下を検索します。

   • リポジトリ名
   • リポジトリのベース名
   • 現在の cwd
   • 重要なモジュール名またはファイル名 まず、最も関連性の高いロールアウトの要約を1～3件だけ開きます。 必要な具体的な証拠が要約に含まれていない場合に限り、生のセッション JSONL を確認します。

4. 新しいスキルを提案する前に、既存のプロジェクトローカルスキルを確認します。 現在のリポジトリルートを基準に、次の場所を確認します。

   • .agents/skills
   • .codex/skills
   • skills SKILL.md と agents/openai.yaml がある場合は、両方を読みます。

5. プロジェクトローカルスキルと繰り返し行われる作業を比較します。 過去のセッションから、次のような繰り返しのパターンを探します。

   • 繰り返し実行される検証手順
   • 繰り返し必要となる失敗防止策
   • 繰り返し生じる担当範囲の境界
   • 繰り返し発生する根本原因のカテゴリ
   • 同じリポジトリ固有の情報を繰り返し必要とするワークフロー パターンが繰り返し現れ、既存のスキルに十分反映されていない場合は、スキルの候補です。

6. 「新しいスキル」と「既存スキルの更新」を分けて考えます。 既存のスキルが適切な分類先であるものの、トリガーが古い、失敗防止策が不足している、パスが更新されていない、検証手順が不十分、または対象範囲が不完全な場合は、更新を提案します。 既存のスキルを拡張すると曖昧になったり、わかりにくくなったりするほどワークフローが独立している場合に限り、新しいスキルを提案します。

7. プロジェクトローカルスキルを確認した後でのみ、グローバルスキルとの重複を確認します。 グローバルに共有されているスキルですでに十分に解決されているワークフローについて、プロジェクトローカルスキルを提案しないよう、$CODEX_HOME/skills と $CODEX_HOME/skills/public を確認します。 グローバルスキルがあるというだけでプロジェクトローカルスキルを却下しないでください。プロジェクト固有の失敗防止策があれば、ローカルで特化する理由になり得ます。

セッション分析

1. まずメモリインデックスを検索する

• リポジトリ名、ベース名、cwd を使い、rg で MEMORY.md を検索します。
• 同じリポジトリパスに対応するロールアウトの要約を参照している項目を優先します。
• 次の情報を記録します。
  • 繰り返し行われるワークフロー
  • 検証コマンド
  • 失敗防止策
  • 担当範囲の境界
  • マイルストーンまたはロードマップとの関連

2. 対象を絞ってロールアウトの要約を開く

• memories/rollout_summaries/ にある、最も関連性の高い要約ファイルを開きます。
• ファイル名、cwd、または keywords が現在のプロジェクトと一致する要約を優先します。
• 次の情報を抽出します。
  • ユーザーから繰り返し依頼された内容
  • 繰り返し発生した手順
  • 繰り返し起きた問題
  • 正しさを証明したコマンド
  • 再確認が必要だったプロジェクト固有の情報

3. 生のセッションはフォールバックとしてのみ使用する

• ロールアウトの要約に具体的な情報が不足している場合に限り、sessions/ の JSONL ファイルを検索します。
• 次の情報で検索します。
  • 正確な cwd
  • リポジトリのベース名
  • ロールアウトの要約にあるスレッド ID
  • 特定のファイルパスまたはコマンド
• 生のセッションは、正確なプロンプト、コマンドの実行順序、差分、またはエラー文を復元するために使用します。要約の確認を置き換えるために使用しないでください。

4. セッションの証拠をスキル候補に変換する

• new skill の候補は、単に同じトピックが繰り返されるのではなく、繰り返し行われるワークフローに対応している必要があります。
• skill update の候補は、ローカルスキルですでに扱われているワークフローに対応している必要があります。そのスキルのトリガー、ガードレール、または検証手順が、記録されたセッションと合わなくなっている場合が該当します。
• 次のような具体的な証拠を優先してください。
  • 「この検証手順は4つのセッションで登場した」
  • 「エクストラクターとランタイムの修正をまたいで、同じ所有権の混乱が繰り返された」
  • 「同じローカルスクリプトとテレメトリープローブを何度も再発見する必要があった」

推薦ルール

• 次の場合は新しいスキルを推薦してください。

  • 同じリポジトリ固有のワークフローまたは障害モードが、複数のセッションで繰り返し登場する
  • 成功するには、プロジェクト固有のパス、スクリプト、所有権ルール、または検証手順が必要である
  • 適切なデフォルト設定や失敗を防ぐ仕組みがあると、ワークフローが改善する

• 次の場合は更新を推薦してください。

  • 既存のプロジェクトローカルスキルですでにニーズの大半をカバーしている
  • SKILL.md と agents/openai.yaml の内容にずれがある
  • パス、スクリプト、検証コマンド、またはマイルストーンへの参照が古くなっている
  • スキルの本文が一般的すぎて、プロジェクトでの実際の進め方を反映していない

• 次の場合はスキルを推薦しないでください。

  • パターンが再利用可能なワークフローではなく、一度限りのバグである
  • 意味のあるプロジェクト固有の追加なしで、汎用のグローバルスキルがすでに適合する
  • 維持コストに見合うだけの頻度でワークフローが再発していない

スキャン対象

• 過去のセッションとメモリ：

  • すでにコンテキストにあるメモリの要約があれば、それを確認する
  • $CODEX_HOME/memories/MEMORY.md または ~/.codex/memories/MEMORY.md
  • 現在のリポジトリに最も関連する1～3件のロールアウト要約
  • 要約だけでは不十分な場合に限り、生の $CODEX_HOME/sessions または ~/.codex/sessions の JSONL ファイル

• プロジェクトローカルのスキル：

  • ./.agents/skills/*/SKILL.md
  • ./.agents/skills/*/agents/openai.yaml
  • ./.codex/skills/*/SKILL.md
  • ./skills/*/SKILL.md

• プロジェクトの規約：

  • AGENTS.md
  • README.md
  • ロードマップ、台帳、アーキテクチャ、または検証に関するドキュメント
  • 必要に応じて、現在のワークツリーまたは最近変更された箇所

出力要件

次の項目を含む、簡潔な監査結果を返してください。

1. Existing skills 見つかったプロジェクトローカルスキルと、それぞれが扱う主なワークフローを列挙します。

2. Suggested updates 更新候補ごとに、次の内容を含めます。

   • スキル名
   • 不完全または古くなっている理由
   • 最も価値の高い変更

3. Suggested new skills 新規作成候補ごとに、次の内容を含めます。

   • 推奨するスキル名
   • 作成すべき理由
   • 起動条件
   • スキルに記述すべき中核的なワークフロー

4. Priority order 期待される効果に基づいて、上位の推薦項目を順位付けします。

命名の指針

• 短いハイフン区切りの名前を優先してください。
• 明確になる場合は、プロジェクトローカルスキルにプロジェクトの接頭辞を付けてください。
• 曖昧な名詞より、動詞で始まる名前や行動を表す名前を優先してください。

失敗を防ぐための指針

• セッションまたはリポジトリの証拠なしに、繰り返し発生するパターンを捏造しないでください。
• 既存スキルの更新で十分な場合に、重複するスキルを推薦しないでください。
• 現在のリポジトリが明らかに進化している場合、1件のメモリだけに依存しないでください。
• ロールアウト要約をすべて一括で読み込まず、対象を絞ってください。
• 要約だけでは不十分でない限り、ロールアウト要約を飛ばして生のセッションを直接確認しないでください。
• テーマだけからスキルを推薦しないでください。推薦の根拠は、繰り返される手順、検証フロー、または障害モードである必要があります。
• プロジェクトの現在の実装タスクと、再利用可能なスキルのニーズを混同しないでください。

フォローアップ

ユーザーが推薦したスキルの作成または更新を実際に依頼した場合は、$skill-creator に切り替え、監査を続けるのではなく、選択されたスキルを実装してください。