はじめに

Claude Code は、ターミナルから使える Anthropic 公式の AI コーディングアシスタントです。
Claude Code の拡張機能（下記の 4 つ）を試したので、メモがてら記事に残しておきます。

Skills
カスタムサブエージェント
 MCP
Hooks

※この記事のサンプルコードは、GitHubにアップロードしました。
https://github.com/aji-taro/claude_code_basics
利用方法はREADME.md に記載しています。

1. Skills（スラッシュコマンド）の設定

Skills を使うと、独自のスラッシュコマンドを作成できます。
Markdown ファイルを置くだけで動作し、コードを書く必要はありません。

ファイルの置き場所:

.claude/skills/配下に、スキル名と同じ名前のディレクトリを作成し、その中に SKILL.md を配置します。

project/
└── .claude/
    └── skills/
        └── hello-world/    # ディレクトリ名をスキル名にあわせる
            └── SKILL.md    # ファイル名は SKILL.md 固定

SKILL.md の書き方:

フロントマター（--- で囲まれた部分）に name と description を定義し、本文に Claude への指示を記述します。

---
name: hello-world
description: ユーザーに挨拶し、現在のプロジェクトの簡単なサマリーを表示します。
---

# Hello World スキル

このスキルが呼び出されたら、以下の手順で動作してください。

1. **挨拶**: ユーザーに「Hello! Claude Code スキルが動作しています。」と伝える
2. **確認**: プロジェクトのファイルを確認する
3. **報告**: プロジェクト名・使用技術・今日の日付を報告する

・name：フィールドがスラッシュコマンドの名前になります。この例では /hello-world と入力すると実行されます。
・description：ユーザーがスラッシュコマンドを直接打たなくても、会話の文脈から Claude が「このスキルを使うべきだ」と判断する際のルーティング基準として使われます。

※name、descriptionは必須です。
他にも指定できるフィールドがあります。

※Skillsのリファレンス
https://code.claude.com/docs/ja/skills

2. カスタムサブエージェントの設定

サブエージェントは、メインの Claude から独立したコンテキストで動く AI エージェントです。
複雑な調査・分析タスクをメインの会話から切り離して実行できます。

ファイルの置き場所:

project/
└── .claude/
    └── agents/
        └── analyzer/    # エージェント名のディレクトリ
            └── AGENT.md # ファイル名は AGENT.md 固定

AGENT.md の書き方:

フロントマター（--- で囲まれた部分）に name と description を定義し、本文に Claude への指示を記述します。

---
name: file-analyzer
description: プロジェクトの構造を分析し、最適な改善案を提示する自律エージェント。
---

# File Analyzer エージェントのミッション

あなたはプロジェクトの品質管理責任者です。以下の手順を自律的に実行してください。

1. **現状把握**: プロジェクトのファイル構成と内容をスキャンする
2. **分析**: 重複コードを見つける
3. **報告**: 問題点・修正案・想定工数をまとめて返却する

**制約事項**:
- メインの会話履歴にはアクセスできません
- 渡されたディレクトリ内の情報のみで判断してください

Skills との違いは「自律性」です。
Skills は Claude の手順書ですが、エージェントは Claude から Agent ツール（Sub-agent tool）経由で呼び出され、独立したコンテキストで動作します。

・呼び出し方
チャット内で @file-analyzer のようにメンションを送るか、「file-analyzerエージェントを使って分析して」と指示することで起動します。

・メリット
エージェントが裏側で大量のファイルを読み込んでも、メインのチャットの記憶（トークン）を消費しません。
そのため、本題の会話が重くなったり、AIが混乱したりするのを防げます。

※カスタムサブエージェントのリファレンス
https://code.claude.com/docs/ja/sub-agents

3. MCP（Model Context Protocol）サーバーの設定

MCP を使うと、Claude に独自のツール（関数）を追加できます。
「URL からファイルを取得する」「データベースを検索する」など、
デフォルトでは持っていない能力を Claude に追加できます。

Skills との大きな違いは、外部サービスと接続できる点です。
Skills は Claude への手順書であり Claude 自身の能力の範囲内で動きますが、
MCP は外部プロセスとの接続口であり、Claude が本来できないことを外部サービスやツールに委ねられます。

ファイルの置き場所:

