microCMS CLIでagent skillを生成物として扱うために、npm同梱と更新漏れチェックから始めた話

microCMS CLIでagent skillを手書きの補助資料ではなく生成物として扱い、npm同梱と更新漏れチェックを先に整えた判断をまとめた記事です。

背景

TanStack の記事を読んだあと、mcms-cli でもドキュメントとタスク定義のあいだにある知識を、agent が使いやすい形で配れる余地がありそうだと感じました。

一方で、ここから先にはもっと大きい方向もあります。たとえば、複数ステップの安全な運用手順を組み立てて実行する仕組みです。validate をして、--dry-run を挟み、問題がなければ本実行に進む、といった流れを 1 つの計画として扱うイメージです。plan や workflow run は、そのような仕組みを考えるときに出てくるコマンド名です。

そうした仕組みまで一気に広げると、便利になる可能性はあるものの、設計の重さに対して戻しづらさも増えそうでした。そこで今回はそこまでは踏み込まず、すでにある SKILL.md を「手で保守する補助資料」から「リポジトリ内の定義から生成される配布物」に寄せるところまでを対象にしました。

変更前の状態

変更前の mcms-cli には skill ファイル自体はありましたが、実質的には手書きの README 拡張に近い位置づけでした。

"files": [
  "dist",
  "README.md",
  "LICENSE"
]

この状態だと、npm パッケージには skill が入りません。さらに、src/core/task-workflow.ts が更新されても、skills/mcms-cli/SKILL.md の追従は人間の記憶に寄りやすい状態でした。

詰まったポイント

実装そのものはそこまで重くなさそうだった一方で、境界線の置き方は少し迷いました。特に気になったのは、今回の変更が、将来的に複数ステップの運用手順をまとめて扱う仕組みを前提にした設計へ引っ張られすぎないか、という点でした。

もし skill 側にだけ情報を足し始めると、あとで task や仕様書より skill の方が詳しい状態になりやすいです。それだと「安全な first step」というより、新しい基準資料を増やした形に近づいてしまうかもしれません。

自分なりの整理

自分の検証では、knowledge が足りないというより、リポジトリの中にある知識のつながりがまだ弱かったように見えました。mcms-cli にはすでに仕様書、task guide、reference 文書がありますが、それらをまとめて agent 向けの配布物にする導線がまだありませんでした。

対応

今回は CLI コマンドの実行時の振る舞いを変えず、次の 4 点に絞って入れました。

src/core/agent-skill.ts で skill 本文を生成する renderer を追加する
scripts/generate-skill.ts で skill:generate と skill:check を提供する
skills/mcms-cli/SKILL.md に参照元メタデータを持たせる
package.json の files と check:ci を更新し、npm 同梱と更新漏れチェックを入れる

export const MCMS_CLI_SKILL_SOURCES = [
  "README.md",
  "docs/CLI_SPECIFICATION.md",
  "src/core/task-workflow.ts",
  "skills/mcms-cli/references/setup-and-auth.md"
] as const;

"files": [
  "dist",
  "skills",
  "README.md",
  "LICENSE"
],
"scripts": {
  "skill:check": "tsx scripts/generate-skill.ts --check",
  "skill:generate": "tsx scripts/generate-skill.ts",
  "check:ci": "npm run skill:check && ..."
}

ここで意識したのは、SKILL.md を起点となる定義に寄せすぎないことでした。情報の起点は引き続き仕様書やタスク定義に置き、skill はそこから作る配布物として扱う形にしました。

結果

この変更で、agent 向けの知識は npm パッケージに同梱されるようになり、CI 上でも更新漏れを検知できるようになりました。加えて、unit test で「生成結果と、リポジトリに置かれている SKILL.md が一致しているか」も固定できました。

自分の感覚では、今回の範囲であれば比較的後戻りしやすそうに見えました。CLI の実行時挙動を触っていないので影響は出にくく、仮にやめたくなっても generator と package 設定を外せば戻しやすそうです。逆に、複数ステップの運用手順をまとめて実行する仕組みまで進むかどうかは、この程度の配布物化を回してみてから判断しても遅くないように感じました。

確認としては npm run check:ci と npm pack --dry-run を通し、skill と reference 群が tarball に入るところまで見ています。

再利用ルール

最初の一歩では、agent 向けの配布物を起点となる定義にしない方が扱いやすそうでした
既存の仕様書やタスク定義から生成できる範囲だけを先に整えると、変更範囲を小さく保ちやすそうでした
CLI の実行時挙動を変えない npm 同梱と更新漏れチェックは、比較的安全に試しやすい印象でした
次の段階として複数ステップの運用手順をまとめて扱う仕組みを考える場合も、まず配布物の運用が回るかを見てからでもよさそうでした

Tech Article

公開 2026年3月7日

更新 2026年3月12日