AIエージェントのスキル設計｜運用で固まった命名と分割の型

AIエージェントのスキル設計を思いつきで進めると、似た用途のスキルが増えて発火が割れます。本記事は、何をスキルにするかの線引きとSKILL.mdの構成要素を整理します。あわせて、59本運用（.agents/skills、2026-07-28時点）で固まった命名と分割の型、導入後の棚卸しも、公式ドキュメントと自社実例でまとめます。

01結論：AIエージェントのスキル設計は、線引き→構成→命名/分割→棚卸しの4層で固まる

Agent Skillsは、Anthropicが開発しオープン標準として公開した仕様で、フォルダ1つにSKILL.mdを置く構成です。metadata（nameとdescription）と本文、任意のscripts・references・assetsを持ちます（出典: Agent Skills公式仕様）。この標準は、Claude Code以外にも複数のエージェント製品が採用しています。例としてCursor・GitHub Copilot・Gemini CLIが挙げられます（出典: Agent Skills公式仕様）。

WEBMARKSは.agents/skills配下に2026-07-28時点で59本のスキルを運用しています。本数が増えるほど、勘だけの命名では衝突と誤発火が増えます。結論は3点です。

1. 何をスキルにするかは、繰り返す手順か、その場限りの事実かで線を引きます。
2. SKILL.mdの構成要素は、name・description・本文・参照ファイルの4つに分かれ、発火の判断に使われるのはdescriptionだけです。
3. 命名と分割の型は運用の中で固まるもので、最初に正解を決め切る必要はありません。ただし棚卸しは仕組みとして先に組み込みます。

スキルはAIエージェントに手順を持たせる手段の1つです。エージェントそのものの条件は『AIエージェントとは｜そう呼べる3条件と、呼べない境界』で扱っています。本記事は、条件②「手順を自分で組む」を支える設計だけに絞ります。

02何をスキルにして、何を書かないのか｜スキル設計の最初の線引き

Claude Code公式ドキュメントは、スキルを作るタイミングを2つ挙げています。同じ指示を会話のたびに貼り直しているとき、またはCLAUDE.mdの1セクションが手順に育ったときです（出典: Claude Code公式ドキュメント）。CLAUDE.mdは常時読み込まれる事実の置き場所、スキルは使うときだけ読み込まれる手順の置き場所という役割分担です。詳しい書き方は『AIに最初に読ませるCLAUDE.md｜章立てテンプレートつき』にまとめています。

スキル設計のベストプラクティスは、SKILL.mdの中身を2種類に分けます（出典: Claude Code公式ドキュメント）。

• Reference content：規約・パターン・ドメイン知識。会話に沿って参照させる知識型
• Task content：デプロイやコミットなど、副作用を伴う具体的な手順のタスク型

タスク型のうち、AIが判断で自動発火してよくない処理はdisable-model-invocation: trueで手動起動限定にします。次の例は、記事の公開作業を人の呼び出しだけに絞る書き方です。

---
name: publish-article
description: 承認済み記事を本番公開する
disable-model-invocation: true
context: fork
---

線引きの判断は、次の4項目のうち2つ以上に当てはまるかで行います。

• 同じ指示・チェックリスト・手順を、会話をまたいで繰り返し貼っている
• CLAUDE.mdの1セクションが、事実ではなく手順として育っている
• 使うたびに前提知識や外部接続の説明をゼロから書き直している
• 数ステップ以上の順序があり、順番を飛ばすと失敗する

「送信・公開・削除」のような取り消せない操作をタスク型スキルに含めるときは、承認の設計そのものが要ります。線引きの先にある止め方は『AIエージェントの承認ゲート｜送信・公開・削除で止める仕組み』で扱っています。

03SKILL.mdの構成要素｜スキル設計を支えるフロントマターと本文

Agent Skillsの公式仕様は、SKILL.mdにname・descriptionの2フィールドを必須と定めています。nameは64文字以内で小文字・数字・ハイフンのみ、予約語「anthropic」「claude」を含めません。descriptionは1文字以上1,024文字以内です（出典: Agent Skills公式仕様）。

一方、Claude Code側の実装はこの標準より緩やかです。フロントマターの全フィールドは任意で、推奨されるのはdescriptionだけです。nameを省略すると、ディレクトリ名がそのまま表示名になります（出典: Claude Code公式ドキュメント）。

同じ「スキル設計」でも、配布先によって書き方の力点は変わります。claude.aiやAPI経由で配布するならnameとdescriptionを標準の書式で固定し、Claude Code専用ならdescriptionだけを厳密に書きます。

主なフロントマターフィールドは次のとおりです。

descriptionの書き方は、三人称で「何をするか」と「いつ使うか」を具体語つきで書くことが公式に推奨されています（出典: Agent Skills公式ドキュメント）。自社のseo-articleスキルは次のように書いています（一部抜粋、2026-07-28時点）。

---
name: seo-article
description: メインKW1個の入力から、Ahrefs調査→構成設計書→本文執筆→図解→品質ゲート→WordPress下書き保存までSEO記事を一気通貫で制作する。「【KW】で記事作って」と言われたとき、またはKWリストが受付フォルダに投入されたときに使う（以下略）。
---

