# creating-agent-skills

> Claude Code スキルの作成、執筆、洗練に関するエキスパートガイダンス。SKILL.mdファイルでの作業、新しいスキルの作成、既存スキルの改善、またはスキル構造とベストプラクティスの理解に使用します。

- Author: Raku
- Repository: rakutek/compound-engineering-plugin
- Version: 20260120153133
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/rakutek/compound-engineering-plugin
- Web: https://mule.run/skillshub/@@rakutek/compound-engineering-plugin~creating-agent-skills:20260120153133

---

---
name: creating-agent-skills
description: Claude Code スキルの作成、執筆、洗練に関するエキスパートガイダンス。SKILL.mdファイルでの作業、新しいスキルの作成、既存スキルの改善、またはスキル構造とベストプラクティスの理解に使用します。
---

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

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

## コア原則

### 1. スキルはプロンプト

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

### 2. 標準Markdownフォーマット

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

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

# マイスキル名

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

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

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

### 3. 段階的開示

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

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

### 4. 効果的な説明

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

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

**悪い例：**
```yaml
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の見出しを使用します：

```markdown
# スキル名

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

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

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

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

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

## 何をしたいですか？

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

## 新しいスキルの作成

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

**シンプルスキル（単一ファイル）：**
- 500行未満
- 自己完結型ガイダンス
- 複雑なワークフローなし

**段階的開示スキル（複数ファイル）：**
- SKILL.mdを概要として
- 詳細ドキュメント用のリファレンスファイル
- ユーティリティ用のスクリプト

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

```markdown
---
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：スクリプトを追加（必要に応じて）

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

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

フィールドを抽出：
```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`
...
```

### 条件パターン

決定ポイントをガイド：

```markdown
## アプローチを選択

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

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

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

## リファレンスファイル

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

- [official-spec.md](references/official-spec.md) - Anthropicの公式スキル仕様
- [best-practices.md](references/best-practices.md) - スキル作成のベストプラクティス

## 成功基準

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

出典：
- [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [GitHub - anthropics/skills](https://github.com/anthropics/skills)