agents-brain

Agents Brain

これらの指示がスラッシュまたはドル記号による呼び出しで会話にすでに含まれている場合は、そのまま従ってください。 その場合、スキルツールを使ってこのスキルを再度呼び出さないでください。

明示的なユーザー指示と、すでに確立された承認をこのスキルの既定の指示より優先してください。変更のない判断について、再度確認を求めないでください。ホスト側の制限と、破壊的な操作に必要な承認を維持してください。

ルート

• maintain [path] [target ...] [flags]：コンテキストを保守し、タスクに基づくスキルのライフサイクル変更を適用します。コンテキストの保守または調査では、既定でこのルートを使用します。references/maintain.md を読んでください。
• create-skill [skill-name]：明示的な依頼に基づき、プロジェクトローカルのスキルを作成します。references/create-skill.md を読んでください。スキャフォールディングの前に、リポジトリカタログの確認を行ってください。明示的な作成依頼では、継続的な使用実績は必要ありません。
• create-agents-md [path] [--root-only] [--dry-run] [--force]：明示的な依頼に基づき、指定範囲の AGENTS.md ファイルを初期化します。範囲のルートファイルを作成し、各サブツリーにネストされたファイルが必要か判断してください。references/create-agents-md.md を読んでください。

調査や書き込みの前にルートを選択してください。どのルートでも、以下のプロンプト作成と STE の要件が適用されます。保守に関するセクションは maintain に適用されます。各作成リファレンスには、そのルートの範囲、ワークフロー、検証、報告についての規定があります。

保守の範囲

リポジトリ内のコンテキストを、一貫性のあるシステムとして保守してください。対象には以下が含まれます。

• ユーザー向けの README.md ファイル。
• エージェント向けの AGENTS.md ファイル。Claude Code がネイティブ対応する前の環境に限り、対応する CLAUDE.md シンボリックリンクを含みます。詳しくは「Claude Code との互換性」を参照してください。
• .agents/skills にインストール済みの既存プロジェクトスキル、および skills/<name>/ にある対象となるソースカタログのスキル。
• コンテキストドキュメント：エージェントまたは人間向けの永続的なガイダンスを提供する、名前やディレクトリを問わないその他の Markdown ファイルです。規約、コマンドカタログ、データ形式のルール、ワークフロー手順書、参考資料などが該当します。

古くなったワークフロー、意味のある重複、または繰り返し発生し記録する価値のある手順がタスクを通じて明らかになった場合は、リポジトリ管理下のスキルを保守してください。

成功とみなすには、選択したすべての対象が次の基準を満たす必要があります。

• リポジトリ内の根拠が内容を裏付けている。
• 対象読者と範囲に沿っている。
• エージェントのコンテキストを、行動を変えるガイダンスにのみ使用している。
• リポジトリで定義された最小限の検証に合格している。

完了または予定している変更、検証、阻害要因を報告したら終了してください。

プロンプトとコンテキストの最適化

特定のモデル向けではなく、現在の Claude および GPT エージェントモデル向けに、スキルやその他のエージェント向けコンテキストを作成してください。その文章では、モデル名、モデルのバージョン、モデル固有のデフォルト設定を明記しないでください。ルーティングテーブル、model: フィールド、API パラメーターなど、モデルを選択、設定、または言及するコンテンツは例外です。README.md は、人が読みやすい明確なドキュメントとして維持してください。

複雑な作業、長時間にわたる作業、複数のツールを使う作業、またはオーケストレーションを多用するコンテキスト作業に取りかかる前に、このスキルディレクトリを基準に scripts/fetch-guidance.sh の場所を解決してください。その作業では、anthropic と openai をそれぞれ指定して、スクリプトを一度ずつ実行してください。2 回の実行は独立しているため、同じターン内に並列呼び出し、または 1 つのシェルコマンドで開始してください。返された両方のファイルを、1 回の並列バッチで最後まで読んでください。タスクでプロンプト、スキル、その他のエージェント向け文章を作成または変更する場合に限り、ヘルパーを実行してガイドを読んでください。それ以外の編集では、ヘルパーを実行せず、どちらのガイドも読まないでください。その場合は、guides: skipped (no agent-facing prose) と報告してください。

