📙

skill の挙動は SKILL.md frontmatter で決まる

に公開
skill
Claude
Claude Code
idea

サムネイル

  • SKILL.md の frontmatter が、誰がいつ skill を呼べるかを決めています。
  • description / disable-model-invocation / user-invocable の3つで、ユーザー手動・Claude 自動・両方を選び分けられます。
  • paths を書くと、glob にあてはまるファイルを Claude が読んだときだけ skill が自動で読み込まれます。

誰が呼ぶかは3つの frontmatter フィールドで決まる

custom skill は SKILL.md という1つの Markdown ファイルが本体です。
SKILL.md は --- で囲んだ YAML frontmatter と、本文の Markdown 2つから構成されます。
本文は skill が呼ばれてから読み込まれる指示文で、frontmatter は呼ばれ方そのものを決める設定欄です。
Anthropic Docs > Extend Claude with skills ページにはこう書かれています。
「custom commands は skills に統合された」というものです。
たとえば commands 配下と skills 配下のどちらに置いても、同じ /deploy という呼び出しになります。
.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は、どちらも同じ動きをします。

本記事で扱う frontmatter は4つあります。
description / disable-model-invocation / user-invocable の3つは、誰が呼ぶかを決めます。
残る paths は、いつ自動で読み込まれるかを決めます。

description は skill 一覧に並ぶ説明文で、Claude はこの文を見て自動で読み込むかを判断します。
description と when_to_use を合わせた表示は 1536字で打ち切られるため、主な使い道を先頭に置きます。
ユーザーが自然に書きそうな言い回しを並べておくと、Claude が自動で skill を選ぶ確率が上がります。

disable-model-invocation を true にすると、Claude は自動でこの skill を読み込まなくなります。
副作用のあるワークフロー (デプロイや commit など) を、ユーザーがタイミングを決めて手動で呼びたい場面に向きます。
true にした skill は、subagent の事前読み込みからも外れます。
この挙動は Anthropic Docs > Create custom subagents ページに明記されています。

user-invocable を false にすると、ユーザーの / メニューから隠れます。
ユーザーが直接呼ぶ意味のない、Claude だけが背景知識として読み込みたい skill に使います。

誰が skill を呼べるかを決める frontmatter のマトリクス

paths は、該当パスのファイルを読んだときだけ skill を呼ぶ

paths 欄に glob を書くと、対象パターンのファイルを Claude が読んだときだけ skill が自動で読み込まれます。
paths の書式は、path-specific rules と同じ glob ルールです。
両者が同じ書式を共有していることは、Anthropic Docs > Extend Claude with skills ページに書かれています。
たとえば paths: "src/api/**/*.ts" と書けば、TypeScript の API 実装を扱うときだけ skill が立ち上がります。
言語別・ディレクトリ別の指示を、必要なときだけ Claude の手元に届ける用途に向きます。

発火のタイミングにも前提があります。
パス指定型ルールは、Claude が一致するファイルを読んだときに発火します。
毎回のツール呼び出しで発火するわけではありません。
この性質は Anthropic Docs > How Claude remembers your project ページに書かれています。
発火のトリガーはファイルの読み取りであって、editor 起動時の cwd でもツール呼び出しのたびでもありません。

paths を書かなかった場合、Claude は description だけを手がかりに「いま呼ぶべきか」を判断します。
description で auto-invoke を狙うか、paths で対象パスに絞るかの2通りが、自動呼び出しの基本パターンです。

一方、ユーザーが /skill-name と直接打つ手動の呼び出しは、paths や description の設定とは独立に動きます。
disable-model-invocation を true にした skill でも、手動で呼ぶ経路はそのまま使えます。
副作用つきの skill を「Claude には任せない、自分のタイミングで呼ぶ」運用にしたいときの基本の組み合わせです。

ユーザー手動と Claude 自動の 2経路と paths glob 評価のフロー

参考文献

  1. Anthropic. Extend Claude with skills. Anthropic Documentation. https://code.claude.com/docs/en/skills
  2. Anthropic. How Claude remembers your project. Anthropic Documentation. https://code.claude.com/docs/en/memory
  3. Anthropic. Create custom subagents. Anthropic Documentation. https://code.claude.com/docs/en/sub-agents

Discussion