何のためのものか
SKILL.md に指示を書いて Claude の能力を拡張する仕組み。関連する場面で Claude が自動的に使うか、/skill-name で直接呼ぶ。
CLAUDE.md と違い、skill の本文は使用時にのみ読み込まれる。 常に効かせたいものは CLAUDE.md、必要なときだけ出てくればよいものは skill、という切り分けになる。
触る
.claude/skills/<skill-name>/SKILL.mdを作る。frontmatter はdescriptionだけでよい/skill-nameで呼ぶ。コマンド名はディレクトリ名から決まる（nameは一覧の表示ラベルを変えるだけ）/skillsで一覧を見る
.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作り、同じように動く。既存の .claude/commands/ はそのまま動く。
編集はセッション中に反映される（live change detection）。ただしセッション開始時に存在しなかったトップレベルの skills ディレクトリを作った場合は再起動が要る。
入れる
置き場所と description を決める。
| 置き場所 | 適用範囲 |
|---|---|
~/.claude/skills/<skill-name>/SKILL.md | 自分の全プロジェクト |
.claude/skills/<skill-name>/SKILL.md | そのプロジェクトのみ。バージョン管理にコミットして配る |
descriptionは「何をするか・いつ使うか」を書く。 Claude はこれで適用を判断する。トリガーになる言い回しはwhen_to_useに足せる- 引数を受けるなら
$ARGUMENTS、$1のような位置指定、argumentsfrontmatter で宣言した$nameが使える ${CLAUDE_SKILL_DIR}と${CLAUDE_PROJECT_DIR}は本文でもallowed-toolsの Bash ルールでも置換される- 手順の途中で現在の状態が要るなら dynamic context injection。
!`<command>`は送信前に実行され、出力で置き換わる（複数行は```!のフェンス） SKILL.mdは 500 行未満に保ち、詳細は補助ファイルへ移す
効かせる
呼び出しの制御を使い分ける。
| frontmatter | ユーザーが呼べる | Claude が呼べる |
|---|---|---|
| （既定） | はい | はい |
disable-model-invocation: true | はい | いいえ（description もコンテキストに入らない） |
user-invocable: false | いいえ | はい |
- 重い調査は
context: fork。 skill の内容が subagent を駆動するプロンプトになり、会話履歴へのアクセスは無い。既定でバックグラウンドで動き、background: falseで呼び出したターン内に結果を待つ allowed-toolsは「そのターンだけの事前承認」。 次のメッセージ送信で解除される。セッション全体で効かせたいなら permission 設定に allow ルールを書く- 一覧のコストを見る。 skill 名と description の一覧はコンテキストに読み込まれ、予算はモデルのコンテキストウィンドウの 1%。溢れると呼び出し回数の少ない skill から description が落ちる。
/doctorで見積もりと主な要因が分かる
落とし穴
- frontmatter の YAML が壊れていると、
/skill-nameは動くのに自動では呼ばれない。 メタデータ空で読み込まれるためdescriptionによるマッチングが効かない。--debugでパースエラーを確認する - 呼び出した skill の本文はセッションの残りの間コンテキストに留まる。 行ごとに継続的なトークンコストになる
- Claude Code は後のターンで skill ファイルを再読み込みしない。 編集した内容を効かせたいなら呼び直す
- バックグラウンドで動く forked skill の編集は
/rewindで戻せない。 git で戻す context: forkはタスクを持つ skill にしか意味が無い。ガイドラインだけの skill を fork しても、実行可能なプロンプトを受け取らない