Skill Guidelines — Anthropic 公式 skills 指針の repo 内 SOR

このドキュメントは Anthropic 公式 (= Claude Code / Agent SDK / Skills repo) の skills 設計指針を、本 repo の運用文脈向けに要約した SOR (Single Source of Record) です。新規 skill 追加・既存 skill 改修・LLM が自己評価する際の参照基準。

バージョン情報

• このドキュメントの version: v1.0.0 (SemVer)
• 転記日: 2026-05-16 (ISO 8601)
• 出典 URL と最終確認日:
  • https://docs.claude.com/en/docs/claude-code/skills (最終確認: 2026-05-16、未直接 fetch、要次回確認)
  • https://docs.claude.com/en/api/agent-sdk/skills (最終確認: 2026-05-16、同上)
  • https://github.com/anthropics/skills (最終確認: 2026-05-16、同上)
  • https://www.anthropic.com/news/claude-skills (最終確認: 2026-05-16、同上)
  • https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/ (MCP 側、最終確認: 2026-05-16)
• Anthropic 上流ドキュメントの版: 公式 docs ページ自体は版番号を持たないため、本要約は 2026-05-16 時点の挙動 を基準にする。

注意: 本 v1.0.0 の内容は claude-code-guide subagent 経由の引用が混在する。実装作業に着手する直前に WebFetch で primary docs を直接再確認すること (= memory feedback「subagent 伝聞情報は鵜呑みにしない」運用)。

1. Skill 構造 / Frontmatter

配置 path (公式 convention)

Frontmatter 必須 / optional

---
# 必須
name: my-skill              # 64 文字以内、lowercase + hyphen
description: 何をする skill か + 何時使うか。LLM が skill selection に使う唯一の材料。
                            # 60〜150 字慣習。`when_to_use` を内包する文章で書く

# Claude Code 拡張 (optional)
allowed-tools: Read Grep    # 事前許可 tool。permission prompt を減らす
disable-model-invocation: true  # user 明示呼出のみ可、Claude 自動起動を抑止
user-invocable: false       # 逆。Claude のみ呼出可
context: fork               # subagent で実行 (= parent context を汚さない)
paths: "src/**,*.ts"        # 該当 path が context にあるときだけ activate
---

2. description の書き方

LLM が skill を選ぶ唯一の材料が description。以下を守る:

• トリガ条件 (= 何時使うか) を keyword 先頭に置く: 「Use when ...」「TRIGGER when ...」「監査ルール定義・新規概念ノード追加・述語選択で判断が必要なときに参照する」のように自然文で書く
• 公式の専用記法は無い (= TRIGGER when: / SKIP: のような prefix は推奨されていない、自然文で書く)
• 慣習字数 60〜150 字。長すぎると keyword index 効率が落ちる。短すぎると trigger 精度が落ちる
• 超過時の挙動は公式に未記載。truncate / 警告のどちらかは要 WebFetch 確認

本 repo 評価

3. 本文の書き方

原則

• 命令形 / concise (= 「動詞 + 目的語」、形容詞は最低限)
• 本体は ≤500 行慣習 (公式に明示上限なし、100〜300 行が標準)
• 詳細は supporting files に分離 (= progressive disclosure):
  • references/<topic>.md — API reference 等
  • examples/<scenario>.md — usage examples
  • scripts/<helper>.<ext> — 実行 helper (= readable but not loaded)
• 1 階層 nesting まで (= 公式 anti-pattern「deeply nested file references」回避)
• dynamic context injection (!`command` で frontmatter / 本文に command 出力を埋め込み) は Claude Code / Agent SDK 両方で挙動が 未確認 → 要 WebFetch

本 repo 評価

全 SKILL.md が 100〜250 行の範囲、supporting files 未使用。現状サイズで問題なし、500 行に近づいたら references/ 分離を検討。

4. トークン効率

公式の 3 段 progressive disclosure:

1. Metadata (= name + description) は常時 load — Claude が skill selection に使う
2. SKILL.md 本体は trigger 時にのみ load — selection 後の全文読込
3. Reference files は明示 read 時のみ load — [FORMS.md](FORMS.md) のような relative link をたどった時だけ

数値慣習

• SKILL.md 本体 ≤500 行
• description ≤150 字 (= keyword index 用)
• supporting files への分割で本体を <300 行に保つ
• auto-compaction は 25,000 token (= claude-code-guide 経由情報、要 WebFetch 確認)

5. 自動呼び出し制御

/skills slash command で user 側からの skill 一覧確認・手動起動が可能。

6. MCP tool 連動

Claude Code (frontmatter)

allowed-tools: Read Grep mcp__logic-solver-remote__freee_auth_status

skill 実行中に許可される tool を事前宣言。permission prompt を減らす。

Agent SDK (programmatic)

options = ClaudeAgentOptions(allowed_tools=["Read", "Grep"])

SDK 側の allowed_tools (= snake_case) と frontmatter allowed-tools (= kebab-case) は別フィールド名なので、両方併記する場合は 両者を明示。

MCP tool annotation

MCP 側 tool (server.tool 登録時) には readOnlyHint / destructiveHint / idempotentHint / openWorldHint を付ける慣習。ただし Claude Code 現状は annotation を permission 判定に使っていない (= code.claude.com/docs/en/permissions 確認、Issue #108 として trackingしている)。

7. 品質チェック

公式の自動 framework は無し

• 自動 lint / linter はない
• manual testing + LLM eval が現状の運用
• /doctor slash command で description token 予算超過を検知できる (= claude-code-guide 経由情報、要 WebFetch)

本 repo の運用 (= Issue #111 の Phase 2 以降で実装予定)

1. drift lint (= 成果物 B): MCP server の tool 一覧と SKILL.md の mention を突き合わせ、未記載 tool / 存在しない tool 言及を fail
2. endpoint 整合 lint (= 成果物 B 内): 各 SKILL.md に対して /docs/skill/<name> route が存在することを assert
3. PR template の skill checklist (= 成果物 D): skill 追加・改修時の確認項目を強制
4. 回帰タスクスイート (= 成果物 C): 内部 LLM に典型タスクを投げて tool call 履歴を比較
5. LLM 自己評価 (= 成果物 E): 週次 reviewer agent が drift / ベスト不一致を指摘

8. 配布形式

marketplace は公式に存在しない。

更新ルール

• 上流の公式 URL 改訂を半年ごとに確認 (= RSS / changelog が出れば subscribe)
• 改訂時は本ドキュメントの 転記日 / version を bump し、末尾 CHANGELOG セクションに差分を明記
• LLM が本ドキュメントを参照する時は、必ず 「version: v?.?.?, 転記日: YYYY-MM-DD」を出力に含める (= 古い要約を引用していないか自己検証する)

CHANGELOG

v1.0.0 (2026-05-16)

• 初版。Issue #111 Phase 1 成果物 A として作成。
• claude-code-guide subagent 経由の伝聞情報が含まれるため、実装着手前に primary docs の WebFetch 再確認を推奨。

関連

• Issue #111 (= 本ドキュメントの親 issue、整合性の仕組み全体)
• Issue #107 (= path consolidation、本ドキュメントの §1 と整合)
• Issue #108 (= MCP tool annotation 整備、本ドキュメントの §6)
• Issue #109 (= permissions allow-list、本ドキュメントの §5・§6)
• Issue #113 (= typo rename、本ドキュメントの §1 例)