Go to Qiita Advent Calendar Top
LoginSignup
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Day 13

コードレビューに関するTipsを投稿しよう！ by CodeRabbit Advent Calendar 2025

@c0ffee(Yuya Kotani)

Agent Skills入門 - MCPとの違いと実装ハンズオン

Last updated at Posted at 2025-12-23

はじめに

ClaudeにMCP（Model Context Protocol）が登場して以来、「Claude環境を拡張する」という話題が盛り上がっています。そんな中、もう一つの重要な拡張機能であるAgent Skillsについてはまだ情報が少ない状況です。

本記事では、Anthropic公式ドキュメント12に基づき、Agent Skillsと従来方法 (通常のプロンプト)との違いを明確にした上で、ハンズオン形式でSkillsの活用方法を解説します。ハンズオンはClaude Code（CLI）環境で実施しますが、作成したSkillはClaude Desktop AppやWeb版でも利用できます。

この記事で得られること：

  • Agent Skillsと従来方法の違い
  • Agent SkillsとMCPの使い分け基準
  • Claude CodeでのSkill実装方法

Agent Skillsと従来方法 (通常のプロンプト)の違い

従来の方法（Agent Skillsなし）
公式ブログ3によれば、通常のプロンプトは一時的なものです。

"Prompts are reactive and ephemeral."

つまり、毎回同じ入力する必要があります。

会話1: このPythonコードをレビューして。
       確認項目：SQLインジェクション、APIキー、PEP 8...（長い）

会話2: このPythonコードをレビューして。
       確認項目：（同じリストを再入力）

会話3: （また同じ...）

Agent Skillsを使う方法
一度Skillを作成すれば、Skillが自動適用されます。

"Skills are proactive—Claude knows when to apply them—and persistent across conversations."

一度だけ: python-code-reviewer Skillを作成

会話1: このPythonコードをレビューして
       → [Skillが自動適用]

会話2: このPythonコードをレビューして
       → [同じSkillが自動適用]

Agent Skillsが有効な場合：

  • チーム全体で統一基準を使いたい
  • 毎回同じチェックリストを適用している
  • 新メンバーにも同じ基準を適用したい
  • 長い指示を毎回入力するのが面倒

不要：

  • 一回限りのレビュー
  • プロジェクトごとに基準が全く異なる

セキュリティについて

Agent Skillsは強力な機能ですが、信頼できるソースからのみ使用してください。悪意のあるSkillは、データの流出や不正なシステムアクセスを引き起こす可能性があります。Anthropic公式セキュリティガイドライン1では、自分で作成したもの、またはAnthropic公式のSkillのみを使用することを強く推奨しています。

Agent SkillsとMCPの違い

以下は、Anthropic公式ドキュメント1とMCP公式仕様4に基づく比較です。

項目 Agent Skills MCP
提供方式 プロンプト拡張（事前知識注入） ツール/リソース提供（実行時呼出）
実装難易度 マークダウンファイルのみ サーバー実装が必要
実装言語 Markdown Python/TypeScript等
最適用途 ベストプラクティス、フォーマット定義 API連携、ファイルアクセス
状態管理 不要 必要（サーバー側で管理）

プログレッシブディスクロージャ（段階的開示）

Agent Skillsの重要な特徴はプログレッシブディスクロージャです。これは、Anthropic Engineering Blogで詳しく解説されている2、必要な情報だけを段階的にロードする仕組みです。

"At startup, the agent pre-loads the name and description of every installed skill into its system prompt. This metadata is the first level of progressive disclosure: it provides just enough information for Claude to know when each skill should be used without loading all of it into context."
— Anthropic Engineering Blog2

起動
  ↓
すべてのSkillの name と description のみロード
  ↓
タスク実行
  ↓
関連するSkillを判定
  ↓
必要なSkillの SKILL.md 全体を読み込み
  ↓
さらに必要な場合のみ、追加ファイル（スクリプトなど）を読み込み

この仕組みの利点：

  • コンテキストウィンドウを圧迫しない
  • 複数Skillsの同時管理が可能

LangChain Blogの解説5によれば、この仕組みは従来のツール方式と比較して大幅なトークン効率の改善をもたらします。

動作の違い

Agent Skills の動作

ユーザー入力
    ↓
Skill判定（name/descriptionで関連性チェック）
    ↓