このヘルパーは、推奨事項が変わる可能性があるため、Anthropic の prompting best practices と OpenAI の最新モデルガイドを取得します。Anthropic のガイドでは、現在のすべての Claude モデルを扱い、モデルごとのプロンプト作成ページにリンクしています。OpenAI のガイドでは、現在の GPT モデルファミリーを扱います。このガイドのプロンプト作成に関する推奨事項は、そのファミリー内の 1 つのモデルでのテストに基づいています。単純なコンテキスト作業には、どちらのガイドも必要ありません。

モデル名を挙げている助言は、そのモデルで測定されたものとして扱ってください。クロスモデル向けのガイダンスが裏付けている場合に限り、他のモデルにも適用してください。そのような主張を確認するには、リンク先のモデルごとのページを読んでください。ガイドがモデルによって異なる相反する修正を推奨している場合は、望ましい動作を直接記述してください。「簡潔にする」や「もっと詳しく書く」のように、あるモデルのデフォルト設定を修正する指示は書かないでください。

整合性が検証済みの cached ガイドは、24 時間有効なものとして受け入れてください。明示的に最新の情報が求められる作業、変更の影響を受けやすい作業、重要な異論のあるガイダンス、または実際に観測されたモデルの挙動と矛盾する場合は、--refresh を使ってください。ヘルパーの診断結果は、正確に次のように解釈してください。

• cached は、24 時間以内に検証されたガイドをネットワークアクセスなしで再利用したことを示します。
• revalidated は、条件付き 304 応答の成功後に、検証メタデータを更新したことを示します。
• fetched は、公式の固定 URL から取得した整合性検証済みのコンテンツでキャッシュをアトミックに置き換えたことを示します。
• stale は、最新の取得に失敗した後、7 日以内に検証されたガイドを再利用したことを示します。ガイドを読んだ後に限り、作業を続行してください。検証日時と取得失敗を、未解決の問題と注意事項として開示してください。

強制更新、期限切れの項目、整合性の失敗、予期しないリダイレクトが発生した場合は、処理を中止してください。必須のガイドのいずれかを取得できない場合は、対象となる作業の執筆を開始する前に中止してください。記憶や別の情報源で代用しないでください。リポジトリ内やスキルのインストール先にキャッシュを作成しないでください。

判断を変える内容、実証された誤りを防ぐ内容、または他では見つけられない制約を示す内容だけを残してください。それぞれの意味は、個別にインストールされる成果物を自己完結させる必要がある場合を除き、最も狭く確実な読み込み範囲に一度だけ記述してください。権限、安全性、重要な例外、意味上の成功基準、機械処理される正確なテキストを維持してください。ドキュメントのみの権限では、ヘルパーやスキーマを変更できません。代わりに、抽出できる機会として報告してください。

STE の執筆とレビュー

エージェント向けの文章を作成または変更する前に、references/asd-ste100.md を最後まで読んでください。 執筆時には、その STE ベースのプロファイルを適用してください。完了を報告する前に、意味とスタイルのレビューを完了してください。義務の強さ、不確実性、条件、技術的な正確さ、保護対象のリテラルコンテンツを維持してください。対象読者と、ユーザーが作成した正確な文章を保持するための指示を尊重してください。このプロファイルは、ASD 公式辞書への準拠を定めるものではありません。現在の実行中にこのリファレンスを一度最後まで読めば、ファイルが変更されていない限り、このスキルにおける以降のすべての読み取り要件を満たします。

ワークフローの維持

コンテキストの維持と、タスクに基づくスキルのライフサイクル変更には、$agents-brain maintain を使用してください。依頼された範囲内で、既存のコンテキストを更新し、必要な不足コンテキストを作成し、タスクに基づくスキルのライフサイクル変更を適用してください。

