Claude Code Agent Skillsの設定方法と注意点｜よくある失敗から学ぶ実践ガイド

Claude Code Agent Skillsで失敗しないために

Claude Codeを使って開発作業を効率化しようとすると、次に気になるのが「Agent Skillsをどう設定すればいいのか」という点です。

コード生成だけなら、そこまで深く考えなくても使える場面はあります。

しかし、テスト実行、コードレビュー、ファイル操作、外部ツールとの連携まで任せようとすると、話は変わります。

Agent Skillsは、設定の仕方によって使いやすさも安全性も大きく変わります。

僕が特に大切だと感じているのは、最初から大きな自動化を目指さないことです。

便利そうだからといって、1つのSkillに何でも詰め込むのはおすすめしません。

1つのSkillに役割を詰め込みすぎると、意図しないタイミングで実行されたり、不要なファイルまで読み込んだり、エラーの原因が追えなくなったりします。

Claude Code Agent Skillsは、正しく設計すれば開発の強力な補助になります。

反対に、設定やディレクトリ構成、トークン管理、セキュリティ設計を軽く考えると、コスト増加・情報漏えい・運用トラブルにつながる可能性があります。

この記事では、Claude Code Agent Skillsを設定するときに押さえておきたい基本、よくある失敗、設計・実装・運用時の注意点を、実務で使いやすい形に整理してご紹介します。

Claude Code Agent Skillsでよくある失敗と影響
インストールと起動でつまずきやすいポイント
Agent Skillsの作り方と設計のベストプラクティス
コードレビュー・テスト・運用で確認すべきこと
セキュリティとプライバシーの設計
デバッグ事例と具体的な修正例
活用事例と今後の拡張
まとめ：安全にClaude Code Agent Skillsを使うためのチェックリスト
よくある質問

Claude Code Agent Skillsでよくある失敗と影響

Agent Skillsは何のために使うものか

Claude CodeのAgent Skillsは、AIエージェントに特定の作業手順や外部ツール連携を覚えさせるための仕組みです。

たとえば、次のような作業をSkillとして切り出せます。

特定ディレクトリのコードレビュー
テストコマンドの実行
LinterやFormatterの実行
Pull Request用の説明文作成
ログ解析
セキュリティチェック
社内ツールやAPIとの連携

ここで大切なのは、Skillを「何でもできる万能機能」として扱わないことです。

Agent Skillsは、役割を絞って設定したほうが安定します。

たとえば、

テストを実行するSkill
PythonファイルだけをレビューするSkill
差分からPR説明文を作るSkill

このように目的を小さく分けておくと、Claude Codeが必要な場面で正しく使いやすくなります。

便利にしようとして広げすぎるほど、逆に使いにくくなる。

Agent Skillsでは、この考え方がかなり重要です。

初期設定で起きやすいミス

最初につまずきやすいのは、環境変数や定義ファイルの配置ミスです。

APIキー、アクセストークン、外部サービスの認証情報などを扱う場合、.env の置き場所や読み込み方法を間違えると、Skillが実行時に認証情報を取得できません。

また、Skillの説明ファイルにあたる description.json や description.md の記述ミスもよくあります。

JSON形式の場合、次のような小さなミスでも認識されない原因になります。

末尾のカンマが残っている
ダブルクォーテーションが閉じていない
必須パラメータの定義が抜けている
ファイル名や配置場所が間違っている
Skill本体と説明ファイルの対応が分かりにくい

こうしたミスは、必ずしも分かりやすいエラーとして表示されるとは限りません。

そのため、

「Skillを作ったのにClaude Codeから見えていない」
「呼び出されない」
「期待通りに動かない」

という状態になりやすいです。

Agent Skillsを作るときは、コードだけでなく、説明ファイルや配置場所まで含めて確認する必要があります。

コンテキストを広げすぎる失敗

Claude Code Agent Skillsで特に注意したいのが、コンテキストの肥大化です。

「念のためプロジェクト全体を読ませよう」

この考え方は、かなり危険です。

必要のないログファイル、ビルド成果物、node_modules、venv、巨大なJSON、過去のダンプファイルまで読み込ませると、トークン消費が一気に増えます。

トークンが増えると、単にコストが上がるだけではありません。