Skill読み込み（必要なSKILL.mdのみ注入）
    ↓
プロンプト拡張（コンテキストに知識追加）
    ↓
Claude処理（拡張された知識で応答）

MCP の動作

ユーザー入力
    ↓
Claude判断（ツールが必要か判定）
    ↓
MCPサーバー呼び出し（外部システムアクセス）
    ↓
結果統合（取得データを元に応答生成）

使い分けの判断軸

Agent Skills を選ぶべきケース：

  • 定められたベストプラクティスを適用
  • 出力フォーマットの統一
  • 定められたチェックリストやガイドラインの参照

MCP を選ぶべきケース：

  • 外部APIとの連携
  • ファイルシステムへのアクセス
  • データベースの操作
  • 動的なデータの取得

ハンズオン - Pythonコードレビューアを作る

今回はPythonコードレビュー支援Skillを作成します。
Agent Skillsは複数の環境で利用できます。

利用可能な環境：

  1. Claude Code（CLI）

    • ローカルファイルシステムに直接アクセス可能
    • 配置方法：~/.claude/skills/ または .claude/skills/ ディレクトリにSKILL.mdを配置

  2. Claude Desktop App と claude.ai（Webチャット）

    • 配置方法：設定 > 機能 から zipファイルをアップロード
    • Pro以上のプランが必要

本記事での環境

mkdirやviewなどのコマンドで動作確認しながら進められるため、今回のハンズオンではClaude Code (CLI)を使用します。

Step 1: 環境準備とディレクトリ作成

重要：skillsディレクトリは自動作成されません。

公式ドキュメント6によれば、Claude CodeのSkillsは以下のディレクトリに配置します。

個人用Skills（全プロジェクトで利用可能）:
~/.claude/skills/

プロジェクト用Skills（そのプロジェクトのみ）:
.claude/skills/

まず、skillsディレクトリが存在するか確認を行います。

# 個人用skillsディレクトリの確認
ls ~/.claude/skills/

存在しない場合（No such file or directoryエラーが出る場合）、以下のコマンドで作成します。

# skillsディレクトリを作成
mkdir -p ~/.claude/skills/

Claude Codeがすでにインストールされている場合、~/.claude/ディレクトリは存在しますが、skills/サブディレクトリは自分で作成する必要があります。

Step 2: Pythonコードレビュー用Skillの作成

今回は実践的なPythonコードレビュー支援Skillを作成します。

Agent Skillsの最も重要なポイントは、YAML frontmatterが必須であることです。公式ドキュメント1では以下のように明記されています：

"At its simplest, a skill is a directory that contains a SKILL.md file. This file must start with YAML frontmatter that contains some required metadata: name and description."
— Agent Skills Documentation1

この YAML frontmatter により、プログレッシブディスクロージャ2が実現されます。

以下、SKILL.mdの内容です。

---
name: python-code-reviewer
description: Pythonコードのセキュリティ、PEP 8準拠、パフォーマンスを確認し、具体的な改善提案を提供するスキル
---

# Python Code Reviewer Skill

## Overview
Pythonコードを3つの観点から体系的にレビューし、品質向上のための具体的な提案を行います。

レビュー観点：
1. Security（セキュリティ）
2. PEP 8 Compliance（コーディング規約）
3. Performance（パフォーマンス）

## When to Use
このスキルは以下のキーワードを含む依頼で自動適用されます：
- "Pythonコードをレビュー"
- "このPythonコードを見て"
- "PEP 8"
- "コードチェック"

## Review Checklist

### 1. Security（セキュリティ）
Pythonコード特有のセキュリティ問題を必ずチェック：

- SQLインジェクション: パラメータ化クエリまたはORMを使用しているか
- コマンドインジェクション: `subprocess`で入力値を直接使用していないか
- eval/exec使用: `eval()`, `exec()`を使用していないか
- ハードコードされた機密情報: パスワード、APIキーがコードに含まれていないか

### 2. PEP 8 Compliance（コーディング規約）
PEP 8に準拠しているか確認：

- 命名規則: 
  - 関数名・変数名: `snake_case`
  - クラス名: `PascalCase`
  - 定数: `UPPER_CASE`
- 行の長さ: 最大79文字
- インポート順序: 標準ライブラリ → サードパーティ → ローカル

### 3. Performance（パフォーマンス）
Pythonの性能に影響する問題をチェック：