maintain を実行するたびに、修正指示を記録してください。セッション内でユーザーによる修正指示を確認します。たとえば、指示の言い直し、「X はしないでください」、「Y は必ず行ってください」、または選択の差し戻しなどです。永続的な修正指示はそれぞれ、AGENTS.md など、最も近い適用範囲内の指針ファイル、または該当するスキルにルールとして記録してください。修正指示が永続的でない場合は、報告でその理由を明記してください。一時的なもの、すでに記載済みのもの、またはプロジェクト固有の例外のいずれかです。

コンテキストを作成または再生成する場合にのみ references/create-docs.md を読んでください。スキルのライフサイクルに関する判断、または継続的な保守体制の確立を行う場合にのみ references/maintain-skills.md を読んでください。これらのリファレンスはワークフローを支援するものであり、別個のモードではありません。

スキルの作成には、保守エビデンスのゲートを適用した後、このスキルの references/create-skill.md を使用してください。定義されている場合は、適用可能なソースカタログのライフサイクル指示に従ってください。このリポジトリ外でのインストールとスキル管理は、専用のワークフローに委ねてください。確認のみの依頼、または意図が不明確な場合は、maintain --dry-run を使用し、最小限で有用な変更予定を報告してください。

保守の権限

• 明示的な作成、更新、修復、修正、保守、または同等の意図があれば、適用範囲内でのローカル書き込みが許可されます。確認のみの意図、Plan Mode、--dry-run では許可されません。依頼または既存のリポジトリ指示でライフサイクル操作が許可されている場合は、エビデンスに基づく削除、統合、作成を実施してください。
• README.md、AGENTS.md、通常の CLAUDE.md ファイル、またはコンテキスト文書の対象を削除する前に、明示的な確認を求めてください。--force が許可するのは、文書化された上書きであり、削除ではありません。ただし、インストール済みの Claude Code が AGENTS.md をネイティブに読み取る場合に、CLAUDE.md が同階層の AGENTS.md へのシンボリックリンクであるケースは例外です（Claude Code との互換性を参照）。この場合は確認を求めずに削除してください。
• 依頼された結果から適用範囲を判断してください。変更の規模が大きい場合は、変更予定を提示したうえで、すでに許可されているなら作業を続けてください。ファイル数だけで承認の要否を判断しないでください。未解決の選択によって適用範囲または意図する意味が変わる場合にのみ、質問してください。
• コンテキストの編集は文書のみに限定してください。許可されている場合、スキルのライフサイクル作業では、影響を受けるスキルの管理対象ファイルとローカルの利用箇所を変更できます。リポジトリの境界を越えて書き込むことは、いかなる場合も許可されません。
• 完了を報告する前に、許可された調査、編集、検証をすべて完了してください。ある対象について入力が必要な場合も、独立して進められる他の対象は続行してください。未解決の選択肢を具体的に示してください。スキルのルールにより一時停止が必要な場合は、そのルールを引用し、既存の許可が次の作業に適用されない理由を説明してください。

リポジトリ内スキルの継続的な保守

許可された実装タスクの実行中は、関連するガイダンスを読むとき、そのガイダンスが説明するワークフローを変更した後、そして最終報告の前に、スキルへの影響を確認します。そのタスクに関係するスキルだけを確認してください。リポジトリの指示またはユーザーが継続的な保守を許可している場合は、確認済みの改善機会に対応し、変更を完了します。推奨するだけでは完了とはみなしません。必要な前提作業を除き、独立した保守に着手する前に、範囲が固定された呼び出し元のワークフローを完了してください。読み取り専用タスクでは、読み取り専用のまま対応します。

