この記事は playpark Blog からの転載です。

この記事で分かること

Skill 命名で外部サービス名を冠してはいけない理由
Skill を分割せず統合側に倒す判断基準
description を「仕様書」ではなく「発火確率の調整値」として設計する理由

背景: Skill 数が増えると設計上の判断が問われる

Claude Code Skills を 50 本以上運用していくと、SKILL.md の書き方は揃っているのに「使いにくさ」が残る場面が出てきます。発火しない、呼び出しに迷う、規約違反が気づかずに混入している。

原因は「書き方」ではなく「設計判断」にあります。本記事では、命名・粒度・description の 3 観点で、なぜそう設計するのかの判断基準を解説します。

選択肢の検討: 命名戦略

Skill の命名には 3 つのアプローチがあります。

アプローチ	メリット	デメリット
外部サービス名プレフィックス（`ig-post`）	直感的、用途が即わかる	サービス変更・拡張で命名と中身が矛盾する
機能ベース（動詞 + 汎用対象）	サービス変化に強い	最初は抽象的に感じる
内部実装詳細（`json-merge-runner`）	実装が明確	呼び出し側が用途を推測できない

なぜ機能ベースの命名を選ぶのか

動画告知系の Skill で外部サービス名プレフィックスを採用していた時期がありました。機能は動いていたが、別プラットフォームへの拡張が必要になった際に命名と中身が矛盾しました。

（Skill 名）: 特定サービス専用を示唆
（実際の中身）: 複数プラットフォーム対応のロジック

新しいメンバーが「なんでこの名前で他プラットフォームの処理が入っているんですか」と聞いてきます。返答に詰まった瞬間が改名判断のサインです。

機能ベースの命名を選ぶ理由:

サービス側の変化（仕様変更・廃止・上位互換）に影響を受けない
description で発火させる前提なので、Skill 名は短く用途が伝われば十分
リネームコストは早期ほど低い。Skill 数が増えるほど依存箇所も増えるため、迷ったら早く改名する

選択肢の検討: 粒度設計

設計	メリット	デメリット
責務ごとに分割（投稿/スケジュール/同期）	設計上の整理整頓	使う側の選択負荷が増える
統合 + サブコマンド構成	呼ぶ側の認知負荷が下がる	SKILL.md が膨らみやすい

なぜ統合側に倒すのか

SNS 投稿系の Skill を 3 つに分けた時期がありました。設計上は綺麗でしたが、実運用では「投稿のほう・スケジュールのほう・同期のほうのどれだったか」毎回判断が必要になりました。3 つの Skill が内部でお互いを呼び出すため起点も曖昧になりました。

統合側に倒す理由:

Skill を分けたコストは使う側が払う。「どっちを呼ぶんだっけ」を毎回判断する負荷は設計上の整理のしわ寄せ
サブコマンド（post/schedule/sync）で機能を吸収すれば、発火の単一性と機能の多様性が両立する

実装例

統合 Skill
├─ post サブコマンド   → 投稿実行
├─ schedule サブコマンド → 投稿予約
└─ sync サブコマンド  → 外部サービス同期

分けるべき判断基準: 明確に違う発火条件を持つときだけ。「投稿」と「分析」のように、呼ぶシーンも入力も出力も違うものは分ける。「投稿」と「投稿のスケジュール」のように同じ目的内で時間軸だけが違うものはサブコマンドで吸収する。

なぜ description は「仕様書」ではなく「発火確率の調整値」なのか

description フィールドを仕様書として書くと、発火に問題が出ます。

問題が起きた例:

（初期 description）: Investigates complex bugs through hypothesis-driven multi-agent analysis
（実際の呼び出し）: 「このバグ調べて」（日本語）
（結果）: 発火しない

AI のトリガー判定は意味マッチです。英語の「bug investigation を期待する Skill」に見えるため、日本語の「バグ調べて」と意味的に対応しません。

改善後の description の設計原則:

description: |
  Collaborative multi-agent bug investigation using Agent Team.
  Use when: (1) complex bugs with unclear root cause, (2) intermittent/hard-to-reproduce issues,
  (3) keywords: bug hunt, root cause, investigate, debug, 原因調査, なぜ落ちる, 再現しない
  Accepts args: <issue-or-description> [--max-hypotheses N] [--max-turns N]

設計要素	理由
英語・日本語キーワードを両方列挙	両言語での発火確率が安定する
`Use when` を箇条書きで明示	似た用途の他 Skill との競合が減る
`Accepts args` を記述	引数付き呼び出し時に Skill 側が確信を持ちやすい

まとめ: どういう場面でこの判断基準を使うか

場面	判断基準
新しい Skill の命名	機能ベース。外部サービス名は回避
Skill を分割するか統合するか	発火条件が明確に違うときだけ分割。迷ったら統合 + サブコマンド
description を書くとき	仕様書ではなく発火トリガーの設計として書く。英語・日本語両方、Use when を 3〜4 件
Skill 数が 10 を超えたとき	SKILL.md の行数チェック（200〜300 行超えたら references/ に分離）

さらに深掘りしたい方へ

この記事では命名・粒度・description の設計判断理由を解説しました。

【Claude Code】Skills 運用で効いた判断 - 命名・粒度・descriptionチューニングの実践知 ではさらに：

フォールバック設計（gh pr review --approve → --comment への Graceful Degradation）
失敗ログが 30 日間ゼロ件だったバグの技術的原因（hook の payload schema 誤読 + bash の静かな失敗）
lint スクリプトによる規約の機械的検証と CI への組み込み方

playpark について

playpark LLC - 業務自動化・AI活用・Web開発

お問い合わせ | ブログ