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

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

バージョン情報

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

1. Skill 構造 / Frontmatter

配置 path (公式 convention)

Scope 公式 path 本 repo
Project .claude/skills/<skill-name>/SKILL.md ./.claude/skills/ (Issue #107 で集約済)
Personal ~/.claude/skills/<skill-name>/SKILL.md 該当なし
Plugin <plugin-dir>/skills/<skill-name>/SKILL.md 該当なし
Submodule 同梱 (慣習) <package>/.claude/skills/<name>/SKILL.md ./packages/logic-solver-mcp/.claude/skills/

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 評価

skill description 字数 評価
logic-solver-mcp-ui-nav 200 字 (Issue #113 修正後) ⚠️ やや長い、120 字に圧縮余地
datalog-debug-skill 約 120 字 ✅
datalog-schema-philosophy 約 90 字 ✅
datalog-migration-skill 約 150 字 ✅ ぎりぎり

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. 自動呼び出し制御

Frontmatter 効果
disable-model-invocation: true Claude が自動起動できない。/skills <name> で user が明示呼出する場合のみ実行
user-invocable: false 逆。Claude のみ呼出可、user の /skills から見えない
paths: "src/**,*.ts" matching file が context にあるときのみ skill が候補に上がる
(none) デフォルト。description match で自動 selection 対象

/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. 配布形式

方式 path 用途
Project <repo>/.claude/skills/ (git 管理) チーム全員に同じ skill を配布
Personal ~/.claude/skills/ (個人) 個人用 utility skill
Plugin <plugin>/skills/ (.claude-plugin/ manifest 経由) 第三者配布
API beta container.skills (claude.com SDK、2025-10〜) programmatic upload
本 repo の HTTP 配信 (非公式) /docs/skill/<name> + /raw (Issue #111 H) LLM agent が WebFetch で取得、Claude Code IDE auto-discover とは独立

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 例)