extension-authoring

このスキルは、Claude Code 拡張機能を作成するための決定版ガイドです。4 種類の拡張機能を扱います。

1. スキル - ドメインの専門知識を提供する、SKILL.md ファイル内のモジュール式の機能
2. フック - ツールの使用時やセッションイベント時に実行される、イベント駆動型の自動化
3. スラッシュコマンド - /command-name 構文で呼び出す、再利用可能なプロンプト
4. サブエージェント - 委任されたタスクを実行する、専門化された Claude インスタンス

4 種類の拡張機能はすべて、純粋な XML 構造、YAML フロントマター、明確な成功基準という基本原則を共有しています。このスキルでは、ベストプラクティスに沿って効果的な拡張機能を作成する方法を学びます。

何を作成、または学びたいですか？

1. スキル - ドメインの専門知識を提供する SKILL.md ファイル
2. フック - イベント駆動型の自動化（PreToolUse、PostToolUse、Stop など）
3. スラッシュコマンド - /command-name で呼び出す再利用可能なプロンプト
4. サブエージェント - 委任されたタスクを実行する専門化されたエージェント
5. ガイダンス - 使用する拡張機能の種類を決めるための支援

番号で回答するか、作成したいものを説明してください。

| 回答 | アクション | |----------|--------| | 1, "skill", "SKILL.md" | [reference/skills.md](reference/skills.md) を読む | | 2, "hook", "hooks" | [reference/hooks.md](reference/hooks.md) を読む | | 3, "command", "slash" | [reference/commands.md](reference/commands.md) を読む | | 4, "subagent", "agent" | [reference/subagents.md](reference/subagents.md) を読む | | 5, "guidance", "help" | 以下の判断ツリーを使用する |

リファレンスを読んだ後は、そのワークフローに正確に従ってください。

<decision_tree> どの種類の拡張機能を使うべきですか？

Is it triggered by specific Claude Code events?
  (tool use, session start/end, user prompt submit)
    YES --> Hook

Is it a reusable prompt the user invokes with /command-name?
    YES --> Slash Command

Is it an isolated task that runs autonomously without user interaction?
    YES --> Subagent

Is it domain knowledge or workflow guidance Claude loads on demand?
    YES --> Skill

簡易判断表：

必要なもの	拡張機能の種類
コマンド実行前の検証	フック（PreToolUse）
編集後のコードの自動フォーマット	フック（PostToolUse）
入力が必要なときのデスクトップ通知	フック（Notification）
再利用可能な git コミットのワークフロー	スラッシュコマンド
コードレビューのチェックリスト	スラッシュコマンド
委任された調査タスク	サブエージェント
自律的なテスト作成	サブエージェント
API 統合の知識	スキル
複数ステップのワークフローガイダンス	スキル
</decision_tree>

<shared_principles> これらの原則は、すべての Claude Code 拡張機能に適用されます。

<xml_structure> 純粋な XML 構造を使用してください。本文の Markdown 見出しはすべて削除してください。

<objective>What it does</objective>
<workflow>How to do it</workflow>
<success_criteria>How to know it worked</success_criteria>

コンテンツ内では Markdown の書式（太字、リスト、コードブロック）を使用できます。

XML を使用する理由

• Claude にとって意味的に明確（見た目だけの書式ではありません）
• セクションの境界が曖昧になりません
• トークン効率に優れています（Markdown 見出しの約 20 トークンに対して約 15 トークン）
• 確実な解析と段階的な開示が可能です </xml_structure>

<yaml_frontmatter> すべての拡張機能に YAML フロントマターが必要です。

---
name: extension-name       # lowercase-with-hyphens
description: What it does and when to use it (third person)
---

名前の規則： create-*、manage-*、setup-*、generate-*

説明のルール：

• 三人称で記述する（「I」や「you」は使わない）
• 何をするのか、いつ使うのかの両方を含める
• 最大 1024 文字 </yaml_frontmatter>