project/
├── .mcp.json              # MCP サーバーの接続設定
└── mcp-server-sample/     # MCP サーバーの実装
    └── main.go            # サーバー本体

設定ファイル .mcp.json:

サーバーの起動情報を記述します。
この例ではシェルスクリプトも利用しています。

<.mcp.json>

{
  "mcpServers": {
    "go-mcp-helper": {
      "type": "stdio",
      "command": "sh",
      "args": [".claude/mcp-start.sh"]
    }
  }
}

※`type: "stdio"` は、標準入出力を通じて Claude とサーバーが通信する方式です。

<mcp-start.sh>

#!/bin/sh
SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)

docker run --rm -i \
  -v "$SCRIPT_DIR/../mcp-server-sample:/app" \
  -v "$SCRIPT_DIR/../mcp-server-sample/_gomodcache:/tmp/gomodcache" \
  -e GOMODCACHE=/tmp/gomodcache \
  golang:1.23-alpine \
  sh /app/run.sh

サーバー側のコード例（Go）:

s := server.NewMCPServer("go-mcp-helper", "1.0.0")

s.AddTool(
	// ツール "fetch_config" を登録する
	// AIはこのツールの名前・説明・引数スキーマを見て、いつ・どう呼ぶかを判断する
    mcp.NewTool("fetch_config",
        mcp.WithDescription("指定されたURLから設定ファイルを取得します"),
        mcp.WithString("url", mcp.Required()),
    ),
    func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        url, _ := req.RequireString("url")
        resp, _ := http.Get(url)
        body, _ := io.ReadAll(resp.Body)
        return mcp.NewToolResultText(string(body)), nil
    },
)

ツール名・説明・引数スキーマを定義すると、Claude が「いつ・どう呼ぶか」を自動で判断します。
MCP サーバーは Go, Python, TypeScript など任意の言語で実装できます。

・呼び出し方
Claude Codeに対してfetch_configで、https://github.com/aji-taro/gorm-introduction/blob/main/README.md を取得して要約してくださいと指示します。

※MCPのリファレンス
https://code.claude.com/docs/ja/mcp

4. Hooks の設定

Hooks を使うと、ツール実行の前後に自動でシェルコマンドを走らせられます。
「ファイル保存のたびに自動フォーマット」などを実現できます。

ファイルの置き場所:

project/
└── .claude/
    ├── settings.json       # チーム共有の設定（Git 管理）
    ├── settings.local.json # 個人用の設定（.gitignore 推奨）
    └── hooks/
        └── post-edit-go-fmt.sh

設定ファイル .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/post-edit-go-fmt.sh"
          }
        ]
      }
    ]
  }
}

PostToolUse → ツール実行後に動く（PreToolUse で実行前も可）
matcher: "Edit" → Edit ツール（ファイル編集）をトリガーにする
type: "command" → フックの種類。現時点では "command"（シェルコマンド実行）のみ指定可能
command → 実行するスクリプトやコマンドのパス

フックスクリプト .claude/hooks/post-edit-go-fmt.sh:

作成したシェルスクリプトには chmod +x で実行権限を付与しておく必要があります。

INPUT=$(cat)
FILE_PATH=$(printf '%s' "$INPUT" | sed -n 's/.*"file_path".*:.*"\([^"]*\)".*/\1/p')

# .go ファイル以外はスキップ
if ! echo "$FILE_PATH" | grep -q '\.go$'; then
  exit 0
fi

docker run --rm -v "$(dirname $FILE_PATH):/work" golang:1.23-alpine \
  go fmt "/work/$(basename $FILE_PATH)"

フックには stdin から JSON が渡され、tool_input.file_path などの情報を取り出せます。
この例では .go ファイル編集後に go fmt を自動実行しています。

・呼び出し方
例えば、bad.goに記述されている文字列"Hello, World no.1"を"Hello, World no.2"にしてと Claude Code に指示してファイルを更新させます。

※Hooksのリファレンス
https://code.claude.com/docs/ja/hooks

まとめ

機能	設定ファイル	できること
Skills	`.claude/skills/*/SKILL.md`	独自スラッシュコマンドを追加
Agents	`.claude/agents/*/AGENT.md`	独立して動く AI エージェントを定義
MCP	`.mcp.json`	Claude に独自ツールを追加
Hooks	`.claude/settings.json`	ツール実行前後に処理を自動化