claude-extensibility

Claude Code の拡張性

Anthropic のベストプラクティスに沿った、エージェント、スキル、出力スタイルの CRUD 操作です。

関連スキル

重要： プロンプトを作成または編集する際は、品質を向上させるために prompt-enhancer スキルを使用してください。

Skill("prompt-enhancer")  → Enhance skill/agent prompt content

基本原則

• シンプルさ：ツールを直接呼び出し、複雑な抽象化は避けます
• 焦点：拡張機能ごとに、明確な責任を 1 つに絞ります
• 簡潔さ：500 行未満を目標とし、段階的開示を活用します
• 効率性：トークン使用量と応答時間を最適化します

拡張機能の種類

種類	呼び出し方法	目的	場所
エージェント	Task ツール	特化型サブプロセス	.claude/agents/
スキル	モデルによる呼び出し（自律的）	ドメイン知識	.claude/skills/{name}/
出力スタイル	/output-style コマンド	メインエージェントの動作を変更	.claude/output-styles/

エージェントの開発

参考資料： references/agent-development.md — YAML 構造全般、モデル／ツールの選択、システムプロンプトのパターン、最適化手法。

クイックスタート：エージェント

---
name: agent-name
description: Use this agent when [use case]. Use PROACTIVELY for [triggers].\n\nExamples:\n<example>\nContext: [situation]\nuser: [request]\nassistant: [response]\n<commentary>[reasoning]</commentary>\n</example>
tools: Grep, Glob, Read, Bash
model: haiku
permissionMode: default
skills: skill-name
---

# Agent Name

Brief mission statement.

## Core Strategy

### 1. Phase Name
Approach and techniques

<format>
Expected output structure
</format>

YAML フィールド

フィールド	必須	説明
name	はい	小文字とハイフンを使用します（例：code-reviewer）
description	はい	改行には \n を使う 1 行の説明です。例も含めます
tools	いいえ	カンマ区切りで指定します。省略すると、すべてのツールを継承します
model	いいえ	haiku、sonnet、opus、inherit（デフォルト：sonnet）
permissionMode	いいえ	default、acceptEdits、bypassPermissions、plan、ignore
skills	いいえ	自動ロードするスキル名をカンマ区切りで指定します

モデルの選択

モデル	使用する場面	目標時間
haiku	高速なタスク、調査、検索	< 3 秒
sonnet	バランスがよく、ほとんどのユースケースに適しています	< 10 秒
opus	複雑な推論、アーキテクチャ	< 30 秒
inherit	メインの会話と同じモデルを使用します	変動

組み込みサブエージェント

エージェント	モデル	ツール	目的
general-purpose	Sonnet	すべて	複雑な調査、複数ステップの操作
plan	Sonnet	Read、Glob、Grep、Bash	プランモードでの調査
Explore	Haiku	読み取り専用	コードベースの高速検索（簡易／中程度／非常に詳細）

エージェントの配置場所

場所	スコープ	優先度
.claude/agents/	プロジェクト	最高
~/.claude/agents/	ユーザー（すべてのプロジェクト）	低
プラグイン agents/	プラグイン固有	変動
--agents CLI フラグ	セッションのみ	中

CLI で定義するエージェント

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

再開可能なエージェント

以前の会話を続けます：

• 各実行には一意の agentId が割り当てられます
• トランスクリプトは agent-{agentId}.jsonl に保存されます
• 以前の agentId を指定して再開すると、完全なコンテキストを引き継いで続行できます

スキルの開発

参考資料： references/skill-development.md — 構造全般、トリガーパターン、フックシステム。

クイックスタート：スキル

---
name: skill-name
description: "[What it does]. [Technologies]. Capabilities: [list]. Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."
allowed-tools: Read, Grep, Glob
---

# Skill Name

## Purpose
What this skill helps with

## When to Use
Specific scenarios and conditions

## Key Information
Guidance, patterns, examples

YAML フィールド

フィールド	必須	説明
name	はい	小文字とハイフンを使用し、最大 64 文字です
description	はい	WHAT + WHEN 形式で、最大 1024 文字です。引用符で囲みます
allowed-tools	いいえ	ツールへのアクセスを制限します（セキュリティ）

説明の形式（WHAT + WHEN）

構造：

"[Core purpose]. [Technologies/Stack]. Capabilities: [list]. Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."

良い例：

description: "Extract text and tables from PDF files, fill forms, merge documents. Formats: .pdf. Tools: pypdf, pdfplumber. Capabilities: text extraction, form filling, document merging. Actions: extract, fill, merge PDFs. Keywords: PDF, form, document, pypdf, pdfplumber. Use when: working with PDF files, extracting data from documents, filling PDF forms."

