dotagents

個人用の AI 開発ツールキット。スキル・hook・リポジトリのプロファイルを、Claude Code・Cursor・Codex の 3 つで同じように動く形でグローバルに 1 回入れる。Claude Code は AGENTS.md を読まないので、CLAUDE.md はここへのシンボリックリンク。

文書もスキル本文もすべて日本語で書く。 英語のまま残すのは、コード・識別子・コマンドと、スクリプトがパースする見出し（🧱 Landing plan の表見出し、修正計画のバケット名。英語を括弧で併記する）だけ。英語の README は置かない。原本と食い違う古い翻訳は、翻訳が無いより悪い。

配置・インストール・upstream スキルの一覧は README.md。なぜこの形なのかは docs/design.md。新しいものをスキル・hook・サブエージェント・MCP・常時ロードのどれにするかは docs/mechanisms.md（出典つき）。何を決め、何を誤って決めたかは docs/decisions.md。ループドライバの使い方（XS/S/M/L、着地を止めるもの、台帳の読み方）は docs/loops.md。セッションの続きは scripts/handoff.sh が git・台帳・gh だけから出す。手書きの引き継ぎ文書は持たない（リポジトリの状態の写しは古くなる）。このファイルには、見ても分からないことだけを書く。

不変条件

どれも壊れたとき黙って壊れる。エラーもログも出ず、動いているように見える。だから一度読めば済む文書ではなく、ここに置く。

1. スキルは name と description だけで動かなければならない。 Cursor が解釈するのは name・description・paths・disable-model-invocation だけで（Codex も name・description のみ）、allowed-tools・context: fork・model・argument-hint は黙って捨てる。制約は本文に書き（「サブエージェントで実行する」「ソースは変更しない」）、Claude 専用の frontmatter は上乗せの最適化として扱う。仕組みにはしない。verify-skills.sh が検査する。
2. disable-model-invocation は、常に自分で打つスキルには正しく、呼び出し先には致命的。 モデルの自動呼び出しだけでなく、Skill による呼び出しとサブエージェントの事前ロードも止め、description も文脈から消える（だから予算はゼロ）。次の 2 か所には絶対に付けない。verify-skills.sh と lint hook の両方が止める。
   • da-verify —— gate.sh arm を実行する唯一のもの。自動呼び出しが無いと Stop ゲートが arm されず、毎ターン素通りする（ガードレールが開く）。scripts/loop.sh もゲートを gate.sh arm の直接呼び出しではなく /da-verify と打つことで arm する。arm には証跡の表、エージェントに禁止されたチェックの委譲、プロファイルが無い時の拒否が一緒に付いてくるので、2 つ目の呼び出し口を作るとそれらが落ちる。コードに合わせて不変条件を曲げない
   • x-review-backend / x-review-frontend / x-review-infra —— da-review-all が名前で呼ぶ。付けると、ディスパッチャはその層を何もレビューせずに「済み」と報告する
3. 本物の YAML パーサが弾く frontmatter でも読み込まれてしまう。 description に引用符なしの ": " があるとネストしたマッピングとして解釈され、メニューには説明付きで出るのに壊れている。値を引用符で囲むか、全角の区切りを使う。
4. hook はコピーで入れる。シンボリックリンクにしない。 リンクが切れると hook は 127 で終了し、Claude Code はそれをブロックしないものとして扱う。ガードレールが閉じずに開く。コピーは切れない。そのぶん、ここで hook を直しても setup.sh install を再実行するまで効かない。
5. reference のファイルは ${CLAUDE_SKILL_DIR} で指す。 絶対パスに展開されるので、サブエージェントが cwd に関係なく解決できる。相対パスはそこで黙って失敗する。

