【2026年4月】Agent Skills完全ガイド｜Claude実装と本番運用

2026.04.28 公開 20分で読める

この記事の結論

Anthropic Agent Skillsを使うと、Claude APIやClaude Codeに独自のAIエージェント機能を追加できます。SKILL.md設計からAPIでの実装（Python）、本番運用まで2026年4月最新情報で解説。

「ChatGPTのGPTsみたいに、Claudeに特定の知識やワークフローを持たせたい。でもプロジェクトごとに同じ指示をコピーするのはもう限界だ…」

先日、あるSaaSスタートアップのエンジニアチームと話していて、こんな課題を聞きました。コードレビューのルール、データベーススキーマ、社内APIの使い方…毎回プロンプトに貼り付けているうちに、コンテキストが埋まりすぎて肝心のタスクに集中できなくなる、という悩みです。

この問題を根本から解決するのが、Anthropicが2025年10月にリリースしたAgent Skills（エージェントスキル）です。SKILL.mdという単純なMarkdownファイルに指示・コード・リソースをまとめることで、Claudeが必要なときだけ自動で読み込む「オンデマンド専門知識」を作れます。この記事では、SKILL.mdの設計から、Claude API（Python）での実装、Claude Codeでの活用、本番運用のベストプラクティスまで、2026年4月時点の最新情報をもとにコピペ可能なコードつきで解説します。

まず試したい「5分即効」セットアップ3選

即効テクニック1：Claude Codeに最初のスキルを作る

Claude Codeを使っているなら、スキルは最も手軽に試せます。ターミナルでディレクトリを作り、SKILL.mdを置くだけです。

# 動作環境: Claude Code（最新版）
# パーソナルスキル（全プロジェクト共通）
mkdir -p ~/.claude/skills/code-reviewer

cat > ~/.claude/skills/code-reviewer/SKILL.md << 'EOF'
---
name: code-reviewer
description: Pythonコードをレビューし、バグ・パフォーマンス・可読性の問題を指摘する。コードレビューを依頼されたとき、または「レビューして」と言われたときに使用する。
---

# コードレビュースキル

## レビュー観点

1. **バグ・エッジケース**: NoneやIndexErrorが起きそうな箇所を列挙
2. **パフォーマンス**: O(n²)以上のループ、N+1クエリを検出
3. **可読性**: 変数名・関数名が意図を表しているか確認

## 出力形式

❌ 問題点（優先度: 高/中/低）
⭕ 修正案（コードブロック付き）
EOF

echo "スキル作成完了。Claude Codeで「このコードをレビューして」と言えば自動で発動します。"

効果: 毎回「以下の観点でレビューしてください…」と書く必要がなくなります。Claude Codeがコードレビューに関連するリクエストを自動検出し、スキルを読み込んで対応します。

即効テクニック2：プリビルトスキルをAPIで即使う（Python）

AnthropicはPowerPoint・Excel・Word・PDFの4つのプリビルトスキルをすぐ使える状態で提供しています。以下はExcelファイルを自動生成する最小構成のコードです。

# 動作環境: Python 3.11+, anthropic>=0.40.0
# pip install anthropic
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "files-api-2025-04-14"
    ],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "xlsx",  # Excel スキル
                "version": "latest"
            }
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "2026年Q1の売上データ（月別・製品別）を集計したExcelファイルを作成してください。サンプルデータを入れて、合計行と円グラフも追加してください。"
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

print(response.content)

ポイント: betasパラメータに3つのヘッダーを指定するのが必須です。`code-execution-2025-08-25`（コード実行環境）、`skills-2025-10-02`（スキル機能）、`files-api-2025-04-14`（ファイル入出力）の3セットを忘れると`400`エラーになります。

即効テクニック3：生成ファイルをダウンロードする

スキルが生成したExcelやPDFをローカルに保存するには、レスポンスからfile_idを取り出してダウンロードします。

# 動作環境: Python 3.11+, anthropic>=0.40.0
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

def download_skill_output(response, output_path: str):
    """スキルが生成したファイルをダウンロードして保存する"""
    for item in response.content:
        # コード実行結果のブロックを探す
        if item.type == "bash_code_execution_tool_result":
            for file in item.content.content:
                if hasattr(file, "file_id"):
                    file_id = file.file_id

                    # メタデータを取得してファイル名を確認
                    metadata = client.beta.files.retrieve_metadata(
                        file_id=file_id
                    )
                    print(f"生成ファイル: {metadata.filename}")

                    # ファイルをダウンロードして保存
                    content = client.beta.files.download(file_id=file_id)
                    content.write_to_file(output_path)
                    print(f"保存完了: {output_path}")
                    return output_path

    print("警告: ファイル出力が見つかりませんでした")
    return None

