skill の構造 (anatomy)¶

最小構成¶

my-skill/
├── SKILL.md          # 必須。YAML frontmatter + 指示本文
├── reference.md      # 詳細リファレンス (必要時のみロード)
├── examples/sample.md
└── scripts/helper.py # Claude が実行可能なスクリプト

.claude/commands/foo.md (1枚)も同じく /foo を生やせるが、付随ファイルが要るなら skills/ に揃える。

SKILL.md frontmatter¶

---
name: skill-name                       # 省略可。ディレクトリ名がデフォルト
description: 何をするか、いつ使うか     # 必須。検索ヒット精度を左右する
allowed-tools: Bash(git *), Read       # 省略可。指定すると他は使えない
disable-model-invocation: false        # true で /name のみ起動可に
user-invocable: true                   # false で Claude 自動呼出のみに
context: fork                          # fork すると subagent で実行
agent: Explore                         # context: fork と組合せ
model: claude-haiku-4-5                # 起動時のモデルを固定
---

本文に書く順番¶

使うタイミング (description の延長)
進め方の番号付き手順
出力フォーマット (Markdown表や JSON スキーマ)
注意点 / アンチパターン

理由: Claude は本文を上から処理するため、最初に「いつ起動すべきか」を再確認させると暴発が減る。

description の書き方¶

文頭にユーザが実際に口にする単語を置く (例: 「PR 作って」「コミットメッセージ」)
1,536 文字でカットされるので冗長な背景は書かない
「〜したいとき」「〜と聞かれたとき」の トリガー言及形 で書く

良い例:

description: 未コミット差分を要約しリスクを指摘する。
何が変わったかを聞かれた時、コミットメッセージを欲しい時に使う。

悪い例:

description: This is a comprehensive skill for analyzing changes...
(前置きが長くトリガーワードが埋もれる)

`!`コマンド`` 構文¶

SKILL.md の本文中で:

## Current diff
!`git diff HEAD`

ロード時に backtick コマンドが実行され、結果がプロンプトに埋め込まれる。allowed-tools で許可している必要あり。

配置の優先順位¶

enterprise > personal (~/.claude) > project (./.claude) > plugin

個人共通の汎用 skill は ~/.claude/skills/
プロジェクト固有 (このレポの research-trends 等) は ./.claude/skills/

出典¶

_research/claude-code-features/2026-05-11-claude-code-features.md
_research/examples/2026-05-11-awesome-templates.md (anthropics/skills の skill-creator 参照)
https://code.claude.com/docs/en/skills