6. ゲートはスキルが arm するまで何もしない。arm するのは gate.sh arm だけ。 プロファイルが合わないまま arm されたゲートは、有効だと報告しながら毎ターン素通りする（arm 時に警告を出す）。~/.claude/.dotagents-gate/trace.log に全呼び出しと通した理由が残るので、「ゲートが何もしなかった」と思ったら先に読む。trace は 200 行で自動で切り詰められるので、残るべき記録は隣の verdicts.log。

   arm が外れるのは disarm と、そのリポジトリでターンが終わらないまま 12 時間経った時の 2 つだけ。ブロックしなくなるのは 3 つ目として、同じチェックが max_attempts（3）回続けて失敗して VERDICT が記録された時。解放されたゲートは緑ではない。 status・verdicts.log・次の arm がすべて「諦めた、未検証」と言う。「not armed」としか出ないなら、それは回収されたのではなくきれいなセッション。

   リポジトリを arm すると、共有 git dir で一致する linked worktree も arm される。試行回数は worktree ごとに数える（ゲートを引き継いでも、別の作業と回数を共有しない）。両方を決める関数は scripts/gate.sh と hook に dotagents:gate-shared ブロックとしてバイト単位で複製してある。不変条件 4 で hook は消えうるパスに依存できないため複製し、verify-skills.sh が一致を検査する。

7. 接頭辞は 2 種類。この分け方がメニューを正直に保つ。 da-* は打つもの。 x-* は内部用（呼び出し先とサブエージェント。打たない）。user-invocable: false は Claude 専用で、Cursor はサブエージェントをコマンドピッカーに出すので、フィールドで隠す方法は両方では効かない。da 接頭辞を共有しないことは効く。/da で Claude Code と Cursor に、$da で Codex に同じ一覧が出る。

   どれかの名前を変えると 3 か所が黙って壊れる。verify-skills.sh の disable-model-invocation の対象、lint hook の同じ一覧、そして名前で検索しても当たらない `x-review-<layer>` のようなテンプレのプレースホルダ。両ファイルは一覧を dotagents:dmi-gate / dotagents:dmi-dispatch 行のデータとして持ち、verify-skills.sh が全名前の解決・2 つの一覧の一致・プレースホルダの接頭辞を検査する。このマーカーのコメントを消すと検査が消えるので、どちらかが無ければ linter がエラーにする。