Claude Codeが本来の指示を見失いやすくなり、回答や実行内容の精度が下がることもあります。

Agent Skillsを設定するときは、読み込む範囲を最初から制限することが大切です。

たとえば、次のようなルールを決めておきます。

対象ファイルは src/ 配下だけにする
node_modules/ や dist/ は読み込まない
ログファイルは最新の1件だけにする
セキュリティレビューでは差分ファイルだけを対象にする
画像、バイナリ、大容量ファイルは除外する

「Claudeにたくさん渡せば良くなる」と考えるのではなく、必要な情報だけを渡すほうが安定します。

情報量は多ければ良いわけではありません。

必要なものだけ渡す。余計なものは渡さない。

これが、Agent Skillsを安定させる基本です。

Agentとサブエージェントの使い分けミス

1つのAgentに、コード生成、テスト、レビュー、デプロイ、通知まで全部任せようとすると、設定が一気に複雑になります。

役割が多すぎるAgentは、どのタイミングで何をすべきか判断しづらくなります。

その結果、テストだけしてほしい場面で修正まで始めたり、レビューだけでよい場面でファイルを書き換えたりする可能性があります。

僕は、Agent Skillsを設計するときは、メインAgentとサブエージェントを分ける考え方が扱いやすいと感じています。

メインAgentは、作業全体の流れを整理します。

サブエージェントは、特定の作業だけを担当します。

種類	役割	扱う情報	メリット
メインAgent	作業の分解、進行管理、最終判断	プロジェクト全体の概要	全体を見失いにくい
サブエージェント	テスト実行、レビュー、ログ解析など	対象ファイルや実行結果のみ	トークンを抑えやすい
補助ツール	Formatter、Linter、通知など	コマンド実行結果	再利用しやすい

このように責任範囲を分けると、エラーが起きたときも原因を追いやすくなります。

1つにまとめるほど楽になるのではなく、分けるほど運用しやすくなる。

Agent Skillsでは、この感覚を持っておくと失敗しにくいです。

公開や共有で起きるセキュリティ上の落とし穴

Agent Skillsは、ローカルファイルや外部ツールにアクセスできる設計になることがあります。

そのため、公開リポジトリやチーム共有環境で使う場合は、セキュリティを強く意識する必要があります。

特に避けたいのは、認証情報や社内情報がSkill経由で外に出てしまうことです。

よくある危険な例は、次のとおりです。

APIキーをコードに直接書く
.env を誤ってGit管理する
社内ドメインやプロジェクト名がログに残る
デバッグログを外部ストレージに保存する
権限の強すぎるトークンを使う
Skillが読み込めるディレクトリを制限していない

Agent Skillsは便利です。

ただし、自由に動ける範囲を広げすぎると、その分リスクも大きくなります。

最初から、

どこまで読めるか
どこまで書けるか
どの外部サービスに接続できるか

を決めておくことが重要です。

インストールと起動でつまずきやすいポイント

CLIのインストールと確認

Claude Codeを使うには、まずCLI環境を整えます。

Node.js環境で導入する場合は、一般的に次のような形でインストールします。

npm install -g @anthropic-ai/claude-code

インストール後は、バージョン確認を行います。

claude --version

ここでコマンドが見つからない場合、インストール自体ではなく、PATH の問題であることも多いです。

特に、npmのグローバルインストール先がシェルから参照できていない場合、claude コマンドが使えません。

また、macOSやLinuxでは権限エラーが出ることもあります。

npmの権限エラーに注意する

npm install -g を使うと、環境によっては EACCES のような権限エラーが発生します。

この場合、安易に sudo を付けて回避するのはおすすめしません。

グローバルパッケージの権限が複雑になり、後から更新や削除が面倒になることがあるからです。

Node.jsのバージョン管理ツールを使っている場合は、Node本体やnpmの管理パスを確認しましょう。

チーム開発では、各メンバーのNode.jsバージョンが違うだけで挙動が変わることもあります。

インストール前に、最低限次のコマンドで状態を確認しておくと安心です。

node -v
npm -v
which node
which npm
which claude

インストールできたかどうかだけでなく、どの環境のNodeやnpmを使っているかも確認する。

