これは、なにをしたくて書いたもの？
Claude Codeのユーザーが拡張できる機能を見ていってみよう、というお題のひとつです。
今回はエージェントスキルについて見ていきます。
なお、サブエージェントもそうでしたが、Geminiの無料版でClaude Codeを使おうとするとレートリミット的に厳しかったです。
エージェントスキル
エージェント スキルとは知識をパッケージ化したものです。エージェントスキルとずっと書いていると長いので、以降は
単に「スキル」と表記することにします。
スキルは以下の要素で構成されます。
スキルは以下の3種類があります。
$HOME/.claude/skills配下に作成され、使用しているユーザーのすべてのプロジェクトで利用できる個人スキル.claude/skills配下に作成され、チーム内で共有できるプロジェクトスキル- プラグインから取得したスキル
スキルの呼び出し方ですが、スキル自体はモデルが呼び出します。Claudeはユーザーのリクエストとスキルの説明から、
スキルを使用するタイミングを自律的に決定します。
How Skills are invoked: Skills are model-invoked—Claude autonomously decides when to use them based on your request and the Skill’s description. This is different from slash commands, which are user-invoked (you explicitly type /command to trigger them).
カスタムスラッシュコマンドは/commandで明示的に呼び出すことができるので、呼び出し方はサブエージェントに
近い感じがしますね。
ベストプラクティスとしては、以下にあるように単機能に特化すること、説明を明確に書くことあたりみたいですね。
説明が明確ではなかった場合は使ってくれないことがあるので、こういうところがトラブルシュートに挙がることに
なります。
Agent Skills / Troubleshooting
スキルの例。
- Agent Skills / Examples / Simple Skill (single file)
SKILL.mdのみで構成された、git diff --statedコマンドを使ってコミットメッセージを作成するスキル
- Agent Skills / Examples / Skill with tool permissions
- ツール（Read、Grep、Glob）を使い、コードレビューを行うスキル
- Agent Skills / Examples / Multi-file Skill
Claude Codeのドキュメントからはこんなところですね。
エージェントスキル？
これだけ見ると、エージェントスキルとカスタムスラッシュコマンドやサブエージェントとの違い、使い分けが
今ひとつわからない気がします。
ここからは、Claudeのドキュメントに書かれているエージェントスキルの話を見ていってみましょう。
スキルのポイントは、オンデマンドで読み込まれることのようです。
Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.
スキルがどのようにして動作するかというところですが、ファイルシステムにアクセスできる仮想マシン上で動作すると
書かれています。
Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member.
Agent Skills / How Skills work
Claude Codeを使っている場合は単にローカルで動作すると捉えればよいみたいですが、
この仕組みでは情報を段階的に読み込むことができるようになるみたいです。これをProgressive Disclosureと呼ぶようです。
This filesystem-based architecture enables progressive disclosure: Claude loads information in stages as needed, rather than consuming context upfront.
ここでいう「段階的」とは、次の3つのレベルがあります。
レベル1はインストラクション（SKILL.md）のFrontmatterに書かれたメタデータで、これは常に読み込まれます。
Agent Skills / How Skills work / Level 1: Metadata (always loaded)
Claudeは起動時にこのメタデータを読み込み、システムプロンプトに追加します。これによりコンテキストを大きく消費
することなく多くのスキルをインストールできます。
レベル2はインストラクション（SKILL.md）の本文で、手順に関する知識（ワークフロー、ベストプラクティス、
ガイダンスなど）が含まれています。
Agent Skills / How Skills work / Level 2: Instructions (loaded when triggered)
ここで本文がコンテキストウィンドウに追加されます。
レベル3は追加のドキュメントやコード、リソースです。これらは必要になった時に読み込まれます。またスクリプトを
使う場合はコンテキストを消費しません。
Agent Skills / How Skills work / Level 3: Resources and code (loaded as needed)
またスクリプトを使うことで決定論的な動作をさせることができます。
このように必要な時に必要なファイルを読み込み、Claudeにタスクを実行させる仕組みがスキルというわけですね。
Agent Skills / How Skills work / The Skills architecture
ちなみに各レベルごとのトークンコストは以下のとおりです。
少なくとも、スキルを追加すると100トークンは消費するということですね。
ベストプラクティスはこちら。
Skill authoring best practices - Claude Docs
少し抜粋してまとめておきましょう。
- Claudeはデフォルトで十分に賢いので、Claudeがまだ知らないと思われる情報のみを簡潔に追加すること
- タスクの内容に応じて、適切な自由度を選択する
- テキストベースの指示では自由度が高く、疑似コードの利用などは中程度、特定のスクリプトの指示などは低い自由度
- スキルの名前は曖昧だったり過度に一般的な名前を避け、動名詞系でなにをするスキルなのか一目でわかるようにする
- Progressive Disclosure（段階的な開示）
- ハイレベルなインストラクションと、必要に応じて参照させるドキュメントなどで構成する
SKILL.mdは500行以下にすること、この制限に近づいたらコンテンツを別々のファイルに分割すること
- 深くネストされた参照を避ける
- スキルから参照するドキュメントは、
SKILL.mdから1階層下にすること SKILL.md→ 別のドキュメント → さらに別のドキュメント、といったネストした参照を繰り返さないこと
- スキルから参照するドキュメントは、
- インストラクションが100行を超える場合は、最初に目次を作成してClaudeが部分的にコンテンツを読んだ場合でも全容を把握できるようにすること
- 複雑なタスクにはワークフローを使用し、必要に応じてチェックリストを設けてチェックさせること
- エラーを自己修復させるフィードバックループを実装すること
あとは上級者向けですね。
最後にチェックリストがついているので、これを見ておくとよいでしょう。
Skill authoring best practices / Checklist for effective Skills
使い分け？
ここまで読んでいくと、スキルがどのようなものかわかってきた気がします。ただ、それはどちらかというとスキルの構成や
スキルを作るにあたってのポイントという感じなのかなと思います。
つまり、Claude Codeが使えるいくつかの仕組みとの使い分けに迷うんだろうな、という気がします。
というか実際によくわからなくなったので、ちゃんとドキュメントを見るなりして理解してみようというのがこのエントリーを
書き始めた主旨だったりします。
なのに、この時点でまだハッキリしていないんですけど。個人的には、このあたりとの使い分けで迷うのではないかなと
思います。
- カスタムスラッシュコマンド（プロンプト）
- サブエージェント
- MCP
そのあたりは、このブログエントリーにまとまっていそうです。
Skills explained: How Skills compares to prompts, Projects, MCP, and subagents | Claude
これを見ると、以下のように捉えるとよいみたいです。
- スキルかプロンプトか？
- 繰り返し必要となる手順や専門知識が必要な場合はスキル
- プロンプトは1度限りの指示（カスタムスラッシュコマンドは繰り返し使える）
- ユーザーのプロンプトによりエージェントがスキルを利用するので、排他的な関係ではない
- スキルかサブエージェントか？
- どのClaudeインスタンスでも必要になる機能の場合はスキル
- 独立したコンテキストとワークフローが必要な場合はサブエージェント
- サブエージェントがスキルを使用することも可能
MCPはツールなので、スキルほど動作がモデルに依存しません。プロンプトによりモデルが使うかどうかを判断するという
意味では似た存在かもしれませんが。
なんとなく、文字通り「エージェント（サブエージェント含む）に能力を付加するものがスキル」といった捉え方をすると
よさそうな気がします。
サブエージェントのようにコンテキストが独立しているわけでもなさそうなので、この点でも「現在のエージェントが
使えるスキル」として見ればいいのかなと。
スキルを比較するとすれば、立ち位置的にはMCPが近いのかなと思います。ユーザーが明示的に呼び出すものでもなく、
エージェントが判断して使うもの、という意味で。
あとはこのあたりも参考に。
How to create Skills for Claude: steps and examples | Claude
それでは、少しスキルを試してみましょう。Claude Code＋Claude Code Router（Gemini）で試します。
環境
今回の環境はこちら。
$ claude --version 2.0.50 (Claude Code) $ ccr version claude-code-router version: 1.0.71
Claude Code RouterはGeminiを使うように設定しています。
$HOME/.claude-code-router/config.json
{ "PORT": 3456, "Providers": [ { "name": "gemini", "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/", "api_key": "xxxxx", "models": ["gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-2.5-pro"], "transformer": { "use": ["gemini"] } } ], "Router": { "default": "gemini,gemini-2.5-flash", "think": "gemini,gemini-2.5-flash", "webSearch": "gemini,gemini-2.5-flash" } }
起動。
$ ccr code
エージェントスキルを使ってみる
それではエージェントスキルを使ってみましょう。
お題をどうしようかと思いましたが、スクリプトを使ってUUID v4を生成するスキルにしてみました。
こんな感じで用意。
.claude/skills/generating-uuid-v4/SKILL.md
--- name: generating-uuid-v4 description: Generate a Version 4 UUID --- # UUIDバージョン4生成 次のスクリプトを実行することで、バージョン4形式のUUIDを得られます。 ```bash ./scripts/generate.sh ``` 結果のサンプルです。 ```bash a3f9272c-a37b-4f12-92cc-b76fdfe64f13 ```
UUID v4を生成するスクリプト。といってもuuidgenコマンドのラッパーでしかないですが。
.claude/skills/generating-uuid-v4/scripts/generate.sh
#!/bin/bash
uuidgen
実行権限の付与。
$ chmod +x .claude/skills/generating-uuid-v4/scripts/generate.sh
Claude Code（Claude Code Router＋Gemini）でUUID v4を生成するように指示してみます。
> バージョン4形式のUUIDを生成してください
するとスキルの利用許可を求められました。スキルを認識していそうです。
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Use skill "generating-uuid-v4"? Claude may use instructions, code, or files from this Skill. Generate a Version 4 UUID (project) Do you want to proceed? ❯ 1. Yes 2. Yes, and don't ask again for generating-uuid-v4 in /home/user/project 3. No, and tell Claude what to do differently (esc)
次にスクリプトの実行許可を求められます。
> The "generating-uuid-v4" skill is running ● Bash(./scripts/generate.sh) ⎿ Running… ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Bash command ./scripts/generate.sh Generate a UUID v4 Do you want to proceed? ❯ 1. Yes 2. Yes, and don't ask again for ./scripts/generate.sh commands in /home/user/project 3. Type here to tell Claude what to do differently
が、プロジェクトのカレントディレクトリーからそのまま実行しようとしたみたいで、エラーになります…。
● Bash(./scripts/generate.sh) ⎿ Error: Exit code 127 /bin/bash: 行 1: ./scripts/generate.sh: そのようなファイルやディレクトリはありません
ここから自分でスクリプトを探して
● Search(pattern: "**/generate.sh") ⎿ Found 1 file (ctrl+o to expand)
再度実行許可を求められました。
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Bash command /home/user/project/.claude/skills/generating-uuid-v4/scripts/generate.sh Generate a UUID v4 Do you want to proceed? ❯ 1. Yes 2. Yes, and don't ask again for similar commands in /home/user/project 3. Type here to tell Claude what to do differently
そして結果が得られましたと。
● Bash(/home/user/projectl/.claude/skills/generating-uuid-v4/scripts/generate.sh) ⎿ 000a1422-5144-4446-9aca-d873ab9fb7ed ● UUIDバージョン4形式のUUIDを生成しました: 000a1422-5144-4446-9aca-d873ab9fb7ed
動くには動きましたが、スクリプトの実行方法がよくなかったですね。またBashツールの許可を求められるのもパスさせたいです。
特にスクリプトをどうするのがいいのかなと思ったのですが、以下のようにスクリプトの場所を参照で教えるだけに
しておきました。あとBashツールをallowed-toolsに追加。
.claude/skills/generating-uuid-v4/SKILL.md
--- name: generating-uuid-v4 description: Generate a Version 4 UUID allowed-tools: Bash --- # UUIDバージョン4生成 [generate.sh](./scripts/generate.sh)スクリプトを実行することで、バージョン4形式のUUIDを得られます。 結果のサンプルです。 ```bash a3f9272c-a37b-4f12-92cc-b76fdfe64f13 ```
Claude Codeを再起動して実行。
> バージョン4形式のUUIDを生成してください ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Use skill "generating-uuid-v4"? Claude may use instructions, code, or files from this Skill. Generate a Version 4 UUID (project) Do you want to proceed? ❯ 1. Yes 2. Yes, and don't ask again for generating-uuid-v4 in /home/user/project 3. No, and tell Claude what to do differently (esc)
依然としてスキルの使用許可は求められますが、スクリプトはそのまま実行できるようになりました。
> The "generating-uuid-v4" skill is running ⎿ Allowed 1 tools for this command ● Bash(./.claude/skills/generating-uuid-v4/scripts/generate.sh) ⎿ 85761bfd-854d-4411-8e85-31840d19c2a3
ただ、ここでGeminiのフリープランのレートリミットを超えてしまいしたが…。
それから、スキルの使用許可を求められるのもなんとかしたいです。
どうにかならないのかな？と思ってこう指定してみたら
.claude/settings.json
{ "permissions": { "allow": [ "Skill" ] } }
なんと動きました（笑）。
> バージョン4形式のUUIDを生成してください ⎿ Allowed 1 tools for this command > The "generating-uuid-v4" skill is running ⎿ Allowed 1 tools for this command ● Bash(./.claude/skills/generating-uuid-v4/scripts/generate.sh) ⎿ 6c3dec17-af34-4e8b-ae95-1c7dc9d32564 ● 6c3dec17-af34-4e8b-ae95-1c7dc9d32564
以下の指定でもOKでしたね。
.claude/settings.json
{ "permissions": { "allow": [ "Skill(generating-uuid-v4)" ] } }
その後にこういうissueも見つけましたが、実際にはどう指定するのが正解なのでしょうか？
[FEATURE] Skill-level permissions · Issue #10833 · anthropics/claude-code · GitHub
ツールに関する権限指定はこちらで確認できるのですが、すべてのツールが列挙されているわけではないようなので
なかなか難しいですね。
Geminiのレートリミット的にも厳しいので、これくらいにしておきましょう。
おわりに
Claude Codeのエージェントスキルについて調べてみて、それからちょっと動かしてみました。
Geminiの無料プランではサブエージェントが厳しかったので、こちらも同じかなと思っていましたがやっぱり…という感じ
でしたね。
まあ、スキルがどういうものかということと、サブエージェントなどの他の仕組みとの使い分けもなんとなくわかった
気がするのでよしとしましょう。
