self-learning

セルフラーニング：確実な手順をスキルとして蓄積する

このスキルは、苦労してたった今解明したことを再利用できる Agent Skill に変えます。次のセッションでは、自分でもチームメイトでも、 最初から実証済みの手順を把握した状態で始められるため、ゼロから 見つけ直す必要がありません。

これはメタスキルです。作業そのものを行うのではなく、作業がどのように 行われたかを記録します。特定のツールに依存せず、Agent Skills 形式を 読み取るあらゆるエージェントで使えます（例：Claude Code と Codex は、 どちらも SKILL.md スキルをネイティブに読み込みます）。手順がツールに よって異なる場合は、まず汎用的な方法を示し、ツール固有の詳細は例として のみ記載します。

その瞬間を見極める

通常の作業中に、次の兆候がないか注意してください。どれか一つでもあれば、 手順を蓄積する合図です。

• タスクが何度か試した後や、間違った方向に進んだ後、またはユーザーの 修正を受けてから、ようやくうまくいきました。成功した手順には、失敗の 数々以上に価値があります。
• エージェントが最初は知らなかったプロジェクト固有の事実を見つけました。 たとえば、認証情報や環境変数の場所、サービスと通信するセレクターや バックエンド、わかりにくいコマンド、必須の実行順序、当然の想定に反する 落とし穴などです。
• 繰り返し発生する可能性が高い運用ワークフローです。開発用／本番用 DB へのアクセス、デプロイ、マイグレーションの実行、データのシード、変更の 本番環境での検証、特定のテスト手順の実行、キーのローテーション、適切な ログの追跡などです。
• ユーザーが明示的に伝えています。「覚えておいて」「これをスキルとして保存して」 「次回、もう一度説明させないで」などです。

ユーザーから頼まれた場合でも、自分で気づいた場合でも、許可を求めずに すぐ対応してください。 スキルとして蓄積した後、何をどこに記録したかを ユーザーに伝えます（手順 5）。ユーザーはいつでも編集または削除できます。

スキル、メモ、それとも見送り？

すべての学びが独立したスキルに値するわけではありません。一行だけの内容で スキル一覧が膨れ上がらないよう、まず振り分けてください。

• 複数段階からなる、再利用可能な手順やワークフロー（デプロイ、DB への アクセス、マイグレーション手順の実行、本番環境での検証方法など）→ 以下の手順に従ってスキルとして蓄積します。
• 単独で成り立つ一つの事実や、一行の修正情報（環境変数名、パス、落とし穴など） → ハーネスに軽量なメモ機能（例：MEMORY.md インデックス）がある場合は、 そちらに記録します。一行の内容にスキルを作るのは大げさです。そのような 機能がない場合は、小さなスキルを作成します。
• 再発する可能性が低い、本当に一度限りのこと → 見送ります。

蓄積する際は、成功だけでなく失敗も記録してください。除外した方法と その理由は、多くの場合、確実な手順そのものよりも次回の時間短縮に役立ちます。

昇格ルール：推測を確定事項として記録しない

スキルは信頼できる情報源です。次のセッションでは内容を再検証せずに信頼します。 そのため、昇格の基準は厳しくしてください。次の三つをすべて満たす場合に のみ、スキルを作成します。

1. チェックに合格していること。 手順が実際に検証済みであること。テストの 成功、コマンドの正常終了、再現手順による事象の再現、ビルドの成功などです。 どのチェックを行ったか記録してください。「動いたように見えた」だけでは合格 とは言えません。
2. 失敗パターンに名前を付けられること。 この手順が回避または診断する失敗を 具体的に特定できること（例：「古いビルドキャッシュ → 存在しない型エラー」）。 「ときどき壊れる」のような曖昧な説明では不十分です。
3. 少なくとも一つの行き止まりを除外していること。 試した上で、理由を添えて 採用しなかった具体的な方法があること。

