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

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

コア原則

1. スキルはプロンプト

すべてのプロンプト作成のベストプラクティスが適用されます。明確に、直接的に説明してください。Claudeは十分に優秀であると仮定し、Claudeが持たないコンテキストのみを追加します。

2. 標準的なMarkdown形式

YAML frontmatterと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              # エントリーポイント（必須）
├── reference.md          # 詳細ドキュメント（必要時に読み込み）
├── examples.md           # 使用例
└── scripts/              # ユーティリティスクリプト（読み込みではなく実行）

4. 効果的な説明

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

良い例:

description: PDFファイルからテキストと表を抽出し、フォームに入力し、ドキュメントをマージします。PDFファイルを操作する場合、またはユーザーがPDF、フォーム、ドキュメント抽出について言及した場合に使用します。

悪い例:

description: ドキュメントに関するヘルプを提供

スキル構造

必須のFrontmatter

フィールド	必須	最大長	説明
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
最速で価値を提供するパス...

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

## Examples
期待される動作を示すインプット/アウトプットペア...

## Advanced Features
追加機能（参照ファイルへのリンク）...

## Guidelines
ルールと制約...

何をしたいですか？

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

新規スキルの作成

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

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

• 500行以下
• スタンドアロンのガイダンス
• 複雑なワークフローなし

段階的な情報開示スキル（複数ファイル）:

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

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

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

# Your Skill Name

## Quick Start

[即座に実行可能な例]

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

Instructions

[コアガイダンス]

Examples

例1: Input: [説明] Output:

[結果]

Guidelines

• [制約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 frontmatter（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`
...

条件付きパターン

決定ポイントをガイドします：

## アプローチを選択

**新しいコンテンツを作成していますか？** 下の「Creation workflow」に従ってください。
**既存のものを編集していますか？** 下の「Editing workflow」に従ってください。

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

• ボディ内のXMLタグ - markdownの見出しを代わりに使用
• 曖昧な説明 - トリガーキーワードで具体的に
• 深いネスト - SKILL.mdから1レベルの参照に保つ
• オプションが多すぎる - デフォルトを提供し、エスケープハッチを用意
• Windowsパス - 常にフォワードスラッシュを使用
• Claudeに任せる - スクリプトはエラーを処理すべき
• 時間に依存する情報 - 代わりに「old patterns」セクションを使用

参照ファイル

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

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

文体

.claude/rules/prose-style.mdのcaveman-lite文体ルール（正規のソース）を適用してください。

成功の基準

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

• 説明的なnameとdescriptionを持つ有効なYAML frontmatterがある
• 標準的なmarkdown見出しを使用している（XMLタグなし）
• SKILL.mdを500行以下に保っている
• 詳細なコンテンツの参照ファイルにリンクしている
• インプット/アウトプットペアを含む具体的な例を含んでいる
• 実際の使用でテストされている

ソース：

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