Claude CodeのAgent Skillsで独自ツールを作る完全ガイド【MCP不要・2026年版】

2026年2月26日

「毎回同じプロンプトを書いている」「チームメンバーに同じ手順を教え続けている」——Claude Codeを使い込むほど、こういった非効率に気づきます。

SKILL.mdという1枚のMarkdownファイルを置くだけで、Claude Codeはそのファイルに書かれた手順・ドメイン知識・プロジェクト固有のルールを覚えます。これがAgent Skillsです。

MCPサーバーの構築・Node.jsのコード記述・デプロイは一切不要。ファイルを1枚書いてディレクトリに置くだけで、「/deployを実行して」という短い指示だけでClaude Codeが認証からスクリプト実行まで自動でやってくれます。

2026年時点の最新Claude Code(v1.x系)でのAgent Skillsの動作・仕様をすべて実機確認済みです。3つのハンズオンサンプルを通じて、初級から上級まで体系的に解説します。


目次


前提条件

このガイドを進める前に、以下の環境が必要です。

  • Claude Code: 最新バージョン(claude --versionで確認。本記事はv1.x系で動作確認)
  • Node.js: 18.x 以上(Claude Codeの実行環境)
  • 前提知識: Claude Codeの基本操作(コードを書かせたり質問したりできるレベル)
# Claude Code バージョン確認
claude --version
# 例: claude 1.x.x

なくてもOK: MCPの知識。Agent SkillsはMCPとは独立した機能です。MCPはサーバー・クライアントの設定が必要ですが、Agent Skillsは.mdファイルを1枚置くだけで動きます。


Agent Skillsとは?

Agent Skillsは、Claude Codeに「このプロジェクト固有の手順」を覚えさせる仕組みです。

通常、Claude Codeに複雑な作業を依頼するときは毎回プロンプトで詳細な手順を説明する必要があります。Agent Skillsを使うと、その手順をSKILL.mdというファイルに書いておくだけで、次回から「/search-consoleを実行して」という短い指示だけで同じことができます。

なぜAgent Skillsが必要か

Claude Codeを業務で使い始めると、こんな場面に出くわします。

  • 「毎回同じプロンプトを書くのが面倒」
  • 「チームメンバーが同じ手順でClaude Codeを使えるようにしたい」
  • 「プロジェクト固有のAPIや設定を毎回説明するのが辛い」
  • 「数週間前に自分が作ったスクリプトの使い方を忘れた」

Agent Skillsはこういった問題を解決するために作られた機能です。SKILL.mdにプロセス・API仕様・認証情報の参照方法などを書いておけば、Claude Codeがそれを読んで適切に動いてくれます。

git-commit / update-post / notion-tasks の各SKILL.mdがClaude Code AIインターフェースに連携する構成図

MCPとAgent Skillsの違い

2026年時点でよく混同されるのがMCP(Model Context Protocol)との違いです。

比較項目 MCP Agent Skills
セットアップ サーバー構築・Node.js実装・設定ファイル SKILL.md1枚を置くだけ
動的ツール提供 可能(リアルタイムデータ取得など) スクリプト経由で対応
チーム共有 サーバーを共有 gitでそのままコミット
保守コスト 高(コード管理・デプロイ) 低(Markdown編集のみ)
主な用途 外部サービスとのリアルタイム連携 プロジェクト固有の手順・ノウハウの蓄積

結論: APIで外部サービスと連携するときはMCP、プロジェクト固有の手順や知識を覚えさせるときはAgent Skillsが適しています。多くのユースケースではAgent Skillsで十分です。

2026年時点の最新仕様

Claude Code v1.x系でのAgent Skills動作仕様:

  • ローカルスキル: プロジェクトルートの.claude/skills/から自動読み込み
  • グローバルスキル: ~/.claude/skills/に置くと全プロジェクトで使用可能
  • スキル呼び出し: /スキル名コマンドまたは自然言語で自動認識
  • ネスト不可: skills/のサブディレクトリは1段階まで(skills/foo/SKILL.mdはOK、skills/foo/bar/SKILL.mdは認識されない)
  • フロントマター必須: namedescriptionフィールドを持つYAMLフロントマターが必要

