Claude Skillsは「配布できるノウハウ」に進化した——SKILL.mdの書き方とnpx skillsエコシステム入門

2026年7月29日

ClaudeのAgent Skillsは、SKILL.mdという1枚のMarkdownファイルにノウハウを詰め込み、必要なときだけAIに読み込ませる仕組みだ。この半年でオープン標準化が進み、skills.shやnpx skillsコマンドを介してClaude Code以外のツールとも共有できるようになった。良いSKILL.mdの書き方と、周辺エコシステムの現在地をまとめる。

Agent Skillsとは何か——3段階の「プログレッシブ・ディスクロージャー」

Agent Skillsは、フォルダ1つにSKILL.md（YAMLフロントマター＋Markdown本文）と、必要に応じてscripts/やreferences/を添えただけの単純な構造だ。しかし中身はよく設計されている。Claudeはスキルを次の3段階でしか読み込まない。

Discovery（起動時）: 各スキルのnameとdescriptionだけ（数十トークン程度）を常時ロードする。
Load（発火時）: リクエストの内容がdescriptionに一致すると判断したときだけ、SKILL.md本文全体を読み込む。
Reference（必要時）: 本文中でしか使わない詳細情報はreferences/*.mdに分離し、実際に必要になった行だけ追加で読ませる。

コンテキストウィンドウは会話履歴やシステムプロンプト、他のスキルのメタデータと共有される有限資源であるため、「常に全部読ませない」設計が肝になる。Anthropicは公式スキル集anthropics/skillsを公開しており、docxやpdf、UIデザインを支援するfrontend-designなど実例を読むだけでも設計思想が掴める。

良いSKILL.mdを書くための実践ポイント

Anthropic自身が公開しているスキル作成支援スキルskill-creatorや各種解説記事から、共通して挙がるポイントを整理した。

観点	やること	理由
簡潔さ	SKILL.md本文は要点のみ。長い手順は`references/`に逃がす	発火のたびに本文全体がコンテキストに乗るため
descriptionの精度	「いつ使うか／いつ使わないか」を具体的に書く（例:「PDFではなくWordの場合に使う」）	Claudeはdescriptionだけを見て発火判断をするため、曖昧だと誤発火・不発火が起きる
驚き最小の原則	スキルの動作がユーザーの期待から外れないようにする	予期しない副作用はデバッグを困難にする
参照ファイルの分割	クラウド別・言語別など枝分かれする知識は`aws.md`／`gcp.md`のように分ける	関係あるファイルだけを読ませ、無駄なロードを避ける
実行コードの活用	決定的な処理は`scripts/`に置き、Claudeに実行させる	毎回文章で説明するより速く確実

特にdescriptionは検索エンジンのメタタグに近い役割を持つ。中身がどれだけ優れていても、descriptionが曖昧だと発火せず「死んだスキル」になる。

スキルを配る・見つける——npx skillsとオープンエコシステム

Agent Skillsはagentskills.ioを旗印にオープン仕様化が進み、Claude Code・Cursor・GitHub Copilot・OpenAI Codex CLI・Gemini CLI・Windsurfなど70以上のエージェントで同じSKILL.md形式を読み込めるようになった。配布のデファクトになりつつあるのがskills.shが提供するCLIパッケージskillsだ。

npx skills find [キーワード] — インストール数ランキング付きでスキルを検索
npx skills add owner/repo — GitHubリポジトリから直接インストール
npx skills add owner/repo --skill 名前 -a claude-code -g -y — 対象エージェント・スコープを指定した非対話インストール（CI向け）
npx skills update — インストール済みスキルを一括更新

ツールごとに保存場所は異なり、Claude Codeは.claude/skills/（グローバルは~/.claude/skills/）、Codex CLIは.codex/skills/、Cursorはプロジェクト配下を読む。npx skillsはこの差異を吸収してくれるので、1つのスキルを複数ツールに同時配布できる。人気の高いスキルには、公式のanthropics/skillsのほか、フロントエンド領域に強いvercel-labs/agent-skillsなどがある。

整理された工具箱 — Photo: florianric / CC BY 2.0（Openverse経由）

SkillsとMCPは何が違うのか

同じ「Claudeを拡張する仕組み」でも、Agent SkillsとModel Context Protocol（MCP）は役割が異なる。Skillsは「手順・知識・判断基準」をMarkdownで渡すのに対し、MCPは外部システム（DB、SaaS、社内API等）への実際の接続口を提供する。両者は排他ではなく併用が前提で、公式スキル集にもMCPサーバーの使い方を教えるスキルが含まれる。

MCP側のエコシステムも急拡大している。Anthropic・GitHub・Microsoft等が共同運営する公式MCPレジストリは2025年9月にプレビュー公開され、2026年半ばには掲載サーバー数が9,400を突破したと報告されている。品質評価やセキュリティ監査付きの検証済みサーバーも増えており、「何を使うか」を選ぶコストが下がりつつある。