skill

name	skill
description	スキル (SKILL.md) の新規作成・編集の進め方の正本。 ユーザーが Claude Code で /skill、Codex で $skill と入力したとき、またはスキルの追加・変更を依頼したとき、 または home/.agents/skills/ 配下の SKILL.md を変更する前に使用する。

/skill

スキルをドキュメントの TDD で作る。読者となる将来の agent が失敗するのを見てから書き、読ませて直るのを見てから確定する。設計の判断は ADR、経緯は dotfiles#1292。

絶対制約

• テストを経ずにスキルを確定しない。書く前にベースライン (RED)、確定前に読者テスト (REFACTOR)。新規作成も 1 行の編集も対象。
• テストより先に書いた本文は消してやり直す。参考として残さない。
• description に本文の手順・安全策・判断基準を要約しない。description だけで動けてしまう agent は本文を読まない。

インタビュー: 作る前に聞く

依頼の一言から要件を推測で埋めない。依頼が詳しく見えても、前提と発動場面はズレていることがある。RED の前に、1 ターン 1 問でユーザーに確認する。

• 何が起きたら発動してほしいか
• 前提にしてよいユーザーの状況
• 読み書きする情報の置き場。public repo に載せてよい内容かも確認する
• 完成時の振る舞いのイメージ。ユーザーに質問して確かめるのか、選択肢を並べて見せるのか

依頼と会話から答えが一意に読み取れる項目は聞かない。全項目が読み取れるときだけ、インタビューなしで RED に進んでよい。

RED: スキルなしで失敗を見る

スキルが対象とするタスクを、スキルを与えない subagent に投げて失敗を観察する。

• テストだと明かすと素の行動が変わる。現実の依頼として投げる
• 作業コピーを一時ディレクトリに作らせ、本番の skills ディレクトリは触らせない
• 同名のインストール済みスキルを読んで偽の結果を出さないよう、親が host trace や invocation metadata から読み込み元の canonical path を確認する。読者の自己申告だけでは合格にしない
• 作業コピー以外を読んでいたら結果を無効にし、live のインストールを変えず、同名スキルを探索しない使い捨て profile・skill root で再実行する。読み込み元を客観的に確認できない環境では実動テストとして扱わない
• 実施したことを時系列で報告させる。検証の有無・手順の抜けがそこに現れる
• 失敗と言い訳を逐語で記録する

編集のときも同じ。直したい失敗が現行版で再現するのを先に見る。

GREEN: 最小限を書く

観察された失敗だけに対処する。観察されていない失敗への対策は書かない。書き方は AGENTS.md の「AGENTS.md・CLAUDE.md・skill・docs・実装コメントなどの書き方」に従う。

形式は失敗のタイプに合わせる:

• 規律の省略 (わかっていて飛ばす) → 禁止と、言い訳への反論
• 出力の形の崩れ → 完成形のレシピやテンプレート。禁止の列挙は形の崩れには逆効果
• 条件で変わる挙動 → 観測できる条件つきの規則 (「〜の場合は」)

依存バージョン

• 通常のプロジェクトで manifest・lockfile・CI・repo 内の script が管理する依存は、再現性のためバージョンを固定する
• SKILL.md の手順から package runner で利用時に取得して実行する外部 CLI は、latest または同等の指定を既定にする。スキルの CLI バージョンを人手で更新し続ける運用にしない
• latest を選ぶことと、外部コードの取得・実行を許可することは別の判断。latest を理由に暗黙実行を許可せず、そのスキルに必要な承認・信頼境界を定める
• mutable であることだけを理由に、スキル内の latest を固定版へ変更しない。ユーザーが版を指定した場合、または特定版が必要な互換性・セキュリティ上の失敗を RED で再現した場合だけ固定し、理由と更新条件を書く

description には、いつ使うか (ユーザーの発話・状況・対象パス) を書く。何をするかは 1 文まで。第三人称で書く。

REFACTOR: 読ませて塞ぐ

SKILL.md を読ませた subagent に RED と同じタスクを投げ、意図どおり動くことを確認する。

