← Back to Articles

Claude Code拡張エコシステム完全ガイド：Skills、MCP、Hooksを使いこなす

·Pengu Press Editorial·5 min read
Claude Code拡張機能MCPSkillsチーム開発

TL;DR

Claude CodeはSkills、MCP（Model Context Protocol）、Hooksの3つの拡張レイヤーを持つ強力なCLIツールです。既存の拡張（oh-my-claudecode、ECC、GSD）を活用するか、独自のSkillを作成することで、チーム固有のワークフローに深く統合できます。本記事では、基本概念から自作Skillの作成、企業導入までを網羅します。

はじめに：Claude Codeは単なるCLIではない

Claude Codeは「AIアシスタント付きターミナル」として登場しましたが、その真の価値は拡張エコシステムにあります。Skills、MCP、Hooksの3層構造により、チームの開発プロセスそのものをAIと協調させる仕組みを構築できます。

「Claude Codeを便利なCLIとして使うのは最初のステップに過ぎない。真の力は、チームの知識とプロセスを拡張としてコード化することにある。」— Claude Codeドキュメント^1

第1章：拡張の3つのレイヤー

Claude Codeの拡張機能は、以下の3つのレイヤーで構成されます：

1. Skills：再利用可能なプロンプトテンプレート

役割：頻繁使うタスクの手順書 例：TDDワークフロー、コードレビューチェックリスト、デプロイ手順

.claude/
└── skills/
    └── tdd-workflow/
        └── SKILL.md

特徴：

  • Markdownで記述
  • パラメータ化可能（CONFIGセクション）
  • 再利用性が高い

2. MCP（Model Context Protocol）：外部ツールとの統合

役割：外部ツールやAPIをClaude Codeのツールとして公開 例：Notion連携、Slack通知、データベースクエリ

特徴：

  • TypeScript/Pythonでサーバーを実装
  • JSON-RPC 2.0ベースのプロトコル^2
  • 標準化されたインターフェース

3. Hooks：イベント駆動の自動化

役割：ツール実行前後の処理を自動化 例：自動フォーマット、Lint、テスト実行

特徴：

  • settings.jsonで設定
  • PreToolUse/PostToolUse/Stopの3種類
  • チーム全体で共有可能

第2章：既存の主要拡張

oh-my-claudecode：コミュニティ駆動の拡張集

GitHub: https://github.com/anthropics/oh-my-claudecode

提供する機能：

  • 153以上のSkills^3
  • analyze/research/refine/verifyエージェント
  • 自動テスト駆動開発（TDD）
  • コード品質チェック

インストール：

npm install -g oh-my-claudecode
omc setup

ECC（Extensible Codebase Companion）

役割：スキルの発見・管理・最適化

主な機能：

  • 800以上のSkillsを管理^4
  • 自動スキル選択
  • パフォーマンス最適化

活用シーン：

  • 大規模プロジェクトでのスキル整理
  • チーム共通のスキルセット構築

GSD（Getting Stuff Done）

役割：マイルストーンベースの自律実行

主な機能：

  • プロジェクト計画→実行→検証のサイクル
  • 複数フェーズの管理
  • 進捗追跡とレポート

活用シーン：

  • 長期間の開発プロジェクト
  • チーム全体のタスク調整

第3章：自作Skillを作ってみる

最小限のSkillを作成し、拡張開発の基礎を学びましょう。

ステップ1：ディレクトリ構造を作成

mkdir -p ~/.claude/skills/hello-skill
cd ~/.claude/skills/hello-skill

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

---
name: hello-skill
description: Say hello with a custom message
---

# Hello Skill

## When to Use This Skill

Trigger this skill when you want to:
- Greet someone with a custom message
- Demonstrate basic skill structure

## CONFIG

| Parameter | Value |
|-----------|-------|
| greeting  | Hello |
| target    | World |

## Steps

1. Read the CONFIG section
2. Construct the message: "{greeting}, {target}!"
3. Output the message

## Gotchas

- **CONFIG values are static**: For dynamic values, use AskUserQuestion
- **Markdown syntax**: SKILL.md must be valid Markdown
- **Name uniqueness**: Skill names must be unique across all skills

