LoginSignup
7
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Day 21

and factory.inc Advent Calendar 2025

@nqnq

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

Last updated at Posted at 2025-12-20

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を作成する際の重要なポイント:

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

7
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
7
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?