SKILL.mdの書き方・設計ガイド｜AIが手順を守らない5つの理由と対策

クイックサマリー: SKILL.mdは、Claude Code・Codex CLI・Antigravity CLIなど複数のAIエージェントツールが対応する「再利用可能な作業手順書」フォーマットです。ただし自然言語で書かれているため、書いた通りに必ず実行される保証はありません。本記事では、SKILL.mdが読み飛ばされる5つの原因と、実行確率を上げるための具体的な書き方をコード例付きで解説します。

SKILL.mdを書いたのにAIが実行してくれない、と悩んでいませんか

生成AIに同じ作業を繰り返し頼むようになると、毎回同じ指示を書き直すのが面倒になります。そこでSKILL.mdに「この順番で作業してください」「必ず確認してください」と手順を書いておけば、次回から説明を省略できる——はずでした。ところが実際に運用してみると、太字で「必ず実行してください」と書いた手順をAIが平気で飛ばし、指摘すると「確かにこの手順を実行すべきでした」と返ってくることがあります。この記事を読むと、次の3点がわかります。

• SKILL.mdが「プログラム」ではなく「モデルへの自然言語の指示」である理由
• Skillが「選ばれる→読まれる→実行される」の各段階でどこにつまずくのか
• 実行確率を上げるための具体的な書き方（MUST/SHOULD/MAY・完了条件・Phase分割・検証コード）

SKILL.mdの仕様自体はOpenAI・Anthropic双方のエージェントツールで採用されている公開フォーマットであり、特定ベンダーのクローズド機能ではありません。

SKILL.mdで何ができるか（対応CLIと仕組み）

SKILL.mdは、次のようなディレクトリ構成でパッケージ化される定義ファイルです。Zenn記事「生成AIよ、Skillに書いたのに、なぜやらない？」（Zenn）で紹介されている構成をもとに、実際にClaude CodeやCodex CLIでSKILL.mdを組んで検証したところ、次の構成が実務でも扱いやすいことを確認しました。

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

対応CLI: Claude Code、OpenAIのCodex系エージェント、Antigravity CLIなど、SKILL.md形式を読み込む複数のCLIツールが該当します。それぞれの読み込み先ディレクトリは異なります（後述のインストール手順を参照）。

主要な仕組みは以下の3点です。実際にいくつかのSkillを配置して動作を観察した結果、次のような挙動が確認できました。

• 段階的な読み込み: AIは最初から全Skillの全文を読むわけではなく、「選択→読み込み→実行」という段階を経ます。つまりSKILL.mdの中身がどれだけ完璧でも、そもそもSkillが選ばれなければ読まれません。
• プロンプトとしての扱い: APIでSkillを使う場合、Skillの指示はシステムプロンプトではなく、ユーザープロンプト側のコンテキストとして扱われるケースがあります。つまりSkillは絶対的な最上位命令ではなく、他の指示と合わせて解釈される情報の一つです。
• 自然言語ベース: SKILL.mdの手順はstep1()のような関数呼び出しではなく、自然言語の指示文です。「書いた＝必ず実行される」という前提自体が、実際に試してみると誤りだとわかります。

SKILL.mdの書き方・実行確率を上げる5つの設計

Skillが期待通り動かない原因は、大きく5つに整理できます。それぞれの改善策を、実際に手元で試して効果を確認したコード例とともに紹介します。

1. descriptionをルーティング条件として書く

「Help create documents.」のような広すぎるdescriptionでは、AIが「今回はこのSkillを使う仕事ではなさそう」と判断してしまう可能性があります。実際に検証した改善例は次のような書き方です。

description: >
  Review a completed business report before final submission.
  Use this skill when the user asks to review, validate,
  quality-check, or finalize a business report.
  Do not use it for drafting a report from scratch.

ポイントは「いつ使うか」だけでなく「いつ使わないか」を明記することです。descriptionはSkillの紹介文ではなく、AIがそのSkillを呼び出すかどうかを判断する条件文として機能します。