# 使用例
download_skill_output(response, "output_q1_sales.xlsx")

Agent Skillsのアーキテクチャ｜3レベルの仕組みを理解する

Agent Skillsが「オンデマンド専門知識」として機能できる理由は、プログレッシブディスクロージャー（段階的情報開示）という設計にあります。全ての情報を最初からコンテキストに詰め込まず、必要なときだけ読み込むことでトークンを節約します。

レベル	コンテンツ	ロードタイミング	トークン消費
Level 1: メタデータ	YAMLフロントマター（name・description）	常時（起動時）	スキル1つ約100トークン
Level 2: 指示書	SKILL.mdの本文	スキルが発動したとき	5,000トークン以下推奨
Level 3: リソース	参照ファイル・実行スクリプト	明示的に参照されたとき	実質無制限（参照時のみ）

具体的なディレクトリ構成はこのようになります：

my-skill/
├── SKILL.md          # メイン指示書（必須）
├── reference.md      # 詳細リファレンス（必要時のみ読み込まれる）
├── examples.md       # 使用例（必要時のみ読み込まれる）
└── scripts/
    └── validate.py   # 実行スクリプト（コードはコンテキストに入らない）

特に重要なのがscripts/内の実行スクリプトです。Claudeがスクリプトを実行するとき、スクリプトのコード自体はコンテキストに入りません。実行結果（標準出力）だけが返ってきます。これにより、何百行もあるバリデーションロジックを「実質0トークン」で活用できます。

カスタムスキルの実装サンプル｜API・Claude Code別

Claude APIでカスタムスキルを作成・利用する

APIでカスタムスキルを使うには、まずスキルをアップロードして管理します。ワークスペース内の全員が共有できるのがAPIスキルの特徴です（1リクエスト最大8スキル、スキルファイルは30MB以下）。

# 動作環境: Python 3.11+, anthropic>=0.40.0
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

from anthropic import Anthropic
from anthropic.lib import files_from_dir
import os

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# ステップ1: カスタムスキルをアップロード
# /path/to/my-skill/ ディレクトリにSKILL.mdが入っている前提
skill = client.beta.skills.create(
    display_title="BigQuery分析スキル",
    files=files_from_dir("/path/to/bigquery-skill")
)

print(f"スキルID: {skill.id}")
print(f"最新バージョン: {skill.latest_version}")

# ステップ2: アップロードしたスキルを使ってAPIリクエスト
response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "files-api-2025-04-14"
    ],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "xlsx",  # プリビルトスキル
                "version": "latest"
            },
            {
                "type": "custom",
                "skill_id": skill.id,  # カスタムスキル
                "version": "latest"
            }
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Q1の売上データを分析して、BigQueryスキルの手順で集計してください"
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

print(response.content)

スキルのバージョン管理

# スキルを更新する場合（新バージョン作成）
# 動作環境: Python 3.11+, anthropic>=0.40.0

# 既存スキルの一覧確認
skills = client.beta.skills.list(source="custom")
for s in skills.data:
    print(f"{s.display_title}: {s.id} (v{s.latest_version})")

# 新しいバージョンを作成（スキルIDは変わらない）
new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated-bigquery-skill")
)
print(f"新バージョン: {new_version}")

SKILL.md設計のベストプラクティス

実際にいくつかのスキルを作ってみて気づいたのは、「コンテキストは公共財」という発想が重要だということです。SKILL.mdに情報を詰め込むほどコンテキストを消費し、他のタスクの邪魔になります。以下の設計原則を守ると品質が大幅に上がります。

descriptionは「何をするか」と「いつ使うか」を両方書く

descriptionはClaudeがスキルを選択する唯一の手がかりです。曖昧な説明では発動しません。

# NG例（発動率が低い）
---
name: data-helper
description: データを助けます
---

# OK例（発動条件が明確）
---
name: bigquery-analyzer
description: BigQueryのクエリを作成・最適化し、クエリ結果を分析する。BigQuery、BQ、データ分析、売上集計について質問されたときに使用する。
---

SKILL.mdは500行以内。長くなったら別ファイルへ

# BigQuery分析スキル

## クイックスタート