ここを見落とすと、あとで原因不明のエラーに悩まされやすくなります。

外部CLIツールのPATHを確認する

Agent SkillsからGit、Linter、Formatter、テストランナーなどを呼び出す場合、Claude Codeを実行する環境から、それらのコマンドが見えている必要があります。

たとえば、Skill内で pytest を実行する場合、ターミナルでは動くのにClaude Code経由では動かないことがあります。

原因としては、次のようなものがあります。

仮想環境が有効になっていない
PATH が異なる
.zshrc や .bashrc が読み込まれていない
CI環境とローカル環境でコマンドの場所が違う
実行ユーザーが異なる

まずは、Skillから呼び出す予定のコマンドを単体で実行して確認します。

git --version
python --version
node --version
pytest --version
eslint --version

Claude Code Agent Skillsを安定させるには、AI側の設定だけでなく、実行環境のコマンド解決も重要です。

description.jsonやdescription.mdの配置場所

Agent Skillsでは、Claude Codeに「このSkillは何をするものか」を伝える説明ファイルが重要になります。

代表的には、次のような構成にします。

project-root/
  .claude/
    skills/
      sample_skill/
        description.json
        run.py

または、Markdown形式で説明を書く場合もあります。

project-root/
  .claude/
    skills/
      sample_skill/
        description.md
        script.js

大切なのは、Skill本体と説明ファイルの対応関係を分かりやすくすることです。

Skillが増えてくると、どの説明ファイルがどのスクリプトを呼ぶのか分からなくなります。

最初は問題がなくても、数が増えると保守が難しくなります。

僕は、Skillごとに1ディレクトリを作り、その中に説明ファイル、実行スクリプト、テスト、READMEをまとめる構成が扱いやすいと考えています。

.claude/
  skills/
    code_review/
      description.json
      run.py
      README.md
      tests/
    run_tests/
      description.json
      index.js
      README.md
      tests/

Skillごとに箱を分ける。

これだけでも、あとから見直すときの負担がかなり減ります。

起動時のエラーとログの見方

起動時や実行時によくあるエラーには、次のようなものがあります。

コマンドが見つからない
実行権限がない
環境変数が読み込めていない
ファイルパスが間違っている
JSONの構文が壊れている
外部APIの認証に失敗している

シェルスクリプトを呼び出す場合は、実行権限も確認します。

chmod +x path/to/script.sh

PythonやNode.jsのスクリプトを実行する場合も、実行方法を明確にしておくと安全です。

python scripts/run_skill.py
node scripts/index.js

エラーが出たら、Claude Code側だけを見るのではなく、同じコマンドをローカルのターミナルで直接実行してみましょう。

Claude Codeを介さずに失敗するなら、Skill以前にスクリプトや環境の問題です。

AIの問題だと決めつける前に、まず通常のコマンドとして動くか確認する。

これが、デバッグの基本です。

Agent Skillsの作り方と設計のベストプラクティス

最初は小さく作る

Agent Skillsは、最初から大きく作らないほうがよいです。

いきなり、

「コードを解析して、修正して、テストして、コミットして、PRまで作る」

というSkillを作ると、どこで失敗しているのか分からなくなります。

おすすめは、段階的に機能を増やす方法です。

最初の段階では、ファイルを1つ読み込んで内容を返すだけにします。

次の段階では、対象ファイルを絞り込みます。

その次に、テストやLinterなどの外部コマンドを呼び出します。

最後に、エラーハンドリングや構造化レスポンスを追加します。

このように分けると、問題が起きたときに原因を切り分けやすくなります。

小さく作ることは、遠回りではありません。

むしろ、あとで安全に広げるための近道です。

descriptionは具体的に書く

Skillの説明は、抽象的に書かないことが重要です。

悪い例は、次のような説明です。

{
  "name": "review_code",
  "description": "Review code and fix problems."
}

これだと、どのコードを、どの観点で、どこまで実行してよいのか分かりません。

より安全な例は、次のような書き方です。

{
  "name": "run_secure_code_review",
  "description": "Use this tool only when reviewing staged Python files for security vulnerabilities. Do not use it for syntax checking, formatting, or general code improvement.",
  "parameters": {
    "type": "object",
    "properties": {
      "target_dir": {
        "type": "string",
        "description": "The relative or absolute path to the directory containing target Python files."
      }
    },
    "required": ["target_dir"]
  }
}