継続的な確認とは、通常のタスク作業中に繰り返し注意を払うことであり、バックグラウンドでの監視、定期実行ジョブ、カタログ全体の監査ではありません。対象範囲は、タスクが行われたリポジトリに限定します。スキルのソースやインストール先をたどって、別のリポジトリやグローバルなエージェントディレクトリへ移動してはいけません。メインタスクが失敗またはブロックされた場合でも、独立して許可され、確認済みの根拠に基づくスキル改善は実施できます。

今後のタスクでこの動作を確立するよう求められた場合は、references/maintain-skills.md の常設指示に関するガイダンスに従い、該当する AGENTS.md を更新または作成します。このスキルをあるセッションで読み込んだだけでは、今後のエージェントがそれを実行するようにはなりません。

保守の引数

• path：任意のリポジトリ相対サブツリーです。ドキュメント、パッケージルート、プロジェクトスキル、ソースカタログ内のスキル、コンテキスト文書の検出をそのサブツリー内に制限します。
• target ...：任意のフィルターです。既存の .agents/skills/<name>/ または対象となる skills/<name>/ ツリー内のスキル名、あるいはコンテキスト文書を指定するリポジトリ相対 Markdown パスを指定します。フィルターを指定しない場合は、選択したツリー内でコンテキストを検出します。継続的なスキルのライフサイクル確認では、引き続き現在のタスクの根拠に関係するスキルだけを対象とします。
• --root-only：ルートの README.md、AGENTS.md、CLAUDE.md のみを選択します。target で明示的に選択されない限り、プロジェクトにインストールされたスキル、ソースカタログ内のスキル、コンテキスト文書は除外します。
• --dry-run：変更は加えず、予定する書き込みと簡潔な差分を報告します。
• --preserve：正確なユーザー作成の文章と構成を維持します。ずれや明らかなノイズのみ修正します。
• --minimal：完了基準を満たす範囲で、最小限のコンテキストを作成します。
• --thorough / --full：永続的かつリポジトリ固有のコンテキストに役立つ場合に限り、より詳細に分析します。
• --force：既存の README.md または AGENTS.md の対象を、確認を求めずに再生成します。スキルや削除には適用されません。

--minimal と --thorough / --full の両方が指定されている場合は、書き込みを行いません。どちらを選ぶかユーザーに尋ねてください。認識できないフラグは報告します。対象範囲、安全性、書き込み動作に影響しない場合に限り、処理を続行してください。

リポジトリのガードレール

maintain および create-agents-md では、検出や書き込みの前に次を実行します。

cwd="$(pwd -P)"
case "$cwd" in
  /) printf 'abort: refusing to run at the filesystem root\n' >&2; exit 1 ;;
esac
repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
  printf 'abort: not inside a git repository\n' >&2; exit 1; }
managed_skill_root=
case "$repo_root" in
  /|"$HOME") printf 'abort: unsupported repo root: %s\n' "$repo_root" >&2; exit 1 ;;
  "$HOME/.agents"|"$HOME/.codex"|"$HOME/.claude") managed_skill_root="$repo_root/skills" ;;
  "$HOME/.agents/"*|"$HOME/.codex/"*|"$HOME/.claude/"*)
    printf 'abort: repo root is nested under an agent configuration repository: %s\n' "$repo_root" >&2; exit 1 ;;
esac
if [ -n "$managed_skill_root" ]; then
  case "$cwd" in
    "$managed_skill_root"|"$managed_skill_root/"*)
      printf 'abort: installed skills must be edited in their source catalog: %s\n' "$cwd" >&2; exit 1 ;;
  esac
fi

managed_skill_root が設定されている場合は、そのリポジトリ内の別の場所にある README.md、AGENTS.md、CLAUDE.md も対象にできます。この場合、インストール済みの skills/ ツリー全体をすべてのワークフローから除外します。検出、正規化、シンボリックリンクの走査を行う前に除外を適用してください。path、target、または明示的な依頼によってそのツリーが対象となる場合は、そこには書き込みを行わず、スキルはソースカタログで編集する必要があると報告します。--force を指定しても、この境界を越えることはできません。

