Claude Codeのスキルに関するドキュメントを見直す

これは、なにをしたくて書いたもの？

前に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のスキルはこれに準拠しています。

Overview - Agent Skills

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

Extend Claude with skills / Configure skills / Frontmatter reference / Available string substitutions

サポートファイル

スキルにはディレクトリー内に複数のファイルを含めることができます。

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が追加されていてスキルコンテンツをプリロードできるように
なったようです。

Create custom subagents / Configure subagents / Control subagent capabilities / Preload skills into subagents

これは、サブエージェントの実行時にスキルを認識してスキルコンテンツをプリロードします。以下の例だと
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のスキルに関するドキュメントを見返してみました。

特にサブエージェントとの関係を読み解くのにだいぶ迷いましたが、ひとまずこんな感じかなと。

あとは使ってみて感覚を掴んでいくとしましょう。