ポイントは、使う場面と使わない場面を明確に書くことです。

たとえば、

「Pythonファイルのセキュリティレビュー専用」
「Formatter目的では使わない」
「対象ディレクトリを必須にする」

このように制約を書いておくと、誤実行を減らせます。

Agent Skillsでは、曖昧な説明ほど危険です。

Claude Codeに正しく使ってもらうためにも、descriptionは具体的に書きましょう。

Skillの責任範囲を絞る

Skillは、単一責任に近い形で設計したほうが安定します。

たとえば、次のように分けます。

skills/
  lint_code/
  run_tests/
  summarize_diff/
  create_pr_description/
  security_review/

この分け方にすると、Claude Codeは必要な処理だけを選びやすくなります。

反対に、次のようなSkillは危険です。

skills/
  do_everything/

何でもできるSkillは便利に見えます。

しかし、意図しない動作が起きやすくなります。

また、ログを見ても、どの処理で失敗したのか判断しにくくなります。

Skillは大きくするほど賢くなるのではなく、役割を絞るほど扱いやすくなります。

メインAgentとサブエージェントを分ける

実務で扱いやすいのは、メインAgentが全体方針を決め、サブエージェントが個別処理を担当する構成です。

たとえば、Pull Request作成を自動化する場合、1つのSkillに全部入れるのではなく、次のように分けます。

main_agent:
  - 作業目的を確認
  - 差分を確認
  - 必要なSkillを呼び出す
  - 最終結果をまとめる

sub_agents:
  - diff_summarizer
  - test_runner
  - lint_runner
  - pr_description_generator

この構成にすると、差分要約だけを改善したい場合は diff_summarizer だけ修正できます。

テスト実行に問題がある場合は test_runner だけ確認できます。

保守性を高めるには、全部入りを避けて、部品として再利用できるSkillにしておくことが大切です。

再利用できるtoolやpluginとして切り出す

複数のSkillで共通して使う処理は、別のtoolやpluginとして切り出すと便利です。

たとえば、次のような処理は共通化しやすいです。

Git差分の取得
JSONバリデーション
Slack通知
ログ整形
ファイル存在チェック
コマンド実行ラッパー
タイムアウト処理

Skillごとに同じ処理を書くと、修正漏れが起きます。

共通処理をモジュール化しておけば、エラーハンドリングやログ形式も統一できます。

よく使う処理は、Skillに直書きしない。

これも、後から運用をラクにするための大事な考え方です。

コードレビュー・テスト・運用で確認すべきこと

コードレビューで見るべきポイント

Agent Skillsのコードレビューでは、通常のアプリケーションコードとは少し違う観点が必要です。

特に確認したいのは、次の点です。

APIキーやトークンを直書きしていないか
読み込むファイル範囲が広すぎないか
書き込み可能なディレクトリが制限されているか
外部コマンドの引数を安全に扱っているか
エラー時に再帰的に同じ処理を繰り返さないか
タイムアウトが設定されているか
出力がClaude Codeにとって解釈しやすい形式になっているか

Agent Skillsは、AIに作業を任せるための設定です。

そのため、「人間が見れば分かる」では不十分です。

Claude Codeが次の判断に使える形で出力する必要があります。

エラーが起きたときも、単に失敗したと返すのではなく、原因や次の対応が分かる形にしておくと安定します。

CI/CDに組み込む

チームでAgent Skillsを使う場合、手元で動くことだけを確認して終わらせないほうがよいです。

リポジトリに入れるなら、最低限の構文チェックやテストをCIで回しましょう。

運用フローの例は次のとおりです。

Local Commit
  ↓
Pre-commit hookでJSONやYAMLを検証
  ↓
Pull Request
  ↓
CIでSkillのダミー実行テスト
  ↓
Code Review
  ↓
Merge
  ↓
チーム環境へ反映

description.json の構文チェックには jq が使えます。

jq . .claude/skills/sample_skill/description.json

Pythonスクリプトなら、最低限の単体テストも用意します。

pytest tests/

Node.jsなら、Lintやテストを組み込みます。