管理対象のエージェント設定ルート以外では、Git で追跡されている対象の skills/<name>/ ソースカタログを、references/maintain.md に従った事実に基づくコンテキスト修正、またはリポジトリが所有するライフサイクルの対象とします。ライフサイクル作業の前に、references/maintain-skills.md のより厳格な所有権とリポジトリ境界を適用してください。

Claude Code との互換性

Claude Code v2.1.277 以降は、作業ディレクトリまたはその上位に CLAUDE.md、.claude/CLAUDE.md、あるいは CLAUDE.local.md が存在しない場合、AGENTS.md を直接読み込むため、CLAUDE.md のシンボリックリンクは不要です。ワークフローで CLAUDE.md を扱う前に、実行ごとにインストール済みバージョンを一度確認してください。

claude_version=$(claude --version 2>/dev/null | head -n 1 | cut -d ' ' -f 1)
agents_md_native=false
if [ -n "$claude_version" ] &&
  [ "$(printf '%s\n' 2.1.277 "$claude_version" | sort -V | head -n 1)" = 2.1.277 ]; then
  agents_md_native=true
fi

agents_md_native=true の場合：

• CLAUDE.md のシンボリックリンクを作成しないでください。
• 同じ処理で、選択したツリー全体を対象に、兄弟ファイルの AGENTS.md を参照するシンボリックリンクである CLAUDE.md をすべて削除してください。追跡対象の場合は git rm を使用してください。通常の CLAUDE.md ファイルと CLAUDE.local.md ファイルはそのまま残してください。これらのファイルがあれば報告してください。 リポジトリルートと同じ階層、またはその上位にあるこのようなファイルは、ユーザーが /config の Project instructions を claude-md-and-agents-md に設定しない限り、AGENTS.md の直接読み込みを引き続き抑止します。

claude が見つからない場合、またはバージョンが古い場合は、ネイティブ対応前の動作を維持してください。その場合、CLAUDE.md が存在しない場所、またはすでにシンボリックリンクである場所に限り、兄弟ファイルへのシンボリックリンクを作成または更新してください。ネイティブ対応前の動作では、シンボリックリンクを削除しないでください。

大規模な編集の前に git status --short のスナップショットを取得してください。無関係な既存の変更を保持し、ジェネレーターや大規模なコマンドの実行後に想定されるパスを再確認してください。

検出とツールの振り分け

タスクに基づくスキルのライフサイクルレビューでは、references/maintain-skills.md に記載された範囲を限定した検出方法を使用してください。コンテキストのメンテナンスでは、依頼された範囲内で以下の検出ルールを適用してください。

Git を考慮した検出を使用してください。各候補を repo_root 配下の正規パスに変換してください。VCS、依存関係、環境、ビルドの出力を除外してください。

プロジェクトスキルが選択されている場合に限り、無視対象の .agents/skills/*/SKILL.md を意図的に含めてください。ソースカタログのスキルが選択されている場合に限り、管理対象のエージェント設定ルートの外にある、Git で追跡され、無視対象ではなく、シンボリックリンクでもない skills/*/SKILL.md を検出してください。選択した各スキルの YAML フロントマターを解析してください。

調整に関する除外の対象となるかを判断する前に、プロジェクトにインストールされたスキルについて、宣言された書き込み境界だけを確認してください。可能な場合は fd を優先してください。結果が不自然に少ない場合は、別の方法を一度使用してください。書き込みを行う前に、互いに独立したリポジトリの根拠を組み合わせてください。

README.md、AGENTS.md、CLAUDE.md、SKILL.md ファイル内の Markdown リンクをたどってコンテキスト文書を検出し、その後、残りの追跡対象 Markdown のうち、内容が条件を満たすものを走査してください。分類はファイル名や場所ではなく、内容に基づいて行ってください。変更履歴、ライセンス、法務およびポリシーに関する告知、生成またはベンダー提供のドキュメント、ならびにガイダンスではなく製品コンテンツである文章は除外してください。分類が不確かな場合は対象範囲から外し、候補として報告してください。