8. スキルには必ず metadata.source: bwkw/dotagents を付ける。 20 以上の他人のスキルの中に自作が並ぶ。自作は書き換えてよく、upstream のものは入れるか外すかしかできない（その場で直しても次の npx skills update で消える）。hook の出力に [dotagents] を付けるのも同じ理由。
9. ここに秘密情報を置かない。 setup.sh はテンプレートが宣言したキーだけをマージし、自分が書いていない値は読みも書き換えもしない。編集先のエージェント設定には他人の認証情報が入っている。
10. エージェントはモデルを固定しない。常に model: inherit。 固定するとセッションで選んだモデルを黙って上書きする。Opus を選んでも別のモデルで動き、プロンプトにも記録にも出ない。固定は実際に安い（トークン約 37% 減）ので、「追跡は機械的だから大きいモデルは要らない」とわざと破られやすい。一度その理屈で出して戻した。 問題は節約の大きさではなく誰の判断か。ユーザーが同意していない節約は、ツールが黙ってユーザーに逆らうことになる。 これは Claude 専用のフィールドではない。 不変条件 1 の「Cursor は model: を捨てる」はスキルの frontmatter の話で、サブエージェントでは Cursor も name・description・model・readonly・is_background を読み、既定は inherit。固定すると両方でユーザーを上書きする。Codex のエージェントは setup.sh が agents/*.md から TOML を生成し、model を書かない（書くと同じく上書きする）。 コストはサブエージェントの数で削る。動かすモデルでは削らない。 レビューは範囲 1,000 行以下では 1 本も起動せず、超えた時だけ担当ごとのレビュー役と所見ごとの反証役を起動する（決定 41）。起動する役もモデルを継ぐ。verify-skills.sh は inherit 以外の model: をエラーにする。

実装の進め方

常にテストから。 先に失敗するテストを書き、それを通すコードを書く。作ったものを後から説明するテストではない。機能追加でもバグ修正でも既定で、頼まれて入るモードではない。詳しい手順は /test-driven-development。ここに書くのは、誰も呼ばない時にも既定を守らせるため。

バグ修正はバグを再現するテストから始める。そうすれば「直った」に意味が出る。実装の後に実装から書いたテストは、コードがコードどおりに動くことしか確かめない。 テストを最後に足したなら、検証として出さずにそう書く。

テストは結合レベルに寄せる。 ユニット同士を、モックではなく本物の境界を通して一緒に動かす。frontend と backend にまたがる変更なら、両方を通るテストが効く。純粋関数にはユニットテストを書く。避けるのは協力者を全部スタブにしたから緑になっているテスト群。

この方針はドライバの実装プロンプト（scripts/loop.sh）にも意図的に重複させている。ループはプロダクトのリポジトリで動き、そこのエージェントはこのファイルを読まないため。

効いてくるサイズ

SKILL.md は 12 KB 以下。スキルの本文はセッションが終わるまで文脈に残り、読み直されない。自動圧縮の後は各スキルの先頭約 5,000 トークンしか戻らず、それ以降は黙って失われる。詳細は必要な時に読む reference/ に置く。日本語は 1 文字 3 バイトなので、バイト数の上限に早く届く。

description は全部が常に文脈に居続ける。スキルを 1 つ足すたびに、既存のスキルすべての選ばれやすさが下がる。/da-skills-audit が測る。

スキルを使う時

作業の前に、既に入っているスキルで足りないか確かめる（/ で一覧、README.md に「こう言う / こういう時」の表）。ユーザーの指示はスキルの記述より優先する。 最初に確認の質問をすることを求めるスキルがある（da-investigate と da-design-review は目的が述べられていないと断る）。スキルの実行条件が質問を求めるなら、作業の前に聞く。

upstream のスキルを入れる時

必ず -s を付ける。 付けずに npx skills add <repo> するとリポジトリ全体が入り、1 回で description の予算を食い潰す。厳選した一覧は README.md。

外すと残骸が残る。 npx skills remove <name> -g -a claude-code -a cursor はエージェントのディレクトリのリンクを外して ~/.agents/.skill-lock.json を更新するが、~/.agents/skills/ の実体は残す。Cursor はそこを直接読むので、Claude Code からは消えたと報告されたまま Cursor では生きている。実体も消し、2 つが一致することを確かめる。

diff <(ls -1 ~/.agents/skills) <(ls -1 ~/.claude/skills)

スキルを書く時

_template/ から始め、./scripts/verify-skills.sh を通す。必須の節（この順）:

• 実行条件 —— 成り立っているべきことの表。各行に、成り立たない時にどうするか（止める、どの条件で止まったか報告する、先に進まない）。linter がこの節の存在を検査する
• 読むファイル —— 「常に読む」と「この時だけ読む」に分ける。最初に全部読むスキルは、自分の作業に要る文脈を先に使い切る
• 調査・レビューをするものには読み取り専用の宣言
• 根拠の扱い —— 本文か reference/ のファイルに。直接確かめたことだけを書く。path/file.ts:L42 で引用する。推測せず「確認できなかった」と書く。事実と推論を分ける。外部の主張には URL を付ける

レビュー観点の置き場所。 skills/_shared/ には仕組みを置く。すべての層で、発見フェーズと検証フェーズの両方に効く観点。シンボリックリンクなので、ここに足した段落は全レビュースキルが読む。各層の reference/perspectives.md には具体例を置く。その仕組みがそのスタックでどう現れるか（フィールド名、ファイル種別、API）。両方に当たるなら仕組みを _shared/ に書き、層のファイルは書き直さずに 1 行で指す。同じ観点の写しが 2 つあるとずれていき、どちらも読めてしまうのでずれが見えない。verify-skills.sh がその 1 行の参照先が存在することを検査する。理由と検査の範囲は docs/decisions.md の決定 30。