どれか一つでも欠けている場合、まだスキルにはできません。メモリに未検証と 明記した暫定メモを残すか、見送ってください。これにより、確信を伴う推測が スキルセットに混入するのを防げます。

抽出手順

• 1. 昇格ルール（上記）を適用します。チェックへの合格＋明確な失敗パターン＋除外した行き止まりがそろっていなければ、スキルではありません。メモリに記録するか、スキップしてください。確信に基づく推測だけで先に進まないでください。
• 2. 以下のヒューリスティックを使ってスコープを選び、名前を付けます。質問のために手を止めないでください。デフォルトではプロジェクトスコープとし、明確で具体的な name を選びます。
• 3. 重複を確認します。 重複させるのではなく、更新できる既存のスキルがないか探します。エージェントのスキルディレクトリ（プロジェクト用とユーザーレベルの両方）を一覧表示します（例：Claude Code の .claude/skills と ~/.claude/skills、Codex の .codex/skills と ~/.codex/skills、または使用するツールに相当するディレクトリ）。メモリやメモのインデックスにも目を通します。すでに記載されている情報なら、ポインターを追加するだけで済むかもしれません。
• 4. 委任する前に、この会話から黄金の手順を抽出します。記憶が新しいうちに、実際に動作した正確なコマンド、ファイルパス、環境変数名、必須の順序、そして同じくらい重要な避けるべき行き止まりを整理します。これが記述の素材になります。
• 5. ツールが対応している場合は、この会話を引き継ぐサブエージェントに記述を委任し、そうでなければ自分で記述します。詳細は以下を参照してください。黄金の手順があるのはこの会話だけなので、記述する担当者にはそのコンテキストが必要です。
• 6. 記述が完了したら、新しいスキルのパスと、何を記録したかを一行でユーザーに伝えます。

スコープ：プロジェクトとグローバル

• プロジェクト（リポジトリのスキルディレクトリ。例：.claude/skills/、.codex/skills/）：パスは、環境変数、ビルド／リリース手順、スキーマ、独自の挙動など、このコードベースに固有です。抽出される実務スキルの大半はプロジェクトスコープであり、Git を通じてチームに共有されます。
• グローバル（ユーザーレベルのスキルディレクトリ。例：~/.claude/skills/、~/.codex/skills/）：パスは複数のプロジェクトに適用できます。個人用ツール、複数リポジトリにまたがる習慣、自分のマシンに紐づくワークフローなどが該当します。

迷った場合はプロジェクトを優先してください。共有範囲が広すぎるグローバルスキルは、コマンドが適用できないリポジトリでも起動してしまいます。

書き込みを委任する（サブエージェント、またはインライン）

スキルを書く担当者には、この会話のコンテキストが必要です。ゴールデンパスがあるのは、この場所だけです。実行方法は、どちらも同じように有効です。

• インライン — メインループで自分で手順を実行します。常に機能します。
• サブエージェント — ツールで、この会話を引き継ぐサブエージェントに作業を委任できる場合は、情報収集の作業をメインのコンテキストから切り離すために利用します。（Claude Code：context: fork を指定したスキル。Codex などでは、それぞれの方法でサブエージェントを起動します。）コンテキストのない新しいエージェントには任せないでください。何もない状態から始まり、抽出できるものがありません。

どちらの方法でも、デフォルトでは対象範囲が広がりすぎるため、厳密に範囲を限定してください。このブリーフ（角括弧内を記入してください）に従い、サブエージェントに渡すか、自分でインラインで進めてください。

あなたはスキルの情報をまとめる担当です。あなたの唯一の仕事は、この会話でまとめたゴールデンパスを記録する新しい Agent Skill を作成することです。 ［ワークフローを1行で説明］。

厳守事項：

