blog

AIブログ

Claude Code Skillsの仕組みと実装ガイド――設計から運用まで

監修

河合継（クリスタルメソッド株式会社代表取締役）

AI・ディープラーニングに関する特許16件の発明者。国立がん研究センターとの共同研究や、テレビ番組でのAI解説実績を持つAI研究者として、AIの研究開発を主導している。
運営会社について｜編集方針

Claude Code Skillsは、再利用可能な手順・指示セットをファイルとして定義し、エージェントが自律的または手動で呼び出せるようにする仕組みだ。本記事では、公式ドキュメント（code.claude.com/docs/en/skills）に基づき、配置ルール・frontmatter仕様・呼び出し方法・コンテキスト効率・関連機能との違いを整理し、設計から運用・セキュリティまでを体系的に解説する。

Claude Code Skillsとは何か――設計思想と技術的位置づけ

Claude Code Skillsは、Anthropicのコーディングエージェント「Claude Code」において、繰り返し実行されるワークフローを再利用可能なモジュールとして定義・管理する仕組みだ。単なるプロンプトテンプレートと根本的に異なるのは、指示書・参照資料・実行手順を一つのパッケージとして統合し、エージェントが自律的に実行できるワークフロー単位として機能する点にある（code.claude.com/docs/en/skills）。

2026年3月のアップデート以降、Claude Codeは「ターミナルに張り付くAIツール」から「どこからでも使える自律エージェント」へと質的に変化したと技術共有プラットフォームnoteで報告されている（note.com/kazu_t, 2026）。この変化を支える中核機能がAgent Skillsだ。

エンジニアの観点から整理すると、Skillsは「ロジックのコード化」に近い概念だ。属人的なプロンプト職人芸を、チームで共有・バージョン管理できる資産へと変換する手段として捉えるのが正確である。

また、国土交通省が推進するPLATEAUプロジェクトでは、都市デジタルツイン向けのPLATEAU Agent Skillsとしてスキル仕様が公開されており（docs.plateauview.mlit.go.jp）、エンタープライズ・公共領域へのスキルベースアーキテクチャの普及が具体的な事例として確認できる。

Claude Code自体の基本的な使い方については、Claude Codeの使い方解説記事を合わせて参照されたい。

図1：Claude Code Skillsのアーキテクチャ概念図。スキルパッケージ（SKILL.md・スクリプト・テンプレート・手順・制約定義・description）がClaude Codeエージェントに遅延ロードされ、定義されたワークフローを自律実行する。

Claude Code SkillsのSKILL.md構造と実装の要点

スキルの中核を担うのがSKILL.mdファイルだ（code.claude.com/docs/en/skills）。Markdownベースで記述されるこのファイルはエージェントへの指示書として機能し、実行するタスクの目的・前提条件・手順・出力形式・制約を明示的に定義する。

配置場所とスコープ

SKILL.mdの配置場所によってスコープが決まる（code.claude.com/docs/en/skills）。

プロジェクト共有：.claude/skills/<skill-name>/SKILL.md ― そのプロジェクト内で共有される。
個人共有（全プロジェクト）：~/.claude/skills/<skill-name>/SKILL.md ― 全プロジェクトをまたいで共有される。