• 新しい言い訳・抜け穴が出たら、その逐語への対処を本文に足して再テストする
• 規律を課すスキル (従うとコストがかかり、省略の誘惑がある) は、時間・サンクコスト・権威などの圧力を 3 つ以上重ねたシナリオで再テストする。圧力下で守られて合格
• 手順・reference 系のスキルは、subagent がそのままタスクを完遂できて合格

発動テスト: description で正しく選ばれるか

本文の読者テストに通っても、description の発動は別に壊れる。確定前に検証する。

• 発動してほしい発話と、発動してはいけない近縁の発話を数個ずつ用意する。言い換え・口語・typo・対象パス入りを混ぜる
• 本文は見せず、インストール済みスキルの description 一覧に対象の description を混ぜて subagent に見せ、発話ごとにどのスキルを使うか判定させる
• 不発動・誤発動が出たら description を直して再テストする。本文の手順や判断基準を description へ移して直すのは絶対制約のとおり禁止

最終検証: Claude Code と Codex で同等にする

両ホストで使うスキルは、REFACTOR の後に互換性を検証する。構文を同じにするのではなく、目的・入力・出力・ユーザーの決定権・安全策・停止条件が同等ならよい。ホスト固有の機能には条件分岐か代替手段を用意する。

対象 surface を先に決める。Claude Code local・cloud、Codex CLI・App・IDE などを一括りにせず、配置と利用場面から実際の対象だけを選ぶ。

チェックリストを先に固定しない。検証のたびに、Agent Skills、Claude Code、Codex の公式ドキュメントの最新取得を試み、対象機能の記述を確認してから今回のチェックリストを作る。同じセッションで鮮度を検証済みの公式キャッシュは再利用してよい。Agent Skills を共通の基準、各ホストの文書をその surface の拡張として読み、基準と拡張の差だけで矛盾扱いしない。

過去のチェックリストやモデルの記憶だけで判定しない。参照した URL、取得時刻、鮮度確認の結果、該当箇所、確認したホストとバージョンをテスト記録に残す。現在の公式情報を取得できない、同じ surface・バージョンの情報が解消不能に食い違う、対象機能が未記載の場合は未確認とする。編集内容は検証待ちとして引き渡せるが、両ホスト同等と判定しない。

公式ドキュメントを確認した後、現在のホストで対象機能を読み取り専用で確認する。利用可能なツールの schema、CLI の --help、skill selector、実際に読み込まれたファイルパスなどを使う。公式ドキュメントによる静的判定と、実装・実動による判定を分けて記録する。食い違う場合は両方を残し、実動結果は確認したホストとバージョンだけの根拠として扱う。

今回のスキルが使う機能だけをチェックする。少なくとも次の観点から該当項目を選ぶ。

• 配置、名前、description、暗黙・明示呼び出し
• frontmatter、ホスト別 metadata、引数展開
• ツール名、権限、承認、ユーザーへの質問
• subagent、Web・ブラウザ操作、作業ディレクトリ、git
• scripts・references・assets のパス解決と実行条件
• 同じ入力に対する成果物、報告内容、失敗時の停止条件

各項目を対象 surface に分け、実動合格・静的合格（実動未確認）・該当なし・未確認のいずれかと根拠を書く。ホスト固有の語や手順を共通手順として要求していないことも確認する。

利用できる各ホストで、同じ現実的な依頼を使って読者テストする。使い捨て profile・skill root の新しいセッションで対象の作業コピーだけを探索させ、host trace や invocation metadata から読み込み元の canonical path を親が記録する。外部書き込みは mock・fixture・一時 repo・一時 remote へ向ける。本物の push・投稿・送信は、ホストごとの明示承認なしに検証で実行しない。

片方を実行できない場合や安全に隔離できない場合は、公式ドキュメントに基づく静的検証まで行い、静的合格（実動未確認）と記録する。実行していない surface まで実動確認済みと扱わない。

完了

• 再テストと対象 surface の最終検証に未確認がなければ編集完了。PR にテスト記録 (シナリオ・観察された失敗・対処・発動テストのクエリと判定・公式情報・surface 別の結果) を書く
• 静的合格を含む場合は静的同等・実動未確認と報告する。両ホストで実動同等と報告できるのは、対象 surface がすべて実動合格した場合だけ
• 3 回直しても同じ失敗が出るときは、文書でなく設計を疑いユーザーに相談する