💡

Claude Code の Agent Skills って？

に公開
tech

Agent Skillsとは

Claude Code で何度も同じプロンプトを書くのが面倒で、カスラムスラッシュコマンドやagentsは使っていたのですが、

最近新しく出た Agent Skills でより効率化できそうな気がしたので、調べてみました!

基本概念

Agent Skillsは、Claude Codeに専門知識やタスクを教え込むための仕組みで、簡単に言うと、.claude/skills/ディレクトリに専門知識をまとめておくことで、Claudeが必要に応じて自動的にその知識を活用してくれる、というものみたいです。

基本的な特徴：

  • Claude Codeが使える専門知識を.claude/skills/にまとめたもの
  • 実行してほしいスクリプトも定義できる
  • Claudeが状況を判断して自動的に使ってくれる

Agent Skillsのメリット

メリットとしては、

🎯 専門特化

Claudeを特定の分野に特化させることができます。たとえば、PDF処理の専門家やAPIテストの専門家のように、特定の作業に強いアシスタントに変身させられます。

⏰ 効率化

一度作ってしまえば、何度も同じプロンプトを入力する必要がなくなります。「いつものテストを実行して」と言うだけで、複雑なコマンドを自動実行してくれます。

🤝 チーム連携

チームで専門知識を共有できるため、誰でも同じレベルの作業ができるようになります。

🔧 組み合わせ効果

複数のSkillsを組み合わせて、より複雑なタスクも自動化できます。

プロンプトの再利用はそうとして、専門分野に特化している、というのがSkillsの特徴なようです！

他との違いは?

これだけだと、いまいちカスタムスラッシュコマンド等との違いがわからなかったので調べてみました。

カスタムコマンドとの違い

公式ドキュメントによると：

Skillsの呼び出し方法: Skillsはモデル呼び出しです—Claudeはあなたのリクエストとスキルの説明に基づいて、いつ使用するかを自律的に決定します。これはユーザー呼び出しのスラッシュコマンド（明示的に/commandと入力してトリガーする）とは異なります。

  • カスタムコマンド: ユーザーが/pr-reviewのように明示的に入力して使う
  • Agent Skills: Claudeが状況を判断して自動的に使うかどうか決める

カスタムコマンドと違い、ユーザが明示的にコマンド入力しなくても、文脈から判断して勝手に参照・使ってくれるのは便利そうです！

CLAUDE.mdとの使い分け

勝手に使ってくれるならCLAUDE.mdも同じじゃ？と思ったので、ここも違いを調べてみました。

この2つは役割が違います：

項目 CLAUDE.md Agent Skills
目的 プロジェクト全体のコンテキスト提供 特定タスクの自動化
内容 方針、アーキテクチャ、コーディング規約 専門知識、実行スクリプト
イメージ プロジェクトの説明書 自動化ツールキット

使い分けの目安：

  • CLAUDE.md: 「このプロジェクトはこんな方針で作られています」
  • Agent Skills: 「このタスクはこの手順で自動実行します」

この区別に気づくまでに少し時間がかかりましたが、「CLAUDE.md」→「全体の設計思想を伝えるもの」で、「Agent Skills」→「特定分野の知識、具体的な作業を自動化するもの」、という違いと考えておくと分かりやすそうです。

実装パターンと具体例

じゃあ実際にはどうするの？となったので、いくつか実装例見てみました。

パターン1: シンプルなガイドライン提供

使用場面: スクリプト不要で、文書だけで完結する専門知識

ディレクトリ構成：

.claude/skills/coding-style/
└── SKILL.md

SKILL.mdの内容例：

---
name: coding-style
description: プロジェクトのコーディングスタイルガイドを提供します。コード生成時に自動的に参照されます。
---

## Guidelines
- 変数名はsnake_caseを使う
- 関数には必ずdocstringを書く
- 1行は80文字以内に抑える
- import文はアルファベット順に並べる