npm test
npm run lint

Skillは一度作ったら終わりではありません。

Claude Codeの使い方やプロジェクト構成が変わるたびに、Skill側も見直す必要があります。

Skillもコードと同じように、テストしながら育てるものです。

レスポンスは構造化する

Skillが返すレスポンスは、Claude Codeが次の行動を判断する材料になります。

そのため、エラー時に単に Error と返すだけでは不十分です。

原因、現在の状態、次に取るべき対応を含めると、Claude Codeが復旧しやすくなります。

たとえば、次のようなレスポンスです。

{
  "status": "error",
  "reason": "target_file is missing",
  "current_state": "No file path was provided to the skill.",
  "suggested_action": "Provide a valid file path and run the skill again."
}

成功時も、できるだけ一定の形式で返します。

{
  "status": "success",
  "summary": "Lint completed successfully.",
  "files_checked": 12,
  "warnings": []
}

このようにすると、ログ解析もしやすくなります。

成功も失敗も、同じ型で返す。

それだけで、Agent Skillsの扱いやすさはかなり変わります。

チーム開発ではローカル差分を減らす

チームでAgent Skillsを使う場合、メンバーごとにローカル設定が違うと、同じSkillでも挙動が変わります。

そのため、Skill定義はGitで管理します。

各自がローカルで勝手に書き換えるのではなく、Pull Requestを通して変更する運用にしたほうが安全です。

おすすめのルールは次のようなものです。

.claude/skills/ はGit管理する
Skill変更はPull Requestでレビューする
個人用Skillとチーム共有Skillを分ける
本番用トークンをローカルに置かない
READMEに使い方と制約を書く
バージョンを明記する

チームで使うSkillは、コードと同じくらい慎重に管理したほうがよいです。

便利だからこそ、属人化させない。

この意識があるだけで、後々のトラブルをかなり減らせます。

セキュリティとプライバシーの設計

認証情報は必ず環境変数で扱う

Agent Skillsから外部APIを呼び出す場合、APIキーやトークンをコードに直接書いてはいけません。

悪い例です。

API_KEY = "sk-xxxxxxxxxxxxxxxx"

安全な例です。

import os

api_key = os.environ.get("API_KEY")

Node.jsの場合も同じです。

const apiKey = process.env.API_KEY;

CI環境では、GitHub ActionsのSecretsなどを使います。

クラウド環境では、AWS Secrets ManagerやGCP Secret Managerのような仕組みと組み合わせます。

ポイントは、認証情報をGitに入れないことです。

また、ログにも出さないようにします。

APIキーは、一度漏れると被害が広がる可能性があります。

「あとで消せばいい」は通用しません。

最初から出さない設計にしておきましょう。

読み込めるファイル範囲を制限する

Claude Code Agent Skillsでは、読み込むファイルの範囲を明確に制限します。

特に、次のようなファイルは不用意に読み込ませないほうがよいです。

.env
秘密鍵
顧客情報
本番ログ
認証情報を含む設定ファイル
社内限定ドキュメント
大容量のダンプファイル
バイナリファイル

除外ルールは、.gitignore のような考え方で用意します。

プロジェクトによっては、Claude Code用に読み込み対象外ディレクトリを明示する運用も必要です。

読める範囲を広げるほど便利になる一方で、漏れる範囲も広がります。

だからこそ、最初に制限しておくことが大切です。

公開前のDisclosureチェック

自作したSkillをGitHubで公開したり、社内の別チームに共有したりする場合は、情報開示のチェックを行います。

確認すべきポイントは次のとおりです。

テストデータに本物の顧客情報が入っていないか
社内ドメインやIPアドレスが残っていないか
description.json に機密プロジェクト名が入っていないか
エラーログに認証情報が出力されないか
サンプルコードに実在のトークンが含まれていないか
外部ストレージのURLが公開状態になっていないか

Agent Skillsは、設定ファイルやサンプルコードに機密情報が紛れ込みやすいです。

そのため、公開前の確認は欠かせません。

公開してから気づくのでは遅い情報があります。

共有前に、必ず一度チェックしましょう。

外部ライブラリの依存関係も確認する

