skill 本体と登録先を分ける
書く場所は 1 つにする
前回 は、rule.md の外にある再利用手順を persona-skills-core に分ける判断を書きました。今回は、その skill を Codex と Claude Code の両方へ届ける Bootstrap CLI の話です。
ここで一番避けたかったのは、skill 本体を2か所に書くことです。Codex 用の手順と Claude Code 用の手順を別々に持つと、更新のたびにズレます。だから、skill 本体は persona-skills-core/skills/ にだけ置きます。
登録先の差は CLI が吸収します。書き手は、どちらのエージェントにどう登録されるかを毎回意識せず、skill 本体の改善に集中できます。
登録先はエージェントごとに違う
同じ skill を呼べるようにしたいだけでも、登録先は同じではありません。
Codex側は plugin marketplace 経由で候補に出すClaude Code側は~/.claude/skills/配下の skill directory として候補に出す- 必要に応じて、
Codex側の互換用 skills symlink も張る
ここを人間が毎回手で処理すると、また同期作業が戻ってきます。Bootstrap CLI は、その登録先の違いを隠すための薄い層です。
Bootstrap CLI が差を吸収する
Codex 側は plugin として登録する
Codex 側では、plugin として見える場所に persona-skills-core を登録します。plugin 用 manifest と marketplace entry を用意し、実体は repository 側へ symlink します。
この形にすると、新規セッションで $ を押したときに persona-skills:technical-writing のような候補が出るようになります。skill 本体を直したら repository 側の差分を見ればよく、登録先の生成物を直接育てる必要はありません。
Codex 側の登録は、ざっくり次のような責務です。
- plugin manifest を Codex から見える位置に置く
- marketplace entry を登録する
- plugin directory を repository 側へ symlink する
- 既存ファイルと衝突する場合は conflict として扱う
Claude Code 側は skill directory として登録する
Claude Code 側では、~/.claude/skills/<skill-name> として skill directory を symlink します。/ スラッシュ候補に出る形です。
こちらも、skill 本体は repository 側に残します。~/.claude/skills/ 配下は登録先であって、作業手順を直接編集する正本ではありません。
Claude Code 側の登録は、ざっくり次のような責務です。
persona-skills-core/skills/配下の skill を列挙する~/.claude/skills/<skill-name>に symlink する- 同名 directory がある場合は上書きせず conflict として扱う
- 新規セッションで
/候補に出ることを確認する
手順は status → dry-run → apply にする
いきなり書き換えない
Bootstrap CLI では、状態確認、差分確認、反映を分けています。
python3 scripts/persona-skills.py status
python3 scripts/persona-skills.py install --dry-run
python3 scripts/persona-skills.py install --applystatus は読み取り専用です。今どこに symlink があり、どの登録先が有効になっているかを見るだけです。--dry-run は、実際に書き換える前に予定差分を表示します。--apply を明示したときだけ本番反映します。
自分のホームディレクトリを触る CLI なので、この段階分けはかなり大事です。最初から apply だけにすると、使う側が確認のタイミングを持てません。
戻す経路も用意する
登録する CLI には、戻す CLI も必要です。uninstall --apply で symlink や登録 entry を外せるようにしておくと、試してみたあとに撤回しやすくなります。
python3 scripts/persona-skills.py uninstall --applyここで大事なのは、skill 本体の repository を消すことではありません。登録先から外すだけです。正本を消さずに、エージェント側の候補から外せるようにしておくと、運用中の試行錯誤がしやすくなります。
書き手から登録の作法を切り離す
skill 本体に集中できるようにする
この構成にした理由は、書き手から登録の作法を切り離したかったからです。Codex の plugin 登録と Claude Code の skill directory 登録は、使う側から見るとどちらも「候補に出す」ですが、実装上の置き場所は違います。
その違いを skill 本体に混ぜると、skill を1つ足すたびに登録方法も考えることになります。自分は、そこを Bootstrap CLI に閉じ込めました。
書き手側の感覚としては、次のようにしたいわけです。
skills/technical-writing/SKILL.md を直す
↓
Bootstrap CLI を実行する
↓
Codex と Claude Code の候補に同じ skill が出るこの単純な流れに寄せるために、登録先の違いを CLI が吸収する構造にしました。
片方だけ使うこともできる
persona-skills-core は、必ず agent-config-core と組み合わせる前提にはしていません。rule.md の配信は使わず、skill だけを両エージェントへ登録したい場面もあるからです。
逆に、agent-config-core だけ使って、skill は不要という端末もあります。両方を独立させておくと、必要なものだけ選べます。全部入りにしないことが、後から扱いやすさにつながりました。
続きはこちら
次の記事では、ここで説明した Bootstrap CLI を実際に叩く手順へ進みます。初回 install では、status、dry-run、apply の順番を守って、候補表示まで確認します。