## Examples
良い例：
```python
def calculate_user_age(birth_date: str) -> int:
    """ユーザーの年齢を計算します。

    Args:
        birth_date: 生年月日（YYYY-MM-DD形式）

    Returns:
        計算された年齢
    """
    # 実装...

悪い例：
def calcAge(birthDate):
    # 実装...

効果: Claudeがコードを生成する際、自動的にこのスタイルガイドに従ってくれます。

確かに、Claudeのコーディング「スキル」として書いておけばいいんですね。都度指示しなくても、コーディング時に勝手に参照してくれるなら便利そうです。

パターン2: 複合ドキュメント参照

使用場面: 専門知識が複雑で、複数のドキュメントに分けて整理したい場合

ディレクトリ構成：

.claude/skills/api-integration/
├── 
SKILL.md

├── 
authentication.md

├── 
endpoints.md

└── 
error-handling.md

SKILL.mdの内容例：

---
name: api-integration
description: API連携のコードを書く際や、API関連のトラブルシューティングが必要な時に使用します。外部API連携のベストプラクティスを提供します。認証、エンドポイント使用法、エラーハンドリングの専門知識を含みます。

---

## References
- [認証方法](./authentication.md)
- [エンドポイント一覧](./endpoints.md)
- [エラーハンドリング](./error-handling.md)

効果: Claudeが必要に応じて関連ドキュメントを読んで、適切な実装方法を判断してくれます。

こうやって、skill配下の同ディレクトリに複数ドキュメント分割、一つのskillから参照させるのもできるんですね~ (skillの「専門分野」の粒度はそう考えると思ったより広そう？)

パターン3: スクリプト実行付き

使用場面: 定型処理を自動化したい場合

ディレクトリ構成：

.claude/skills/test-runner/
├── SKILL.md
└── run_tests.sh

SKILL.mdの内容例：

---
name: test-runner
description: プロジェクトのテストを実行します。「テストを実行して」と言われたら自動的に使用します。
---

## Usage
`./run_tests.sh`を実行することで、全テストを実行できます。

## Scripts
- `run_tests.sh`: 全テストの実行

run_tests.shの内容例：

#!/bin/bash
echo "テストを開始します..."
python -m pytest tests/ -v --coverage
echo "テストが完了しました。"

効果: 「テストを実行して」と言うだけで、Claudeが自動的にスクリプトを実行してくれます。

スクリプト実行機能もあるのは良さそうです！まだ試せてないですが、だいぶ作業効率化できそうな気がします。

成功するSkillsを作るポイント

Skills実際に作るにあたり、公式がベストプラクティス出してくれていたのでまとめてみました。

単一責任の原則を守る

良い例：

  • pdf-extractor: PDFからテキスト抽出だけに特化
  • test-runner: テスト実行だけに特化
  • api-client: 特定のAPI連携だけに特化

悪い例：

  • document-processor: PDF、Word、Excel、PowerPoint全対応を目指す
  • dev-tools: テスト、ビルド、デプロイ、ドキュメント生成を全部やろうとする

理由: 一つのSkillで複数のことをやろうとすると、Claudeが「いつ使えばいいか」混乱してしまいます。

確かに、実装と同じことがskillsにも言えるんですね。

descriptionは具体的に書く

ClaudeがそのSkillをいつ使えばいいか判断できるよう、以下の3点を明確に書きましょう：

  1. 何をするのか（What）
  2. どうやってやるのか（How）
  3. いつ使うのか（When）

良い例：

description: pdfplumberを使ってPDFファイルからテキストとテーブルを抽出し、分析可能な形式に変換します。
PDFの内容を読み取りたい時や、データ抽出が必要な時に使用します。

悪い例：

description: PDFを処理します。

descriptionの書き方は確かに悩みました。最初は簡潔に書けばいいと思っていましたが、それだとClaudeが全然使ってくれなかったので、Claudeが使い所を判断できるよう思ったより具体的に書く必要があるみたいです。

よくある失敗パターンと対策

アンチパターンも、同じく公式が出していたので見てみました。

失敗パターン1: descriptionが曖昧

❌ ダメな例: 「ドキュメント処理」
✅ 良い例: 「PDFからテキストとテーブルを抽出して分析用データに変換」

対策: 具体的なファイル形式、処理内容、期待される結果を明記する

失敗パターン2: 主語が混乱している

公式でも注意喚起されているポイントです。

❌ ダメな例: 「あなたはこのスキルをPDF処理に使うことができます」
✅ 良い例: 「PDF処理を実行する」

理由: Skillのdescriptionは、Claude自身が参照するドキュメントなので、「あなた」という表現は混乱を招きます。

失敗パターン3: ツールの選択肢が多すぎる

❌ ダメな例: 「pdf2image、PyMuPDF、pdfplumber、pypdfなどを使えます」
✅ 良い例: 「pdfplumberを使ってPDFからテキスト抽出します」

対策: チームで推奨するツールを一つ選んで、それに統一する

失敗パターン2の「主語の混乱」は、私も最初にハマりました。人間向けのドキュメントを書く感覚でSkillを作ると、Claudeが混乱してしまうんですね。Claude自身が読むものだという視点が重要だと気づきました。

まとめ

以下Skillsのまとめです。

核となる理解（3つのポイント）

  1. Agent Skillsは自動化の鍵: 一度設定すれば、Claudeが自動的に専門知識を活用
  2. 単一責任の原則: 一つのSkillは一つのことに集中
  3. 具体的な説明が重要: descriptionには「何を・どうやって・いつ」を明確に記載

今日から始められること

  • まずは小さなSkillから作ってみる（例：コーディングスタイルガイド）
  • チームでよく使う処理をSkills化して共有する
  • 複雑な処理は複数のSkillsに分割して整理する

さらに学ぶべき領域

最初はカスラムスラッシュコマンド、agentsとの違いがイマイチわからず、設定もよくわからなかった (全然使ってくれない) だったのですが、一度作ってみると便利だなと思いました！

あと、これまでagentsに書いていた専門知識部分を、skillsに切り出しして整理できる、というメリットもあるかなと思いました。

まずは小さく始めて、徐々に拡張・育ててみようかなと思います！

参考資料

GitHubで編集を提案

Discussion