SKILL.mdの書き方・配置場所

配置場所

SKILL.md.claude/skills/ ディレクトリ以下に置きます。

プロジェクトルート/
└── .claude/
    └── skills/
        ├── search-console/
        │   └── SKILL.md
        ├── deploy/
        │   ├── SKILL.md
        │   └── deploy.sh   ← スキルが使うスクリプト
        └── git-commit/
            └── SKILL.md

スキルごとにサブディレクトリを作り、その中にSKILL.mdを置きます。関連スクリプトや設定ファイルも同じディレクトリに置いておくと管理しやすいです。

基本フォーマット

---
name: スキル名
description: いつ使うかの説明(Claudeがスキルを選択する判断基準になる)
---

# スキルのタイトル

## 概要
このスキルが何をするかの説明

## 実行方法
具体的な手順をMarkdownで記述する

## 認証情報
必要な環境変数の参照方法

## 注意事項
ハマりやすいポイント

重要なのは フロントマターのdescription です。Claude Codeはこの説明文を読んで「このスキルを使うべき状況かどうか」を判断します。「〜するとき」「〜を確認したいとき」という形式で書くと認識精度が上がります。

フロントマターの詳細仕様

Claude Codeのフロントマターはnamedescriptionの2フィールドが必須です:

---
name: スキル名(スラッシュコマンドのキーになる)
description: |
  トリガー条件を複数行で書ける。
  具体的なシナリオを複数列挙するほど精度が上がる。
---

descriptionフィールドに日本語のトリガーシナリオを複数列挙すると、日本語での呼び出し精度が向上します。1行に収めず、複数行にわたって「〜するとき。〜を確認したいとき。」と書くと認識精度が上がります。

スキルの呼び出し方

スキルを呼び出すには、チャットで /スキル名 と入力します。

/search-console    ← Search Consoleデータを取得
/deploy            ← デプロイを実行
/git-commit        ← コミットメッセージを自動生成

または自然な日本語でも呼び出せます。「Search Consoleのデータを取得して」と言えば、Claude Codeが関連するスキルを自動で読み込んで実行します。


ハンズオン3種

ハンズオン①:Gitコミットメッセージ生成スキル(初級)

まず最もシンプルな例から始めましょう。git diffの内容を読んで、日本語のConventional Commitsメッセージを自動生成するスキルです。

このスキルで解決する問題:
– Conventional Commitsのルールを毎回思い出すのが面倒
– 変更内容の要約をうまく書けない
– チームでコミットメッセージの書き方がバラバラ

フォルダ構成

.claude/skills/git-commit/
└── SKILL.md

スクリプト不要。SKILL.mdだけで完結するシンプルな例です。

SKILL.mdの全文

---
name: git-commit
description: Gitの変更差分を読んでコミットメッセージを生成するとき。
             変更内容を日本語Conventional Commits形式でまとめたいとき。
             git commitする前にメッセージを確認したいとき。
---

# Gitコミットメッセージ自動生成

## 概要

`git diff`の差分を読んで、日本語のConventional Commitsメッセージを生成するスキル。

## 手順

1. `git status` と `git diff HEAD` を実行して変更内容を確認する
2. ステージング済みのファイルがあれば `git diff --staged` も確認する
3. 変更の種類と内容を把握する
4. 以下の形式でコミットメッセージを生成する

## コミットメッセージのフォーマット

```text
<type>(<scope>): <要約>

<詳細(省略可)>
```

### typeの選び方

| type | 用途 |
|------|------|
| feat | 新機能追加 |
| fix | バグ修正 |
| docs | ドキュメントのみの変更 |
| refactor | 機能変更を伴わないリファクタ |
| chore | ビルド・CI・設定ファイルの変更 |
| test | テストの追加・修正 |
| perf | パフォーマンス改善 |

