maintain-environment

環境を保守する

環境とは、エージェントが実行される際の権限、グローバル指示、プロジェクト指示、スキルのことです。このスキルは、環境に変更を加える際の出発点です。変更を加える場所を選び、その場所固有のガイドに従ってください。マシンやプロジェクトをセットアップするには、代わりに /set-up-machine または /set-up-project を使用してください。

• 各変更は、その変更元に一度だけ記述します。 そうすれば、後で変更するときも一か所を編集するだけで済みます。
• 公開ファイルに個人的な情報を含めないでください。 スキルリポジトリとほとんどのプロジェクトは公開されています。名前、アカウント、ユーザーのマシン上のパス、その他のプロジェクトに関する情報は、ワークステーションリポジトリにのみ記述してください。ワークステーションリポジトリがないマシンでは、共有グローバル指示ファイルに記述します。スキルや公開 AGENTS.md では、詳細を一般化するか、パラメーターにしてください。
• ハーネスのメモリー機能は無効のままにしてください。 メモリーは他のハーネスから見えず、どのリポジトリにも属さない場所に保存されます。メモリーに記録する内容は、代わりに適切な変更元に記述してください。

パラメーター

• <skills-repo>：GitHub 上にある、ユーザー自身のスキルリポジトリ（owner/repo）。
• <path-to-skills-repo>：そのリポジトリのクローン先。
• <workstation-repo>：ユーザー自身の個人的なエージェント設定用リポジトリ（通常は非公開、owner/repo）。
• <path-to-workstation-repo>：そのリポジトリのクローン先（例：~/code/agent-setup）。

変更を加える場所

2 つの質問で変更元を選びます。誰に必要か――このユーザーだけか、1 つのプロジェクトに携わる人か、タスクを実行するすべてのエージェントか。強制する必要があるか、それとも指針でよいか。次の表は、強制力が高いものから順に並んでいます。上から確認し、最初に当てはまる行を使用してください。

変更	変更元	ガイド
誰にでも適用されるルール：拒否、確認、または許可して報告する	<skills-repo> 内の /set-up-machine の rules.json	<path-to-skills-repo>/docs/design/set-up-machine.md。/set-up-machine に対するその他の変更にも適用
このユーザーだけが望むもの：作業上の合意事項やワークフローの項目、ロール用のツール、個人的な権限、ハーネスのデフォルト設定、プラグイン、すべてのマシンにインストールするもの	<workstation-repo> の <path-to-workstation-repo> にあるクローン	そのリポジトリの DESIGN.md：そこで指定されているファイルの形式を踏襲
1 つのプロジェクトでチームメイトに必要なもの	プロジェクトの AGENTS.md。CLAUDE.md には @AGENTS.md を記述します。プロジェクトで追加できるのは許可項目のみ	プロジェクトの AGENTS.md
チームのツールでタスクを実行する方法	<skills-repo> のスキル、または 1 つのプロジェクト内のローカルスキル	<path-to-skills-repo>/docs/design/<skill>.md があればそれに従い、references/skill-operations.md も参照

• 詳細がスキルの一部の実行時だけ必要な場合： SKILL.md の隣にあるリファレンスに記述します。本文にはそのリファレンスを読むタイミングを記し、末尾の ## References 行でそのリファレンスが扱う内容を示します。
• ユーザーにワークステーションリポジトリがない場合： 個人的な指示は共有ファイル自体に記述します。個人的な権限にはそのファイル内に適切な場所がないため、references/workstation.md に従ってワークステーションリポジトリの作成を提案してください。
• このマシンにポインターがない場合（~/.config/agents/source.md）：まず /set-up-machine を実行してください。これによってポインターが書き込まれます。
• ユーザーがワークフローの改善を求めた場合： <path-to-workstation-repo>/AGENTS.md と、そこで指定されている原則などのドキュメントを読んでください。変更を加える前に、その変更と相反する原則をそれぞれ挙げてください。