```sql
-- 基本的な売上集計クエリ
SELECT
  date,
  product_name,
  SUM(revenue) AS total_revenue
FROM `project.dataset.sales`
WHERE date BETWEEN '2026-01-01' AND '2026-03-31'
GROUP BY 1, 2
ORDER BY 1
```

## 利用可能なテーブル

**売上**: 日別・製品別の売上 → [reference/sales.md](reference/sales.md)
**財務**: ARR、請求データ → [reference/finance.md](reference/finance.md)
**製品**: API使用量、機能採用率 → [reference/product.md](reference/product.md)

## 共通ルール

- **テストアカウント除外**: 全クエリに `WHERE account_type != 'test'` を追加
- **タイムゾーン**: 全日付はJSTで表示（`DATETIME(date, 'Asia/Tokyo')`）

テーブルごとにファイルを分けておくと、Claudeは売上の質問にはreference/sales.mdだけを読み、財務の質問にはreference/finance.mdだけを読みます。無関係なスキーマがコンテキストを圧迫しません。

【要注意】よくある失敗パターンと回避策

失敗1: betasヘッダーの指定漏れ

# ❌ NG: betas指定なし → 400エラー
response = client.messages.create(
    model="claude-opus-4-7",
    container={"skills": [{"type": "anthropic", "skill_id": "xlsx"}]},  # エラー
    ...
)

# ⭕ 正解: 3つのbetaヘッダーを必ず指定
response = client.beta.messages.create(
    model="claude-opus-4-7",
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "files-api-2025-04-14"
    ],
    container={"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]},
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    ...
)

なぜ重要か: SkillsはコードExecution環境で動作するため、3つのベータ機能が連動して有効化されている必要があります。1つでも欠けると動きません。

失敗2: descriptionを一人称で書く

# ❌ NG: 一人称はClaude自身の発言として解釈され、発動精度が下がる
description: 私はExcelファイルの処理を手伝います

# ⭕ 正解: 三人称で書く
description: Excelファイルを処理し、データ集計・グラフ生成・レポート作成を行う。Excelや.xlsxファイルの操作を依頼されたときに使用する。

失敗3: 参照リンクを深くネストする

# ❌ NG: SKILL.md → advanced.md → details.md と2段階以上ネストする
# Claude が途中で head -100 だけ読んで情報を見落とす可能性がある

# ⭕ 正解: SKILL.md から全ての参照ファイルへ直接リンク（1段階のみ）
## 詳細ガイド
- 基本操作: [basics.md](basics.md)
- エラー対処: [troubleshooting.md](troubleshooting.md)
- APIリファレンス: [api-reference.md](api-reference.md)

失敗4: Claude API経由でスキルをネットワーク通信させようとする

Claude APIのコード実行環境（Skills）はネットワークアクセスなしで動作します。外部APIを叩くコードはClaude.aiでは動きますが、Claude API経由では動きません。

# ❌ NG: APIで外部リクエストするコードをSKILL.mdに書く
Use `requests.get("https://api.example.com/data")` to fetch data

# ⭕ 正解: 事前にデータを渡す設計にする
User will provide the data as a file attachment or in the message.
Process only what is provided in the conversation context.

本番運用ベストプラクティス

評価駆動開発（スキルを書く前にテストケースを作る）

スキルを作る前に、「このスキルが正しく動いたと判断できる基準」を先に定義します。感覚的なチューニングを減らし、改善の効果を数値で確認できるようになります。

{
  "skills": ["bigquery-analyzer"],
  "query": "2026年Q1の製品別売上ランキングを出してください",
  "expected_behavior": [
    "テストアカウントを除外するWHERE句が含まれている",
    "日付範囲が2026-01-01から2026-03-31に設定されている",
    "製品名でGROUP BYしている",
    "SUM(revenue)で集計している"
  ]
}

Claude Codeではdisable-model-invocationで制御する

副作用があるスキル（デプロイ・コミット・外部送信など）は、Claudeが自動発動しないよう制御します。

---
name: deploy-production
description: 本番環境にアプリケーションをデプロイする
disable-model-invocation: true  # ユーザーが /deploy-production と手動で呼ぶときだけ動く
allowed-tools: Bash(git *) Bash(npm *)
---

## 本番デプロイ手順

1. テストスイートを実行: `npm test`
2. ビルド: `npm run build`
3. デプロイ: `npm run deploy:prod`
4. ヘルスチェック: `curl https://api.example.com/health`

Haiku・Sonnet・Opusを使い分ける

