配布用の zip を作って、中身を unzip -l で何気なく眺めていたとき、見覚えのあるファイル名が目に入って指が止まった。Pro 版のライセンスキーを生成する、開発のときにしか使わないツールだった。配布物には、絶対に入ってはいけないものだ。もしこれがそのままユーザーの手に渡っていたら、ライセンス生成の仕組みや内部の秘密情報を解析され、有効な Pro ライセンスを作られるおそれがあった。

間に合った、と言いたいところだけれど、正しくは「たまたま目に入った」だ。除外し忘れていただけで、気づかなければそのまま出していた。その「たまたま」が後から効いてきて、リリースのたびに同じ作業を手でやって、疲れているときに一個飛ばす自分が怖くなった。

それで、リリース前の手順を Claude Code の skill にして、毎回機械的に同じチェックを通すことにした。skills が流行っているから乗った、というより、自分の地味なミスを二度とやらないための仕組みが欲しかった、という順番だ。この記事は、そのとき作った SKILL.md を実物で共有する。動作は Claude Code（2026年5月時点）、macOS、自作プラグインのリポジトリで確認している。

skill とは何か（最小限）

知っている人は読み飛ばしてほしい。Claude Code の skill は、SKILL.md を置いたフォルダだ。SKILL.md は --- で囲った YAML フロントマターと、その下の Markdown 本文でできている。Claude Code ではフロントマターの項目はすべて任意で、推奨されるのは description だけ。name は省略するとディレクトリ名が使われる。Claude が skill を自動で使うかどうかは、主にこの description で判断される（省略すると本文の最初の段落が使われる）。トリガーになりそうな言い回しや利用例は、任意の when_to_use に足せる。だから description（と when_to_use）には、自分が実際に打ちそうな言葉を入れておくと、必要なときに自動で読み込まれる。

呼び出しは、/skill名 と明示する方法と、頼んだ内容が description に合致して自動で読み込まれる方法の二通り。個人用に ~/.claude/skills/ に置けば全プロジェクトで使えるし、リポジトリの .claude/skills/ に置けばそのプロジェクト限定になる。仕様の詳しいところは公式（Claude Code Docs の skills ページ）に譲る。

毎回プロンプトに書くのでは足りなかった

最初は、リリースのたびにチェック項目をプロンプトに書いていた。でもプロンプトは終われば消える。次のリリースでまた書くし、書くのが面倒だと省略する。省略したときに限って、今回の事件のような取りこぼしが起きる。

SKILL.md はリポジトリに残る。一度ちゃんと書いておけば、次の自分が同じ手順をそのまま踏める。手順書を頭の中に置くのをやめて、ファイルに固定した、という感覚に近い。

実際の SKILL.md

私のリリース手順は4ステップだ。それをそのまま skill の手順に落とした。.claude/skills/release-build/SKILL.md：

---
name: release-build
description: プラグインのリリース前作業を補助する。readme.txtとメインPHPのバージョン更新、readme.txtの変更履歴の追記、配布用zipのビルドを行う。
disable-model-invocation: true
allowed-tools:
  - Read
  - Edit
  - Bash(git status *)
  - Bash(git log *)
  - Bash(scripts/build-zip.sh *)
  - Bash(unzip -l *)
---

# リリース前ビルド補助

リリース時の手順を順番に、抜けなく踏むための skill。
バージョンと変更履歴は確認のうえ書き換えてよいが、
コミット/プッシュは「提案」までに留め、実行しない。

## 注意

`allowed-tools` はここに挙げたツールを「確認なしで使ってよい」と事前承認するもので、
使えるツールの範囲を制限するものではない。
commit / push は実行せず、コマンド案の提示までに留めること。

## 手順

1. バージョン番号を上げる（2か所）
   - `readme.txt` の `Stable tag:`
   - メインPHPファイルのヘッダの `Version:`
   両方の現在値を読み出して提示し、新しい番号を確認してから、
   この2か所を一致させて書き換える。

2. `readme.txt` の変更履歴を更新する
   `git log <前回のバージョン>..HEAD` を要約し、`== Changelog ==` に
   新バージョンのエントリ下書きを出す。文面を確認してから書き込む。

3. コミットしてプッシュする（提案のみ）
   `git status` で対象を確認し、コミットメッセージ案（例: `Release vX.Y.Z`）と、
   実行すべき `git commit` / `git push` コマンドを「提案」として提示する。
   実際の commit / push はここでは実行しない。ユーザーが自分の手で行う。

4. 配布用zipを作る（Pro版・Free版それぞれ）
   `scripts/build-zip.sh <スラッグ>` を、Pro版・Free版のスラッグそれぞれで実行する。
   ビルド後は必ず `unzip -l` の出力を見せ、配布してはいけないものが
   入っていないことを確認する。特に、開発専用のツール類が混ざっていないか。
   最終チェックは人間が目視で行う。

ここで注意したいのが allowed-tools だ。これは「Claude が使えるツールを絞る」設定ではなく、挙げたツールを確認なしで使ってよい、と事前承認する設定になっている。リストに無いツールも呼び出し自体は可能で、その場合は通常の権限設定に従う。だから本当に使わせたくない操作は、allowed-tools から外すだけでは塞げず、権限設定の deny ルールや disallowed-tools で別途止める必要がある。今回は Bash 全体を白紙委任せず、git status や git log、ビルドスクリプト、unzip -l のように使うコマンドだけを絞って事前承認している。そして取り返しのつかない commit / push は、allowed-tools の話とは別に、本文の指示で「提案のみ・実行しない」と明示して止めている。

