これは、なにをしたくて書いたもの？
前にClaude Codeのスキルに関するエントリーを書きました。
Claude Codeのエージェントスキルってなんだ？ - CLOVER🍀
ですが、この時からスキルで設定できることも変わっていますし、カスタムスラッシュコマンドと統合されたり
しているのでこのタイミングで1度見直しておこうということで。
なお、カスタムスラッシュコマンドがスキルに統合されたという点については前に書きました。
Claude Codeの（カスタム）スラッシュコマンドがスキルに統合されたという話 - CLOVER🍀
スキル？
Claude Codeのスキルに関するページはこちらです。
Extend Claude with skills - Claude Code Docs
以前、スキルに関するエントリーを書いた時からページの内容がだいぶ変わっていて、前のエントリーは
もはやほとんど役に立ちませんね…。
あらためて見直しましょう。
スキルはClaudeの機能を拡張するものとされています。指示を含んだSKILL.mdを作成すると、Claudeは
ツールキットに追加します。スキルはClaudeが必要に応じて使うこともあれば、/skill-nameのように
直接呼び出すこともできます。
Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name
これが今の「スキル」の概要です。
なお、スキルに関するClaude CodeおよびClaudeのドキュメントはこのあたりを参照しましょう。
Extend Claude with skills - Claude Code Docs
Agent Skills - Claude API Docs
A complete guide to building skills for Claude | Claude
標準化されたスキル
スキルは「Agent Skills」として標準化されており、Claude Codeのスキルはこれに準拠しています。
Claude Codeのドキュメントを見ていけば同じような内容は把握できそうですが、他のコーディングエージェントで
スキルを使う場合は標準化された内容と固有のドキュメントを見ていくことになるんでしょうね。
今回は「Agent Skills」にはあまり触れないことにします。
あらためてスキルを見直す
配置場所
スキルは以下に配置するルールになっています。
- 企業設定
$HOME/.claude/skills/<skill-name>/SKILL.md… すべてのプロジェクトで有効なスキル.claude/skills/<skill-name>/SKILL.md… スキルが配置されたプロジェクトで有効なスキル<plugin>/skills/<skill-name>/SKILL.md… プラグインとして配布されるスキル
Extend Claude with skills / Getting started / Where skills live
優先度は上に行くほど高く、同じ名前のスキルがあった場合はプロジェクトレベルよりもユーザーレベルの
配置場所にあるスキルの方が優先されることになります。
また従来のカスタムスラッシュコマンドとスキルの名前が衝突した場合は、スキルが優先されます。
ネストしたディレクトリーに.claude/skillsディレクトリーが含まれている場合は、この中にあるスキルも
Claude Codeは検出します。
設定
Extend Claude with skills / Configure skills
スキルの種類
スキルには任意のプロンプトとファイルを含めることができますが、なにを含めるべきかはスキルの種類によって
決まります。スキルは、リファレンスコンテンツとタスクコンテンツの2つがあるとされています。
Extend Claude with skills / Configure skills / Types of skill content
リファレンスコンテンツは知識に関するものです。規約、パターン、スタイルガイドやドメイン知識をClaudeに
与えます。このコンテンツはインラインで実行されるため、Claudeはユーザーとの会話の中でスキルを
活用できます。
--- name: api-conventions description: API design patterns for this codebase --- When writing API endpoints: - Use RESTful naming conventions - Return consistent error formats - Include request validation
もうひとつはタスクコンテンツで、デプロイやコミット、コード生成といった特定のアクションについて
Claudeにステップバイステップで指示を与えます。これらのアクションは実行タイミングをClaudeに
判断させるのではなく、/skill-nameで直接実行したくなる場合が多いでしょう。Claudeが自動的に
実行しないようにするにはfrontmatterにdisable-model-invocation: trueを追加します。
--- name: deploy description: Deploy the application to production context: fork disable-model-invocation: true --- Deploy the application: 1. Run the test suite 2. Build the application 3. Push to the deployment target
Frontmatterと引数
Frontmatterでは以下の設定ができます。
- name … スキルの表示名
- description … スキルの機能と使用タイミング
- argument-hint … オートコンプリート中に表示されるヒントで、必要な引数を表示する
- disable-model-invocation … trueにするとClaudeがスキルを自動で読み込まないようになり、
/skill-nameで実行するワークフローで使用する。デフォルトはfalse - user-invocable … falseにするとユーザーから直接呼び出せなくなる。デフォルトはtrue
- allowed-tools … このスキルが有効な場合にClaudeが許可を求めず使用できるツール
- model … 使用するモデル
- context … フォークされたサブエージェントのコンテキストで実行するにはforkを指定する
- agent …
context: forkを指定した時にどのサブエージェントで実行するかを指定する - hooks … スキルのライフサイクルをスコープとするフック
Extend Claude with skills / Configure skills / Frontmatter reference
disable-model-invocationやuser-invocableについては、こちらでも書きました。
Claude Codeの（カスタム）スラッシュコマンドがスキルに統合されたという話 - CLOVER🍀
また引数をとることもできます。
$ARGUMENTS… スキルの呼び出し時に渡されたすべての引数$ARGUMENTS[N]… インデックスで指定した特定の引数にアクセスする。たとえば最初の引数にアクセスする場合は$ARGUMENTS[0]とする$N…$ARGUMENTS[N]の省略形で、$0や$1のように使う${CLAUDE_SESSION_ID}… 現在のセッションID
サポートファイル
スキルにはディレクトリー内に複数のファイルを含めることができます。
my-skill/ ├── SKILL.md (required - overview and navigation) ├── reference.md (detailed API docs - loaded when needed) ├── examples.md (usage examples - loaded when needed) └── scripts/ └── helper.py (utility script - executed, not loaded)
リファレンスとなるドキュメントやスクリプトを含めることができ、必要になるまでコンテキストに
読み込むことはありません。
Extend Claude with skills / Configure skills / Add supporting files
またこの仕組みを活用することで、スキルは500行以内に収めることが推奨されています。
高度なパターン
動的なコンテキストインジェクション
!command構文を使うと、スキルがClaudeに送信される前にシェルコマンドを実行できます。コマンドの
出力内容はプレースホルダーを置き換えます。
Extend Claude with skills / / Advanced patterns / Inject dynamic context
以下の例だと、gh pr diff --name-onlyなどの結果がプロンプトに反映されるということですね。
--- name: pr-summary description: Summarize changes in a pull request context: fork agent: Explore allowed-tools: Bash(gh *) --- ## Pull request context - PR diff: !`gh pr diff` - PR comments: !`gh pr view --comments` - Changed files: !`gh pr diff --name-only` ## Your task Summarize this pull request...
サブエージェントでスキルを実行する
サブエージェントでスキルを実行する方法についてです。
Extend Claude with skills / Advanced patterns / Run skills in a subagent
スキルを現在のコンテキストから分離して実行したい場合は、context: forkを追加します。この場合、SKILL.mdに
書かれた内容はサブエージェントのプロンプトになります。このサブエージェントは会話履歴にはアクセス
できません。
どのサブエージェントで実行するのかはagentで指定しますが、省略した場合はgeneral-purposeを指定したことに
なります。
The agent field specifies which subagent configuration to use. Options include built-in agents (Explore, Plan, general-purpose) or any custom subagent from .claude/agents/. If omitted, uses general-purpose.
指定する場合は組み込みのサブエージェント（Explore、Plan、general-purpose）を指定します。組み込みの
サブエージェントはこちら。
Create custom subagents / Built-in subagents
Claude Code上で見るとこちらですね。
❯ /agents ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ Agents │ │ No agents found │ │ │ │ ❯ Create new agent │ │ │ │ No agents found. Create specialized subagents that Claude can delegate to. │ │ Each subagent has its own context window, custom system prompt, and specific tools. │ │ Try creating: Code Reviewer, Code Simplifier, Security Reviewer, Tech Lead, or UX Reviewer. │ │ │ │ │ │ Built-in (always available): │ │ Bash · inherit │ │ general-purpose · inherit │ │ statusline-setup · sonnet │ │ Explore · haiku │ │ Plan · inherit │ │ claude-code-guide · haiku │ │ │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
context: forkは、スキルのプロンプトに明示的な指示がないと意味がありません。
スキルに「ガイドを参照すること」のようなガイドラインだけが含まれている場合、サブエージェントは
ガイドラインを受け取った後に実行するタスクがないため意味のある出力を返さないことになります。
ちなみに、サブエージェントのFrontmatterにもskillsが追加されていてスキルコンテンツをプリロードできるように
なったようです。
これは、サブエージェントの実行時にスキルを認識してスキルコンテンツをプリロードします。以下の例だと
APIの規約やエラーハンドリングパターンのガイドをコンテキストに追加する、というイメージでしょう。
--- name: api-developer description: Implement API endpoints following team conventions skills: - api-conventions - error-handling-patterns --- Implement API endpoints. Follow the conventions and patterns from the preloaded skills.
サブエージェントは親となる会話からスキルを継承しないため、このような明示的なリストアップが必要です。
また、このアプローチはcontext: forkとは逆だと書かれています。
話をサブエージェントでスキルを実行する方に戻します。スキルとサブエージェントのどちらを主にするかで
以下の関係になるようです。
| アプローチ | サブエージェントのシステムプロンプト | サブエージェントが実行するタスク | ロード対象 |
|---|---|---|---|
スキル＋context: fork |
general-purposeサブエージェントのプロンプト | SKILL.mdの内容 |
CLAUDE.md |
スキル＋context: fork＋agent |
agentで指定したサブエージェントのプロンプト |
SKILL.mdの内容 |
CLAUDE.md |
サブエージェント＋skills |
サブエージェントのプロンプト | 親エージェントからの指示 | プリロードされたスキル＋CLAUDE.md |
こう見ると、サブエージェントのプロンプトの位置づけがちょっとよくわからなくなりますね。
少なくとも実行するタスクはスキルまたは親エージェントの指示に依存することになります。サブエージェントの
プロンプトには役割や期待する振る舞いが書かれることになるんでしょうね。
少なくとも具体的な実行タスクが書かれていると、スキルのプロンプトや親エージェントからの指示との関係が
おかしくなります。
となると、agentで明示的にサブエージェントを指定することはあまりなく、スキルに実行したいタスクが
しっかり書かれていればデフォルトのgeneral-purposeサブエージェントを使う（もしくはagentを指定しない）
ということでよさそうな気がしますね。
ところで、context: forkはその時点の親エージェントのコンテキストのコピーが作られ、サブエージェントの
コンテキストのスタート地点になるような印象を持ったのですが、context: forkが具体的にどういう設定なのか
詳しい説明がない気がするのですが…。
ドキュメントを見ると、「このサブエージェントは会話履歴にはアクセスできません」とあるので「fork」という言葉から
連想するイメージとは逆なのでしょうか…？
The skill content becomes the prompt that drives the subagent. It won’t have access to your conversation history.
Extend Claude with skills / Advanced patterns / Run skills in a subagent
それに明確に関連付けられてはいませんが、こちらのドキュメントで言っている「fork」（ここまで書いている
内容）と同じ意味で捉えたらよいのでしょうか…？
How Claude Code works / Work with sessions / Resume or fork sessions
Claudeのドキュメント
Claudeのドキュメントについてはそんなに変わっていなさそうなので、省略します。
Agent Skills - Claude API Docs
自分は以前書いたこちらとClaudeのドキュメントを交互に眺めていました。
Claude Codeのエージェントスキルってなんだ？ - CLOVER🍀
スキルとサブエージェント？
ところで、スキルにはリファレンスコンテンツとタスクコンテンツの2種類があったという話でした。
- リファレンスコンテンツ … エージェントに知識を与えるもの
- タスクコンテンツ … エージェントにデプロイのようなある手続きに沿ってタスクを実行させるもの
サブエージェントでスキルを実行する、を読んだあたりからよくわからなくなる気がしますが、スキル視点で
見た時にはこういう使い分けではないでしょうか。
- リファレンスコンテンツに分類されるスキル
- 現在のエージェントにスキルに書かれた知識を与えたい時に使う
- サブエージェントを使う時に、
skillsでスキルに書かれた知識を与えたい時に使う
- タスクコンテンツに分類されるスキル
- 現在のエージェントに対して、スキルに書かれたタスクを実行させたい時に使う
- 現在のエージェントとコンテキストを分けたい場合は、
context: fork＋agent（未指定の場合はgeneral-purpose）でサブエージェントにスキルに書かれたタスクを実行させる
context: forkしないスキルは、これまでのカスタムスラッシュコマンド相当ですね。
またcontext: forkとサブエージェント＋skillsが逆のアプローチだと書かれていたのは、このようにスキルを
実行させることにサブエージェントを使うのか、サブエージェントに知識を与えるためにスキルを使うのかの
差だと思います。
context: forkはスキルのプロンプトに明示的な指示がないと意味がないと書きましたが、これは
リファレンスコンテンツに分類されるスキルに対してcontext: forkを指定しても実行するタスクがない、
ということを言っていたのでしょう。
リファレンスコンテンツについてはわかりやすいですが、タスクコンテンツについてはすべて/skill-nameのように
明示的に呼び出すもののみかというとそうではないと思うので、タスクコンテンツについては使い方に
もうちょっと悩むことになりそうです…。
おわりに
Claude Codeのスキルに関するドキュメントを見返してみました。
特にサブエージェントとの関係を読み解くのにだいぶ迷いましたが、ひとまずこんな感じかなと。
あとは使ってみて感覚を掴んでいくとしましょう。