• [skills dir]/[skill-name]/ の下にのみ書き込んでください。プロジェクトのソースを変更したり、ビルドを実行したり、何かをインストールしたり、元のタスクを再開したりしないでください。
• まず [this-skill-dir]/references/skill-authoring.md と [this-skill-dir]/assets/SKILL.template.md を読み、その仕様に従って SKILL.md を作成してください。手順に必要な場合は、references/ または assets/ 内のファイルも作成してください。
• 単発の回答ではなく、手順（コマンド、パス、必須の順序、注意点）を記録してください。次回も使えるように一般化してください。
• 失敗した方法も記録してください。却下したアプローチとその理由を記載し、次回は行き止まりを避けられるようにします。「機能しなかったこと」というセクションに記載してください。
• 昇格ルールを守ってください。スキルには、この方法を検証した合格チェックを記録し、対処する失敗パターンに名前を付け、却下した行き止まりを少なくとも1つ列挙する必要があります。いずれかが欠けている場合（実際に検証されていない場合など）は、昇格可能ではないと報告して停止してください。スキルは作成せず、代わりに暫定的なメモを残してください。
• シークレットの値（パスワード、トークン、接続文字列、API キーなど）は絶対に書き込まないでください。記録するのは、その所在（環境変数名、選択関数、MCP ツール、シークレットマネージャー）のみです。シークレットをスキルファイルに複製すると漏えいにつながります。
• 完了前に自己検証してください（skill-authoring.md のチェックリストを参照）。
• 報告する内容：作成したファイルの絶対パスと1行の要約。その後は停止し、元のタスクに戻らないでください。

注意点

• シークレットをスキルファイルに含めてはいけません。 スキルはコミットされ、オープンソースとして公開されます。 シークレットがある場所を示し、値を再掲してはいけません。これは、このスキルで最も重要なルールです。
• write_file を呼び出す直前に、この10秒のセルフ監査を行ってください — 作成予定の本文を、頭の中で次のフィルターにかけます。
  • いずれかの行に、Bearer 、Basic 、sk-、ghp_、 xox[bpars]-、AKIA、または32文字以上のBase64／16進数の文字列が含まれていますか？ → マスキングします。
  • 接続文字列（postgres://、mysql://、mongodb://、 redis://、https://user:pass@、amqp://、kafka://）が含まれていますか？ → 認証情報を取り除き、スキーム、ホスト、パスは残します。
  • 会話の前の方でユーザーが貼り付けた値を、ここで再入力しようとしていますか？ → ソースを示す文字列（env:FOO_TOKEN、 ~/.aws/credentials、MCP ツール secrets/get など）に置き換えます。
  • これはフックによって値が設定されるプレースホルダー（YOUR_TOKEN_HERE、<api-key>、 ${TO_FILL}）ですか？ → それでもマスキングします。自動入力されるプレースホルダーも、リテラルと同じように漏えいします。
  • ドキュメントのスニペットにある例のURLですか？ → example.com、 user:[email protected]、または文書化されたテスト用フィクスチャを使います。
• name はディレクトリ名と一致し、小文字の a-z／0-9／ハイフンのみで構成する必要があります — 先頭、末尾、連続するハイフンは使用できません。一致しないとスキルは読み込まれません。
• スキルを書く人は、デフォルトで範囲を超えた作業をしがちです（特にサブエージェント）。そのため、上記の指示ではプロジェクトのソースに触れたり、タスクを再開したりすることを禁じています — スキルディレクトリ内に作業を限定してください。
• 重複させないでください。 ほぼ同じスキル（またはメモリ）がすでに存在する場合は、トリガーを競合させるものを新たに作るのではなく、既存のものを更新してください。
• 回答ではなく手順を記録してください。 「EMEA の注文を顧客と結合する」では次回役に立ちません。「適切なテーブルを見つけてクエリを作成する方法」がスキルです。references/skill-authoring.md を参照してください。
• SKILL.md は簡潔に保ってください（500行未満、約5000トークン未満）。詳細は references/ に移し、各ファイルをいつ読み込むかを読者に伝えてください。

作成仕様の全文については、 references/skill-authoring.md を参照してください。記入用テンプレートは assets/SKILL.template.md です。