2. MUST / SHOULD / MAYで優先順位を分ける

「必ず」「絶対に」を多用すると、逆にどれが本当に重要か分からなくなります。実際に試して効果があったのは、次のように分類する書き方です。

## MUST
1. Validate all required sections.
2. Run `scripts/validate_report.py`.
3. Do not report completion if validation fails.

## SHOULD
- Improve ambiguous wording.

## MAY
- Suggest optional examples.

特に「やってはいけないこと」（Do not claim the task is complete if validation fails.）を書くほうが、「チェックしてください」よりも境界が明確になります。

3. 「実行した」の完了条件（Completion Contract）を数値・条件で定義する

「最後に内容を確認してください」という指示は、人間とAIで「確認」の定義がずれます。実際に検証して効果を確認した改善例は次の通りです。

The report is considered validated only when:
- All 5 required headings exist.
- No placeholder text remains.
- Every numeric claim includes a source.
- `scripts/validate_report.py` returns exit code 0.

4. 長い手順はPhase分割し、STOP条件を入れる

手順が20ステップ近くになると、途中が読み飛ばされやすくなります。Phase 1〜4のように区切り、各Phaseに「STOP if the required input is missing.」のような停止条件を入れることで、AIが情報不足のまま推測で進めてしまう事故（いわば「親切事故」）を防げます。

5. 完了の証跡（Completion evidence）を出力させる

「A、B、Cを確認しました」という自己申告だけでは、本当に確認したか後から検証できません。実際に運用して有効だったのは、次のような出力形式です。

## Completion evidence
Before reporting completion, output:
- Checked headings: [...]
- Missing headings: [...]
- Validation script result: PASS / FAIL

さらに、見出しの存在チェックのようにAIの判断を必要としない項目は、Pythonスクリプトでdeterministicに検証する設計が有効です。

REQUIRED_HEADINGS = [
    "Executive Summary", "Background", "Findings",
    "Recommendations", "Risks",
]

def validate_report(path: str) -> int:
    text = Path(path).read_text(encoding="utf-8")
    missing = [h for h in REQUIRED_HEADINGS if f"# {h}" not in text]
    if missing:
        print("FAIL")
        return 1
    print("PASS")
    return 0

各CLIへの配置場所

SKILL.mdの記述ルール自体は共通ですが、配置先はツールごとに異なります。

• Claude Code: プロジェクト直下の .claude/skills/<skill-name>/SKILL.md に配置します。マーケットプレイス経由のプラグインとして配布する場合は /plugin marketplace add → /plugin install の手順を使います。
• Antigravity CLI (agy): ワークスペース単位なら <プロジェクトルート>/.agents/skills/<skill-name>/SKILL.md、全プロジェクト共通で使うグローバル設定なら ~/.gemini/antigravity-cli/skills/<skill-name>/SKILL.md に置きます。

配置後は、簡単な発火テスト（Skillの説明文に合致する依頼を投げて、実際にそのSkillが選択されるか確認する）を行うことをおすすめします。

6. Skillが認識されているか・発火しなかった理由をデバッグする

ここまでの対策を講じても、「Skillを置いたのに呼ばれない」「呼ばれたのに途中で手順が飛ばされる」という状態は起こり得ます。原因の切り分けは、次の順番で行うと効率的です。

• ステップA: そもそもSkillとして認識されているかを確認する。SKILL.md自体の構文エラー（frontmatterのYAML崩れ、必須フィールドの欠落）があると、CLIがそのディレクトリをSkillとして読み込まない場合があります。
• ステップB: 候補には挙がったが選ばれなかったのかを確認する。descriptionの表現が曖昧で、他のSkillや「Skillを使わない通常応答」に負けている可能性があります。
• ステップC: 選ばれて実行はされたが、手順の途中が飛ばされたのかを確認する。MUST/完了条件の書き方、Phase分割の粒度を見直す対象です。

CLIごとの具体的な確認方法は以下の通りです。

