目次
AIエージェントに自分でスキルを足してみると、置いたのに一度も呼ばれない、というつまずきによく出くわします。読み込まれても他のスキルと混ざる、本文が長くて後半を無視される、といった話もよく聞きます。公式の作法と既に動いているスキルの実例を見比べていくうちに書き方の原則が見えてきたので、スキルを「呼ばれて、効く」形で書くための整理をします。
主要なAIエージェントが共通して採用しているのが、SKILL.md というマークダウンファイルでスキルを定義する形式です。Claude Code[1]、OpenAI Codex CLI[2]、GitHub Copilot CLI[3] のいずれも、.claude/skills/<name>/SKILL.md や .agents/skills/<name>/SKILL.md のような同じディレクトリ構造を読みにいきます（似た名前の AGENTS.md は別物で、こちらはリポジトリ規約を常時システムプロンプトに乗せる用途です。スキルは「呼ばれた時だけロードされる」点が違います）。
descriptionとnameでスキルが「呼ばれる」かが決まる
スキルが置かれていても、本文がどれだけ丁寧でも、description の書き方が悪いと一度も発動しません。エージェント起動時に読み込まれるのは各スキルの name と description だけで[4]、ユーザーの発話とこの文字列が合致した時点で本体が読み込まれます。100個並んだスキルから1つを選ぶための索引なので、ここがすべての入り口です。
descriptionを三人称・動詞先頭で書く
公式の制約は3つです[4:1]。
- 三人称で書く（システムプロンプトに差し込まれるため、視点が混ざると判定が荒れる）
- 1024文字以内
- XMLタグを含めない
中身は動詞ではじめ、「何をするか」と「いつ使うか」の両方を入れます。
良い例:
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
悪い例:
description: Helps with documents
description: I can help you process Excel files
最初の悪い例は何のキーワードにも引っかからず眠ったままになり、2つ目は一人称が混ざっているため判定が荒れます。Use when ... の節でユーザーが実際に打ちそうな発話を入れてあるかが決定的です。
トリガー語を意図して埋め込む
公開されているスキル grill-me[5] の description は次のように書かれています。
Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
mentions "grill me" の部分が要で、ユーザーが実際に打つ語そのものを description に埋め込んでいます。「何をするか」だけでなく「どんな発話で呼ばれてほしいか」を仕様に書ききると、判定の精度がはっきり上がります。
nameは動名詞、64文字以内、英小文字とハイフン
公式は name を動名詞形式（processing-pdfs analyzing-spreadsheets writing-documentation）で書くことを推奨しています[4:2]。64文字以内、英小文字と数字とハイフンのみ。helper や tools のような汎用名は他のスキルと混ざりやすく、判定が鈍ります。動名詞にすると「何をする箱か」が名前単体で読めるので、デバッグや一覧表示でも追いやすくなります。
本文は短く保ち、モデルが既に知っていることは書かない
description で呼ばれた後、本文の長さがそのまま効きに直結します。短ければ短いほど読み手モデルの集中力が残り、長ければ長いほど後半が無視されます。
公式は500行以下、Codexの実測では先頭220行で切れる
Anthropic 公式は SKILL.md 本文を500行以下に保つことを推奨しています[4:3]。さらに踏み込んだ実測として、Codexの挙動を Terminal-Bench で全数調査した検証があります[6]。SKILL.mdを読みにいくシェルコマンドが41タスク中39タスクで sed -n '1,220p' の形に揃っていた、という報告です。
これは Codex側に「220行で切る」という明示の仕様があるわけではありません。読み込み自体をモデルがコマンド生成で行う構造になっており、学習段階で身に付いた典型的なSKILL.mdの長さがそのまま出力に反映されている、という分析です。つまり仕様上は500行まで書けますが、Codexで使うなら220行を超えた地点から後半は読まれない前提になります。
本文の上限は500行、Codexを含めるなら220行を目安に切り詰める。これだけで「読まれない後半」が物理的に発生しなくなります。
「モデルが既に知っていること」は書かない
公式が繰り返し強調する原則が "Claude is already very smart" です[4:4]。情報を書くたびに「これはモデルがすでに知っていることか？」を1回挟むだけで、本文は半分以下になります。
公式が悪い例として挙げているのが、PDFを扱うスキルでこんな前置きを書いてしまうケースです[4:5]。
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because...
PDFが何か、なぜライブラリが必要か、は当然知っているので削れます。良い例はこの程度で十分です[4:6]。
## Extract PDF text
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
入力トークン量で約50対150の差になります。スキルは一度読み込まれるとそのセッション中ずっと文脈に居続けるので[4:7]、1行ごとの長さが毎ターンの課金に直結します。
10行のスキルでも複雑な行動を駆動できる
短くて済む実例として、先ほどの grill-me[5:1] は本文が約10行・見出しなし・命令形だけで構成されています。Interview me relentlessly とだけ指示しておけば、モデルは質問を一度に1つずつ投げる対話を続けます。プランを詰める一連の振る舞いを、たった数行で駆動できているわけです。
本文に長く書く必要があるのは、モデルが知らない手順・ドメイン用語・組織固有の制約だけです。それ以外は削っていい、と最初から思っておくと、書き始めの量がだいぶ違ってきます。
詳細は references/ や scripts/ に逃がす
本文を短く保つと、当然書き切れない内容が出てきます。それを外部ファイルに逃がして必要時だけ読ませる設計が、公式のいう progressive disclosure（段階的開示） です[4:8][7]。
スキルは3層でロードされる
スキルは3段階でロードされます[7:1]。
- 第1層:
nameとdescription（常時システムプロンプトに乗る） - 第2層:
SKILL.md本文（スキルが呼ばれた時にロード） - 第3層: 同梱ファイル（本文から参照された時に読まれる）
第3層を活かすディレクトリ構成は次の形になります[4:9]。
pdf/
├── SKILL.md # メインの指示
├── FORMS.md # フォーム入力ガイド（必要時）
├── reference.md # APIリファレンス（必要時）
└── scripts/
├── analyze_form.py # 実行スクリプト
└── fill_form.py
references/ には参照ドキュメント、scripts/ には実行コード、assets/ には型紙やフォントを置きます。scripts/ 配下は実行されるだけで中身がコンテキストに読み込まれないため、大きな処理を入れてもトークン代がかかりません[4:10]。
参照は1階層まで、100行超のreferenceには目次を
公式の重要な注意点が「参照は SKILL.md から1階層までに留める」です[4:11]。深い入れ子参照は、モデルが head -100 のような部分読みで切ってしまい、後ろの情報が消えます。
悪い例:
# SKILL.md
See [advanced.md](advanced.md)...
# advanced.md
See [details.md](details.md)... # ここでdetailsが部分読みされる
良い例:
# SKILL.md
**基本**: 本文に直接書く
**高度な機能**: See [advanced.md](advanced.md)
**API**: See [reference.md](reference.md)
また、参照先ファイルが100行を超える場合は冒頭に目次を入れます[4:12]。モデルが部分読みする時でも全体の構造が見えるためです。
grill-with-docsが外部ファイルを分割する例
grill-meの派生版である grill-with-docs[8] は、本文を約88行に抑えています。その上で、CONTEXT-FORMAT.md（ドメイン用語集の書式）と ADR-FORMAT.md（決定記録の書式）を外部参照する構成です。本文には「何を質問するか」「いつ CONTEXT.md を更新するか」「いつ ADR を起こすか」だけが書かれ、書式の細則は外部ファイルに逃がしています。
このパターンを真似ると、自分のスキルも本文を200行台に抑えながら、必要な情報を漏らさず提供できます。本文は判断と意思決定、外部ファイルは詳細な書式や仕様、という分担が基本形です。
自分のスキルを点検する3手順
書いたスキルを見直すときは、次の順で点検すると抜けが見つけやすいです。
descriptionを声に出して読み、想定ユーザーが実際に打つ発話と並べてみるwc -l SKILL.mdで本文の行数を測る（500超なら分割、220超ならCodexで後半が読まれない前提）- 本文から
references/やscripts/への案内が貼られているか確認する
Extend Claude with skills - Claude Code Docs (2026-05-26 アクセス) ↩︎
Agent Skills – Codex | OpenAI Developers (2026-05-26 アクセス) ↩︎
Adding agent skills for GitHub Copilot CLI - GitHub Docs (2026-05-26 アクセス) ↩︎
Skill authoring best practices - Claude API Docs (2026-05-26 アクセス) ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎
mattpocock/skills - grill-me/SKILL.md (2026-05-26 アクセス) ↩︎ ↩︎
CodexはSKILL.mdの最初の220行までしか読まないかもしれない (2026-05-26 アクセス) ↩︎
Agent Skills - Claude API Docs (2026-05-26 アクセス) ↩︎ ↩︎
mattpocock/skills - grill-with-docs/SKILL.md (2026-05-26 アクセス) ↩︎