悪い例：

description: Helps with documents  # Too vague
description: PDF skill  # Missing WHEN triggers

ツールアクセス制御

allowed-tools を使用して Claude のツールを制限します：

---
name: safe-reader
description: "Read-only file access. Use when viewing code without modifications."
allowed-tools: Read, Grep, Glob
---

スキルの配置場所

場所	スコープ
.claude/skills/{name}/SKILL.md	プロジェクト（git 経由で共有）
~/.claude/skills/{name}/SKILL.md	ユーザー（すべてのプロジェクト）
プラグイン skills/	プラグインにバンドル

スキルの構造

my-skill/
├── SKILL.md (required)
├── references/ (optional - detailed docs)
├── scripts/ (optional - utilities)
└── templates/ (optional - templates)

出力スタイル

Claude Code のメインエージェントの動作を変更します。

クイックスタート：出力スタイル

---
name: My Custom Style
description: Brief description of behavior
keep-coding-instructions: true
---

# Custom Style Instructions

You are an interactive CLI tool that helps users...

## Specific Behaviors
[Define assistant behavior...]

YAML フィールド

フィールド	目的	デフォルト
name	表示名	ファイル名
description	UI の説明	なし
keep-coding-instructions	コーディング指示を保持	false

組み込みスタイル

• Default：標準的なソフトウェアエンジニアリング
• Explanatory：タスクの合間に学習に役立つ解説を提供
• Learning：TODO(human) マーカーを使った協調型

出力スタイルの保存場所

• ユーザー：~/.claude/output-styles/
• プロジェクト：.claude/output-styles/

使用方法

/output-style              # Access menu
/output-style explanatory  # Switch directly

テスト

重要な問い：想定どおりに起動しますか？

エージェントのテスト：

Task(
  subagent_type="agent-name",
  description="Test task",
  prompt="Detailed test prompt"
)

スキルのテスト：

• 起動するはずのプロンプトをテストします
• 起動しないはずのプロンプトをテストします
• claude --debug でデバッグします

一般的なワークフロー

エージェントの作成

1. .claude/agents/{name}.md を作成します
2. YAML フロントマター（name、description、tools、model）を記述します
3. システムプロンプト（500 行未満）を記述します
4. Task ツールでテストします
5. パフォーマンスに基づいて最適化します

スキルの作成

1. .claude/skills/{name}/SKILL.md を作成します
2. WHAT + WHEN の説明を含む YAML フロントマターを記述します
3. 内容（500 行未満）を記述します
4. Skill("prompt-enhancer") を使ってプロンプトを改善します
5. 詳細な内容には参照ファイルを追加します
6. テストします：想定どおりに起動しますか？

拡張機能の最適化

1. ベースラインを測定します（行数、トークン使用量、応答時間）
2. 詳細を参照ファイルに移します
3. Skill("prompt-enhancer") を使ってプロンプトを改善します
4. 二人称の表現を削除します
5. 文章よりコードブロックを使います
6. XML 構造を追加します
7. テストして改善を確認します

ベストプラクティス

Anthropic のガイドライン

✅ 500 行ルール：SKILL.md とエージェントのプロンプトは 500 行未満に保ちます
✅ 段階的な情報開示：詳細な内容には参照ファイルを使います
✅ 積極的な表現：説明に「use PROACTIVELY」を含めます
✅ WHAT + WHEN の説明：機能と起動条件の両方を記述します
✅ まずテスト：ドキュメントを広範に作成する前に、3 件以上の評価を用意します
✅ 最小権限：ツールを必要なものだけに制限します

アンチパターン

❌ 起動条件のない曖昧な説明
❌ 参照ファイルを使わずに 500 行を超える
❌ 二人称の表現（「you should...」）
❌ 一部のツールで十分なのに、すべてのツールを使う
❌ エージェントの説明に例がない

クイックリファレンス

エージェントのモデル選択：

• Haiku：高速で単純なタスク（3 秒未満）
• Sonnet：バランスがよく、ほとんどのユースケースに適しています（10 秒未満）
• Opus：複雑な推論（30 秒未満）
• Inherit：メインの会話に合わせます

ファイルの保存場所：

• エージェント：.claude/agents/*.md
• スキル：.claude/skills/{name}/SKILL.md
• 出力スタイル：.claude/output-styles/*.md

管理コマンド：

• /agents - 対話形式でエージェントを管理します
• /output-style - 出力スタイルを切り替えます

---

ステータス：本番環境対応 | 行数：約 200 | 段階的な情報開示：✅