Agent Skillsでnpmやpipのライブラリを使う場合、依存関係の脆弱性にも注意します。

Node.jsなら、次のように確認できます。

npm audit

Pythonなら、pip-audit などを使います。

pip-audit

外部ライブラリを入れると実装は楽になります。

ただし、サプライチェーンリスクも増えます。

不要な依存は増やさず、使う場合は定期的に更新と監査を行うことが大切です。

便利なライブラリほど、管理もセットで考える。

Agent Skillsを安全に使うなら、この視点は外せません。

デバッグ事例と具体的な修正例

Pythonスクリプトでよくある失敗

まず、よくない例です。

# bad_skill.py
import sys

target = sys.argv[1]
data = open(target).read()
print(data)

このコードは、引数がないと IndexError になります。

ファイルが存在しない場合も例外がそのまま出ます。

さらに、エラーが起きたときにClaude Codeが次に何をすればよいか判断できません。

Agent Skillsで使うスクリプトは、エラー時ほど丁寧に返す必要があります。

修正例です。

# good_skill.py
import sys
import os
import json

def main():
    if len(sys.argv) < 2:
        print(json.dumps({
            "status": "error",
            "reason": "Missing argument 'target_file'.",
            "suggested_action": "Provide a valid file path."
        }, ensure_ascii=False))
        sys.exit(1)

    target = sys.argv[1]

    if not os.path.exists(target):
        print(json.dumps({
            "status": "error",
            "reason": f"File not found: {target}",
            "suggested_action": "Check the file path and run again."
        }, ensure_ascii=False))
        sys.exit(1)

    try:
        with open(target, "r", encoding="utf-8") as f:
            content = f.read()

        print(json.dumps({
            "status": "success",
            "content": content
        }, ensure_ascii=False))

    except Exception as e:
        print(json.dumps({
            "status": "error",
            "reason": str(e),
            "suggested_action": "Check file encoding and permissions."
        }, ensure_ascii=False))
        sys.exit(1)

if __name__ == "__main__":
    main()

このように、成功時も失敗時もJSONで返すと、Claude Codeが結果を扱いやすくなります。

人間に伝わるエラーではなく、AIが次に動けるエラーにする。

ここがポイントです。

Node.jsで外部コマンドを呼ぶときの注意点

Node.jsでSkillを作る場合、外部コマンドを呼び出すことがあります。

そのときに注意したいのが、タイムアウトです。

タイムアウトがないと、コマンドが終わらずに処理が止まることがあります。

安全な実装例です。

const { exec } = require("child_process");

function runCommand(command) {
  return new Promise((resolve) => {
    exec(command, { timeout: 5000 }, (error, stdout, stderr) => {
      if (error) {
        resolve({
          success: false,
          error: stderr.trim() || error.message
        });
        return;
      }

      resolve({
        success: true,
        output: stdout.trim()
      });
    });
  });
}

ここでは、timeout: 5000 を設定しています。

これにより、コマンドが長時間止まったままになることを防げます。

ただし、外部から受け取った文字列をそのまま exec に渡すのは危険です。

コマンドインジェクションのリスクがあるため、実行できるコマンドを限定したり、引数を検証したりする必要があります。

外部コマンドは便利ですが、入力を信じすぎないことが重要です。

description.jsonの出力確認

description.json は、作ったら必ず構文チェックをします。

jq . .claude/skills/sample_skill/description.json

構文が壊れていると、Skillが認識されない原因になります。

また、パラメータ定義も確認します。

必須項目が足りない場合に、想定どおりエラーになるかをテストしましょう。

たとえば、次のような観点で確認します。

必須パラメータがない場合に失敗するか
文字列を期待する場所に数値を渡した場合にどうなるか
存在しないパスを渡した場合に分かりやすいエラーになるか
成功時のレスポンス形式が一定か
失敗時のレスポンスに原因と対応策が含まれているか

Agent Skillsは、正常系だけでなく異常系の設計が重要です。

うまくいくときより、失敗したときにどう戻れるか。

ここを見ておくと、実運用でかなり助かります。

バグを切り分ける手順

Skillが意図通りに動かない場合、僕は次の順番で確認します。

まず、Claude CodeがSkillに渡した引数を確認します。

