advanced-features-2025

高度なプラグイン機能（2025）

クイックリファレンス

機能	場所	目的
エージェントスキル	skills/*/SKILL.md	知識の動的な読み込み
フック	hooks/hooks.json	イベントの自動化
MCP サーバー	.mcp.json	外部サービスとの統合
チーム設定	.claude/settings.json	リポジトリプラグイン

フックイベント	発生タイミング	用途
PreToolUse	ツール実行前	検証
PostToolUse	ツール実行後	テスト、リンティング
SessionStart	セッション開始時	ロギング、セットアップ
SessionEnd	セッション終了時	クリーンアップ
UserPromptSubmit	プロンプト送信時	前処理
PreCompact	コンパクト化の前	状態の保存
Notification	通知の表示時	カスタムアラート
Stop	ユーザーによる停止時	クリーンアップ
SubagentStop	サブエージェント終了時	ロギング

変数	目的
${CLAUDE_PLUGIN_ROOT}	プラグインのインストール先
${TOOL_INPUT_*}	ツールの入力パラメーター

エージェントスキル

概念

スキルはタスクのコンテキストに応じて動的に読み込まれ、次のことが可能になります。

• 無制限の容量：知識を複数のファイルに分割できます
• コンテキスト効率：必要なものだけを読み込みます
• 段階的な開示：3段階で読み込みます

3段階の読み込み

1. フロントマター：起動時に読み込みます（トリガー）
2. SKILL.md の本文：有効化時に読み込みます
3. references/：詳細が必要なときに読み込みます

構成

skills/
└── skill-name/
    ├── SKILL.md           # Core content
    ├── references/        # Detailed docs
    │   └── deep-dive.md
    ├── examples/          # Working code
    │   └── example.md
    └── scripts/           # Utilities
        └── tool.sh

SKILL.md の形式

---
name: skill-name
description: |
  When to activate this skill. Include:
  (1) Use case 1
  (2) Use case 2
  Provides: what it offers
---

# Skill Title

## Quick Reference
[Tables, key points]

## Core Content
[Essential information - keep lean]

## Additional Resources
See `references/` for detailed guidance.

フック

設定

plugin.json 内に直接記述：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh"
      }]
    }]
  }
}

hooks.json を個別に使用：

{
  "PostToolUse": [{
    "matcher": "Write",
    "hooks": [{
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
      "timeout": 5000
    }]
  }]
}

マッチャー

• Write - ファイルへの書き込み
• Edit - ファイルの編集
• Bash - シェルコマンド
• Write|Edit - 複数のツール
• .* - 任意のツール（使用は控えめにしてください）

一般的なパターン

変更後に自動テストを実行：

{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh"
    }]
  }]
}

Bash の実行前に検証：

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-cmd.sh"
    }]
  }]
}

MCP サーバーの統合

設定

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

外部サービス

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp-server"],
      "env": {
        "STRIPE_API_KEY": "${STRIPE_API_KEY}"
      }
    }
  }
}

リポジトリ設定

チームへの配布

リポジトリのルートに .claude/settings.json を作成します。

{
  "extraKnownMarketplaces": [
    "company/internal-plugins"
  ],
  "plugins": {
    "enabled": [
      "deployment-helper@company",
      "code-standards@company"
    ]
  }
}

ワークフロー

1. メンテナーが .claude/settings.json を作成します
2. チームメンバーがリポジトリをクローンします
3. 確認を求められたらフォルダーを信頼します
4. プラグインが自動的にインストールされます

ベストプラクティス

段階的な開示

• SKILL.md は500行未満にします
• 詳細は references/ に移します
• 動作するコードには examples/ を使用します
• 相対パスでファイルを参照します

フック

• 具体的なマッチャーを使用します（.* は避けてください）
• 適切なタイムアウトを設定します
• パスには ${CLAUDE_PLUGIN_ROOT} を使用します
• スクリプトを個別にテストします

MCP

• 必須の環境変数を記載します
• セットアップ手順を用意します
• シークレットには環境変数を使用します
• 配布前に接続をテストします

追加リソース

詳しいパターンについては、以下を参照してください。

• references/hooks-advanced.md - フックパターンの全容
• references/mcp-patterns.md - MCP 統合の例
• references/team-distribution.md - リポジトリ設定
• examples/hook-scripts.md - 動作するフックスクリプト