## ルール

- 要約は50文字以内
- 命令形ではなく体言止めで書く(例: 「〜を追加」「〜を修正」)
- 破壊的変更がある場合は本文に `BREAKING CHANGE:` を明記する
- scopeは変更されたモジュール・ファイル名(省略可)

実際の使い方

# ファイルを変更・追加してステージングする
git add -A

# Claude Codeのチャットで入力
/git-commit
# または「コミットメッセージを作って」でも可

Claude Codeがgit diff --stagedを実行し、変更内容を読んで以下のようなメッセージを提案します。

feat(search-console): Search ConsoleのAPIレート制限対応を追加

- 429エラー時に自動リトライ(最大3回)
- リトライ間隔を指数バックオフで制御
- エラーログにリトライ回数を記録

git addしてClaude Codeに/git-commitと入力すると、右パネルにConventional Commitsメッセージが自動生成される様子

このスキルのポイント: わずか40行のMarkdownで、毎回「Conventional Commitsの仕様に従ってコミットメッセージを書いて、typeはfeat/fix/docs…」と説明する手間がゼロになります。

発展させるポイント: descriptionに「コミットしたいとき」「変更をgitに保存したいとき」などの日本語シナリオを追加すると、自然な日本語での呼び出し精度が上がります。


ハンズオン②:WordPress記事投稿スキル(中級)

これがAgent Skillsの真価を発揮するケースです。実際に運用しているスキルを元に解説します。

ユースケース

Markdownで書いた記事をWordPressに自動投稿するスキルです。単純なAPI呼び出しだけでなく:

  • アイキャッチ画像の設定方法
  • 下書き/公開の切り替え
  • Markdownのフロントマター解析

といったプロジェクト固有のノウハウもSKILL.mdに含めています。

フォルダ構成

.claude/skills/update-post/
├── SKILL.md          ← 手順書
└── update_post.py    ← 実際のスクリプト

SKILL.mdの全文

---
name: update-post
description: Use when updating or publishing a WordPress post for gendosu.jp
             from a Markdown draft. Triggers when applying article rewrites,
             publishing edited content, or updating post body and title via REST API.
---

# WordPress 記事公開

## 概要

Markdown ドラフトを WordPress に公開するための完全な手順。
本文投稿・アイキャッチ生成・画像アップロードまでをすべて含む。

## 公開フロー

### ステップ1: WordPress に下書き投稿して post_id を取得

```bash
bash -c 'set -a; source .env; set +a; curl -s -X POST \
  -u "$WP_USERNAME:$WP_APP_PASSWORD" \
  "$WP_SITE_URL/wp-json/wp/v2/posts" \
  -H "Content-Type: application/json" \
  -d "{\"title\": \"記事タイトル\", \"status\": \"draft\"}" \
  | python3 -c "import sys,json; p=json.load(sys.stdin); print(p[\"id\"])"'
```

### ステップ2: 本文を投稿

```bash
python3 .claude/skills/update-post/update_post.py <post_id> <draft_path> draft
```

### ステップ3: アイキャッチ画像を生成・設定(未設定の場合のみ)

`.claude/skills/image-gen/SKILL.md` を参照して生成する。

### ステップ4: レビュー → 公開

```bash
python3 .claude/skills/update-post/update_post.py <post_id> <draft_path> publish
```

## 既存記事のリライト時

既存記事を更新する場合はステップ2と4のみ実行する(アイキャッチは変更不要)。

## 必要環境変数

`.env` に以下を設定済み:

| 変数名 | 説明 |
|--------|------|
| `WP_SITE_URL` | WordPress サイト URL |
| `WP_USERNAME` | WordPress ユーザー名 |
| `WP_APP_PASSWORD` | WordPress アプリケーションパスワード |

## ⚠️ 注意事項

