同じ指示を、会話のたびに貼り直していないでしょうか。
前提の説明、チェックリスト、実行の順番。毎回ゼロから打ち込んでいるうちは、任せた気になっているだけで、手間は人の側に残っています。かといって思いつきで増やしていくと、似た用途のスキルが並び、どれが呼ばれるのか分からなくなります。
この記事は、何をスキルにするかの線引きから始めます。そこからSKILL.mdの構成要素、命名と分割の型、増えたあとの棚卸しまでを順に扱います。根拠はAgent Skillsの公式仕様とClaude Code公式ドキュメント、そして運営元WEBMARKSが.agents/skillsで運用してきた中身です。
本記事の検証環境：Claude Code公式ドキュメント（code.claude.com/docs、platform.claude.com/docs、2026-07-28時点の記載）。
こんなふうに調べていませんか
- 同じ指示を毎回貼り直していて、そろそろ型にしたい
- スキルを作ってはみたが、依頼しても呼ばれないことがある
- 本数が増えてきて、どこまでを1本に入れるべきか分からない
この記事を読み終えたときに手に入るもの
- スキルに切り出すものと、その場で説明して終わるものを線引きできるようになります
- descriptionを「呼ばれる条件」として書き直せるようになります
- 増えたスキルを棚卸しする順番が決まります
結論30秒でわかる、この記事の結論
- スキル設計で決めるのは、切り出すか・呼ばせるか・残すかの3つです。
- 呼ばれるかどうかを決めているのはdescriptionだけで、名前は人が探すためのものです。
- 命名と分割の型は運用の中で固まります。先に組み込むのは、棚卸しのほうです。
進行役は3人です。若葉さん（Web担当2年目）が用語のそもそもを聞き、高梨課長が自分の手で動かす側の疑問を出し、鈴木さん（本誌監修）が答えます。近い立場の人の質問から読んでいただいて構いません。
01AIエージェントのスキル設計は、そもそも何を決める作業なんですか？
若葉さんスキルって、よく使うプロンプトを保存しておくフォルダのことですか？
鈴木さん置き場所としてはそのとおりです。設計の話になるのは、置いたものが「いつ読まれるか」まで決められるからなんですよ。読ませたいときだけ読ませる、という条件がついた手順書だと思ってください。
Agent Skillsは、Anthropicが開発し、オープン標準として公開された仕様です（出典: Agent Skills公式仕様）。構成はごく単純で、フォルダを1つ作り、その中にSKILL.mdを置きます。SKILL.mdはmetadata（nameとdescription）と本文を持ち、必要に応じてscripts・references・assetsを添えられます。
この標準は、Claude Code以外のエージェント製品にも採用されています。例としてCursor・GitHub Copilot・Gemini CLIが挙げられています（出典: Agent Skills公式仕様）。書き方を覚えると、使い回せる範囲がその分だけ広がります。
運営元WEBMARKSは、.agents/skills配下に2026-07-28時点で59本のスキルを運用しています。この本数まで来ると、勘だけで名前を付けていては衝突と誤発火が増えます。
設計として決めることは、大きく3つです。切り出すか、呼ばせるか、残すか。この記事はその順に進みます。
スキルは、AIエージェントに手順を持たせる手段の1つです。エージェントそのものの条件は別記事に譲り、本記事は「手順を自分で組む」を支える設計だけに絞ります。
この章のまとめ
スキル設計は、文章をどこに保存するかではなく、いつ読ませるかを決める作業です。
02どこまでをスキルにして、どこからはAIエージェントに毎回説明するんですか？
Claude Code公式ドキュメントは、スキルを作るタイミングを2つ挙げています（出典: Claude Code公式ドキュメント）。同じ指示を会話のたびに貼り直しているとき、そしてCLAUDE.mdの1セクションが手順に育ったときです。
裏にあるのは役割分担です。CLAUDE.mdは常時読み込まれる事実の置き場所で、スキルは使うときだけ読み込まれる手順の置き場所になります。事実はいつも要りますが、手順は使う場面でしか要りません。
線引きの判断は、次の4項目のうち2つ以上に当てはまるかで行います。
- 同じ指示・チェックリスト・手順を、会話をまたいで繰り返し貼っている
- CLAUDE.mdの1セクションが、事実ではなく手順として育っている
- 使うたびに前提知識や外部接続の説明をゼロから書き直している
- 数ステップ以上の順序があり、順番を飛ばすと失敗する
当てはまらないものは、その場で説明して終わらせたほうが軽く済みます。1度しか使わない事情を型にしても、あとで読む人の判断材料が増えるだけです。
03知識を渡すのと手順を渡すのでは、AI社員のスキルは書き分けるんですか？
高梨課長社内の規約をまとめたものと、公開作業の手順書を、同じ形で置いてよいものでしょうか。
鈴木さん形は同じでかまいません。分けるのは「勝手に走ってよいか」のほうです。規約は読まれても困りませんが、公開は読まれた勢いで実行されると困りますよね。
高梨課長たしかに、そこは自分で押したいです。
スキル設計のベストプラクティスは、SKILL.mdの中身を2種類に分けています（出典: Claude Code公式ドキュメント）。
- Reference content：規約・パターン・ドメイン知識。会話に沿って参照させる知識型
- Task content：デプロイやコミットなど、副作用を伴う具体的な手順のタスク型
タスク型のうち、AIの判断で自動発火してほしくない処理は、disable-model-invocation: trueを付けて手動起動だけに絞ります。記事の公開作業を人の呼び出し限定にすると、次のような書き方になります。
---
name: publish-article
description: 承認済み記事を本番公開する
disable-model-invocation: true
context: fork
---区画で見ると、扱いが変わる理由が見えてきます。繰り返さない依頼は、そもそも切り出しません。繰り返すけれども取り消しがきくものは、自動で呼ばれてかまいません。取り消せないものだけ、呼び出しを人の手に戻します。
送信・公開・削除のように取り消せない操作を含めるときは、止め方の設計そのものが要ります。承認をどこに置くかは、承認ゲートの記事で扱っています。
04descriptionの書き方で、AIエージェントがスキルを呼ぶかどうかが決まるんですか？
先に答えを書きます。決まります。名前ではなく、descriptionのほうです。
Claudeが自動発火を判断する材料はdescriptionだけで、nameは一覧に出る表示名にすぎません（出典: Claude Code公式ドキュメント）。名前をいくら工夫しても、呼ばれ方は変わりません。
公式が推奨する書き方は、三人称で「何をするか」と「いつ使うか」を具体語つきで書くことです（出典: Agent Skills公式ドキュメント）。運営元のseo-articleスキルは、次のように書いています（一部抜粋、2026-07-28時点）。
---
name: seo-article
description: メインKW1個の入力から、Ahrefs調査→構成設計書→本文執筆→図解→品質ゲート→WordPress下書き保存までSEO記事を一気通貫で制作する。「【KW】で記事作って」と言われたとき、またはKWリストが受付フォルダに投入されたときに使う（以下略）。
---「何をするか」は工程の矢印で具体化し、「いつ使うか」はユーザーが実際に言いそうな文言をそのまま置いています。トリガー句が曖昧な一般論だと、Claudeは100以上あるスキルの中から選べません（出典: Agent Skills公式ドキュメント）。
書き終えたら、自分の依頼文を声に出してみてください。その言い回しがdescriptionに入っていなければ、呼ばれる手がかりがない状態です。
05スキルのフロントマターは、生成AIに何を伝える欄なんですか？
若葉さんフロントマターの項目は、全部埋めたほうがいいんでしょうか。
鈴木さんそこは配る先で変わります。公開標準として配るなら決まりが厳しく、手元のClaude Codeで使うだけなら、ほとんどが任意なんですよ。まず、どちらに向けて書くのかを決めるといいです。
Agent Skillsの公式仕様は、SKILL.mdにnameとdescriptionの2フィールドを必須と定めています（出典: Agent Skills公式仕様）。nameは64文字以内で、小文字・数字・ハイフンのみ。予約語「anthropic」「claude」は含められません。descriptionは1文字以上1,024文字以内です。
一方、Claude Code側の実装はこれより緩やかです。フロントマターの全フィールドが任意で、推奨されるのはdescriptionだけになります。nameを省略すると、ディレクトリ名がそのまま表示名になります（出典: Claude Code公式ドキュメント）。
06allowed-toolsやcontext: forkは、AIエージェントの動きをどう変えるんですか？
欄ごとに、効く場所が違います。nameとdescriptionが「呼ばれるかどうか」を決めるのに対して、残りの欄は「呼ばれたあとの動き方」を決めます。混ぜて考えると、直したい挙動と触る欄がずれます。
| フィールド | 必須 | 効果 |
|---|---|---|
| name | 任意（Claude Codeでは省略可。省略時はディレクトリ名） | スキル一覧に出る表示名。標準では64文字以内・小文字英数字とハイフンのみ |
| description | 推奨（Agent Skills標準では必須） | Claudeが自動発火を判断する唯一のフィールド。最大1,024文字 |
| disable-model-invocation | 任意 | trueで自動発火を止め、/スキル名の手動起動だけにする |
| user-invocable | 任意 | falseでメニューから消え、Claudeだけが自動で使う知識になる |
| allowed-tools | 任意 | 起動したそのターンだけツールを承認なしで使わせる。次の発言で失効する |
| context: fork | 任意 | 独立したサブエージェントで実行する。会話履歴を持たずに動く |
同じスキル設計でも、配布先によって力点は変わります。claude.aiやAPI経由で配るならnameとdescriptionを標準の書式で固定し、Claude Code専用ならdescriptionだけを厳密に書きます。
07スキルの置き場所は、AI導入の範囲に合わせてどう選ぶんですか？
置き場所は、誰に効かせたいかで決めます。
| 置き場所 | パス | 適用範囲 |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | 自分の全プロジェクト |
| Project | .claude/skills/<name>/SKILL.md | そのプロジェクトのみ |
| Plugin | <plugin>/skills/<name>/SKILL.md | プラグインが有効な範囲 |
| Enterprise | Managed settings | 組織の全ユーザー |
同名のスキルが複数の階層にあるときは、Enterprise・Personal・Projectの順で上位が優先されます（出典: Claude Code公式ドキュメント）。
ここで見落としやすいのがallowed-toolsです。この許可は、そのスキルを呼び出したターン限りで消えます。次の発言では失効するので、毎ターン使う操作の許可はallowed-toolsではなく通常の権限設定に置きます。設定の配分は権限設定の記事にまとめています。
0859本まで増えたスキルの命名は、AIエージェントの設計としてどう揃えたんですか？
運営元WEBMARKSは、7部署・30体のAI社員体制を2026-06-24に統合しました。.agents/skillsは2026-07-28時点で59本です。増える過程で、命名は公式の推奨と自社の実態がずれました。
公式のベストプラクティスは、動詞のing形（gerund）での命名を推奨しています。processing-pdfsやanalyzing-spreadsheetsが例に挙がり、helperやutilsのような曖昧な名前は避けるよう明記されています（出典: Agent Skills公式ドキュメント）。
実際に運用しているスキル名を見返すと、ing形はほとんど使っていません。代わりに4つの型へ収束していました。
| 型 | パターン | 実例 | 向く用途 |
|---|---|---|---|
| 対象＋成果物型 | 〈対象〉-〈出力物〉 | seo-article／data-chart-maker | 決まった型の成果物を毎回出すスキル |
| 対象＋点検型 | 〈対象〉-audit／-health | vault-audit／automation-health | 定期点検・監査系 |
| 役割そのもの型 | 〈役割名〉 | devils-advocate／diagram-maker | 人格・専門役を1つ立てるスキル |
| 動詞命令型 | 〈動詞〉-〈目的語〉 | resume-tasks／promote | 手動起動が前提のタスク型スキル |
型がぶれても、発火精度そのものへの影響は限られます。判定に使われる材料がdescriptionだけだからです。命名を整える目的は発火ではなく、人が一覧を見たときに探しやすくすることにあります。
言い換えると、名前は人向け、descriptionはAIエージェント向けです。この2つを混ぜて考えると、名前を直しては呼ばれないままという時間が続きます。
この章のまとめ
命名の型は、最初に決め切らなくてかまいません。増えてから揃えても間に合う層です。
091つのスキルが大きくなったら、エージェントに読ませる単位でどう分けるんですか？
高梨課長1本のSKILL.mdが長くなってきました。どこで割ればいいんでしょう。
鈴木さん目安は本体500行です。ただ、割り方のほうが大事でして、深く割ると読まれ方まで変わってしまうんですよ。
高梨課長深く、というと。
鈴木さん参照ファイルから、さらに別のファイルを参照させる形です。そうすると全部は読まれず、途中まで読んだ状態で進んでしまうことがあります。
分割の型は、SKILL.md本体を500行以内に収める目安から逆算します（出典: Agent Skills公式ドキュメント）。超えそうな知識は、reference.mdのような参照ファイルへ切り出します。
参照はSKILL.mdから1階層だけにとどめます。参照ファイルからさらに別ファイルを孫参照させないことが推奨されています。孫参照があると、Claudeがheadコマンドで部分的にしか読まず、情報が欠けたまま処理を進めることがあるためです（出典: Agent Skills公式ドキュメント）。
運営元のhtml-diagram-explainerスキルは、この分割型をそのまま実装しています。
.agents/skills/html-diagram-explainer/
├── SKILL.md
├── MASTER_PROMPT.md
├── README.md
├── assets/design-skeleton.html
├── references/html-diagram-patterns.md
└── scripts/
├── preflight_diagram_check.py
└── scaffold_diagram.py骨格の指示はSKILL.md、素材はassets、判断基準の細部はreferences、実行するコードはscriptsに置いています。役割ごとに置き場所が分かれているので、直したい対象からファイルを引けます。
1スキル1責務の境界線は、「その処理を別の依頼で単独で呼び出したいか」で引きます。単独で呼びたいなら別のスキルへ分け、いつもセットで使うなら同じスキルの参照ファイルに留めます。
10使わないスキルは、AI活用の棚卸しでいつ効かなくなるんですか？
高梨課長増やしたスキルが、いつのまにか呼ばれなくなることはありますか。
鈴木さんあります。しかも、こちらが何も壊していないのに起きるんです。一覧に載せられる説明文の量に予算があって、そこへ近づくと、呼ばれにくいものから説明が削られていきます。
高梨課長削られると、どうなるんでしょう。
鈴木さん手がかりの言葉が消えるので、さらに呼ばれなくなります。放っておくと、その一方通行が進みます。
スキル一覧のメタデータは、モデルのコンテキストウィンドウの約1%を目安に予算化されています（出典: Claude Code公式ドキュメント）。この予算を超えると、呼び出し頻度が低いスキルから順にdescriptionが短縮されます。
短縮されるとtrigger keywordsが欠けていきます。使われないまま放置したスキルは、気づかないうちに発火しなくなります（出典: Claude Code公式ドキュメント）。壊れた形跡が残らないので、こちらから探しにいかないと気づけません。
11棚卸しでは、AI社員のスキルの何を見て残すか決めるんですか？
見るところを決めておくと、点検が感想で終わりません。順番は、洗い出してから突き合わせ、最後に外すかどうかを決める流れになります。
棚卸しで見る指標は3つです。
- 直近で1度も呼ばれていないスキルがないか
- descriptionの文言が、実際にユーザーが使う言い回しとずれていないか
- SKILL.md本体が500行の目安を超えていないか
公式ドキュメントは、この予算の見積もりを/doctorコマンドで確認できると案内しています（出典: Claude Code公式ドキュメント）。
使わなくなったスキルは、ファイルを消さずにskillOverrides設定で切り替えられます。"name-only"は説明文だけを隠し、"off"は一覧からも隠します（出典: Claude Code公式ドキュメント）。削除しないので、棚卸しの判断はあとから取り消せます。
運営元WEBMARKSは、59本まで増えたペースを踏まえ、棚卸しの頻度を上げる運用を検討しています。増えるペースが速い組織ほど、古い基準のまま型が固まっていないかを、早めに見直す必要があります。
12スキル設計が崩れると、AIエージェントの動きにどんな症状が出るんですか？
崩れ方は、だいたい3つの症状として出ます。
症状1は「スキルが発火しない」です。公式のトラブルシューティングは、descriptionにユーザーが実際に使う言葉が入っていないことを主な原因に挙げています。対処は、依頼文をそのままdescriptionへ反映することです。What skills are available?と聞いて、一覧に出るかを確かめます（出典: Claude Code公式ドキュメント）。
症状2は「スキルが発火しすぎる」です。descriptionが広すぎると、関係のない依頼にも反応します。対処はdescriptionを狭めることで、副作用があるならdisable-model-invocation: trueで手動限定に切り替えます（出典: Claude Code公式ドキュメント）。
症状3は「分割し過ぎて参照が追えなくなる」です。SKILL.mdから2階層以上先のファイルを参照させると、Claudeが全文を読まず断片的にしか情報を得られません。対処は、参照を1階層に統一し、100行を超える参照ファイルには目次を置くことです（出典: Agent Skills公式ドキュメント）。
背景には、よくある思い込みがあります。
| よくある誤解 | 公式ドキュメントの実際 | スキル設計での対処 |
|---|---|---|
| nameを工夫すれば発火精度が上がる | 発火判定に使われるのはdescriptionのみ | 三人称・具体語・「いつ使うか」をdescriptionに書く |
| SKILL.mdはコンパクトなほど良い | 本文500行が目安の上限で、詳細は参照ファイル前提 | 概要はSKILL.md、詳細はreference.mdへ分割する |
| allowed-toolsは一度許可すれば以後も有効 | 許可はそのスキルを呼び出したターン限定 | 毎ターン使う処理は通常の権限設定側に置く |
この章のまとめ
症状はどれも、名前の付け方ではなく、descriptionと参照の深さから出ています。直す場所を間違えないでください。
13AI社員にスキルを渡す前に、設計として何を確かめておくんですか？
着手前に、自分のスキルへ当てはめる項目にまとめます。「いいえ」が1つでもあれば、そこから先に手を入れてください。
- このスキルは「同じ指示を繰り返し貼っている」または「CLAUDE.mdの一部が手順化している」に当てはまるか
- nameは64文字以内・小文字英数字とハイフンのみで、予約語（anthropic／claude）を含んでいないか
- descriptionは三人称で「何をするか」と「いつ使うか」を具体語つきで書いているか
- 副作用のあるタスク型スキルに
disable-model-invocation: trueを付けたか - 参照専用の知識型スキルで、allowed-toolsを付けすぎていないか
- SKILL.md本体は500行を超えていないか。超えるなら参照ファイルへ分割したか
- 参照ファイルはSKILL.mdから1階層にとどめ、孫参照を作っていないか
- 命名は自分たちの型（対象＋成果物・対象＋点検・役割名・動詞命令）に沿っているか
- 使われなくなったスキルを見直す棚卸しの頻度を決めているか
- 配布先ごとに必要なフィールド（Claude Codeは任意、公開標準は必須）を確認したか
14よくある質問
スキル設計は何行までに収めるべきですか
公式の目安は、SKILL.md本体で500行以内です。超えそうな知識はreference.mdのような参照ファイルへ切り出し、本体には概要と参照先だけを残します。行数そのものより、読む側が一度に受け取る量を抑えることが目的です。長い資料を1本に押し込むと、必要な部分だけが読まれて残りが落ちることがあります。分けたうえで、参照は本体から1階層にとどめてください。
CLAUDE.mdとスキル設計はどう役割分担しますか
CLAUDE.mdは常時読み込まれる事実の置き場所、スキルは使うときだけ読み込まれる手順の置き場所です。同じ指示を繰り返し貼っている、またはCLAUDE.mdの1セクションが手順として育っている。そのどちらかに当てはまったら、スキルへ切り出す合図になります。逆に、1度きりの事情はどちらにも書かず、その場の依頼文で伝えたほうが軽く済みます。
発火の精度を上げたいとき、nameとdescriptionのどちらを直しますか
descriptionです。自動発火の判断材料はdescriptionだけで、nameは一覧に出る表示名にすぎません。命名を整えるのは、人がスキルを探しやすくするためです。直す順番を取り違えると、名前を何度も書き換えたのに呼ばれないまま、という時間が続きます。まず、自分が実際に打つ依頼文の言い回しがdescriptionに入っているかを確かめてください。
個人で使う場合でも、スキル設計は要りますか
要ります。繰り返す手順がいくつかあるなら、1人での利用でも切り出す価値があります。descriptionを具体的に書いておくと、自分が依頼するときの手間も減ります。手元のClaude Codeで使うだけなら欄はほとんど任意なので、まずdescriptionだけを丁寧に書き、ほかの欄はあとから足す進め方でも間に合います。
スキルが増えすぎたら、まず何をしますか
削除より先にskillOverrides設定で"name-only"や"off"へ切り替え、一覧から一時的に外します。外してみて困らなければ、その時点で不要と判断できます。困ったら戻せばよいので、判断を先送りしたまま様子を見られます。ファイルの整理は、その判断が固まってからで遅くありません。
命名と分割の型は、最初にどこまで決めておくべきですか
すべてを最初に決め切らなくてかまいません。本記事の4つの命名パターンは、59本を運用する中であとから収束した型です。数本のうちは自由に書き、増えてきた段階で揃える順番でも間に合います。先に組み込むとよいのは、命名規約ではなく棚卸しのほうです。見直す仕組みさえあれば、型はあとからでも直せます。
15まとめ｜今日やる3つのこと
決めることは、切り出すか・呼ばせるか・残すかの3つでした。名前は人向け、descriptionは選ぶ側のAI向け。この分け方だけ持ち帰っていただければ、直す場所を取り違えずに済みます。
今日この順で手をつけます
繰り返し貼っている指示を1つ選ぶ
型にする価値があるのは、2度目が来たものだけです
descriptionに自分の依頼文の言い回しを入れる
呼ばれる手がかりは、この欄にしかありません
呼ばれていないスキルを書き出す
消す前に隠せば、判断はあとから戻せます
AI検索では、こう聞かれています
AIエージェントのスキル設計って、何から決めるんですか？
「AIエージェントのスキル設計は、そもそも何を決める作業なんですか？」の章で説明しています
SKILL.mdには何を書けばいいんですか？
「スキルのフロントマターは、生成AIに何を伝える欄なんですか？」の章に欄ごとの効果があります
スキルが呼ばれないのはなぜですか？
「descriptionの書き方で、AIエージェントがスキルを呼ぶかどうかが決まるんですか？」の章で扱っています
スキルが増えすぎたらどうすればいいですか？
「使わないスキルは、AI活用の棚卸しでいつ効かなくなるんですか？」の章に見る順番があります
次に読むなら、この記事です