次に、その引数を使って、ターミナルから直接スクリプトを実行します。

Claude Codeを介さずに再現するかどうかを見ます。

python good_skill.py path/to/file.py

ここで同じエラーが出るなら、Skill本体の問題です。

ターミナルでは成功するのにClaude Code経由で失敗するなら、実行環境、PATH、環境変数、権限の問題を疑います。

切り分けの流れは次のようになります。

1. Claude Codeが渡した引数を確認
2. 同じ引数でローカル実行
3. エラーが再現するか確認
4. PATHや環境変数を確認
5. 権限とファイルパスを確認
6. 修正後に単体テスト
7. Claude Code経由で再テスト

この順番にすると、AI側の問題なのか、スクリプト側の問題なのか、環境側の問題なのかを分けやすくなります。

原因を一気に探さない。順番に潰す。

これが、Agent Skillsのデバッグでは一番確実です。

活用事例と今後の拡張

Pull Request作成を補助するSkill

実用性が高いのは、Pull Request作成を補助するSkillです。

たとえば、Git差分を取得し、変更内容を要約し、PR本文の下書きを作成します。

流れは次のようになります。

git diffを取得
  ↓
変更ファイルを分類
  ↓
変更内容を要約
  ↓
影響範囲を整理
  ↓
PR本文を作成

このSkillを使うと、毎回のPR作成にかかる時間を減らせます。

ただし、自動生成されたPR本文をそのまま使うのはおすすめしません。

最後は人間が確認する運用にしたほうが安全です。

Agent Skillsは、作業の下書きや整理にはとても役立ちます。

一方で、最終判断まで丸投げしないことが大切です。

レガシーコード移行に使う

古いコードの移行にもAgent Skillsは役立ちます。

たとえば、古いライブラリの書き方を新しい形式に変換したり、非推奨APIを洗い出したりできます。

ただし、移行系のSkillは書き込み操作を伴うため、慎重に扱う必要があります。

安全に使うなら、次のような流れにします。

対象ファイルを一覧化
  ↓
変更案を生成
  ↓
差分を確認
  ↓
テストを実行
  ↓
人間がレビュー
  ↓
反映

いきなり自動で全ファイルを書き換えるのではなく、差分確認とテストを挟むことが大切です。

レガシーコード移行では、速さよりも戻せることが重要です。

変更前後の差分を確認できる形にしておくと、安心して使いやすくなります。

他のLLM環境でも使いやすい設計にする

Claude Code向けに作る場合でも、将来的に他のLLMやエージェント環境へ応用する可能性があります。

そのため、パラメータ定義はなるべく標準的なJSON Schemaに近い形にしておくと扱いやすいです。

また、スクリプト本体もClaude Code専用の前提を減らし、標準入力、標準出力、環境変数で動くようにしておくと再利用しやすくなります。

たとえば、次のような設計です。

入力はJSONで受け取る
出力もJSONで返す
認証情報は環境変数で読む
エラー形式を統一する
実行コマンドをREADMEに書く
Claude Codeに依存しない単体テストを用意する

この形にしておくと、後から別のツールに組み込みやすくなります。

Claude Code専用に閉じすぎない設計にしておく。

これも、長く使うためには大切なポイントです。

まとめ：安全にClaude Code Agent Skillsを使うためのチェックリスト

Claude Code Agent Skillsは、開発作業を効率化する強力な仕組みです。

ただし、設定を雑にすると、意図しない実行、トークン消費の増加、情報漏えい、チーム内での挙動差分などにつながります。

安全に使うためには、最初から大きな自動化を作るのではなく、小さなSkillを段階的に作ることが大切です。

また、Skillの説明は具体的に書き、使う場面と使わない場面を明確にします。

特に重要なのは、コンテキストを広げすぎないことです。

必要なファイルだけを読み込み、不要なディレクトリや機密情報は対象外にします。

最後に、Agent Skillsはコードと同じようにレビューし、テストし、Gitで管理します。

個人の便利機能として始める場合でも、後からチームで使う可能性があるなら、最初から運用しやすい構成にしておくと安心です。

必須チェックリスト

最後に、Claude Code Agent Skillsを安全に使うためのチェックリストを紹介します。