- 画像は必ずWordPressメディアライブラリにアップロードしてからURLを埋め込む
- ローカルファイルパス(`/home/...`)は絶対に使わない
- `load_dotenv()` はパスを明示: `load_dotenv(".env")`

スクリプト(update_post.py)の実装

#!/usr/bin/env python3
import os, markdown, requests, sys
from pathlib import Path
from dotenv import load_dotenv

load_dotenv(Path(__file__).parent.parent.parent.parent / ".env")

site_url = os.environ['WP_SITE_URL']
auth = (os.environ['WP_USERNAME'], os.environ['WP_APP_PASSWORD'])

post_id = sys.argv[1]
draft_path = Path(sys.argv[2])
status = sys.argv[3] if len(sys.argv) > 3 else 'publish'

md_text = draft_path.read_text()
lines = md_text.strip().split('\n')

# YAMLフロントマター(--- ... ---)をスキップ
start = 0
if lines[0].strip() == '---':
    try:
        end = lines.index('---', 1)
        start = end + 1
    except ValueError:
        pass

content_lines = lines[start:]

# 空行をスキップして最初の # タイトル行を探す
title_idx = 0
for i, line in enumerate(content_lines):
    if line.strip().startswith('#'):
        title_idx = i
        break

title = content_lines[title_idx].lstrip('# ').strip()
body_md = '\n'.join(content_lines[title_idx + 1:]).strip()

# アンカーIDを含む見出しを変換(例: ## 見出し {#anchor} → ## 見出し)
import re
body_md = re.sub(r'\{#[^}]+\}', '', body_md)

html_content = markdown.markdown(
    body_md,
    extensions=['tables', 'fenced_code', 'attr_list']
)

resp = requests.post(
    f'{site_url}/wp-json/wp/v2/posts/{post_id}',
    auth=auth,
    json={
        'title': title,
        'content': html_content,
        'status': status,
    }
)

if resp.status_code in (200, 201):
    p = resp.json()
    print(f"更新成功!")
    print(f"   タイトル: {p['title']['rendered']}")
    print(f"   URL: {p['link']}")
else:
    print(f"エラー: {resp.status_code}")
    print(resp.text[:500])

実際の実行結果

タイトル: Claude CodeのAgent Skillsで独自ツールを作る完全ガイド
ステータス: publish
HTML文字数: 24180

更新成功!
   タイトル: Claude CodeのAgent Skillsで独自ツールを作る完全ガイド
   URL: https://gendosu.jp/archives/3705
   更新日: 2026-04-06

SKILL.mdに手順・スクリプトを定義することで、Claude Codeが「/update-post」の一言から投稿完了まで自動実行する

このスキルのポイント: SKILL.mdにプロジェクト固有の注意事項(.envの変数名、スクリプトのパス、画像のアップロード手順)が書いてあるので、Claude Codeが毎回正しい方法で実行してくれます。「WordPressに投稿して」という一言で、認証からMarkdown→HTML変換まですべて自動化されます。


ハンズオン③:マルチスキル連携(上級)

複数のスキルを組み合わせると、より高度な自動化ができます。SEOブログのデイリー実行ワークフローを例に解説します。

ワークフロー概要

① Notionからタスク取得 (/notion-tasks)
    ↓ 「自動実行可」かつ「未着手」のタスク一覧
② タスク種別で分岐
    ├── 【リライト】→ Search Consoleデータ取得 → 記事更新 (/update-post)
    ├── 【新規記事】→ キーワード調査 (/keyword-research) → 記事生成
    └── 【インデックス確認】→ URL検査 (/url-inspect)
③ 結果をNotionに記録 + ステータス更新

このワークフローはcron/daily-execute.mdというファイルに定義されており、Claude Codeが毎日自動でこれを読んで実行します。

スキル間の連携パターン

スキル同士を連携させるときの書き方は2パターンあります。

パターンA:オーケストレーター型(推奨)

メインのワークフロー定義ファイルがスキルを呼び出す形式です。

# デイリー自動実行

