self-improving-agent

self-improving-agent スキルの概要

self-improving-agent が実際にすること

self-improving-agent スキルは、Agent Orchestration 向けのメタスキルです。1つの作業を直接助けるのではなく、完了済みタスク、エラー、繰り返し現れるパターンからエージェントが学べるようにし、その学びをスキルやメモリへ還元します。このリポジトリでは、hook ベースのトリガー、複数レイヤーのメモリ設計、修正・検証用テンプレートを組み合わせて実現しています。

このスキルを入れるべき人

self-improving-agent スキルは、複数のセッション・スキル・リポジトリにまたがって再利用するエージェント運用をしている人に向いています。エージェント群の中で時間をかけてパターンを蓄積し、同じミスの再発を減らし、その場しのぎの修正を再利用可能なガイダンスへ変えたい場合に特に有効です。

本当に片づけたい仕事

多くのユーザーに必要なのは、汎用的な「振り返って改善しよう」というプロンプトではありません。必要なのは、次のことを繰り返し実行できる仕組みです。

• タスクから有用なパターンが生まれたことを検知する
• そのパターンを永続的な場所に記録する
• そのパターンを残す価値が本当にあるか検証する
• 必要に応じて関連スキルを更新したり、レビュー用の PR を作成したりする

これが self-improving-agent の実務的な価値です。タスク後の学習を、あいまいな習慣ではなく運用フローとして回せるようにします。

普通のプロンプトと何が違うのか

主な違いは文体ではなく構造にあります。

• セッション開始・完了・エラーログ周辺で自動起動できる hook メタデータ
• semantic memory、episodic memory、working memory に分かれたメモリモデル
• 修正、パターン抽出、検証のためのテンプレート
• 改善内容をチャット履歴に埋もれさせず、レビュー可能な形で扱うことを前提にしたリポジトリ構成

強くハマるケース

複数のスキルを併用していて、スキル横断で学習させたいなら、self-improving-agent for Agent Orchestration は有力です。単発タスクより、継続運用のシステムで力を発揮します。最大の悩みが「エージェントが同じ教訓を何度も学び直している」ことなら、このスキルは十分に検討する価値があります。

インストールすべきでないケース

軽量な個人用プロンプトだけ欲しい場合、メモリを永続化する予定がない場合、生成された改善案をレビューするつもりがない場合は、self-improving-agent install は見送った方がよいです。このスキルの価値は運用プロセスの規律にあります。それがなければ、単なるオーバーヘッドになりがちです。

self-improving-agent スキルの使い方

self-improving-agent スキルをインストールする

リポジトリの README では、symlink ベースのインストール方法が示されています。

ln -s ~/path/to/agent-playbook/skills/self-improving-agent ~/.claude/skills/self-improving-agent

別の skills manager を使っている場合は、パス構成を自分の環境に合わせて読み替えてください。重要なのは、スキルフォルダを崩さずそのまま保つことです。hook、テンプレート、メモリ例、各種参照ファイルまで含めて、このスキルの利用モデルになっています。

初回利用前に activation model を理解する

SKILL.md のメタデータには、重要な hook のタイミングが3つあります。

• before_start: セッションの文脈を記録する
• after_complete: 完了内容を記録し、スキル変更があった場合は ask_first 付きで create-pr を起動できる
• on_error: エラーのみを記録し、再帰的な自己修復ループを意図的に避ける

最後の点は重要です。この self-improving-agent usage は「失敗を全部自動修正する」仕組みではありません。目的は、安全に学習を収集して適切に流すことにあり、無限に自分を再試行させることではありません。

まず読むべきファイル

手早く見極めたいなら、次の順で読むのがおすすめです。

1. skills/self-improving-agent/SKILL.md
2. skills/self-improving-agent/README.md
3. skills/self-improving-agent/references/appendix.md
4. skills/self-improving-agent/memory/semantic-patterns.json
5. skills/self-improving-agent/templates/correction-template.md
6. skills/self-improving-agent/templates/validation-template.md
7. skills/self-improving-agent/hooks/pre-tool.sh
8. skills/self-improving-agent/hooks/post-bash.sh
9. skills/self-improving-agent/hooks/session-end.sh

この順で読むと、repo 全体をざっと眺めるよりも早く、このスキルが実運用向けのワークフロー部品なのか、それともコンセプトメモ止まりなのかを判断できます。

このスキルがうまく機能するために必要な入力

self-improving-agent skill は、単に「自分を改善して」だけでは力を発揮しません。少なくとも次を渡してください。

• 直前に実行したタスクまたはスキル
• 何が成功し、何が失敗したか
• 出力、diff、ログなど、確認すべき成果物
• memory 更新、skill 更新、validation、PR 準備のどれを求めるか
• 編集を許可するファイル範囲に関する安全制約

