Agent Skills導入とベストプラクティス

この記事はand factory.inc Advent Calendar 2025 21日目の記事です。
前回の記事は @doihei さんのGitHub Projectsで複数のプロジェクトタスク管理でした

はじめに

Claude CodeのAgent Skillsを使うと、Claude に専門知識や独自のワークフローを追加できます。

この記事では、Agent Skillsの基本的な概念から導入方法、そしてAnthropic公式のAgent Skills Best Practicesに基づいたベストプラクティスをまとめました。

Agent Skillsとは

Agent Skillsは、Claude にプロジェクト固有の知識や手順を追加する機能です。

どんな時に使う？

社内のコーディング規約を共有したい
特定の技術スタックのベストプラクティスを伝えたい
複雑なワークフローを定義したい
ドメイン固有の制約や要件を教えたい

何ができる？

Agent Skillsを追加することで、Claude は:

プロジェクト固有の知識を参照できる
定義されたワークフローに従って作業できる
ドメイン固有の制約を考慮した提案ができる

Agent Skillsの導入方法

ファイル構造

Agent Skillsは、プロジェクトの.claude/skills/ディレクトリに配置します。

your-project/
└── .claude/
    └── skills/
        └── my-skill/
            ├── SKILL.md
            └── process_data.py  # オプション: スクリプトも含められる

Agent Skillsには、SKILL.mdだけでなく、実行可能なスクリプトも含めることができます。

事前に用意されたスクリプトは、Claude がコードを毎回生成するより信頼性が高く、トークンも節約できます。

基本的なSKILL.mdの構造

---
name: my-skill
description: このSkillの説明。何をするか、いつ使うかを明記します。
---

# My Skill

## 概要
このSkillが提供する知識や手順の概要

## 詳細
具体的な内容...

nameとdescriptionの書き方

name（動名詞形を推奨）:

name: processing-pdfs      # ○ 何をするか分かる
name: analyzing-data       # ○ 何をするか分かる
name: pdf-helper          # △ 動作が不明確
name: utils               # × 曖昧すぎる

description（「何を」「いつ」を明記）:

# 良い例
description: PDFファイルからテキストとテーブルを抽出します。PDFを扱う場合に使用してください。

# 悪い例
description: PDFを処理します。

descriptionには、何をするかといつ使うかの両方を書きましょう。

Skillの使い方

Skillを.claude/skills/に配置すると、Claude が自動的に認識して使用します。明示的に呼び出す必要はありません。

スクリプトを含める場合

Agent Skillsにスクリプトを含める場合は、SKILL.mdで明確に指示します:

## データ処理スクリプト

`process_data.py`を実行して、CSVファイルを処理します。