• Claude Code: /skills（環境によっては一覧表示コマンド名が異なるため、まず /help でSkill関連コマンドの有無を確認してください）でロード済みSkillの一覧とdescriptionを表示し、意図したSkillが一覧に載っているか（＝ステップAの認識確認）をチェックします。認識されているのに呼ばれない場合は、Skill名を明示して直接呼び出すスラッシュコマンド形式（例: /<skill-name>、環境やSkillの登録方法により呼び出し名は変わります）で強制実行し、Skill自体の中身（MUST/完了条件）に問題があるのか、選択ロジックの問題なのかを切り分けます。加えて、対話ログ・トランスクリプト上でどのツール／Skillが呼ばれたかの実行履歴が表示される場合は、そこでSkillの呼び出し有無を直接確認できます。
• Antigravity CLI: /skills相当の一覧表示コマンド（バージョンにより名称が異なることがあるため、公式ドキュメントまたは--helpで現在のコマンド名を確認してください）でSkillの認識状況を確認し、同様にSkill名を指定した強制呼び出しで動作テストを行います。
• 共通のデバッグ手順: 意図的にdescriptionを極端に具体的な文言（他と絶対に被らないキーワード）に変えて呼び出しテストを行うと、「認識はされているが選択ロジックで負けている」のか「そもそも認識されていない」のかを素早く切り分けられます。切り分け後、ステップAの問題ならSKILL.mdのfrontmatter構文を、ステップBの問題ならdescriptionを、ステップCの問題ならMUST/完了条件の書き方を、それぞれ本記事の該当セクションに戻って見直してください。

これらのコマンド名・表示形式はCLIのバージョンによって変更される可能性があるため、想定通りに動かない場合はまず利用しているCLIの公式ドキュメントで最新のデバッグ手段を確認することをおすすめします。

複数Skillを運用するときの設計 — 競合・誤発火を防ぐ

SKILL.mdの有用性を実感すると、レビュー用・テスト用・デプロイ用など複数のSkillを同じプロジェクトに配置することになります。ところがSkillの数が5〜10個を超えてくると、「似た依頼を投げたら意図しない別のSkillが呼ばれた」「descriptionが重複していてどちらが選ばれるか予測できない」というトラブルが起きやすくなります。実際に検証した対策は次の3点です。

排他条件（Do not use when…）を全Skillで相互に書く

descriptionに「いつ使わないか」を書くこと自体は前述の通りですが、複数Skill運用時はこれを「自分がやらないことは、どのSkillがやるのか」まで踏み込んで書くと効果が上がります。

# skills/review-report/SKILL.md
description: >
  Review a completed business report before final submission.
  Use this when the user asks to review, validate, or finalize a report.
  Do not use it for drafting a report from scratch — use `draft-report` for that.
  Do not use it for deploying or publishing a report — use `publish-report` for that.

# skills/draft-report/SKILL.md
description: >
  Draft a new business report from a topic or outline.
  Use this when the user asks to write, draft, or create a report from scratch.
  Do not use it to review or validate an existing report — use `review-report` for that.

このように「隣接するSkill名を名指しして棲み分ける」書き方にすると、descriptionが似た語彙（「レポート」「report」など）を含んでいても、AIがどちらを選ぶべきか判断しやすくなります。

常時参照ファイル（CLAUDE.md / agents.md）と個別Skillの境界線を引く

複数Skillが競合する背景には、「プロジェクト全体のルール」と「特定タスクの手順」を両方SKILL.mdに詰め込んでしまい、複数のSkillが同じルールを重複して持ってしまう問題もあります。役割分担の目安は次の通りです。

実際に試して効果があった見分け方は、「この指示は、今回のSkillと無関係な別のタスクでも常に守ってほしいか？」と自問することです。YESならCLAUDE.md/AGENTS.md側に書き、NOなら個別SKILL.mdに残します。これにより、複数のSkillのdescriptionやMUST項目に同じ禁止事項をコピー＆ペーストする必要がなくなり、結果としてdescription同士の重複による誤発火も減らせます。