Skillの役割は1つに絞っているか
メインAgentとサブエージェントの役割が分かれているか
description.json や description.md の内容は具体的か
使う場面と使わない場面が明記されているか
不要なファイルをコンテキストに含めていないか
node_modules、venv、ログ、ビルド成果物を除外しているか
APIキーやトークンをコードに直書きしていないか
.env をGit管理していないか
エラー時に構造化されたレスポンスを返しているか
タイムアウト処理を入れているか
ローカル実行で再現確認できるか
CIで構文チェックやテストを実行しているか
チーム共有SkillはPull Requestで管理しているか

このチェック項目を押さえておくだけでも、よくある失敗はかなり防げます。

Agent Skillsは、作ることよりも、安全に運用できる形にすることが重要です。

サンプルdescription.json

新しいSkillを作るときは、次のようなテンプレートから始めると整理しやすいです。

{
  "name": "custom_task_runner",
  "description": "Execute a specific local development task. Use this tool only for test, lint, or format tasks. Validate all inputs before execution and return a structured JSON response.",
  "parameters": {
    "type": "object",
    "properties": {
      "command_type": {
        "type": "string",
        "enum": ["test", "lint", "format"],
        "description": "The type of development task to execute."
      },
      "project_path": {
        "type": "string",
        "description": "The target project directory path."
      }
    },
    "required": ["command_type", "project_path"]
  }
}

配置例です。

.claude/
  skills/
    custom_task_runner/
      description.json
      run.py
      README.md
      tests/

使い方は次の流れです。

1. .claude/skills/custom_task_runner/ を作成
2. description.json を配置
3. 実行スクリプトを配置
4. ローカルで単体実行
5. JSON構文をチェック
6. Claude Codeから認識されるか確認
7. 小さなタスクで動作確認

Claude Code Agent Skillsは、設計次第で開発の頼れる仕組みになります。

まずは小さく作り、対象範囲を絞り、ログとエラーを分かりやすく返すところから始めるのが安全です。

小さく作る。広げすぎない。秘密情報を渡さない。

この3つを守るだけでも、Agent Skillsの失敗はかなり減らせます。

よくある質問

Q1. Claude Code Agent Skillsは最初に何から作るべきですか？

最初は、ファイルを1つ読み込んで内容を返すだけの小さなSkillから作るのがおすすめです。

いきなりコード修正やデプロイまで任せると、問題が起きたときに原因を切り分けにくくなります。

まずは読み込み、次に検証、次に外部コマンド実行という順番で広げると安全です。

最初から完成形を作ろうとしないことが大切です。

Q2. 1つのSkillに複数の作業を入れてもよいですか？

できるだけ避けたほうがよいです。

テスト、Lint、レビュー、PR作成などを1つにまとめると、Skillの責任範囲が広くなりすぎます。

役割ごとに分けたほうが、Claude Codeが適切な場面で呼び出しやすくなり、保守もしやすくなります。

「全部入り」は便利そうに見えて、あとで管理が大変になります。

Q3. description.jsonには何を書けばよいですか？

Skill名、説明、入力パラメータ、必須項目を書きます。

特に大切なのは説明文です。

「何をするSkillか」だけでなく、「どんな場面で使うか」「どんな場面では使わないか」まで書くと誤実行を減らせます。

曖昧な説明にすると、Claude Codeが意図しない場面で呼び出す可能性があります。

Q4. トークン消費を抑えるにはどうすればよいですか？

読み込むファイル範囲を制限することが最も重要です。

node_modules、venv、ビルド成果物、ログ、大容量ファイル、機密ファイルは除外しましょう。

必要なファイルだけを対象にし、差分ベースで処理する設計にすると、トークン消費を抑えやすくなります。

たくさん読ませるより、必要な情報だけ読ませるほうが安定します。

Q5. Agent Skillsをチームで共有するときの注意点は何ですか？

Gitで管理し、Pull Requestでレビューする運用にすることです。

各メンバーがローカルで自由に書き換えると、同じSkillでも挙動が変わります。

READMEに使い方、前提環境、必要な環境変数、禁止事項を書き、CIで構文チェックや簡単な実行テストを行うと安定します。

チームで使うなら、Agent Skillsも通常のコードと同じように扱いましょう。