- リスト内包表記: ループより内包表記が適切な場合
- 文字列結合: `+`演算子ではなく`''.join()`や`f-string`を使用
- 適切なデータ構造: リストではなく集合（set）やdictが適切な場合

## Output Format

レビュー結果は以下の形式で出力すること：

### 総合評価
- レベル: Critical / High / Medium / Low
- 概要: 1-2文で全体的な評価

### 指摘事項

各指摘は以下の形式：

[重要度] カテゴリ: 問題の概要
- 該当箇所: `ファイル名:行数` または関数名
- 問題点: 具体的な問題の説明
- 推奨対応: 改善方法の提案
- 修正例: Pythonコードでの改善例

### Good Points（良い点）
- 評価できる実装を必ず2-3個記載

## Examples

### Example 1: セキュリティ - SQLインジェクション

[Critical] Security: SQLインジェクションのリスク
- 該当箇所: `database.py:45` `get_user_by_id()`関数
- 問題点: ユーザー入力を直接SQL文に結合している
- 推奨対応: パラメータ化クエリまたはORMを使用する

```python
# 問題のあるコード
def get_user_by_id(user_id):
    query = f"SELECT * FROM users WHERE id = {user_id}"
    cursor.execute(query)
    return cursor.fetchone()

# 修正後（パラメータ化クエリ）
def get_user_by_id(user_id: int):
    query = "SELECT * FROM users WHERE id = ?"
    cursor.execute(query, (user_id,))
    return cursor.fetchone()
```

### Example 2: PEP 8 - 命名規則違反

[Medium] PEP 8: 命名規則が非準拠
- 該当箇所: `utils.py:12-25`
- 問題点: 関数名がキャメルケースになっている
- 推奨対応: snake_caseに変更

```python
# 問題のあるコード
def CalculateTotal(items):
    totalPrice = 0
    for item in items:
        totalPrice += item.price
    return totalPrice

# 修正後
def calculate_total(items):
    """アイテムリストの合計金額を計算する。"""
    total_price = 0.0
    for item in items:
        total_price += item.price
    return total_price
```

### Example 3: パフォーマンス - ループの最適化

[Medium] Performance: 非効率な文字列結合
- 該当箇所: `report.py:78` `generate_report()`関数
- 問題点: ループ内で`+`演算子による文字列結合を繰り返している
- 推奨対応: リスト内包表記と`join()`を使用

```python
# 問題のあるコード
def generate_report(data):
    report = ""
    for item in data:
        report += f"{item.name}: {item.value}\n"
    return report

# 修正後
def generate_report(data):
    """データアイテムからレポートを生成する。"""
    lines = [f"{item.name}: {item.value}" for item in data]
    return '\n'.join(lines)
```

## Important Notes

- Pythonらしさ: "Pythonic"な書き方を推奨する
- 具体性: 抽象的な指摘ではなく、コード例を必ず含める
- 優先順位: Critical → High → Medium → Low の順
- バランス: 批判だけでなく、良い点も必ず指摘する

Step 3: Skillファイルの配置

作成したSKILL.mdを正しいディレクトリ構造で配置します。

正しいディレクトリ構造（Claude Code）

~/.claude/skills/
└── python-code-reviewer/     # スキル名のディレクトリ
    └── SKILL.md

ファイル名について

技術解説記事7によれば、SKILL.mdは大文字小文字を区別しません（case-insensitive）：

"Every Skill is defined in a markdown file named SKILL.md (case-insensitive)"

他環境での配置

Claude Desktop AppやWeb版では、このpython-code-reviewerディレクトリをzipファイルに圧縮してアップロードします。zipファイルの構造は同じです：

python-code-reviewer.zip
└── python-code-reviewer/
    └── SKILL.md

Step 4: Claude Code再起動

重要：Skillの変更を反映するには、Claude Codeの再起動が必要です。

公式ドキュメント6に明記されています：

"Changes take effect the next time you start Claude Code. If Claude Code is already running, restart it to load the updates."

再起動方法

# 現在のClaude Codeセッションを終了（Ctrl+CまたはExitコマンド）
exit

# Claude Codeを再起動
claude code

または、新しいターミナルウィンドウでClaude Codeを起動することで、新しいSkillsが読み込まれます。

Step 5: 動作確認

実際にPythonコードをレビューをclaude codeに実行させます。

テストコード：