「何をするか」を工程の矢印で具体化し、「いつ使うか」をユーザーが実際に言いそうな文言で書いています。トリガー句が曖昧な一般論だと、Claudeは100以上あるスキルの中から選べません（出典: Agent Skills公式ドキュメント）。

スキルの置き場所は、適用範囲で使い分けます。

同名スキルが複数の階層に存在するときは、Enterprise・Personal・Projectの順で上位が優先されます（出典: Claude Code公式ドキュメント）。allowed-toolsの許可も、そのスキルを呼び出したターン限りで消える仕様です。毎ターン使う操作の許可はallowed-toolsではなく、通常の権限設定に置きます。設定の書き方は『Claude Codeの権限設定｜allow・ask・denyの配分と設定例』にまとめています。

04AIエージェントのスキル設計｜59本運用で固まった命名と分割の型

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つの型に収束しています。

命名の型がぶれても、発火精度そのものへの影響は限定的です。Claudeが自動発火を判定する材料はdescriptionだけであり、nameは一覧に出る表示名に過ぎません（出典: Claude Code公式ドキュメント）。命名を整える目的は発火精度ではなく、人がスキル一覧を見たときに探しやすくすることです。

分割の型は、SKILL.md本体を500行以内に収める目安から逆算します（出典: Agent Skills公式ドキュメント）。500行を超えそうな知識は、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責務の境界線は、「その処理を別の依頼で単独で呼び出したいか」で引きます。単独で呼びたいなら別スキルに分け、常にセットで使うなら同じスキルの参照ファイルに留めます。

05スキル設計の棚卸し｜導入後に何を見直すか

スキルは増やして終わりではありません。スキル一覧のメタデータは、モデルのコンテキストウィンドウの約1%を目安に予算化されています（出典: Claude Code公式ドキュメント）。この予算を超えると、呼び出し頻度が低いスキルから順にdescriptionが短縮されます。結果としてtrigger keywordsが欠けていき、使われないまま放置したスキルは気づかないうちに発火しなくなります（出典: Claude Code公式ドキュメント）。

棚卸しで見る指標は3つです。

• 直近で1度も呼ばれていないスキルがないか
• descriptionの文言が、実際にユーザーが使う言い回しとずれていないか
• SKILL.md本体が500行の目安を超えていないか

公式ドキュメントは、この予算の見積もりを/doctorコマンドで確認できると案内しています（出典: Claude Code公式ドキュメント）。使わなくなったスキルは、ファイルを消さなくてもskillOverrides設定で切り替えられます。"name-only"は説明文だけ隠し、"off"は一覧からも隠します（出典: Claude Code公式ドキュメント）。削除せずに一時的に外せるため、棚卸しの判断を後から取り消せます。

WEBMARKSは59本まで増えたペースを踏まえ、棚卸しの頻度を上げる運用を検討しています。増えるペースが速い組織ほど、命名や分割の型が古い基準のまま固まっていないかを、早めに見直す必要があります。

06スキルの型が崩れると起きること｜つまずきやすい3つの症状

症状1は「スキルが発火しない」です。公式のトラブルシューティングは、descriptionにユーザーが実際に使う言葉が入っていないことを主な原因に挙げます。対処は、依頼文をそのままdescriptionへ反映することです。What skills are available?と聞いて一覧に出るかを確かめます（出典: Claude Code公式ドキュメント）。

症状2は「スキルが発火しすぎる」です。descriptionが広すぎると、関係ない依頼にも反応します。対処はdescriptionを狭めることです。副作用があるならdisable-model-invocation: trueで手動限定に切り替えます（出典: Claude Code公式ドキュメント）。

症状3は「分割し過ぎて参照が追えなくなる」です。SKILL.mdから2階層以上先のファイルを参照させると、Claudeが全文を読まず断片的にしか情報を得られません。対処は、参照をSKILL.mdから1階層に統一し、100行を超える参照ファイルには目次を置くことです（出典: Agent Skills公式ドキュメント）。

07スキル設計チェックリスト

• このスキルは「同じ指示を繰り返し貼っている」または「CLAUDE.mdの一部が手順化している」に当てはまるか
• nameは64文字以内・小文字英数字とハイフンのみで、予約語（anthropic／claude）を含んでいないか
• descriptionは三人称で「何をするか」と「いつ使うか」を具体語つきで書いているか
• 副作用のあるタスク型スキルにdisable-model-invocation: trueを付けたか
• 参照専用の知識型スキルで、allowed-toolsを付けすぎていないか
• SKILL.md本体は500行を超えていないか。超えるなら参照ファイルへ分割したか
• 参照ファイルはSKILL.mdから1階層にとどめ、孫参照を作っていないか
• 命名は自分たちの型（対象＋成果物・対象＋点検・役割名・動詞命令）に沿っているか
• 使われなくなったスキルを見直す棚卸しの頻度を決めているか
• 配布先ごとに必要なフィールド（Claude Codeは任意、公開標準は必須）を確認したか

08FAQ