ビルドスクリプト

ステップ4の実体はシェルスクリプトにして、skill から呼ぶ。私は zip -x で除外するやり方を使っているので、それに合わせている。scripts/build-zip.sh：

#!/usr/bin/env bash
set -euo pipefail

# 使い方: ./scripts/build-zip.sh <スラッグ> [バージョン]
SLUG="${1:?スラッグを指定してください}"
VERSION="${2:-$(grep -m1 '^Stable tag:' "${SLUG}/readme.txt" | sed 's/.*:[[:space:]]*//')}"
OUT="${SLUG}-${VERSION}.zip"

rm -f "${OUT}"

# プラグインフォルダごと固め、配布に含めないものを -x で除外する
# -X は macOS の拡張属性を付けない指定
zip -rX "${OUT}" "${SLUG}/" \
  -x "*/.git/*" \
     "*/.github/*" \
     "*/.ci/*" \
     "*/.claude/*" \
     "*/docs/*" \
     "*/tools/*" \
     "*/__MACOSX/*" \
     "*.DS_Store" \
     "*/README.md" \
     "*/CLAUDE.md"

echo "built: ${OUT}"
unzip -l "${OUT}"   # 中身を一覧表示。最後に人間が混入チェック

*/docs/* と */tools/* が、今回の事件の再発防止だ。開発でしか使わないツール（私の場合はライセンス生成ツール）を tools/ に、ドキュメントを docs/ のような配布しないフォルダにまとめて置き、丸ごと除外する。README.md（GitHub 用）は落とすが readme.txt（WordPress.org 用）は残す、という取り違えにも注意する。

このスクリプトはいくつか前提を置いている。カレントディレクトリ直下に <スラッグ>/readme.txt がある構成を想定しているので、リポジトリのルート自体がプラグイン本体ならパスを直す必要がある。Stable tag: が trunk 運用のリポジトリではバージョン名として使えないので、その場合は第2引数でバージョンを明示する。ステップ2で使う git log <前回のバージョン>..HEAD も、その名前の Git タグが存在する前提で、タグが v1.2.3 形式か 1.2.3 形式かはリポジトリの運用に合わせて確認する。

置き場所と、手動起動に倒すまで

このリリースチェックはプラグインごとに微妙に違うので、個人用ではなくリポジトリの .claude/skills/ に置いている。

最初は、description に「リリース」「バージョンを上げる」「配布zipを作る」といった言葉を入れて、自動で拾われるように調整していた。ただ、実際に使ってみると、この skill は readme.txt やメインPHPのバージョンを書き換える。つまり参照用ではなく、副作用のあるワークフローだ。Claude Code 公式でも、commit / deploy 系のようにタイミングを人間が制御したい skill には disable-model-invocation: true が推奨されている。

そこで最終的には、自動ロードではなく /release-build と明示して起動する形にした。少し手間は増えるが、リリース作業だけは「Claude が気を利かせて始める」のではなく、自分が明示的に引き金を引くほうが安心だった。disable-model-invocation: true を付けても description が無駄になるわけではなく、/ の一覧や人間が読むときの説明としては残る。ただ、Claude の自動判断には使われなくなる。

ハマったところと、そこから考えたこと

この skill を作って一番はっきりしたのは、zip -x が「名前を挙げたものしか除外できない」という当たり前の事実だった。今回ヒヤッとしたのは、除外リストに無い新しいファイルが増えていたからで、リストに書いてある限りは安全、という前提そのものが崩れていた。-x のブラックリストは、自分が予想できたものしか守ってくれない。

だから skill にしても、最後の unzip -l の目視だけは省けない。むしろ skill の本当の値打ちは、その目視を毎回必ず通すところにある、と今は思っている。理屈の上では、ホワイトリスト方式（配布してよいファイルだけを明示して固める）にすれば、未知のファイルは構造的に入らない。次はそちらに寄せたいと考えているが、まだ手元の運用は zip -x のままなので、ここは断定せず、目視を最後の砦として残している。

SKILL.md を太らせすぎないことも途中で学んだ。手順の詳しい背景まで全部書くと長くなるので、本体は短く保ち、込み入った補足は別ファイルに逃がして、必要なときだけ読ませる形にした。

どこまで任せるか

バージョンの書き換えや変更履歴の下書きは skill に任せている。けれど、コミットとプッシュは提案までにして、実行は自分の手でやる。取り返しのつかない操作だけは、一拍置いて人間が引き金を引く、という線引きだ。AI エージェントにどこまで実行を許すか、未信頼の入力をどう扱うか、という重たい話は別の記事にまとめたので、ここでは深入りしない。

まとめ

派手な AI 活用ではなく、毎回やる地味な定常作業を SKILL.md に固定する、という使い方が、自分には一番効いた。きっかけは、配布物にライセンス生成ツールを混ぜかけたヒヤッとした一件だった。手順を仕組みに落としたいま、同じミスは起きにくくなったし、未来の自分が同じ手順をそのまま踏める。

プラグインの配布まわりでは、WordPress.org への SVN 公開作業の記録や、審査で差し戻された全記録を本家ブログに書いている。この記事を読んで、自分の配布zipの中身を一度 unzip -l で確かめてみた人がいたら、それでこの文章の役目は果たせている。