### 実行方法
\```bash
python process_data.py input.csv output.json
\```

### 必要なパッケージ
- pandas>=2.0.0
- numpy>=1.24.0

ポイント:

実行方法を明記: Claude がスクリプトを実行すべきか、参照として読むべきか明確にする
依存関係を記載: 必要なパッケージとバージョンをリストアップ
パスは前方スラッシュ: クロスプラットフォーム対応のため/を使用

Agent Skillsのベストプラクティス

ここからは、高品質なAgent Skillsを作成するための8つのベストプラクティスを紹介します。各項目はAnthropic公式のBest Practicesに基づいています。

1. 「Claude は既に賢い」原則

出典: Concise is key

最も重要な原則: Claude は既に膨大な知識を持っています。一般的な知識を書いても、コンテキストの無駄です。

避けるべき例:

## Reactとは
Reactは、Facebookが開発したJavaScriptライブラリです。
コンポーネントベースのUI構築が可能で...

Claude はこれを知っています。

推奨される例:

## 社内Reactコンポーネントの規約

### 状態管理
- Zustandを使用（Reduxは使用禁止）
- グローバル状態は`src/stores/`に配置

### Props設計
- 必須propsは最小限に（3つ以内を推奨）
- booleanプロパティは`is`/`has`プレフィックス

Claude が知らない具体的な情報だけを書きましょう。

2. SKILL.mdのサイズ管理

出典: Token budgets

SKILL.md本体は500行以内が目安です。

行数	評価	対応
0-500行	◎	理想的
501-750行	○	分割を検討
751-1000行	△	分割推奨
1000行超	×	分割必須

理由: コンテキストウィンドウは、システムプロンプト、会話履歴、他のSkillsと共有されています。長すぎると、必要な情報が入らなくなります。

3. プログレッシブディスクロージャー

出典: Progressive disclosure patterns

必要になるまで詳細を読み込まない設計にしましょう。

推奨される構造:

my-skill/
├── SKILL.md (概要、200行)
├── API_GUIDELINES.md (API設計の詳細、300行)
├── EXAMPLES.md (実装例、150行)
└── TROUBLESHOOTING.md (トラブルシューティング、100行)

SKILL.mdは「目次」として機能し、詳細は別ファイルに。Claude は必要に応じてファイルを読み込みます。

避けるべき構造:

my-skill/
└── SKILL.md (全部詰め込み、1500行)

4. ファイル参照のルール

出典: Avoid deeply nested references

深さは1レベルまで: SKILL.mdから直接参照
説明的なファイル名: doc2.md → form_validation_rules.md
100行超えたら目次を含める: Claude がhead -100で全体像を把握可能
パスはフォワードスラッシュ: folder/file.md

悪い例（深すぎるネスト）:

my-skill/
├── SKILL.md
├── guides/
│   ├── advanced/
│   │   └── details/
│   │       └── reference.md  # 深すぎる

5. ワークフローはチェックリスト形式で

出典: Use workflows for complex tasks

複雑なタスクは、ステップを明確にします。

## データ移行ワークフロー

### ステップ1: 計画作成
- [ ] スキーマを分析
- [ ] `migration_plan.json`を生成
- [ ] バリデーターで検証

### ステップ2: プレビュー実行
- [ ] 最初の10件を移行
- [ ] 結果をユーザーに確認
- [ ] 問題があれば計画を修正

### ステップ3: 本番実行
- [ ] ユーザーの承認を取得
- [ ] 全件を移行
- [ ] エラーログを確認

### ステップ4: 検証
- [ ] 移行後のデータ件数を確認
- [ ] サンプルデータの整合性チェック
- [ ] 完了レポートを生成

チェックリスト形式にすることで、Claude が進捗を追跡しやすくなります。

6. エラーハンドリングを明示的に

出典: Solve, don't punt

Skillにコードやスクリプトを含める場合、エラーハンドリングを明示的に書きます。

避けるべき例:

def process_file(path):
    # TODO: エラーハンドリング追加
    return open(path).read()

推奨される例:

def process_file(path: str) -> str:
    """ファイルを安全に読み込む

    Args:
        path: 読み込むファイルのパス

    Returns:
        ファイルの内容

    Raises:
        ValueError: ファイルが見つからない、またはエンコーディングエラー
    """
    try:
        with open(path, 'r', encoding='utf-8') as f:
            return f.read()
    except FileNotFoundError:
        raise ValueError(f"ファイルが見つかりません: {path}")
    except UnicodeDecodeError:
        raise ValueError(f"ファイルのエンコーディングが無効です: {path}")

7. マジックナンバーの排除

出典: Solve, don't punt

すべての定数に、理由とソースを添えましょう。

避けるべき例:

MAX_SIZE = 1000000

推奨される例:

# BigQueryのクエリ結果の最大サイズ制限（1MB）
# 参照: https://cloud.google.com/bigquery/quotas#query_jobs
MAX_QUERY_RESULT_SIZE = 1_000_000

8. 用語の一貫性

出典: Use consistent terminology

1つの概念には1つの用語を使います。

悪い例:

## データベース接続

最初にDBに接続します。
次に、データストアからレコードを取得します。
最後に、永続化層との接続を閉じます。

「DB」「データストア」「永続化層」が同じデータベースを指していますが、用語がバラバラです。

良い例:

## データベース接続

最初にデータベースに接続します。
次に、データベースからレコードを取得します。
最後に、データベース接続を閉じます。

ベストプラクティスまとめ

Agent Skillsを作成する際の重要なポイント:

「Claude は既に賢い」原則: 一般知識は書かず、ドメイン固有の情報だけ
SKILL.mdは500行以内: 長すぎたら分割
プログレッシブディスクロージャー: 必要な時だけ詳細を読み込む
ファイル参照は1レベルまで: 深いネストを避ける
チェックリスト形式のワークフロー: 進捗を追跡可能に
エラーハンドリング明示: TODOで済ませない
マジックナンバーの排除: すべての定数に理由とソースを
用語の一貫性: 概念ごとに1つの用語

おまけ: Agent Skillsを自動レビューするSkill

これらのベストプラクティスを自動的にレビューしてくれるAgent Skillを作成しました。
よかったら作ってみたSkillに対してレビューさせてみてください。
https://github.com/low2xxx/claude-code-settings

使い方は上記リポジトリの

.claude/skills/reviewing-agent-skills/

をご自身の環境に持ってきて、

  reviewing-agent-skills を使って .claude/skills/xxxx/ をレビューして

とやるとSkill使ってレビューしてくれます。

最後に

Agent Skillsの導入方法とベストプラクティスを紹介しました。

これらを意識することで、効果的なAgent Skillsを作成できます。