誤発火に気づくための運用ルール

Skillを追加・修正した際は、既存の類似Skillに対して「本来別のSkillが呼ばれるはずの依頼文」を試しに投げてみて、意図しないSkillが呼ばれないかを確認する運用を組み込むことをおすすめします。Skillの数が増えるほど、この簡易な相互テストのコストは小さく、誤発火による手戻りのコストは大きくなります。

実際の開発フローでSKILL.mdをどう使うか

SKILL.mdは単発の指示書ではなく、Claude CodeやCodex CLIの継続的な開発フローに組み込むことで効果を発揮します。たとえば、レポートレビューのような定型業務であれば、以下のような流れで運用できます。

• スラッシュコマンド化: 「レポートをレビューして」という自然言語の呼び出しに対して、description条件が一致するSkillが自動選択されるようにdescriptionを書く。
• スクリプトとの併用: MUST項目に含めたバリデーションスクリプト（scripts/validate_report.pyなど）を、Skill内のscripts/ディレクトリに同梱し、AIの主観的判断とPythonの決定論的チェックを分離する。
• サブエージェントでの並列レビュー: Claude Codeのサブエージェント機能と組み合わせ、同じSKILL.mdのCompletion Contractを複数の観点（構成・数値・結論の一貫性）で並列にチェックさせる。

この設計により、「Skillに書いた→AIが読んだ→AIが理解した→AIが実行した→正しく完了した」という5段階のうち、最後の2段階（実行・完了）を自己申告ではなく検証可能な形に変えられます。

類似アプローチとの比較

注意点・制約

• 外部通信・データ送信: SKILL.md自体はローカルのMarkdownファイルであり、それ単体が外部へ通信することはありません。ただしscripts/内に外部APIを呼ぶコードを含める場合は、そのスクリプトの通信先を個別に確認する必要があります。
• 権限スコープ: Skill内のスクリプトがファイル削除やDB操作などの破壊的操作を行う場合、実行権限の範囲をCLI側の設定（Claude Codeのpermissions設定など）で明示的に制限することが推奨されます。
• バージョン依存: Skillの「選択→読み込み→実行」という段階的な挙動はCLIの実装・モデルのバージョンによって変わり得ます。公式ドキュメントで挙動が変更されていないか定期的に確認してください。デバッグ用のコマンド名（一覧表示・強制呼び出し等）もバージョンによって変わることがあるため、想定通りに動かない場合は最新の公式ドキュメントを確認してください。
• 過信は禁物: MUST/完了条件を丁寧に書いても、自然言語である以上100%の実行保証にはなりません。重要な検証はPythonスクリプトなど決定論的な仕組みに寄せるのが安全です。

よくある質問（FAQ）

まとめ

• SKILL.mdは「絶対服従の命令書」ではなく、AIに渡す再利用可能なランブックであり、書いた内容がそのまま実行される保証はありません。
• 実行確率を上げるには、descriptionをルーティング条件として明確化し、MUST/SHOULD/MAYで優先順位を分け、完了条件を数値・条件で定義することが効果的です。
• 発火しない・手順が飛ばされる場合は、Skill一覧表示や強制呼び出しコマンドで「認識・選択・実行」のどの段階でつまずいているかを切り分けると原因特定が早まります。
• 複数Skillを運用する際は、descriptionでの相互の排他条件明記と、CLAUDE.md/AGENTS.md（常時ルール）とSKILL.md（タスク固有手順）の役割分担で、誤発火や重複を防げます。
• 「確認しました」という自己申告に頼らず、Completion evidenceの出力や、見出しチェックのようなdeterministicな検証をPythonスクリプトに任せることで、Skillは単なるプロンプトから小さなワークフローへと進化します。

SKILL.mdの詳細な仕様や最新のベストプラクティスについては、利用しているCLI（Claude Code / Codex CLI / Antigravity CLI）の公式ドキュメントもあわせて参照することをおすすめします。