# test_code.py
def getUserData(userId):
    query = f"SELECT * FROM users WHERE id = {userId}"
    result = db.execute(query)
    return result

def ProcessData(data):
    output = ""
    for i in range(len(data)):
        item = data[i]
        output = output + str(item) + "\n"
    return output

API_KEY = "sk-1234567890abcdef"  # 本番APIキー

Claudeへの依頼：

test_code.pyをレビューしてください。

Skillが適用されると、Claudeは以下のようなレビューを実施します。
実際の出力（Agent Skills適用後）：

総合評価

  - レベル: Critical
  - 概要: 重大なセキュリティ問題（SQLインジェクション、機密情報漏洩）が含まれており、即座の修正が必要です。加えて、PEP 8違反とパフォーマンス上の問題も見られます。

  ---
  指摘事項

  [Critical] Security: SQLインジェクションのリスク

  - 該当箇所: test_code.py:2 getUserData()関数
  - 問題点: ユーザー入力を直接f-stringでSQL文に結合しており、SQLインジェクション攻撃に対して脆弱です
  - 推奨対応: パラメータ化クエリまたはORMを使用する

  # 問題のあるコード
  def getUserData(userId):
      query = f"SELECT * FROM users WHERE id = {userId}"
      result = db.execute(query)
      return result

  # 修正後（パラメータ化クエリ）
  def get_user_data(user_id: int):
      """指定されたユーザーIDのデータを取得する。"""
      query = "SELECT * FROM users WHERE id = ?"
      result = db.execute(query, (user_id,))
      return result

  ---
  [Critical] Security: 機密情報のハードコード

  - 該当箇所: test_code.py:13
  - 問題点: APIキーがソースコードに直接記載されており、バージョン管理システムに保存されるリスクがあります
  - 推奨対応: 環境変数または設定ファイル（.env）を使用し、.gitignoreに追加する

  # 問題のあるコード
  API_KEY = "sk-1234567890abcdef"  # 本番APIキー

  # 修正後
  import os
  from dotenv import load_dotenv

  load_dotenv()
  API_KEY = os.getenv('API_KEY')

  if not API_KEY:
      raise ValueError("API_KEY environment variable is not set")

  ---
  [Medium] PEP 8: 命名規則が非準拠

  - 該当箇所: test_code.py:1, 6
  - 問題点: 関数名と変数名がキャメルケースになっている（PEP 8ではsnake_caseを推奨）
  - 推奨対応: snake_caseに変更する

  # 問題のあるコード
  def getUserData(userId):
      ...

  def ProcessData(data):
      ...

  # 修正後
  def get_user_data(user_id: int):
      """指定されたユーザーIDのデータを取得する。"""
      ...

  def process_data(data: list) -> str:
      """データリストを文字列形式に変換する。"""
      ...

  ---
  [Medium] Performance: 非効率な文字列結合

  - 該当箇所: test_code.py:10 ProcessData()関数
  - 問題点: ループ内で+演算子による文字列結合を繰り返しており、データ量が多いと性能が劣化します
  - 推奨対応: リスト内包表記とjoin()を使用する

  # 問題のあるコード
  def ProcessData(data):
      output = ""
      for i in range(len(data)):
          item = data[i]
          output = output + str(item) + "\n"
      return output

  # 修正後
  def process_data(data: list) -> str:
      """データリストを文字列形式に変換する。"""
      return '\n'.join(str(item) for item in data)

  ---
  [Low] Performance: 非Pythonic なループ

  - 該当箇所: test_code.py:8-9
  - 問題点: for i in range(len(data))は非Pythonic であり、可読性も低い
  - 推奨対応: 直接イテレートする

  # 問題のあるコード
  for i in range(len(data)):
      item = data[i]

  # 修正後
  for item in data:
      # 処理

  ---
  Good Points（良い点）

  - シンプルな構造: 関数が短く、単一責任の原則に従っている
  - 型推論が容易: 関数の引数と戻り値の型が推測しやすい構造になっている

  ---
  修正後の完全なコード例

  """ユーザーデータ処理モジュール。"""

  import os
  from typing import Any, List
  from dotenv import load_dotenv

  # 環境変数の読み込み
  load_dotenv()
  API_KEY = os.getenv('API_KEY')

  if not API_KEY:
      raise ValueError("API_KEY environment variable is not set")


  def get_user_data(user_id: int) -> Any:
      """指定されたユーザーIDのデータを取得する。

      Args:
          user_id: 取得するユーザーのID

      Returns:
          ユーザーデータ
      """
      query = "SELECT * FROM users WHERE id = ?"
      result = db.execute(query, (user_id,))
      return result


  def process_data(data: List[Any]) -> str:
      """データリストを文字列形式に変換する。

      Args:
          data: 処理するデータのリスト

      Returns:
          改行区切りの文字列
      """
      return '\n'.join(str(item) for item in data)

  優先対応: セキュリティの2つの問題（SQLインジェクションと機密情報のハードコード）を最優先で修正してください。

