2026年4月7日公開
1. はじめに
Anthropicが提供するAIアシスタントClaudeには、その能力を拡張する仕組みとしてSkill (Agent Skills)、Plugin、MCP (Model Context Protocol) の3つがある。本稿では各メカニズムの特徴と違いを整理したうえで、筆者が実際に作成・運用した2種類のSkill群 (PlantUML図生成9種、ソースコード解析ドキュメント生成5種) の経験をもとに、Skillの実用的な効用を報告する。
2. 3つの拡張メカニズムの概要
各メカニズムは比喩的に言えば、Skillは「カンニングペーパー」、Pluginは「ツールキット」、MCPは「外部アプリケーションへの橋」である。三者は競合するものではなく、異なるレイヤーの課題を解決する補完的な関係にある。
| 項目 | 概要 | 特徴 |
|---|---|---|
| Skill | SKILL.mdに手続き的知識を記述。Claudeがタスク文脈に応じて自動ロード。 | Markdownのみで作成可能。1Skillあたり30〜50トークンと軽量。claude.ai/Claude Code/APIで共通利用可。 |
| Plugin | Skills・MCP設定・コマンド・Hooksをパッケージ化した配布単位。 | 2026年1月公開。名前空間で衝突防止。マーケットプレイス経由で共有可能。主にClaude Code向け。 |
| MCP | 外部ツール・DB・APIとClaudeを接続するプロトコル (JSON-RPC 2.0)。 | GitHub, Slack, DB等とリアルタイム連携。5サーバーで約55,000トークン消費。Linux Foundation 傘下で業界標準化。 |
2.1 Skillの優位性
3つの中で最も導入コストが低いのがSkillである。その理由は以下のとおり。
- 作成に必要なのはSKILL.mdファイル1つだけで、コーディング不要。
- コンテキストウィンドウへの負荷が極めて小さい。(MCPの約1/1000)
- claude.ai、Claude Code、APIの3環境すべてで動作する。
- Gemini CLIやCodex等の他ツールでも利用可能な相互運用性。
- description記述によりトリガー条件を精密に制御できる。
2.2 公式Pluginによる開発ワークフロー強化
Pluginの実用例として、Anthropicが公式に提供する開発ワークフロー系Pluginがある。代表的なものにfeature-devとcode-reviewがあり、いずれもClaude Code上で動作する。
| Plugin 名 | 機能と構成 |
|---|---|
| feature-dev | /feature-devコマンドで起動。code-explorer (コードベース調査)、code-architect (アーキテクチャ設計)、code-reviewer (品質レビュー) の3つの専門エージェントが連携し、機能開発を探索→設計→実装→レビューのワークフローでガイドする。 |
| code-review | /code-reviewコマンドまたはPR作成時に自動起動。5つの並列SonnetエージェントがCLAUDE.md準拠チェック、バグ検出、履歴コンテキスト分析、PR履歴確認、コードコメント生成を同時に実行。信頼度スコアによる偽陽性フィルタリングも行う。 |
導入により期待できる効果:
- feature-dev: 機能開発の初期段階でコードベース調査とアーキテクチャ設計を構造化できるため、実装前の設計品質が向上する。特に既存コードベースへの機能追加時に、既存コードとの整合性を保ちやすい。
- code-review: Anthropic社内では導入前に16%だった実質的レビューコメント率が54%に向上したと報告されている。1,000行超の大規模PRでは84%でバグや問題が発見され、平均7.5件の指摘がなされる。AIによるコード生成量の増加に伴うレビューボトルネックの解消に寄与する。
- その他の公式Pluginとして、PRレビューの6観点 (コメント・テスト・エラーハンドリング・型設計・品質・簡素化) を個別エージェントで分析するpr-review-toolkitや、コード明瞭化を行うsimplifyなども提供されている
これらの公式Pluginは、Skill単体では実現しにくいマルチエージェント構成やHooksによる自動実行をPluginとしてパッケージ化した好例であり、Pluginの実用的な価値を示している。
3. 実践1: PlantUML図生成Skillの作成
3.1 背景と目的
ソースコードからの設計図自動生成は、ドキュメント整備の効率化に直結する。しかし Claudeに「クラス図を作って」と依頼するだけでは、存在しないクラスやメソッドを捏造する (ハルシネーション) 問題が発生しやすい。そこで「推測禁止・必ずソースコードを読んでから図を作成」という原則をSKILL.mdに埋め込むことで、品質を担保する仕組みとしてSkill化を行った。PlantUMLを使用したのは、Microsoft Visual Studio Codeの拡張機能として普段から開発に利用していたからである。
3.2 作成した Skill 群
以下の9種類のPlantUML図生成Skillを作成した。各SkillはUML図の種類に1対1で対応し、トリガー条件を相互に排他的に設計している。
| # | Skill 名 | 生成する図 | 主な発動フレーズ |
|---|---|---|---|
| 1 | plantuml-class-diagram | クラス図 | 「クラス図を作って」「構造を図にして」 |
| 2 | plantuml-sequence-diagram | シーケンス図 | 「処理フローを図にして」「呼び出し順を可視化」 |
| 3 | plantuml-module-diagram | モジュール図 | 「パッケージ図を出力して」「依存関係を可視化」 |
| 4 | plantuml-architecture-diagram | アーキテクチャ図 | 「システム構成図を描いて」「C4モデルで」 |
| 5 | plantuml-er-diagram | ER図 | 「テーブル構造を図にして」「DB設計を可視化」 |
| 6 | plantuml-state-diagram | ステートマシン図 | 「状態遷移図を描いて」「ライフサイクルを図に」 |
| 7 | plantuml-usecase-diagram | ユースケース図 | 「誰が何をできるか図にして」 |
| 8 | plantuml-activity-diagram | アクティビティ図 | 「業務フローを図にして」「承認フローを図に」 |
| 9 | plantuml-api-endpoint-diagram | APIエンドポイント図 | 「API一覧を作って」「ルーティングを図に」 |
3.3 skill-creatorを活用したSkill作成
これらのSkillを作成するにあたり、Anthropic公式が提供するskill-creatorを事前に導入した。skill-creatorはSkill開発のライフサイクル全体を支援するツールキットであり、以下の4つのモードを提供する。
| モード | 機能 |
|---|---|
| Create | 対話的なワークフローで要件定義 → SKILL.mdの雛形生成 → テストケース作成までをガイドする。YAMLフロントマターの書式やディレクトリ構成のベストプラクティスが自動的に適用される。 |
| Eval | 作成したSkillに対して複数のテストプロンプトを実行し、期待どおりの出力が得られるかを自動検証する。Executor (実行) と Grader (評価) の2つのエージェントが連携して動作する。 |
| Improve | Evalの結果に基づき、AnalyzerエージェントがSKILL.mdの改善点を特定し、修正案を提示する。descriptionのトリガー精度向上にも活用できる。 |
| Benchmark | 複数バージョンのSkillをA/B比較し、Comparatorエージェントが分散分析付きで性能差を定量評価する。どのバージョンが優れているかをデータに基づいて判断できる。 |
skill-creator 導入の効果:
- SKILL.mdの構造 (フロントマター書式、ディレクトリ構成、progressive disclosureパターン) がベストプラクティスに沿った形で統一され、9種のSkill間で一貫した品質を確保できた。
- descriptionの書き方について「undertrigger (発動すべき場面で発動しない) を防ぐためにやや積極的に記述する」というガイドラインが示され、トリガー精度の設計指針が明確になった。
- テストケースの自動生成により、作成したSkillが意図どおりに動作するかの検証が体系化された。「一度動いたから完成」ではなく、複数のプロンプトパターンで品質を担保するアプローが定着した。
- セキュリティ面のガイドライン (マルウェアやエクスプロイトコードの禁止、ユーザーの意図に反する動作の禁止) が明示されており、安全なSkill設計の基準を学べた。
skill-creatorはSkillを「なんとなく作る」段階から「設計・テスト・改善のサイクルを回す」段階へ引き上げるツールであり、特に複数のSkillを体系的に作成する場合には導入を強く推奨する。
3.4 Skillの構造と設計方針
SKILL.mdの基本構成:
- YAMLフロントマター: name (Skill名) と description (発動条件・トリガーワード)
- 重要原則: 推測禁止、段階的作業、大規模対応の方針
- 生成ステップ: プロジェクト把握 → クラス抽出 → 関係分析 → PlantUML出力
- 品質チェック: 生成後にソースコードと照合し不整合を修正するセルフレビュー手順
特に重要なのがdescriptionフィールドである。ここに書かれたキーワードやフレーズが、ClaudeがどのSkillを選択するかのルーティング判定に直結する。UML用語だけでなく「コードの構造を図にして」のような自然な日本語表現も含めることで、UMLに馴染みのないユーザーでも意図したSkillが発動するよう設計した。
3.5 作成過程で得た知見
- パッケージ形式はZIP: claude.aiにアップロードする.skillファイルは、拡張子こそ.skillだが中身はZIPアーカイブである必要がある。当初tar.gz形式で作成してしまい「Invalid zip file」エラーに遭遇した。
- 重複Skillの選択不安定性: 同一種類の図を生成するSkillが複数存在すると、リクエストの微妙な表現差でどちらが選ばれるかが不安定になる。同一出力を生成するSkillは1つに統合し、descriptionで明確に境界を定義することが重要である。
- 発動条件の競合管理: 9種のSkillを運用すると、「処理フローを図にして」がシーケンス図とアクティビティ図の両方にマッチし得る。各Skillのdescriptionに「他Skillとの違い」を明記し、description最適化 (undertrigger防止) を行うことで選択精度を向上させた。
4. 実践2: ソースコード解析ドキュメント生成Skillの作成
4.1 背景と目的
PlantUML Skillが設計図の可視化を担うのに対し、プロジェクトの運用・保守に必要なのはテキストベースの仕様書やガイドである。API仕様書、DB設計書、環境構築ガイド、テスト仕様書などは多くのプロジェクトで整備が不十分であり、ソースコードから自動生成できれば大きな効率化になる。そこでPlantUML Skillと同じ設計原則 (推測禁止・段階的作業・セルフレビュー) を踏襲しつつ、Markdownドキュメントを出力するSkill群を作成した。
4.2 作成したSkill群
5つのSkillを作成し、それぞれが3種類のドキュメントを生成する。合計15種類のドキュメントに対応する。
| # | Skill 名 | 領域 | 生成するドキュメント (各3種) |
|---|---|---|---|
| 1 | doc-api-reference | 外部インターフェース | API仕様書 (REST/GraphQL)、コンポーネントカタログ、関数・クラスリファレンス |
| 2 | doc-architecture | 全体像と構造 | ディレクトリ構成説明書、ミドルウェア・パイプライン仕様書、README・プロジェクト概要書 |
| 3 | doc-data-definition | データ構造と定義値 | データベース設計書、設定ファイル仕様書、エラーコード・例外一覧 |
| 4 | doc-operations | 運用・DevOps | 環境構築ガイド、バッチ・ジョブ一覧、変更履歴 (CHANGELOG) |
| 5 | doc-quality-audit | 品質・コンプライアンス | テスト仕様書、依存パッケージ・ライセンスレポート、セキュリティチェックリスト |
4.3 Skillの内部構造
各SkillはSKILL.md本体とreferences/ディレクトリで構成される。SKILL.mdには共通原則とワークフロー (ドキュメント種別の判定ロジック含む) を記述し、3種類のドキュメントそれぞれの詳細手順はreferences/配下の個別ファイルに分離した。これにより、Claudeは必要なドキュメント種別の手順だけを参照でき、コンテキスト消費を抑えられる。5Skill全体の規模は合計約5,100行・76KBに達するが、progressive disclosure (段階的開示) により、1回のリクエストで読み込まれるのはその一部である。
4.4 PlantUML Skillとの棲み分け
同じ対象 (例: データベース設計) に対して、PlantUML Skillは図を、ドキュメント生成SkillはMarkdownテキストを出力する。この競合を防ぐため、ドキュメント生成Skillのdescription末尾に「PlantUML図ではなくMarkdownを生成」と明記し、出力形式レベルでの境界を定義した。
| やりたいこと | PlantUML Skill | doc Skill |
|---|---|---|
| DB設計を整理したい | plantuml-er-diagram (ER図) | doc-data-definition (設計書) |
| アーキテクチャを把握したい | plantuml-architecture-diagram | doc-architecture (概要書) |
| クラスの仕様を知りたい | plantuml-class-diagram | doc-api-reference (リファレンス) |
| 処理の流れを確認したい | plantuml-sequence-diagram | doc-architecture (パイプライン仕様) |
4.5 description最適化の取り組み
5つのSkillが「ソースコードを解析して」という同じ出だしで始まっていたため、Claudeの選択精度に課題があった。そこで以下の最適化を行った。
- 冒頭の差別化: 各Skillの冒頭に本質を一言で明示した。例えばdoc-api-referenceは「外部から見たインターフェース」、doc-operationsは「動かす・運用するための情報」と定義し、5Skillを即座に区別可能にした。
- カジュアル表現の追加: 「このプロジェクトはどうなってるか説明して」 → doc-architecture、「何のライブラリを使ってるか」 → doc-quality-auditのように、日常的な言い回しもトリガーに含めた。
- 文字数制約への対応: descriptionの上限は1,024文字である。英語トリガーの削除、類似フレーズの統合、セクション見出しの削除などの圧縮を行い、全Skillを上限内に収めた。
5. Skillの作り方 (簡易ガイド)
手順1: フォルダとSKILL.mdを作成する。skill-name/フォルダ配下にSKILL.mdを配置する。冒頭にYAMLフロントマター (name, description) を書き、本文にClaudeへの指示をMarkdownで記述する。なお、Anthropic公式のskill-creatorを事前に導入しておくと、対話的なワークフローでベストプラクティスに沿った雛形を自動生成できる。
手順2: descriptionを設計する。Skillのルーティング精度を決める最重要要素。「このスキルを使うとき」と「使わないとき」の両方を明記し、日本語・英語の両方のトリガーワードを列挙する。文字数上限は1,024文字。
手順3: ZIP化してアップロードする。SKILL.mdを含むフォルダをZIP圧縮し、拡張子を.skillに変更。claude.aiでは「設定 > Skills」からアップロード。Claude Codeでは~/.claude/skills/にフォルダを配置する。
手順4: テストと改善。実際にリクエストを投げて意図どおりのSkillが発動するか確認する。skill-creatorのEvalモードを使えば、複数パターンのテストプロンプトで体系的に検証できる。発動しない場合はdescription のトリガーワードを追加し、誤発動する場合は境界条件を明確化する。
6. まとめ
SkillはMarkdownファイル1つで作成でき、コンテキスト負荷も極めて小さいため、Claudeの能力を拡張する最も手軽かつ実用的な手段である。外部システム連携が必要であればMCPを、チームへの配布やマルチエージェント構成が必要であればPluginをそれぞれ組み合わせればよい。Anthropic公式のfeature-devやcode-review等のPluginは、Skill単体では実現しにくい高度な開発ワークフローを提供しており、Pluginの実用的価値を示す好例である。
今回、PlantUML図生成Skill9種とドキュメント生成Skill5種の合計14種を作成・運用した経験から、以下の教訓を得た。
- skill-creatorを活用することで、Skillの設計・テスト・改善のサイクルが体系化され、一貫した品質を確保できる。
- descriptionの設計がSkillの品質を決定づける。トリガーワードと境界条件の記述が安定運用の鍵。
- 同一対象に複数Skillが存在する場合、出力形式 (図 vs テキスト) で明確に境界を引く。
- Skill数が増えるとdescription間の競合管理が重要になる。定期的な発動条件の見直しが必要。
- progressive disclosure (参照ファイルの分離) により、大規模Skillでもコンテキスト負荷を抑制可能。