## Step 1: タスク取得
.claude/skills/notion-tasks/SKILL.md を参照して、未着手タスクを取得する。

## Step 2: タスク実行
取得結果に応じて以下を呼び出す:
- 【リライト】→ update-post スキルを参照
- 【インデックス確認】→ url-inspect スキルを参照

## Step 3: 結果記録
Notion MCP で完了ステータスに更新する。

パターンB:スキル内参照型

スキルのSKILL.mdの中から別のスキルを参照する形式です。

# デプロイスキル

## 手順
1. テストを実行する(`.claude/skills/run-tests/SKILL.md` を参照)
2. テストが通ったら以下を実行:
   ```bash
   ./deploy.sh production
   ```
3. デプロイ後のヘルスチェックを行う

実際のNotionタスクスキル(SKILL.md抜粋)

---
name: notion-tasks
description: Notionのタスクを一覧・確認するとき。
             タスクのステータスをカテゴリや優先度でフィルタしたいとき。
             今日やるべき作業を確認したいとき。
---

# Notion タスク取得

## 実行方法

Notion MCP の `notion-query-database-view` を使ってクエリする。

## 取得後の表示形式

カテゴリ順にグループ化して表示する:

| ID | タスク名 | 優先度 | ステータス |
|----|---------|--------|----------|
| N  | ...     | 🔴/🟡/🟢 | 未着手/進行中/完了 |

このスキルのポイント: Notionのビュー URLやフィルタ条件は毎回調べるのが面倒ですが、SKILL.mdに書いておけばClaude Codeが自動で正しいURLを使ってクエリします。

複数のSKILL.mdをオーケストレーターから呼び出すことで、各スキルが連携した自動化ワークフローが実現する


Agent Skills 実践Tips

Tip 1: descriptionは「いつ使うか」で書く

# NG: 機能の説明になっている
description: Search Consoleのデータを取得するスキル

# OK: 使うべき場面が明確
description: Search Consoleのデータを取得するとき。
             ページのCTR・順位・表示回数を確認したいとき。
             リライト前のベースライン計測が必要なとき。

descriptionはClaude Codeが「このスキルを今使うべきか」を判断するために使います。具体的なシナリオを複数書いておくと、適切なタイミングで自動的に呼び出されます。

Tip 2: ハマりポイントを必ず書く

実際の運用で発見したトラブルはSKILL.mdに記録しておきましょう。

## ⚠️ 注意事項

- `load_dotenv()` をheredoc実行時に引数なしで使うとクラッシュする
  → `load_dotenv(".env")` と明示的にパスを渡すこと
- `.env` の変数はBashのサブシェル内で展開すること
  → `bash -c 'set -a; source .env; ...'` パターンを使う
- curlのレスポンスは必ずパイプでpython3に渡してJSONパースすること
  → 直接シェル変数に代入すると文字化けする場合がある

Tip 3: スクリプトをスキルと同じディレクトリに置く

.claude/skills/search-console/
├── SKILL.md
├── search_console.py      ← スキルが使うスクリプト
├── batch_index_check.py   ← 関連スクリプト
└── README_for_debugging.md  ← デバッグ用メモ(任意)

スキルが依存するスクリプトをSKILL.mdと同じディレクトリに置くと、パスの管理が楽になります。スキルを別プロジェクトに移植するときも、ディレクトリごとコピーするだけで済みます。

Tip 4: プロジェクトごとに.claude/を分ける

Agent Skillsはプロジェクトルートの.claude/skills/から読み込まれます。プロジェクトAのスキルがプロジェクトBに影響することはありません。

ただし、~/.claude/skills/(ホームディレクトリ直下)に置いたスキルはすべてのプロジェクトで使えるグローバルスキルになります。「git-commit」のような汎用スキルはグローバルに、「notion-tasks」のようなプロジェクト固有スキルはローカルに置くのがおすすめです。

Tip 5: gitで管理してチームと共有する