SKILL.mdの指示が反映されているかの確認

実際の出力を見ると、SKILL.mdで定義した内容が反映されています。

  • チェック項目：
    • SQLインジェクション、機密情報、PEP 8、パフォーマンス → すべて指摘されている
  • 出力形式：
    • 総合評価/指摘事項/Good Pointsの構造 → SKILL.mdで定義した通り
    • 各指摘に該当箇所/問題点/推奨対応/修正例 → SKILL.mdで定義した通り
  • 修正例の形式：
    • # 問題のあるコード / # 修正後 → SKILL.mdのExample通り

まとめ

本記事では、Agent SkillsとMCPの違いを明確にし、Claude Codeを使ったPythonコードレビューを例にした実践的なハンズオンを通じて基本を解説しました。

重要ポイントの再確認：

  1. Agent Skillsは複数の環境で利用可能

    • Claude Code（CLI）：ローカルファイルシステムに配置
    • Claude Desktop App / Web：zipファイルでアップロード
    • 一度作成すれば、どの環境でも使える

  2. 使い分けが重要

    • 固定知識・ベストプラクティス → Agent Skills
    • 動的データ取得・外部システム連携 → MCP

  3. SKILL.mdの書き方（公式ベストプラクティス12）

    • YAML frontmatter必須: name と description を必ず含める
    • プログレッシブディスクロージャ: descriptionでClaudeが判断
    • 言語特化: Pythonなど特定言語に最適化
    • 具体的な指示: 抽象的な表現を避ける
    • 豊富な例示: Good/Bad例を3つ以上、実際のコードで

  4. 品質向上のコツ（公式推奨2）

    Anthropic Engineering Blog2では、以下のベストプラクティスが推奨されています：

    "Start with evaluation: Identify specific gaps in your agents' capabilities by running them on representative tasks and observing where they struggle or require additional context. Then build skills incrementally to address these shortcomings."

    • 評価から開始: 実際のコードでテストし、不足を特定
    • 段階的構築: 小さく始めて改善を重ねる

  5. セキュリティ1

    • 信頼できるソースのみ使用
    • 使用前の徹底的な監査
    • 不明なSkillは使用しない

Claude Code以外の環境をお使いの方は、完成したSkillディレクトリをzipファイルに圧縮して、設定 > 機能 からアップロードすることで同様に利用できます。

参考文献

本記事は以下の公式ドキュメントなどを情報源に執筆しています。

Agent Skills 公式リソース

1 Anthropic Agent Skills（公式ドキュメント）
URL: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
Agent Skillsの公式ガイド、API使用方法、セキュリティ考慮事項を網羅。YAML frontmatterの仕様などが記載。Agent Skills使用時のセキュリティガイドライン。

2 Equipping agents for the real world with Agent Skills（Anthropic Engineering Blog）
URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
ベストプラクティスに関して解説。

MCP (Model Context Protocol) 公式リソース

4 Model Context Protocol 公式サイト
URL: https://modelcontextprotocol.io/
MCPの概要。

コミュニティリソース

5 Using skills with Deep Agents（LangChain Blog）
URL: https://blog.langchain.com/using-skills-with-deep-agents/

  1. Agent Skills - Claude Docs ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8

  2. Equipping agents for the real world with Agent Skills - Anthropic Engineering ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8

  3. Skills explained: How Skills compares to prompts, Projects, MCP, and subagents ↩

  4. Model Context Protocol - Official Documentation ↩ ↩2

  5. Using skills with Deep Agents - LangChain Blog ↩ ↩2

  6. Agent Skills - Claude Code Docs ↩ ↩2

  7. Claude Agent Skills: A First Principles Deep Dive ↩

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?