実行結果に基づく具体的な証拠がないと、このスキルは抽象的で弱い一般化を作りがちです。

ぼんやりした依頼を強い invocation に変える

弱いプロンプト:

• “Use self-improving-agent to learn from this.”

より良いプロンプト:

• “Run self-improving-agent on the last debugger session. Inspect the final diff, failed command output, and user correction. Extract one reusable semantic pattern, record one episodic summary, and propose updates only if the guidance would help future debugger runs. Do not edit production code; limit changes to skill docs, templates, or memory artifacts.”

この形が優れているのは、参照すべき証拠、期待する出力の種類、更新範囲、そして更新してよいかの判断基準まで明示しているからです。

実践的な self-improving-agent usage ワークフロー

堅実な進め方は次のとおりです。

1. まず通常の task skill を実行する
2. ログ、エラー、編集内容、ユーザーフィードバックなどの成果物を集める
3. self-improving-agent を呼び出す
4. 次の3つを分けて扱うよう指示する
   • 一度限り起きたこと
   • 再利用パターンとして昇格させるべきこと
   • 信頼する前に検証が必要なこと
5. 提案された skill 変更をレビューする
6. 必要ならレビューしやすい更新として create-pr を起動する

この切り分けこそが品質管理の中核です。成功した修正がすべて、共有ガイダンスへ昇格するべきとは限りません。

メモリモデルが実運用にどう効くか

この repo で最も実践的に効いてくるのは、メモリ設計です。

• semantic memory は再利用可能なパターンやベストプラクティスを保存する
• episodic memory は個別の出来事やセッションを保存する
• working memory は直近のエラーなど、現セッションの状態を保持する

self-improving-agent usage では、観察結果が次のどれに当たるのかを都度判断する必要があります。

• 長く残すべきルール
• 事例として残すケース
• 一時的なコンテキスト

この区別が曖昧になると、自己改善型システムはノイズが増えやすくなります。

例の pattern file から読み取れること

memory/semantic-patterns.json が参考になるのは、学習パターンとして期待される粒度がわかるからです。問題、解決の構造、品質ルール、対象スキル、confidence まで含まれています。これは「PRD はもっと明確にすべき」といった緩いメモより、はるかに実用的です。

self-improving-agent を使うときは、同じ形の出力を求めると、パターンを移植しやすく、レビューもしやすくなります。

hook ファイルから見える現在の自動化レベル

このスキルに含まれる hook script は比較的軽量です。主に tool input、tool output、exit code、session end といった文脈情報を echo している程度です。つまり、現状の実装は完全自律の改善エンジンというより、統合の足場として理解するのが適切です。

インストール判断ではここが重要です。self-improving-agent が提供するのはワークフローの設計骨格であり、広い orchestration stack へ組み込むには、まだ自分で配線が必要になる場合があります。

高品質な結果を得やすい prompt パターン

一度に依頼する内容は、次のうち1つか2つに絞るのがおすすめです。

• confidence 付きで再利用パターンを抽出する
• correction report を作成する
• validation report を下書きする
• 更新すべき関連スキルを特定する
• 人間のレビュー向けに PR summary を準備する

証拠が薄い状態でこれらを一気に全部求めると、たいてい品質が落ちます。狭い依頼の方が、良い memory entry になりやすいです。

編集を許可する前に決めておくべき境界

書き込み権限を有効にする前に、次を明確にしてください。

• 許可する file path
• memory file を append-only にするか
• 既存パターンの merge を許すか
• confidence が高い場合を除き proposal-only にするか

チーム利用なら、共有 skill docs の編集にはレビューを必須にすべきです。自己改善システムは、ガイダンスを自由に書き換えさせると、修正より速く誤りを広げてしまうことがあります。

self-improving-agent スキル FAQ

self-improving-agent は初心者にも有用か

はい。ただし主な役割は最初のスキルではなく、レビューと学習のレイヤーです。初心者でも、何がうまくいかなかったか、何を記憶すべきかを整理する用途には使えます。ただし真価が出るのは、すでに複数のスキルを繰り返し運用している場合です。

普通の振り返りプロンプトより何が優れているか

普通のプロンプトでも振り返り自体は出せます。self-improving-agent が優れているのは、構造化メモリ、スキル横断での再利用、validation、必要に応じた workflow hook まで含められる点です。違いは言い回しではなく、永続性と統合性にあります。

self-improving-agent はエラーを自動修正するか

それ単体で、完全自律的に直すわけではありません。メタデータ上でも on_error で無限再帰を避ける設計が明示されており、実際には logging と debugging や code review など他スキルとの連携に依存します。魔法の修復ループではなく、学習と改善のコーディネーターとして扱うのが適切です。

