creating-agent-skills

エージェントスキルの作成

このスキルでは、Anthropic の公式仕様に沿って、効果的な Claude Code スキルを作成する方法を説明します。

基本原則

1. スキルはプロンプトです

プロンプト作成のベストプラクティスはすべて適用されます。明確に、直接的に記述してください。Claude は賢いものと想定し、Claude が知らない情報だけを追加してください。

2. 標準的な Markdown 形式

YAML フロントマターと Markdown の本文を使用します。XML タグは使わず、標準的な Markdown の見出しを使ってください。

---
name: my-skill-name
description: What it does and when to use it
---

# My Skill Name

## Quick Start
Immediate actionable guidance...

## Instructions
Step-by-step procedures...

## Examples
Concrete usage examples...

3. 段階的な開示

SKILL.md は 500 行未満にしてください。詳細な内容は参照ファイルに分割します。必要なものだけを読み込みます。

my-skill/
├── SKILL.md              # Entry point (required)
├── reference.md          # Detailed docs (loaded when needed)
├── examples.md           # Usage examples
└── scripts/              # Utility scripts (executed, not loaded)

4. 効果的な説明

description フィールドによってスキルが見つけやすくなります。スキルが何をするのか、そしていつ使うのかの両方を含めてください。三人称で記述します。

良い例：

description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

悪い例：

description: Helps with documents

スキルの構成

必須のフロントマター

フィールド	必須	最大長	説明
name	はい	64 文字	小文字のアルファベット、数字、ハイフンのみ
description	はい	1024 文字	何をするのか、いつ使うのか
allowed-tools	いいえ	-	Claude が確認せずに使用できるツール
model	いいえ	-	使用する特定のモデル

命名規則

スキル名には動名詞形（動詞＋-ing）を使います。

• processing-pdfs
• analyzing-spreadsheets
• generating-commit-messages
• reviewing-code

避ける名前：helper、utils、tools、anthropic-*、claude-*

本文の構成

標準的な Markdown の見出しを使います。

# Skill Name

## Quick Start
Fastest path to value...

## Instructions
Core guidance Claude follows...

## Examples
Input/output pairs showing expected behavior...

## Advanced Features
Additional capabilities (link to reference files)...

## Guidelines
Rules and constraints...

何をしますか？

1. 新しいスキルを作成する - ゼロから作成します
2. 既存のスキルを監査する - ベストプラクティスに照らして確認します
3. コンポーネントを追加する - ワークフロー、参照資料、例を追加します
4. ガイダンスを受ける - スキル設計について理解します

新しいスキルの作成

ステップ 1：種類を選ぶ

シンプルなスキル（単一ファイル）：

• 500 行未満
• 自己完結したガイダンス
• 複雑なワークフローなし

段階的に開示するスキル（複数ファイル）：

• SKILL.md を概要として使用
• 詳細なドキュメント用の参照ファイル
• ユーティリティ用のスクリプト

ステップ 2：SKILL.md を作成する

---
name: your-skill-name
description: [What it does]. Use when [trigger conditions].
---

# Your Skill Name

## Quick Start

[Immediate actionable example]

```[language]
[Code example]

指示

[基本的なガイダンス]

例

例 1： 入力：[説明] 出力：

[result]

ガイドライン

• [制約 1]
• [制約 2]

### Step 3: Add Reference Files (If Needed)

Link from SKILL.md to detailed content:

```markdown
For API reference, see [REFERENCE.md](REFERENCE.md).
For form filling guide, see [FORMS.md](FORMS.md).

参照ファイルは SKILL.md から1 階層以内に配置してください。

ステップ 4：スクリプトを追加する（必要な場合）

スクリプトはコンテキストに読み込まずに実行できます。

## Utility Scripts

Extract fields:
```bash
python scripts/analyze.py input.pdf > fields.json

### Step 5: Test With Real Usage

1. Test with actual tasks, not test scenarios
2. Observe where Claude struggles
3. Refine based on real behavior
4. Test with Haiku, Sonnet, and Opus

## Auditing Existing Skills

Check against this rubric:

- [ ] Valid YAML frontmatter (name + description)
- [ ] Description includes trigger keywords
- [ ] Uses standard markdown headings (not XML tags)
- [ ] SKILL.md under 500 lines
- [ ] References one level deep
- [ ] Examples are concrete, not abstract
- [ ] Consistent terminology
- [ ] No time-sensitive information
- [ ] Scripts handle errors explicitly

## Common Patterns

### Template Pattern

Provide output templates for consistent results:

```markdown
## Report Template

```markdown
# [Analysis Title]

## Executive Summary
[One paragraph overview]

## Key Findings
- Finding 1
- Finding 2

## Recommendations
1. [Action item]
2. [Action item]

### Workflow Pattern

For complex multi-step tasks:

```markdown
## Migration Workflow

Copy this checklist:

• ステップ 1：データベースをバックアップする
• ステップ 2：移行スクリプトを実行する
• ステップ 3：出力を検証する
• ステップ 4：設定を更新する

**Step 1: Backup database**
Run: `./scripts/backup.sh`
...

条件分岐のパターン

判断が必要なポイントを順に案内します。

## Choose Your Approach

**Creating new content?** Follow "Creation workflow" below.
**Editing existing?** Follow "Editing workflow" below.

避けるべきアンチパターン

• 本文で XML タグを使う - 代わりに Markdown の見出しを使います
• 曖昧な説明 - トリガーとなるキーワードを具体的にします
• 深い入れ子構造 - 参照ファイルは SKILL.md から 1 階層以内に配置します
• 選択肢が多すぎる - 既定の方法を示し、必要に応じて別の方法を選べるようにします
• Windows のパス - 常にスラッシュを使います
• Claude に丸投げする - スクリプト側でエラーを処理します
• 時間とともに変わる情報 - 代わりに「古いパターン」セクションを使います

参照ファイル

詳細なガイダンスについては、次を参照してください。

• official-spec.md - Anthropic の公式スキル仕様
• best-practices.md - スキル作成のベストプラクティス

成功基準

適切に構成されたスキルには、次の要素があります。

• 説明的な名前と description を含む、有効な YAML フロントマターがある
• 標準的な Markdown の見出しを使っている（XML タグではない）
• SKILL.md が 500 行未満である
• 詳細な内容について参照ファイルにリンクしている
• 入力と出力の組み合わせを含む具体例がある
• 実際の使用でテストされている

出典：

• Agent Skills - Claude Code Docs
• Skill authoring best practices
• GitHub - anthropics/skills