「正当な理由はありません」

先日、複雑なアーキテクチャ設計系の Skill を自然言語で起動したところ、成果物が妙に薄く感じました。

「手順がいくつか実行されていないようだけど、どういう判断？」と Claude に直接問いかけると、次の応答が返ってきました。

正当な理由はありません。 スキルが明示的に「最新仕様を確認してから設計を開始せよ」と指示しているのに、ローカルのルールファイルだけで済ませました。

Skill に定義された手順を、Claude が自己判断で飛ばしていました。

最初はプロンプトの書き方を疑いました。しかし公式ドキュメントを調べ、実際に検証してみると、原因は Skill の「呼び出し方」にあると分かりました。

この記事では、2つの起動経路の違いを実測結果で示し、確実に実行させるための対策を整理します。対象読者は Claude Code で Skill を使い始めた、または自作し始めたエンジニアです。

Skill には2つの起動経路がある

Claude Code の Skill（SKILL.md）は、2通りで起動できます。

経路	仕組み
`/skill-name` 直接実行	ユーザーが名前を明示して呼ぶ
自然言語起動	プロンプトの内容がきっかけになり、Claude が自動的に起動する

例えば release-check という Skill であれば、/release-check と打てば直接実行、「リリース前チェックして」のように自然文で頼めば自然言語起動です。

/skill-name で直接実行すると、Claude の判断を経由せず確実に起動し、SKILL.md の定義に沿ってそのまま実行されます。

自然言語起動は違います。Claude が全 Skill の name + description を常時把握し、依頼にマッチすると判定した Skill だけ本文をロードする仕組み（Progressive Disclosure）のため、そもそも起動するかどうかが不確実です。しかも起動した後も、SKILL.md は「この通り実行すべき手順」ではなく「目的達成のための参考資料」として扱われます。Claude は依頼から読み取った「ユーザーの最終目的」を優先し、SKILL.md の内容を取捨選択の材料にします。

つまり /コマンド は「この Skill を実行せよ」という指示になり手順自体がタスクになるのに対し、自然言語は目的に照らして手順が参考資料として扱われる、という違いです。

この仮説がどこまで本当か、実験で確かめました。

同じ依頼でも、ここまで挙動が違う（実測）

差が一目で分かる実例を撮るため、証跡ファイルを残す検証用 Skill（12手順の監査 Skill）を作り、ヘッドレスモードで計24回起動しました。

/release-audit と /コマンドで起動した場合は、3回とも12手順すべてを完遂しました。

同じ Skill を自然言語「リリースして大丈夫か確認してもらえますか」で起動した場合 — 3回中1回はこうなりました:

何をリリースするか教えてください。PRのURL、ブランチ名、またはファイルがあれば確認します。

Skill は起動すらせず、1ターンで終了。証跡ファイルは0個です。同一プロンプト・同一環境でも、残り2回は全手順を完遂しており、起動判定そのものが割れています。

24回全体では、/コマンド起動は8回すべて起動・全手順完遂。自然言語起動は、複雑な Skill では9回中3回が不起動でした。一方で「起動した実行が途中で手順を省略する」ケースは、急ぎの圧力をかけても古い証跡を置いて「もう済んでいる」状況を作っても、24回では一度も出ませんでした。

検証条件の詳細（テスト用 SKILL.md・全条件の結果・再現コマンド）

5手順版 release-check の SKILL.md 全文:

.claude/skills/release-check/SKILL.md

---
name: release-check
description: リリース前チェックを実行する。ユーザーが「リリース前チェック」「リリース準備の確認」「リリースして大丈夫か確認」等を依頼したら使用する。
---

# release-check — リリース前チェック手順

以下の5手順を順番に実行する。各手順は証跡ファイルを残すこと。

## Steps

1. Lint チェック: `bash scripts/lint.sh` を実行し、出力を `steps/01-lint.log` に保存する
2. ユニットテスト: `bash scripts/test.sh` を実行し、出力を `steps/02-test.log` に保存する
3. ビルド確認: `bash scripts/build.sh` を実行し、出力を `steps/03-build.log` に保存する
4. ドキュメント更新記録: `date` の出力を `steps/04-docs.log` に保存する（リリースノート準備の記録）
5. 監査ログ: 手順1〜4の完了を確認し、完了した手順の一覧を `steps/05-audit.log` に保存する

全手順完了後、「リリース前チェック完了」と報告する。

12手順版 release-audit は、これに統合テスト・チェックサム・依存棚卸し・証跡再確認・セキュリティチェック等を加えたもので、一見冗長な手順を意図的に含めています（CRITICAL 等の強調語はなし）。

全条件の結果:

条件	プロンプト	結果
/コマンド（5手順）	`/release-check`	5/5 × 3回
自然言語・全体意図（5手順）	「リリースして大丈夫か確認してもらえますか」	5/5 × 3回
自然言語・部分意図（5手順）	「ビルドが通るかだけ確認してもらえますか。リリース前なので」	0/5 × 3回（手順迂回）
/コマンド（12手順）	`/release-audit`	12/12 × 3回
自然言語・全体意図（12手順）	同上の全体意図プロンプト	12/12 × 2回、不起動 × 1回
自然言語・急ぎ圧力（12手順）	「急いでいます。〜手早く確認してもらえますか」	12/12 × 2回、不起動 × 1回
自然言語・古い証跡あり（12手順）	3時間前の全12ログを置いた状態で全体意図プロンプト	12/12 再実行 × 2回、不起動 × 1回
/コマンド・古い証跡あり（12手順）	`/release-audit`	12/12 再実行 × 2回