モデル	スキルとの相性	推奨用途
Claude Haiku	シンプルな指示を詳しめに書く必要あり	大量バッチ処理、コスト重視
Claude Sonnet 4.6	バランスが良い（推奨）	日常的なAPI利用
Claude Opus 4.7	説明過多にしないよう注意	複雑なワークフロー、高品質出力

正直にお伝えすると、同じSKILL.mdがHaikuでは意図通りに動かないケースがあります。スキルを本番投入する前に、実際に使う全モデルでテストしてください。

スキルのコンテキスト保持（Claude Codeでの注意点）

Claude Codeでスキルを発動すると、SKILL.mdの内容はセッション全体に残ります。ただしauto-compactionが走った場合、古いスキルが圧縮されることがあります。長いセッションで「スキルが効かなくなった」と感じたら、/スキル名で再発動してください。

FAQ：よくある疑問

Q: Claude.aiのカスタムスキルとAPIのカスタムスキルは共有できますか？

A: 共有できません。Claude.aiにアップロードしたスキルはそのユーザー個人にのみ有効で、APIにはアップロードされません。APIのカスタムスキルはワークスペース全体で共有されますが、Claude.aiには反映されません。Claude Codeのスキルはファイルシステムベースで独立しています（~/.claude/skills/）。3つのサーフェスで別々に管理する必要があります。

Q: 1リクエストにスキルはいくつまで使えますか？

A: Claude API経由では1リクエストあたり最大8スキルです。Claude Codeでは上限なしに複数スキルを組み合わせられますが、description・when_to_useの合計が1,536文字を超えると短縮されます。多数のスキルを使う場合は、descriptionの冒頭に重要なキーワードを前置きしてください。

Q: スキルのZero Data Retention（ZDR）は対応していますか？

A: 対応していません（2026年4月現在）。スキルの定義と実行データはAnthropicの標準データ保持ポリシーに従います。機密データを含むスキルを使う場合は、自社のセキュリティポリシーと照合してください。

Q: スキルが自動発動しない場合はどうすれば？

A: まずdescriptionが発動条件を具体的に書いているか確認してください。「何について質問されたときに使うか」をdescriptionに明示するのが最も効果的です。それでも発動しない場合は、/スキル名で手動呼び出してください。

参考・出典

Agent Skills Overview — Anthropic Developer Docs（参照日: 2026-04-28）
Using Agent Skills with the API — Anthropic Developer Docs（参照日: 2026-04-28）
Skill authoring best practices — Anthropic Developer Docs（参照日: 2026-04-28）
Extend Claude with skills — Claude Code Docs（参照日: 2026-04-28）
Equipping agents for the real world with Agent Skills — Anthropic Engineering（参照日: 2026-04-28）
anthropics/skills — GitHub（公式スキルリポジトリ）（参照日: 2026-04-28）

まとめ：今日から始める3つのアクション

今日: Claude Codeに最初のスキルを作る（「即効テクニック1」のコードをコピペするだけ）。自分がよく使う指示やルールをSKILL.mdに書き出してみてください
今週中: プリビルトスキル（Excel・PowerPoint・PDF）をAPIで試す。ドキュメント生成の自動化が最も効果を実感しやすいです
今月中: チームの共通知識（DB スキーマ・APIルール・コードレビュー観点）をカスタムスキルとして整備し、ワークスペース全体で共有する

あわせて読みたい:

【2026年4月】OpenAI Agents SDK完全ガイド｜実装とコスト試算 — AgentsフレームワークをAnthropicスキルと組み合わせた比較も掲載
【2026年4月】E2B・Daytona・Modal完全比較｜AI実行環境選定 — Skillのコード実行環境に近いサンドボックスを比較

Agent Skillsを実際の業務に導入したいが、社内への定着まで不安があるという方へ

UravationではAIエージェント導入の研修・コンサルを行っています。スキル設計から社内展開のロードマップまでお気軽にご相談ください。

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー10万人超。
100社以上の企業向けAI研修・導入支援。著書累計3万部突破。
SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。
ご質問・ご相談はお問い合わせフォームからお気軽にどうぞ。

Need help moving from reading to rollout?

この記事を読んで導入イメージが固まってきた方へ

Uravationでは、AIエージェントの要件整理、PoC設計、社内導入、研修まで一気通貫で支援しています。

30分無料相談を予約支援実績を見る

※ 本記事の情報は2026年4月時点のものです。サービスの料金・仕様は変更される可能性があります。最新情報は各サービスの公式サイトをご確認ください。