コンテキストウィンドウは共有されています。Claude がすでに知っていることは追加しないでください。

• Claude は賢いものとして扱う
• すべての内容について、「トークンを使う価値があるか」を検討する
• 選択肢を列挙するのではなく、既定の方法と、必要に応じて変更できる手段を提示する
• メインファイルは 500 行未満に保ち、必要に応じてリファレンスファイルに分割する

<success_criteria> すべての拡張機能に、明確な完了基準を定めてください。

<success_criteria>
- Specific measurable outcome 1
- Specific measurable outcome 2
- How to verify it worked
</success_criteria>

</success_criteria> </shared_principles>

<quick_reference> ファイルの配置場所：

拡張機能	プロジェクトの配置場所	ユーザーの配置場所
スキル	.claude/skills/	~/.claude/skills/
フック	.claude/hooks.json	~/.claude/hooks.json
スラッシュコマンド	.claude/commands/	~/.claude/commands/
サブエージェント	.claude/agents/	~/.claude/agents/

最小限の例：

<skill_example>

---
name: process-pdfs
description: Extract text from PDF files. Use when working with PDFs.
---

<objective>Extract text from PDF files using pdfplumber.</objective>

<quick_start>
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

</quick_start>

<success_criteria>エラーなくテキストが抽出されました。</success_criteria>

</skill_example>

<hook_example>
```json
{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

</hook_example>

<command_example>

---
description: Create a git commit
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
---

<objective>Create a git commit for current changes.</objective>

<context>
Current status: ! `git status`
Changes: ! `git diff HEAD`
</context>

<process>
1. Review changes
2. Stage relevant files
3. Create commit following repository conventions
</process>

<success_criteria>Commit created successfully.</success_criteria>

</command_example> <subagent_example>

---
name: code-reviewer
description: Reviews code for quality and security. Use after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

<role>
You are a senior code reviewer focused on quality and security.
</role>

<workflow>
1. Read modified files
2. Identify issues
3. Provide specific feedback with file:line references
</workflow>

<constraints>
- NEVER modify code, only review
- ALWAYS provide actionable feedback
</constraints>

</subagent_example> </quick_reference>

<reference_index> 詳細ガイド：

リファレンス	内容
reference/skills.md	SKILL.md の構造、ルーターパターン、段階的な情報開示
reference/hooks.md	フックの種類、マッチャー、入出力スキーマ、例
reference/commands.md	スラッシュコマンドの YAML、引数、動的コンテキスト
reference/subagents.md	エージェントの設定、実行モデル、オーケストレーション
</reference_index>

<anti_patterns> すべての拡張タイプに共通するよくある誤り：

```markdown ## Bad - Using markdown headings ```

<good>Using XML tags instead</good>

```yaml description: Helps with stuff # Bad description: Extract text from PDF files. Use when processing documents. # Good ``` ```yaml description: I help you process files # Bad - first person description: Processes files for analysis # Good - third person ``` 代替案の一覧ではなく、抜け道を用意したデフォルトの方法を1つ提示してください。

<success_criteria> 適切に作成された Claude Code 拡張機能には、以下が備わっています。

• 説明的な名前と説明を含む有効な YAML frontmatter
• 純粋な XML 構造（本文に Markdown 見出しがない）
• 明確な目標／目的の記述
• 定義された成功基準または完了確認
• 適切な詳細レベル（過剰に複雑化していない）
• 実環境でのテストと反復
• 三人称でのドキュメント </success_criteria>

成果サイドカーの出力

最後の手順として、~/.claude/skill-analytics/last-outcome-extension-authoring.json に以下を書き込みます。

{"ts":"[UTC ISO8601]","skill":"extension-authoring","version":"1.1.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"extensions_created":[n],"extension_type":"[skill|hook|command|subagent]"},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部のステージに失敗しても結果が生成された場合は、ステータスに "partial" を使用してください。出力が生成されなかった場合に限り、"error" を使用してください。