# .claude/ ディレクトリをgitで管理
git add .claude/skills/
git commit -m "feat(skills): Add WordPress update-post skill"

# チームメンバーはgit pullするだけで同じスキルが使える

SKILL.mdはMarkdownなので、gitの差分管理・レビューが簡単です。「このスキルのdescriptionをこう直したほうが精度が上がる」といったノウハウもPRで共有できます。

Tip 6: スキルのバージョン管理

スキルが動作しなくなったときのためにバックアップを取る習慣をつけましょう。

# スキルのスナップショットを残す
cp .claude/skills/update-post/SKILL.md .claude/skills/update-post/SKILL.md.bak

# Gitタグでバージョン管理
git tag -a v1.0-skills -m "Working skill set as of 2026-04"

よくある質問

Q: Agent Skillsは有料プランのみ使えますか?

A: Claude Code自体の料金プランに依存します。Claude Codeが使えるプランであれば、Agent Skillsも追加料金なしで使用できます。

Q: SKILL.mdのファイル名は変えられますか?

A: いいえ。現時点ではSKILL.mdという固定ファイル名が必要です。skill.md(小文字)は認識されません。

Q: スキル数に上限はありますか?

A: 公式ドキュメントに明記された上限はありませんが、スキル数が増えるとClaude Codeがスキルを選択する際の精度に影響する可能性があります。実運用では20〜30スキル程度が安定動作することを確認しています。

Q: SKILL.mdにコードブロックを書くと動きが変わりますか?

A: コードブロック内のコードは「参考として提示されたもの」として扱われ、自動実行はされません。「このコマンドを実行する」という文章があった場合に、Claude Codeがそのコマンドを実行します。

Q: 日本語のSKILL.mdは英語より精度が低いですか?

A: Claude Sonnet/Opusであれば日本語でも十分な精度が出ます。ただし、nameフィールドの値は英数字にすることを推奨します(スラッシュコマンドとして使うため)。


トラブルシュート

症状 原因 解決策
スキルが呼び出されない descriptionが曖昧 「〜するとき」の形式で具体的なシナリオを書く
SKILL.mdの内容が無視される ファイルが読み込まれていない .claude/skills/<name>/SKILL.mdの配置を確認
スクリプトが見つからない パスが間違っている SKILL.md内のパスをプロジェクトルートからの相対パスで書く
環境変数が読み込まれない load_dotenv()の引数なし load_dotenv(".env")と明示的にパスを指定
毎回手順を忘れる SKILL.mdに書いていない ハマった手順は即SKILL.mdに追記する
日本語で呼び出せない descriptionの日本語シナリオが不足 descriptionに「〜するとき」の形式で日本語シナリオを追加する
スキルが古い内容で動く キャッシュの問題 Claude Codeを再起動して再試行する

まとめ

Agent Skillsは「Claude Codeを使いこなしている人の暗黙知」をチーム全体の資産に変える仕組みです。

このガイドで作成した3つのスキルを振り返ると、共通して言えることがあります。MCPのように外部サーバーを立てず、Pythonのコードを書かなくても、「何をする手順か」をMarkdownで書くだけでClaude Codeがその通りに動きます。

特に効果が大きいのは、「毎回説明しないといけないこと」を持っているチームです。.envの変数名、スクリプトのパス、APIの使い方——こういった情報は今まで誰かの頭の中か、Confluenceのどこか深いページに眠っていました。SKILL.mdに書くことで、Claude Codeが毎回正しい方法で実行します。

今日から始めるAgent Skills 3ステップ

  1. 今すぐ試す: git-commitスキルを40行のMarkdownで作る
  2. 1週間後: チームで共有したい手順をSKILL.mdに書き起こす
  3. 1ヶ月後: スキル間の連携(オーケストレーター型)で複雑なワークフローを自動化する

今日試すなら git-commit スキルが最速です。40行のMarkdownで作れて、翌日から毎回のコミット作業が変わります。


関連記事

未分類

Posted by GENDOSU