creating-agent-skills

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

このスキルは、Anthropicの公式仕様に従った効果的なClaude Code スキルの作成方法を教えます。

コア原則

1. スキルはプロンプト

すべてのプロンプティングベストプラクティスが適用されます。明確に、直接的に。Claudeは賢いと仮定し、Claudeが持っていないコンテキストのみを追加します。

2. 標準Markdownフォーマット

YAMLフロントマター + Markdownボディを使用します。XMLタグは使用しない - 標準Markdownの見出しを使用します。

---
name: my-skill-name
description: 何をするか、いつ使用するか
---

# マイスキル名

## クイックスタート
すぐに実行可能なガイダンス...

## 手順
ステップバイステップの手順...

## 例
具体的な使用例...

3. 段階的開示

SKILL.mdは500行未満に保ちます。詳細なコンテンツはリファレンスファイルに分割します。必要なものだけを読み込みます。

my-skill/
├── SKILL.md              # エントリーポイント（必須）
├── reference.md          # 詳細ドキュメント（必要に応じて読み込み）
├── examples.md           # 使用例
└── scripts/              # ユーティリティスクリプト（実行されるが読み込まれない）

4. 効果的な説明

description フィールドはスキルの発見を可能にします。スキルが何をするかとそれをいつ使用するかの両方を含めます。三人称で記述します。

良い例：

description: PDFファイルからテキストとテーブルを抽出し、フォームを埋め、ドキュメントをマージします。PDFファイルを扱う場合、またはユーザーがPDF、フォーム、ドキュメント抽出に言及した場合に使用します。

悪い例：

description: ドキュメントのヘルプ

スキル構造

必須フロントマター

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

命名規則

スキル名には 動名詞形（動詞 + -ing）を使用します：

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

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

ボディ構造

標準Markdownの見出しを使用します：

# スキル名

## クイックスタート
最速の価値提供パス...

## 手順
Claudeが従うコアガイダンス...

## 例
期待される動作を示す入出力ペア...

## 高度な機能
追加機能（リファレンスファイルへのリンク）...

## ガイドライン
ルールと制約...

何をしたいですか？

1. 新しいスキルを作成 - ゼロから構築
2. 既存のスキルを監査 - ベストプラクティスに対してチェック
3. コンポーネントを追加 - ワークフロー/リファレンス/例を追加
4. ガイダンスを取得 - スキル設計を理解

新しいスキルの作成

ステップ1：タイプを選択

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

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

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

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

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

---
name: your-skill-name
description: [何をするか]。[トリガー条件]の場合に使用します。
---

# あなたのスキル名

## クイックスタート

[すぐに実行可能な例]

```[language]
[コード例]

手順

[コアガイダンス]

例

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

[結果]

ガイドライン

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

### ステップ3：リファレンスファイルを追加（必要に応じて）

SKILL.mdから詳細コンテンツへリンク：

```markdown
API リファレンスについては、[REFERENCE.md](REFERENCE.md)を参照してください。
フォーム入力ガイドについては、[FORMS.md](FORMS.md)を参照してください。

リファレンスはSKILL.mdから1階層までに保ちます。

ステップ4：スクリプトを追加（必要に応じて）

スクリプトはコンテキストに読み込まれずに実行されます：

## ユーティリティスクリプト

フィールドを抽出：
```bash
python scripts/analyze.py input.pdf > fields.json

### ステップ5：実際の使用でテスト

1. テストシナリオではなく、実際のタスクでテスト
2. Claudeが苦労する場所を観察
3. 実際の動作に基づいて改善
4. Haiku、Sonnet、Opusでテスト

## 既存スキルの監査

この評価基準に対してチェック：

- [ ] 有効なYAMLフロントマター（name + description）
- [ ] descriptionにトリガーキーワードを含む
- [ ] 標準Markdownの見出しを使用（XMLタグではない）
- [ ] SKILL.mdが500行未満
- [ ] リファレンスは1階層まで
- [ ] 例は抽象的ではなく具体的
- [ ] 一貫した用語
- [ ] 時間に依存する情報なし
- [ ] スクリプトは明示的にエラーを処理

## 共通パターン

### テンプレートパターン

一貫した結果のために出力テンプレートを提供：

```markdown
## レポートテンプレート

```markdown
# [分析タイトル]

## エグゼクティブサマリー
[1段落の概要]

## 主な発見
- 発見1
- 発見2

## 推奨事項
1. [アクションアイテム]
2. [アクションアイテム]

### ワークフローパターン

複雑な複数ステップのタスク用：

```markdown
## マイグレーションワークフロー

このチェックリストをコピー：

• ステップ1：データベースのバックアップ
• ステップ2：マイグレーションスクリプトを実行
• ステップ3：出力を検証
• ステップ4：設定を更新

**ステップ1：データベースのバックアップ**
実行：`./scripts/backup.sh`
...

条件パターン

決定ポイントをガイド：

## アプローチを選択

**新しいコンテンツを作成？** 以下の「作成ワークフロー」に従います。
**既存を編集？** 以下の「編集ワークフロー」に従います。

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

• ボディ内のXMLタグ - 代わりにMarkdownの見出しを使用
• 曖昧な説明 - トリガーキーワードで具体的に
• 深いネスト - リファレンスはSKILL.mdから1階層に保つ
• 選択肢が多すぎる - デフォルトと逃げ道を提供
• Windowsパス - 常にスラッシュを使用
• Claudeへの丸投げ - スクリプトはエラーを処理すべき
• 時間に依存する情報 - 代わりに「古いパターン」セクションを使用

リファレンスファイル

詳細なガイダンスについては以下を参照：

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

成功基準

よく構造化されたスキル：

• 説明的なnameとdescriptionを持つ有効なYAMLフロントマター
• 標準Markdownの見出しを使用（XMLタグではない）
• SKILL.mdが500行未満
• 詳細コンテンツ用のリファレンスファイルへのリンク
• 入出力ペアを含む具体的な例
• 実際の使用でテスト済み

出典：

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