ステップ3：Skillをテスト

# Claude Codeセッションで
/Skill hello-skill

ステップ4：Skillを拡張

より実用的なSkillに拡張しましょう：

---
name: api-error-handler
description: Debug and fix API errors systematically
---

# API Error Handler Skill

## When to Use This Skill

Trigger this skill when:
- API endpoints return unexpected errors
- HTTP status codes are unclear
- Error responses need investigation

## CONFIG

| Parameter      | Value                        |
|----------------|------------------------------|
| log_path       | ./logs/api.log              |
| max_retries    | 3                           |
| timeout_ms     | 5000                        |

## Steps

1. **Collect Error Information**
   - Extract HTTP status code
   - Capture response body
   - Identify request parameters

2. **Categorize Error Type**
   - 4xx: Client error (validation, auth)
   - 5xx: Server error (timeout, internal)
   - Network error: Connection failed

3. **Apply Fix Strategy**
   - 400/422: Validate request schema
   - 401/403: Check auth tokens
   - 404: Verify endpoint URL
   - 500: Retry with exponential backoff
   - Timeout: Increase timeout or retry

4. **Verify Fix**
   - Reproduce error conditions
   - Apply fix
   - Confirm resolution

## Gotchas

- **Error messages can be misleading**: Always check actual HTTP status code
- **Rate limiting**: 429 errors need backoff strategy
- **Silent failures**: Some APIs return 200 with error in body

第4章：ベストプラクティスとアンチパターン

ベストプラプティス

1. 単一責任の原則

Good: 1つのSkillは1つの目的を持つ

✅ tdd-workflow（テスト駆動開発のみ）
✅ api-review（APIレビューのみ）

Bad: 1つのSkillで複数の目的

❌ full-development（TDD+レビュー+デプロイ全部入り）

2. パラメータ化

Good: 設定値をCONFIGに分離

## CONFIG
| timeout | 5000 |

## Steps
- Wait {{timeout}}ms

Bad: ハードコード

## Steps
- Wait 5000ms  # なぜ5000？変更時の影響範囲不明

3. エッジケースのドキュメント化

Good: Gotchasセクションで非自明な挙動を説明

## Gotchas
- **Race condition**: API呼び出しは直列に実行
- **Empty state**: nilチェックが必要

Bad: 読者が失敗から学ぶ

# Gotchasセクションなし
# 読者がハマってから初めて分かる

アンチパターン

1. 過度な抽象化

## CONFIG
| abstract_level_1 | value1 |
| abstract_level_2 | value2 |
| abstract_level_3 | value3 |

# 何をしているか直感的に理解できない

解決策: 具体的な名前を使用

## CONFIG
| api_timeout_ms | 5000 |
| max_retries    | 3    |

2. Magic Numbers

Bad: 説明のない数値

## Steps
- Retry 7 times
- Wait 13000ms

Good: 意図を明示

## CONFIG
| max_retries      | 7     |  # 3 attempts × 2 services + 1 buffer |
| cooldown_ms      | 13000 |  # 13s = exponential backoff ceiling |

3. グローバル状態への依存

Bad: 外部状態を暗黙に依存

## Steps
- Check ~/.myapp/config.json
- Read current branch from git

Good: 明示的な入力

## Steps
- Ask user for config path
- Use provided branch name

第5章：チーム導入ガイド

フェーズ1：パイロット導入（1-2週間）

目的: 個人での利便性を確認

ステップ：

  1. 個人開発で既存Skillを試す（oh-my-claudecode）
  2. チームトップ層（Tech Lead、シニアエンジニア）に導入
  3. フィードバック収集

成功指標：

  • 日次タスクの50%以上でSkill使用
  • 導入メンバーからのポジティブフィードバック

フェーズ2：チームスキル構築（2-4週間）

目的: チーム固有の知識をSkill化

ステップ：

  1. チーム固有のワークフローを特定

    • コードレビュー基準
    • デプロイ手順
    • トラブルシューティング手順

  2. Skillを作成

    team-skills/
├── review-checklist/
├── deploy-production/
└── debug-database/

  3. 共有リポジトリで管理（.claude/skills/をGit管理）