チームテスト。 別のハーネス、別のセッションホストを使い、/set-up-machine でセットアップしたものの、ユーザー個人のワークフローは何もないマシンを使うチームメイトを想定してください。変更後も、そのチームメイトは、プロジェクトの指示、スキル、/set-up-machine が書き込むロールだけを使って、ユーザーのあらゆるプロジェクトに取り組めなければなりません。つまり、チームメイトに必要なものをグローバル指示に置いてはならず、スキルがユーザーのデフォルトツールに依存してもいけません。設定によって異なる値は、スキル内で <kebab-case> のパラメーターにします。新しいロールは、まず /set-up-machine のロール表に追加します。条件に合わない部分は、それぞれ該当する行に移してください。

手順

1. 行を選び、変更内容をチームテストに照らして確認します。
2. ガイドに従って、変更をそのソースで行います。すべての指示とスキルは /writing-for-agents を使って記述します。インストール済みのスキルは、インストール先のコピーではなく、ソースリポジトリで変更してください。次の npx skills update で上書きされるためです。
3. 変更がグローバル指示に関わる場合は、変更した行に印を付けたうえで、共有ファイル全体がどのようになるかをユーザーに提示します。これらの行はすべてのエージェントに影響するため、コミットまたはリリースする前に承認を待ちます。
4. スキルの変更後、チームテストの監査を実行します。ユーザーの環境デフォルトにある各ツールと「environment defaults」を、スキル内で grep します。ただし、各ツール自身のスキル、2つのセットアップスキル、およびこのスキルは除外します。
   • スキルがツール自体を選択する場合： それをパラメーターにし、ツールのコマンドをそのツール自身のスキルに移します。
   • 例やデータとして使われている場合： そのまま残します。
   • 環境デフォルトの名前が記載されている場合： その記述を削除します。
5. スキルリポジトリの変更は、ブランチ上で行い、/to-pr を使ってプルリクエストを作成してから停止します。ユーザーがマージするか、依頼するまで待ちます。
6. 次の表に従って、変更をすべての環境に反映します。npx skills はデフォルトブランチからインストールするため、インストールと更新はマージ後に実行します。
7. このセッションで対応できない各手順と、それがこのマシン、他の各マシン、または各プロジェクトのどこで実行されるかを報告します。

変更	すべての環境への反映方法
全員向けのルール、またはセットアップスキル	マージ後、npx skills update を実行し、各マシンで /set-up-machine を再実行するか、各プロジェクトで /set-up-project を再実行します。
個人的な変更	ユーザーがコミットしてプッシュします。各マシンでプルし、/set-up-machine を再実行します。
ワークステーションリポジトリのないグローバル指示	各マシンで /set-up-machine を再実行します。
プロジェクトの指示または権限	プロジェクト内でコミットします。すべてのプロジェクトで共有する標準を変更する場合は、/set-up-project を変更し、各プロジェクトで再実行します。
ソースリポジトリにあるスキル	マージ後、スキルをインストールしているすべてのスコープで、すべてのマシン上で npx skills update <name> を実行します。ワークステーションリポジトリにそのスキルが記載されているマシンでは、/set-up-machine によっても反映されます。
ローカルスキル	プロジェクトとともにコミットします。

スキルの実行コストをユーザーから尋ねられた場合は、references/efficiency-analysis.md に従います。

参考資料

• references/skill-operations.md：スキルの種類と、その作成、インストール、更新、移動、削除、フォーク、リリース、監査、公開について説明します。
• references/efficiency-analysis.md：スキルを1回実行するコストの測定方法と、次回の実行コストを下げる方法について説明します。
• references/workstation.md：ワークステーションリポジトリの目的と、作成の始め方について説明します。

スクリプト

• scripts/session-usage.py：効率分析用に、指定した時点で区切ったセッショントランスクリプトのトークン使用量と時間を示します。