なお、旧形式の .claude/commands/*.md は互換性が維持されているが、新規作成には SKILL.md 形式が推奨されている。たとえば .claude/skills/deploy/SKILL.md と .claude/commands/deploy.md はどちらも /deploy を呼び出し可能にする（code.claude.com/docs/en/skills）。

frontmatterの実在フィールド

SKILL.mdのfrontmatterには以下のフィールドが実在する（code.claude.com/docs/en/skills）。

description（必須）：Claudeがこのスキルを使うべき場面かどうかを判断するために参照する。適切に記述することが自動呼び出し精度を左右する最重要フィールドだ。
invoke：auto または manual。auto に設定するとClaudeがdescriptionを参照し文脈に応じて自動使用する。manual（デフォルト）はスラッシュコマンドによる明示的な呼び出しのみ。
tags：スキルの分類・検索用タグ。

なお、disable-model-invocation のようなfrontmatterフィールドは公式ドキュメントに存在しない。呼び出し制御が必要な場合はsettingsの skillOverrides で対応する。

呼び出し方法とコンテキスト効率

スキルの呼び出しは /skill-name 形式の手動呼び出しと、invoke: auto による自動呼び出しの2通りがある（code.claude.com/docs/en/skills）。スキルの一覧確認は / コマンドで行う（全コマンド・スキル一覧が表示され、フィルタも可能）。/skills や /list-skills といったコマンドは存在しない点に注意されたい。

コンテキスト効率の面でも重要な特性がある。スキル名とdescriptionはセッション開始時にロードされるが、スキル本文（SKILL.mdの本体内容）は実際に使用されるときにのみロードされる。常時コンテキストを消費するCLAUDE.mdとは異なり、使わないスキルはトークンを消費しない設計だ（code.claude.com/docs/en/skills）。

Agent Skills標準規格との互換性

Claude Code SkillsはAgent Skills標準規格（agentskills.io）に準拠しており、複数のAIツール間でスキルを共有できる設計となっている。

実装上の重要な設計原則

実装上の重要な勘所は次の3点に集約される。

スコープの明示（何をするか・何をしないかの両方）：AIに曖昧な裁量を持たせると、予期しないファイル操作や外部API呼び出しが発生するリスクがある。許可するコマンド・ツールの範囲を明示的に列挙することが、セキュリティと動作の予測可能性を両立させる基本設計だ。
descriptionの質がスキルの自動判断精度を決める：invoke: auto を使う場合、Claudeはdescriptionだけを見て「このスキルを使うべきか」を判断する。曖昧な記述は誤発動や見落としにつながる。具体的なトリガー条件を簡潔に記述することが重要だ。
記述量とトークン効率：Claude Codeベストプラクティス（ai-heartland.com, 2026/04/11）では、指示書は200行以内に収めることが推奨されている。スキル本文は遅延ロードのためCLAUDE.mdほど即時的な影響はないものの、指示書の肥大化はエージェントの判断精度低下を招く。必要最小限の記述で最大の制御を実現するという設計原則は一貫して適用すべきだ。

以下にSKILL.mdの実装骨格を示す。コードレビュー自動化スキルを例として取り上げる。

---
description: Pull Requestの差分を解析し、バグ・セキュリティリスク・コーディング規約違反を指摘する。git diffが利用可能なリポジトリで自動的に呼び出す。
invoke: auto
tags: [review, quality, security]
---

# SKILL: コードレビュー自動化

## 目的
Pull Requestの差分を解析し、バグ・セキュリティリスク・
コーディング規約違反を指摘する。

## 前提条件
- git diffが取得可能な環境であること
- 対象リポジトリのCODING_STYLE.mdが存在すること

## 許可するツール・コマンド
- git diff
- ファイル読み取り（読み取り専用）

## 手順
1. `git diff origin/main HEAD` を実行し差分を取得
2. CODING_STYLE.mdの規約と照合
3. 指摘事項をMarkdownリストで出力
   （severity: critical / warning / info）

## 制約（明示的禁止事項）
- 自動コミット・プッシュは行わない
- 外部APIへのデータ送信は行わない
- ファイルの書き換えは行わない

## 出力形式
### レビュー結果
- [critical] <ファイルパス>:<行番号> <内容>
- [warning]  <ファイルパス>:<行番号> <内容>
- [info]     <ファイルパス>:<行番号> <内容>

セキュリティ面では、IPA「AIセキュリティ短信 2026年3月号」がAIエージェントへの指示インジェクション（Prompt Injection）リスクを具体的な脅威として取り上げており、実装段階からの対策を求めている（IPA, 2026年3月）。SKILL.mdで実行可能なツール・コマンドの範囲を許可リスト形式で明示し、外部入力（ユーザー入力・ファイル内容）をそのままプロンプトに展開する構造を避けることが基本的な対策となる。

インストール手順の詳細はClaude Codeのインストール解説記事を、スラッシュコマンドとの連携についてはスラッシュコマンド解説記事（公式：code.claude.com/docs/en/slash-commands）を参照されたい。

Agent Skillsの実践的ユースケースと活用パターン

Agent Skillsの実用性は、具体的なユースケースの中でこそ評価できる。以下に代表的な活用パターンを示す。

コード品質管理スキル

テスト生成・レビュー・リファクタリング提案を一連のスキルとして定義し、CIパイプラインに統合する構成は、最も汎用性の高い活用パターンの一つだ。Claude Codeベストプラクティス（ai-heartland.com, 2026/04/11）では「3〜5並列ワーク」が推奨されており、複数スキルを同時実行することでスループットを高められる。ただし並列実行はトークン消費の増加に直結するため、コスト管理との兼ね合いで実行本数を設計する必要がある。

ドキュメント生成スキル

コードから仕様書・API仕様・変更履歴を自動生成するスキルは、ドキュメント陳腐化問題への実践的な解となる。テンプレートをSKILL.mdに組み込むことで出力フォーマットの一貫性が保たれ、レビューコストを削減できる。ただし生成ドキュメントの最終確認を人間が担う運用フローを設計しないと、誤情報の蓄積リスクが生じる点は留意が必要だ。

GitHubからのスキル探索と導入

Reddit（r/claude）コミュニティでは「find-skills」というGitHub上のスキルを検索するメタスキルが注目されており、コミュニティ主導のスキルエコシステムが形成されつつある（reddit.com/r/claude, 2026）。スキルの検索・探索・導入の具体的な操作手順については、Qiita記事（2026/03/04）が実際の手順を詳説している。外部スキルを導入する際は、SKILL.md内に記述された許可コマンドの内容を必ず確認する習慣が重要だ。

公共・エンタープライズ領域での活用

国土交通省PLATEAUプロジェクトでは、都市3Dモデルの操作・クエリ・可視化を担うPLATEAU Agent Skillsが仕様として公開されている（docs.plateauview.mlit.go.jp）。国家規模のGISプロジェクトでスキルベースのエージェントアーキテクチャが採用されている事実は、エンタープライズ導入における参照事例として重要な位置を占める。技術仕様の公開は、他のエンタープライズ案件がスキル設計を行う際の参考資料としても機能する。

Claude Codeの他ツールとの比較・選定については、Claude CodeとCursorの比較記事およびClaude CodeとCodexの比較記事も参照されたい。

Skills・サブエージェント・MCP・スラッシュコマンドの違い

Claude Codeには類似した拡張機能が複数存在するため、役割の違いを正確に把握することが設計判断の基礎となる（code.claude.com/docs/en/skills）。

表：Skills・サブエージェント・MCP・スラッシュコマンドの役割比較
機能	定義ファイル	主な役割	呼び出し確認コマンド
Skills	SKILL.md	再利用可能な手順・指示セット（遅延ロード）	`/`（一覧）
サブエージェント	.claude/agents/	独立したコンテキストを持つ専門AI	`/agents`
MCP	外部ツール接続設定	外部ツール・サービスとの接続	`/mcp`
スラッシュコマンド	―	セッション制御や実行インターフェース	`/`（一覧）

Skillsはコマンド実装の基盤の一つであり、「スキルはスラッシュコマンドの一種」という説明は正確ではない。サブエージェントの詳細は公式ドキュメント（code.claude.com/docs/en/sub-agents）、MCPは公式ドキュメント（code.claude.com/docs/en/mcp）を参照されたい。

Claude Code Skillsの選定・比較と導入時のトレードオフ

Claude Code Skillsを導入する際の技術的な判断軸を整理する。類似する仕組みとして、Cursor RulesのProject Rules、GitHub Copilot WorkspaceのカスタムInstructionsが挙げられる。各アプローチの主要な差異を以下の比較表にまとめる。

表1：AIコーディングエージェントのスキル管理機能比較（2026年6月時点）
比較項目	Claude Code Skills	Cursor Rules（Project）	GitHub Copilot Workspace Inst.
定義ファイル形式	SKILL.md（Markdown）	.cursorrules（Markdown）	.github/copilot-instructions.md
自律実行（エージェント）	あり（invoke: auto対応）	部分的（Composer Agent）	あり（Workspace Agent）
スキルのパッケージ化・共有	あり（agentskills.io標準準拠）	手動ファイル共有のみ	リポジトリ単位のみ
本文の遅延ロード	あり（使用時のみロード）	公式に明記がない	公式に明記がない
指示書の推奨上限	200行以内	公式推奨値は確認できず	公式推奨値は確認できず
主なセキュリティリスク	Prompt Injection、トークン消費増	指示の競合・優先度管理	機密情報のプロンプト混入
エンタープライズ・公共導入事例	PLATEAU Agent Skills（国交省）	公開事例は確認できず	公開事例は確認できず

導入時に直面する主なトレードオフは次の通りだ。

柔軟性 vs セキュリティ：スキルに与えるツール実行権限を広げるほど自動化の恩恵は大きくなる一方、IPAが指摘するPrompt Injectionリスクも高まる（IPA, 2026年3月）。本番環境へのデプロイ権限をスキルに与えることは、現時点では慎重な検討が必要だ。
再利用性 vs 精度：汎用的なスキルほど多くの場面で使えるが、特定ユースケースに特化したスキルの方が出力精度は高い傾向がある。プロジェクト固有スキル（.claude/skills/）とチーム共有スキル（~/.claude/skills/）の粒度設計が、実運用の品質を左右する。
トークンコスト：スキル本文は遅延ロードのため常時消費はないが、実行時のSKILL.mdの記述量はトークン消費に直結し、並列実行では複数スキルのトークンが同時に発生する。コスト構造についてはClaude Codeの料金体系解説およびAPI料金の詳細解説を確認した上で、スキルの規模感とバッチ実行の設計を行う必要がある。
外部スキルの品質保証：コミュニティ配布のスキルは内容の検証が不十分なケースがある。導入前にSKILL.mdの許可コマンドと制約定義を必ず精査することが原則だ。

セキュリティと品質担保――実装チェックリストと一次実装知見

エンジニアがClaude Code Skillsを本番投入する前に確認すべき項目を整理する。IPA「AIセキュリティ短信 2026年3月号」の指摘事項（IPA, 2026年3月）および各種技術一次情報をもとに構成した。

スキル設計段階

SKILL.mdのfrontmatterに description（必須）を適切に記述し、自動呼び出しの精度を確保しているか
SKILL.mdに実行可能なコマンド・ツールの許可リストを明示しているか
外部入力（ユーザー入力・ファイル内容）をそのままプロンプトに展開する箇所がないか
スキルのスコープ外操作（予期しないファイル削除・外部送信）を制約セクションで明示しているか
記述量が200行以内に収まっているか（トークン効率と判断精度の確保）
プロジェクト共有（.claude/skills/）か個人共有（~/.claude/skills/）かをスコープに応じて正しく選択しているか

評価・テスト段階

エッジケース（入力が空、依存ファイルが存在しない、文字コードが異なる等）での動作を確認したか
意図しないファイル書き換えやコマンド実行が発生しないことをサンドボックス環境で検証したか
/（コマンド・スキル一覧）でスキルが正しく認識されていることを確認したか

運用・管理段階

スキルファイルをGitで管理し、変更履歴を追跡しているか
チーム共有スキルの更新権限者・レビュープロセスが明確になっているか
利用しているモデルのバージョンアップに伴うスキル動作変化の確認サイクルを設けているか
外部から取得したスキルのSKILL.md内容を導入前に精査しているか

弊社が開発するDeepAIでは、機械学習・深層学習（CNN）による2D画像認識・異常検知を実装しており、ソファーのように形状が一定でない対象物の正常・異常分類においておよそ99%の精度を実現している（出典：crystal-method.com/solutions/deepai/）。弊社での実装経験から、AIパイプラインを本番運用する際の共通課題として、「エージェントが何をしているかを常に追跡可能にする」という設計原則の重要性を実感している。Claude Code Skillsにおいても、SKILL.mdでの明示的な制約定義と、遅延ロードによるコンテキスト管理の活用は、この原則を実現する有効な手段として機能する。異常検知パイプラインの自動化・監視スキルとしてClaude Code Skillsを組み合わせる構成は技術的な整合性が高く、実装検討の対象となりうる。

Claude Codeの全体像を把握するにはClaude Code概要記事を、初学者向けの導入ガイドははじめてのClaude Code記事も合わせて参照されたい。なお、SEOワークフローへのClaude Code活用についてはClaude Code SEO活用の入門記事が参考になる。

まとめ

Claude Code Skillsは、AIコーディングエージェントの能力を「一回限りのプロンプト」から「再利用・共有・チーム管理可能な資産」へと昇華させる仕組みだ。本記事で確認した主要ポイントを整理する（code.claude.com/docs/en/skills）。

スキルの本体は SKILL.md。プロジェクト共有は .claude/skills/<skill-name>/SKILL.md、個人共有は ~/.claude/skills/<skill-name>/SKILL.md に配置する。
frontmatterの実在フィールドは description（必須）・invoke・tags の3つ。description の質が自動呼び出し精度を決定する。
スキル本文は使用時のみロードされる遅延ロード設計で、常時コンテキストを消費するCLAUDE.mdとは異なりトークン効率が高い。
スキル一覧の確認は /（全コマンド・スキル一覧）。/skills や /list-skills は存在しない。
Agent Skills標準規格（agentskills.io）に準拠し、複数ツール間での共有も可能。

一方で、Prompt Injectionリスク（IPA指摘）・トークンコスト・スキル粒度の設計・外部スキルの品質保証といった課題は、実装段階から意識的に対処する必要がある。国土交通省PLATEAUへの採用事例が示すように、スキルベースのエージェントアーキテクチャは公共・エンタープライズ領域での実績を積みつつあり、技術選定の候補として検討する価値は高まっている。

具体的な導入コストの試算にはClaude Codeの料金解説記事を、他ツールとの詳細比較にはCursorとのAgentモード比較記事を参照し、自チームの技術スタックとのフィット感を見極めた上で意思決定することを推奨する。

参考文献

Claude Code Skills 公式ドキュメント（Anthropic）
https://code.claude.com/docs/en/skills
Claude Code Sub-agents 公式ドキュメント（Anthropic）
https://code.claude.com/docs/en/sub-agents
Claude Code MCP 公式ドキュメント（Anthropic）
https://code.claude.com/docs/en/mcp
Claude Code Slash Commands 公式ドキュメント（Anthropic）
https://code.claude.com/docs/en/slash-commands
Agent Skills 標準規格
https://agentskills.io
PLATEAU Agent Skills概要（国土交通省）
https://docs.plateauview.mlit.go.jp/skills/overview/
AIセキュリティ短信 2026年3月号（IPA）
https://www.ipa.go.jp/digital/ai/security/rcu1hd0000007gji-att/2-1_202603.pdf
Claude Codeベストプラクティス2026（ai-heartland.com, 2026/04/11）
https://ai-heartland.com/explain/claude-code-best-practice-guide-2026/
【2026年最新】Claudeでスキルを作成（Qiita, 2026/03/04）
https://qiita.com/kamome_susume/items/acbfcae9e61ec9a90b51
【2026年3月版】Claude Codeがどれだけ進化したかまとめ（note.com/kazu_t）
https://note.com/kazu_t/n/n1a207262b51c
2026年に私が使う最高のクロードスキル（reddit.com/r/claude）
https://www.reddit.com/r/claude/comments/1s5qyef/best_claude_skills_i_use_in_2026/?tl=ja
Claude Code 2026年最新アップデート（speakerdeck.com/oikon48, 2026/03/12）
https://speakerdeck.com/oikon48/claude-code-0312

Study about AI

AIについて学ぶ

Claude Code 公式ドキュメント完全読解ガイド｜導入判断から運用まで

監修河合継（クリスタルメソッド株式会社代表取締役） AI・ディープラーニングに関する特許16件の発明者。国立がん研究センターとの共同研究や、テレビ番組での...
Claude Code ベストプラクティス完全解説｜実装現場で使える設計指針2026

監修河合継（クリスタルメソッド株式会社代表取締役） AI・ディープラーニングに関する特許16件の発明者。国立がん研究センターとの共同研究や、テレビ番組での...
Claude Code 自動化の実装ガイド――設計・事例・セキュリティを徹底解説

監修河合継（クリスタルメソッド株式会社代表取締役） AI・ディープラーニングに関する特許16件の発明者。国立がん研究センターとの共同研究や、テレビ番組での...