update-herdr-skill

name	update-herdr-skill
description	herdr のバージョンが上がったときに、herdr プラグインの SKILL.md を現在インストールされている herdr の CLI 仕様に追従させる。「herdr スキルを更新して」「herdr のバージョンが上がったからスキルを直して」といった指示で発動する。

herdr スキルの更新手順

herdr プラグインの SKILL.md を、現在インストールされている herdr の CLI 仕様に合わせて更新する。対象は herdr 本体の自作スキルであり、herdr 本体のアップデート自体はこのスキルの範囲外 (herdr update 等でユーザーが別途行う)。

前提

• このスキルを実行する時点で、ターミナル上で最新化したい herdr バージョンがすでに動いていること (herdr --version で確認できる)。
• スキル本体にはバージョン番号や「vX.Y.Z で追加」のような来歴注釈を書かない。このスキルは自分しか使わず、スキル記載時点より古い herdr を使うことは無い前提のため、現在の事実だけを書けば十分。バージョン情報は git のコミット履歴側に残す (後述)。

手順

1. 前回同期時点を特定する

git log --oneline -- packages/claude-plugins/plugins/herdr/skills/herdr/SKILL.md

直近のコミットメッセージから、前回同期した herdr バージョンを拾う (コミット規約は手順6を参照)。見つからない・読み取れない場合はユーザーに確認する。

2. 差分の当たりをつける (あくまで仮説、鵜呑みにしない)

前回バージョンから現在バージョンまでの 公式 CHANGELOG を取得し、CLI サブコマンド・フラグ・挙動に関わりそうな Added/Changed/Fixed エントリを洗い出す。

ここで拾った内容は「疑わしい変更点の候補」に過ぎない。CHANGELOG の文言をそのまま SKILL.md に書き写さない — 手順4で実機検証してから書く。

新しいトップレベルコマンドツリー (herdr <noun> ...) は herdr --help の usage 一覧に載らないことがある (例: plugin, terminal は追加時点で usage に出てこなかった)。CHANGELOG 内の herdr <word> パターンを grep するなどして見落としを防ぐ。

3. 現在の CLI 仕様を機械的に取得する

判明している全サブコマンドツリーに対して --help を取得する:

for cmd in "" status update config channel workspace worktree tab notification agent pane wait session integration api completion server plugin terminal; do
  echo "===== herdr $cmd --help ====="
  herdr $cmd --help
done

手順2で見つけた「usage に出てこない新規ツリー」があれば、上記のコマンドリストに追加してから実行する。

--help はサブコマンドの構文しか教えてくれない。公式 CLI リファレンスの環境変数一覧 (HERDR_PANE_ID 等) のように、--help に出てこないが CLI 経由の操作に関わる情報源もあるので、変更が疑われる場合はそちらも確認する。

4. SKILL.md の現状と突き合わせ、変わった箇所を洗い出す

SKILL.md を通読し、手順3の --help 出力と食い違う箇所 (存在しなくなったコマンド・フラグ、新規コマンド・フラグ、レスポンス形状の変化) を洗い出す。

5. 非自明な挙動は実機で検証してから書く

--help はコマンドの構文までしか教えてくれない。挙動の解釈が絡む記述 (id が再利用されるか、プロセスが exit したときに pane がどうなるか、target 解決の優先順位、等) を新しく書く・書き換える場合は、CHANGELOG や --help の記述を鵜呑みにせず、安全な範囲で実際に再現してから書く。

検証の進め方の実例:

• pane/tab/workspace を試しに作る (split / tab create / workspace create)
• 対象の挙動を発生させる (close する、プロセスを exit させる、時間を置く、など)
• レスポンスや後続コマンドの結果で挙動を確認する
• 検証が終わったら作った pane/tab/workspace は必ず close して片付ける (テスト用の痕跡を残さない)
• 一つのサンプルだけで一般化しない。挙動が階層 (pane/tab/workspace など) によって違う可能性があるなら、面倒でも各階層で確認する。1箇所しか確認できなかった・サンプルが矛盾するなど確信が持てない場合は、その記述自体を書かない (無理に一般化した記述を残さない)

検証していないことを検証済みであるかのように書かない。書けるのは実際に確認できた範囲だけ。

再現にリスクが伴う場合

安全に再現できない (ユーザーの画面上の UI フォーカスを動かす、既存の workspace/pane に影響しうる、その他副作用が読み切れない、等) 挙動に当たったら、次のどちらも避ける:

• 黙って再現を諦めて「CHANGELOG の記述による」のようなヘッジ付きの記述のまま SKILL.md に残す
• 確認せずに黙って実行する

代わりに、何を・どう再現すれば確認できるか (具体的なコマンド列と、想定される副作用) をユーザーに提示し、実施してよいか確認を待つ。承認が得られたら実際に実行し、確認できた結果を SKILL.md にヘッジなしで反映する (副作用があった場合は元の状態に戻す)。「検証しようとしたがリスクを理由にやめた」状態の記述は、書く価値がほとんど無い — 結局あとから「じゃあやって」と言われるだけなので、その手前で確認を挟む。

6. SKILL.md を更新する

手順4・5で判明した差分を反映する。書き方は以下のハウススタイルに従う:

• バージョン番号・「vX.Y.Z で追加/修正」といった来歴注釈は書かない
• 「旧 SKILL.md では〜と書かれていたが」のような過去との比較説明も書かない — このスキルを読むエージェントは過去のバージョンのことを知らないし、知る必要もない。現在の事実だけを現在形で書く
• 実機検証で判明した非自明な挙動は「罠」節に集約する (このリポジトリの他のツールラッパースキル、例えば atuin プラグインの recall-commands スキルと同じ形式)
• なくなったコマンド・セクションは削除する。互換性メモや「以前はこうだった」的な注釈を残さない
• コーディングエージェントの操作対象外 (herdr 自体のセットアップ・アップデート・プラグイン管理等) は簡潔な一覧に留め、深追いしない
• recipes 内の id は、その recipe の中で実際にレスポンスから捕捉したものだけを使う。捕捉していない id をハードコードしない (例: NEW_PANE=$(herdr pane split ... | python3 -c '...') で受け取ってから使う。前の手順で作っていない pane id を勘で埋めない)

7. 差分をユーザーに確認してもらう

packages/claude-plugins/plugins/herdr/ 配下だけが変更対象であること (marketplace.json や設定ファイルへの追加登録は初回のみ必要な作業で、通常の更新では不要) を確認しつつ、変更内容をユーザーに提示する。想定外の追加判断が必要になった場合 (例: プラグイン構成そのものを変える必要が出てきた等) は、その場で立ち止まってユーザーに確認する。

8. コミットする

ユーザーの確認が取れたら、次回の手順1で拾えるように、コミットメッセージに同期先バージョンを明記する:

docs(herdr): sync skill with vX.Y.Z

X.Y.Z は手順1〜3で確認した「今回同期した herdr バージョン」。