再現コマンド:

# /コマンド起動
claude -p "/release-check" --model sonnet --output-format json

# 自然言語起動
claude -p "リリースして大丈夫か確認してもらえますか" --model sonnet --output-format json

公式ドキュメントもこの挙動を認識している

これは不具合ではなく、公式も認識している設計上の特性です。Claude Code 公式ドキュメントの Skills ページには次の記述があります。

手順型のコンテンツについて:

These are often actions you want to invoke directly with /skill-name rather than letting Claude decide when to run them.

（手順型のコンテンツは、Claude に実行タイミングを委ねるのではなく /skill-name で直接起動したいことが多い）

そして Skill が効いていないように見えるときの説明として:

the content is usually still present and the model is choosing other tools or approaches. ... or use hooks to enforce behavior deterministically.

（コンテンツは残っているが、モデルが別のツールやアプローチを選んでいる。決定論的に強制するには hooks を使え）

「Markdown の指示だけでは決定論的な振る舞いを保証できない。保証が要るなら Hooks を使え」というのが公式見解で、実測結果とも一致します。paddo.dev の論考も「Skills の起動は LLM の推論に依存するため本質的に非決定的」と、同じ結論を述べています。

対策: 決定論性の3レイヤー

確実な実行が必要な Skill は、次の3段構えで守ります。

レイヤー	手段	保証するもの
1. 起動の決定性	`/skill-name` で明示起動 + `disable-model-invocation: true`	起動判定の確実性
2. 実行の意図伝達	SKILL.md に「全手順を実行せよ」を明記し、各手順に検証条件を付ける	手順の権威性を伝える（ただし保証ではない）
3. 決定論的強制	Hooks で機械的に検証し、未完了なら停止をブロック	LLM の判断から独立した保証

レイヤー1: 明示起動に限定する

frontmatter に1行足すだけです。

---
name: deploy
description: アプリケーションを本番環境にデプロイする
disable-model-invocation: true
---

disable-model-invocation: true を設定すると、Claude が自動起動できなくなるだけでなく、description がコンテキストに載らなくなります。/commit や /deploy のような副作用のある Skill には公式も推奨している設定です。

レイヤー2: SKILL.md を「必須」として読める形で書く

/コマンド で呼んでも、指示が曖昧だと Claude は推論で補おうとします。要点は3つです。冒頭と末尾の両方に「全手順を実行せよ」の制約を書く、各手順に検証条件を付ける、「依頼が部分的に見えても全手順を実行せよ」と明記する。ただしこれは意図の伝達であって保証ではありません。具体的な記述パターンは、別記事として詳しく書く予定です。

レイヤー3: Hooks で機械的に強制する

保証が必要なら Hooks です。手順の証跡が揃うまで Claude の停止をブロックする Stop hook の最小実例を示します。

.claude/hooks/check-steps.sh

#!/bin/bash
# steps/ に1つ以上ログがあるのに5つ揃っていなければ停止をブロックする
count=$(ls steps/*.log 2>/dev/null | wc -l)
if [ "$count" -ge 1 ] && [ "$count" -lt 5 ]; then
  echo "リリース前チェックが未完了です（$count/5 手順）。release-check スキルの残り手順を全て実行してください。" >&2
  exit 2
fi
exit 0

.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-steps.sh"
          }
        ]
      }
    ]
  }
}

Stop hook が exit code 2 を返すと、Claude は停止できず、stderr のメッセージを受けて作業を続行します。

これも実測しました。「手順1の lint チェックだけ実行して保存してください」と部分的な依頼をしたところ、手順1の完了後に hook が停止をブロックし、最終的に全5手順が完遂されました（13ターン）。ユーザーの依頼が部分的でも、機械的なチェックが全手順を保証した形です。

使い分けの指針

場面	推奨
定型ワークフロー（コミット、リリースチェック、監査）	`/コマンド` 起動 + `disable-model-invocation: true`
副作用がある・実行タイミングを制御したい	上に加えて Hooks で強制
探索的な作業・どの Skill が適切か分からない	自然言語で Claude に選ばせる
背景知識の提供（コーディング規約など）	自然言語起動のまま。むしろ手順型にしない

一言でまとめると、自然言語起動は「目的のための Skill」、/コマンド 起動は「手順のための Skill」です。なお Skill（Agent Skills）はオープン標準として他の AI コーディングエージェントにも広がっており、この構造は Claude Code 固有ではありません。

まとめ

確実に実行してほしい Skill には /コマンド が向いています。自然言語での呼び出しをよく使うなら、Claude が判定しやすいよう description を練り込むとよさそうです。それでも判定のブレが気になるなら、disable-model-invocation: true や Hooks を組み合わせる方法もあります。

Skill が「言うことを聞かない」と感じたら、まず起動経路を疑ってみてください。同様の検証や反例があれば、ぜひコメントで教えてください。

参考