| 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 バージョン」。