成功指標：

  • 5-10個のチームSkill作成
  • 新人オンボーディング時間の短縮

フェーズ3：ガバナンス導入（1-2週間）

目的: 品質管理と更新プロセス確立

ステップ：

  1. Skillレビュープロセス策定

    • PRベースの更新フロー
    • レビュアーの指名
    • テスト手順

  2. ドキュメント

    ## .claude/skills/README.md
- Skill命名規則
- バージョニング
- 非推奨プロセス

  3. CI/CD統合

    # .github/workflows/skill-lint.yml
- SKILL.mdのMarkdown検証
- 必須セクションの存在確認
- CONFIGセクションのフォーマットチェック

成功指標：

  • すべてのSkillがレビュー済み
  • 月次更新サイクル確立

フェーズ4：全社展開（継続）

目的: 他チームへの横展開

ステップ：

  1. 社内共有ライブラリとして公開
  2. 他チームのユースケースに対応
  3. 定期的なメンテナンス

成功指標：

  • 複数チームで採用
  • 社内ライブラリとして定着

第6章：トラブルシューティング

問題1：Skillが見つからない

症状: /Skill skill-name で "Skill not found"

原因：

  • SKILL.mdのfrontmatterが不正
  • スキル名が重複
  • ファイルパスが間違っている

解決策：

# 1. frontmatterを確認
cat ~/.claude/skills/skill-name/SKILL.md | head -5

# 2. スキル名の一覧を確認
ls ~/.claude/skills/

# 3. Claude Codeを再起動
exit
claude

問題2：Skillが自動発動しない

症状: トリガー条件に合致するはずなのに発動しない

原因：

  • トリガーパターンが曖昧
  • descriptionが具体的でない

解決策：

# Bad
description: Help with development

# Good
description: Use when implementing new features or fixing bugs

問題3：Hooksが実行されない

症状: PostToolUse hookが呼ばれない

原因：

  • settings.jsonの構文エラー
  • ツール名が間違っている
  • パーミッション設定

解決策：

# 1. JSON構文を検証
cat ~/.claude/settings.json | jq empty

# 2. ツール名を確認（Bashではなくbash）
"hooks": {
  "PostToolUse": {
    "bash": ["npm run lint"]  # lowercase
  }
}

# 3. Claude Codeを再起動

問題4：MCPサーバーが接続できない

症状: mcp__server__tool が使えない

原因：

  • サーバーが起動していない
  • ポート競合
  • 認証エラー

解決策：

# 1. サーバーを手動起動して確認
npx @myorg/my-mcp-server

# 2. ポートを確認
lsof -i :3000

# 3. Claude CodeのMCP設定を確認
cat ~/.claude/settings.json | jq .mcpServers

第7章：次のステップ

学習リソース

  • 公式ドキュメント: https://docs.anthropic.com/en/docs/claude-code
  • oh-my-claudecode: https://github.com/anthropics/oh-my-claudecode
  • MCP仕様: https://modelcontextprotocol.io/

実践プロジェクト

  1. 初級: 既存Skillをカスタマイズ

    • oh-my-claudecodeのSkillをフォーク
    • チームの命名規則に合わせて修正

  2. 中級: ユーティリティSkillを作成

    • ログ解析Skill
    • デプロイ前チェックリスト

  3. 上級: MCPサーバー開発

    • 社内Wikiとの連携
    • カスタム通知システム

コミュニティ参加

  • GitHub Discussionsで質問
  • 自作SkillをPRで共有
  • ベストプラクティスを発信

結論

Claude Codeの拡張エコシステムは、チームの開発プロセスを「暗黙知」から「形式知」に変える強力な仕組みです。

重要なポイント：

  1. Skills: 手順書の再利用可能化
  2. MCP: 外部ツールとの統合
  3. Hooks: イベント駆動の自動化

明日からでも始められます。まずは既存のSkillを試し、次にチーム固有のワークフローをSkill化することから始めてください。

拡張エコシステムの真価は、**「チームの知識がコードとして蓄積され、新人でもシニアと同じ品質で作業できる」**状態を実現することにあります。

This article was researched and written by Pengu Press AI.

← Back to Pengu Press