self-improving-agent は Claude 風のローカル skill 環境専用か

例では ~/.claude/skills/ や ~/.claude/memory/ を使っているため、その環境に寄せて設計された repo であることは明らかです。ただし、同じ考え方――hooks、複数段の memory、templates、gated updates――を再現できるなら、他の agent framework にも発想自体は持ち込めます。

導入時の主なリスクは何か

大きなリスクは次のとおりです。

• 低品質なパターンを保存してしまう
• 単発の出来事を一般ルールと取り違える
• レビューなしでガイダンスを書き換えさせる
• 同梱の hook script が実際に提供する自動化以上のものを期待してしまう

self-improving-agent for Agent Orchestration を使うべきでないのはいつか

ワークフローがほぼアドホックである場合、タスクの種類が散らばりすぎて安定したパターンになりにくい場合、チームが memory hygiene を維持できる状態にない場合は、self-improving-agent for Agent Orchestration は向きません。そのようなケースでは、シンプルな振り返りプロンプトで十分なこともあります。

self-improving-agent スキルを改善する方法

ambition を増やす前に、証拠を良くする

self-improving-agent の出力品質を最も速く改善する方法は、期待値を上げることではなく、元データを良くすることです。

• ユーザーの正確な修正指示
• before/after の diff
• 失敗した command
• 最終的に採用された解決策
• どの skill がその結果を出したか

「ここで何か学びがあった」といった抽象的な指示より、材料が豊富な方が強いパターンを作れます。

episode と pattern を必ず分ける

よくある失敗は、単発の出来事を全体ルールへ昇格させてしまうことです。self-improving-agent を改善したいなら、明示的に次を問いかけてください。

• “What belongs in episodic memory only?”
• “What is strong enough for semantic memory?”
• “What still needs validation?”

この1つの区別だけでも、memory の汚染を大きく減らせます。

confidence と target-skill を必須にする

semantic memory の例には confidence と target skill の情報が含まれています。ここは維持すべきです。実用的な self-improving-agent guide は、単にパターンを述べるだけでなく、それがどれほど信頼でき、どこに適用されるのかまで示すべきです。そうしておくと、後からの整理やレビューがずっと楽になります。

自由記述ではなく templates を使う

templates/ にあるテンプレートは、このスキルの実用面でかなり重要な資産です。出力が弱いなら、agent に次を埋めさせてください。

• templates/correction-template.md
• templates/pattern-template.md
• templates/validation-template.md

構造化された出力の方が、レビュー、比較、却下がしやすくなります。

昇格の前に validation を入れる

reference appendix には、次のような確認項目を含む validation report template があります。

• 例が compile または実行できる
• checklist が repo の慣例と一致している
• external reference が有効である
• 重複や矛盾する guidance がない

より高品質な self-improving-agent の結果を求めるなら、共有 skill instruction を変更する前に validation を必須にしてください。

repository integration は段階的に進める

このスキルを導入するなら、最初から全面的に書き換えさせないでください。より安全な展開順は次のとおりです。

1. logging のみ
2. proposal draft
3. memory update
4. レビュー済みの skill-doc 変更
5. 必要に応じた PR 作成

このように段階的に採用すると、信頼を保ちやすく、失敗時のデバッグもしやすくなります。

noisy または stale な semantic memory に注意する

self-improving-agent は、semantic memory が何でも入れる引き出しになると性能が落ちます。次のようなパターンは整理対象です。

• 一度も再利用されていない
• confidence が低い
• より新しいパターンと重複している
• すでに変わった repository 慣例を前提にしている

memory を選別して保つほど、このスキルは良くなります。

update scope は具体的に指示する

「スキルを改善して」ではなく、たとえば次のように依頼してください。

• “update one checklist item in SKILL.md,”
• “draft a correction note using the template,”
• “append a new semantic pattern with confidence justification,”
• or “prepare a validation report only.”

スコープを狭くすると、レビューしやすくなり、意図しない過剰変更も減ります。

self-improving-agent と human review の習慣をセットで運用する

repo 側でも、ask_first モードの create-pr や appendix の human-in-the-loop メモを通じて、その前提が示されています。この運用規律は維持すべきです。理想的な self-improving-agent skill は、無制限の自律性ではなく、明示的なレビューゲートを伴う高速学習です。

結果が generic なら、prompt の形を変える

出力が generic になるのは、たいてい prompt に次のどれかが欠けているからです。

• 対象となる source session
• 具体的な artifact の集合
• 更新先の target location
• 何を durable learning と見なすかの判断ルール

より良い self-improving-agent usage prompt は、この4点をすべて明示します。たいていの場合、ちょっとした文言調整よりも、こちらの方が大きく品質を改善します。