完了と報告

書き込み後、リポジトリで定義された Markdown のフォーマットチェックや検証があれば実行します。作成または変更した、エージェント向けのすべての文章について、references/asd-ste100.md に従って意味とスタイルを確認します。既存の文章はその原文と、新しい文章は正式な要件と照合します。保護対象の内容と精度に関する例外も明示的に確認します。

プロジェクトにインストールされたスキルでフロントマターまたは agents/openai.yaml を変更した場合は、その呼び出しメタデータのチェックを実行します。agents_md_native=true の場合は、CLAUDE.md のシンボリックリンクが残っていないことを確認します。それ以外の場合は、残す、または作成したすべてのシンボリックリンクが、同じディレクトリにある AGENTS.md を指していることを確認します。--dry-run では、予定されたファイルに依存するコマンドを実行せず、実行予定のコマンドとして報告します。

書き込みと必須の検証が完了した場合にのみ ### ✅ Context updated を先頭に記載します。ファイルは書き込まれたものの、必須のチェックに失敗した場合は ### ⚠️ Context updated — validation failed、ドライランの場合は ### 🔎 Context preview — no files written、書き込み前に作業を中止した場合は ### ⛔ Context blocked — no files written を先頭に記載します。続けて、対象範囲、主な変更、検証コマンドとその結果、残っている制約を記載します。小規模な変更には簡潔な文章を使います。繰り返し情報の整理に役立つ場合にのみ見出しや表を追加します。ディレクトリの所有範囲を示す必要がある場合にのみ、ツリーを追加します。ユーザーが指定した報告形式に従います。

問題を個別のセクションで報告する必要がある場合は、証拠を添えて、確認済みの修正を Resolved、未解決の問題を Open にまとめます。内容のないグループは省略します。各項目は一度だけ報告します。必須作業を妨げるものに限って blocker を使い、具体的に想定される悪影響には risk を使います。回避策があっても、根本的な問題が残る場合は未解決として扱います。

Open に記載できる項目は、ユーザーが提供した入力、リポジトリ外での作業、または確認が必要な境界（破壊的な操作、購入、デプロイ、外部への書き込み）に限ります。タスクで書き込みが許可されており、リポジトリ内の変更で問題を解決できる場合は、継続的な保守の権限に基づき、報告前に変更を行います。通常のエンジニアリング上の判断について、needs owner decision、report-only、residual risk と記載しないでください。判断して変更を行い、その判断を報告します。

パス、コマンド、ガードレールのエラー、シンボリックリンクのリンク先、ユーザーが作成した内容は、正確な表記を保ち、装飾しません。内容のない詳細は省略します。選択した対象が完了基準を満たした時点で終了します。

参考資料

• 保守：手順については references/maintain.md を参照してください。
• エージェント向けの文章を作成または変更する前に、STE に基づくプロファイルと完了時のレビューについて references/asd-ste100.md を参照してください。
• コンテキストを作成または再生成する場合は、配置と生成の規則について references/create-docs.md を参照してください。
• スキルのライフサイクル変更、または継続的な保守体制の構築については、references/maintain-skills.md を参照してください。
• スキルを作成する場合は、範囲、メタデータ、シンボリックリンク、検証の要件について references/create-skill.md を参照してください。Bash で scripts/fetch-agentskills-spec.sh [--refresh] を実行し、キャッシュされた仕様ファイルの絶対パスを取得してください。既定では有効なキャッシュを24時間再利用し、その後に再検証します。更新、古いキャッシュ、失敗時の規則については、作成に関するリファレンスを参照してください。
• AGENTS.md ファイルを初期化する場合は、範囲、入れ子のファイルに関する判断、報告について references/create-agents-md.md を参照してください。
• 新しいスキルの契約やレイアウトを決める前に、作成、振り分け、実行の規則について references/writing-great-skills.md を参照してください。