Skill authoring best practices

一行要約

Skill を書く技術の中核は「context window は公共財である」という認識と、「タスクの壊れやすさに応じて自由度を選ぶ」という判断であり、書く前に eval を作れというのが最も強い規範。

要点

中核原則

1. 簡潔さがすべて

The context window is a public good. context window は公共財である。

Skill は system prompt、会話履歴、他 Skill のメタデータ、実際のリクエストと context を分け合う。起動時に読まれるのは全 Skill の name と description だけで、SKILL.md 本体は関連が生じたときに初めて読まれる。それでも簡潔さは重要 — 読まれた瞬間から全トークンが他の文脈と競合する。

デフォルトの前提: Claude はすでに非常に賢い。以下を自問する。

「Claude はこの説明を本当に必要としているか？」
「これは Claude が知っていると仮定できるか？」
「この段落はトークンコストに見合うか？」

2. 自由度 (degrees of freedom) を適切に設定する

タスクの壊れやすさと変動性に、指示の具体性を合わせる。

自由度	形式	使うとき	例
High	文章による指示	複数のアプローチが妥当 / 判断が文脈依存	コードレビューの観点リスト
Medium	擬似コード、パラメータ付きスクリプト	推奨パターンはあるが変動も許容	テンプレート関数
Low	具体的なスクリプト、パラメータほぼなし	操作が壊れやすい / 一貫性が critical / 手順が固定	DB マイグレーション

比喩: Claude を道を進むロボットと考える。両側が崖の細い橋なら安全な道は1つしかないので、正確な指示とガードレールを与える。危険のない広い野原なら多くの道が成功に至るので、方向だけ示して最良のルートは任せる。

3. 使う予定のすべてのモデルでテストする

Skill はモデルへの追加物なので、効果は下地のモデルに依存する。

Haiku: 十分なガイダンスがあるか？
Sonnet: 明確で効率的か？
Opus: 説明しすぎていないか？

構造

命名: gerund 形（動名詞）を推奨 — processing-pdfs、analyzing-spreadsheets、testing-code。避けるべきは helper / utils / tools のような曖昧な名前、documents / data のような汎用すぎる名前。

description の書き方（Skill 選択の成否を決める最重要フィールド）:

必ず三人称で書く。system prompt に注入されるため、視点が混ざると discovery に問題が出る
- ✅ “Processes Excel files and generates reports”
- ❌ “I can help you process Excel files” / “You can use this to…”

何をするか と いつ使うか の両方を含める

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

100個以上の Skill から選ぶ前提なので、選択に足る詳細を description 側に置く

progressive disclosure:

SKILL.md 本文は 500行未満に保つ
超えそうなら別ファイルに分割する
参照は SKILL.md から1階層だけにする。ネストされた参照は、Claude が head -100 などで部分読みするため情報が欠ける
100行を超える参照ファイルには先頭に目次を置く（部分読みでも全体像が見える）

ワークフローとフィードバックループ

複雑な操作は明確な逐次ステップに分解し、Claude が返信にコピーしてチェックオフできるチェックリストを提供する
validator を回す → エラーを直す → 繰り返す のパターンは出力品質を大きく改善する。validator はスクリプトでもよいし、STYLE_GUIDE.md のような参照文書でもよい

コンテンツの指針

時間依存の情報を書かない。「2025年8月より前なら旧API」のような記述は必ず陳腐化する。代わりに「Current method」と、<details> で畳んだ「Old patterns」節に分ける
用語を統一する。“API endpoint” / “URL” / “API route” / “path” を混ぜない

評価と反復

eval を先に作る（Build evaluations first）

Create evaluations BEFORE writing extensive documentation. 大量のドキュメントを書く「前」に evaluation を作れ。

ギャップを特定: Skill なしで代表的タスクを実行させ、失敗や不足を記録する
eval を作る: そのギャップを突く3シナリオを作る
ベースラインを測る: Skill なしの性能を測定
最小限の指示を書く: ギャップを埋め eval を通す分だけ
反復する

Claude A / Claude B パターン

Skill 開発は Claude 自身と行うのが最も効果的。Claude A（Skill を設計・改良する相棒）と Claude B（Skill を読んで実タスクをこなす別インスタンス）を分ける。

Skill なしで Claude A とタスクをやり切り、自分が繰り返し提供している情報に気づく
再利用可能なパターンを特定する
Claude A に Skill 化を依頼する（専用のプロンプトや「skill を書く skill」は不要 — Claude は Skill 形式をネイティブに理解している）
冗長さをレビューして削らせる
情報アーキテクチャを改善させる
Claude B（Skill をロードした fresh instance）でテストする
Claude B の躓きを具体的に Claude A に持ち帰る

Claude の navigate の仕方を観察する: 想定外の探索順（構造が直感的でない）/ 参照を辿らない（リンクが目立たない）/ 同じファイルばかり読む（SKILL.md 本体に入れるべき）/ 一度も読まれないファイル（不要か signal が弱い）。

アンチパターン

Windows形式のパス（scripts\helper.py）— 常に forward slash
選択肢を出しすぎる — 「pypdf でも pdfplumber でも PyMuPDF でも…」ではなく、デフォルトを1つ示し、逃げ道を1つ添える
スクリプトで Claude に判断を先送りする（“solve, don’t defer”）。エラーは明示的に処理する
voodoo constants（TIMEOUT = 47 # Why 47?）。値の根拠をコメントで残す（Ousterhout’s law）
MCP ツールは完全修飾名で書く（BigQuery:bigquery_schema）。prefix がないと解決に失敗しうる

そのまま使える具体例

description の良し悪し:

# ✅ 何をするか + いつ使うか、三人称
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
 
# ❌
description: Helps with documents

eval の構造:

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF file and save it to output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
    "Extracts text content from all pages in the document without missing any pages",
    "Saves the extracted text to a file named output.txt in a clear, readable format"
  ]
}

注: 原典は「これを走らせる組み込みの仕組みは現時点で存在しない。ユーザーが自前で評価システムを作る必要がある」と明記している。

ドメイン別の progressive disclosure:

bigquery-skill/
├── SKILL.md            # 概観とナビゲーションのみ
└── reference/
    ├── finance.md      # 売上・請求指標
    ├── sales.md        # 商談・パイプライン
    ├── product.md      # API 利用状況
    └── marketing.md    # キャンペーン・アトリビューション

売上を聞かれたら reference/finance.md だけが読まれ、他はファイルシステム上に残ってトークンを消費しない。

原典で言及されている関連文書

effective-context-engineering-for-ai-agents — 「context は公共財」の理論的裏づけ
claude-code-best-practices — Claude Code 側の skills の使い方
https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview — Skills の仕組み
https://code.claude.com/docs/en/skills — Claude Code での skills

未取得の派生リンク

https://platform.claude.com/docs/en/test-and-evaluate/develop-tests — 成功基準と eval の作り方
https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills — Skills の設計思想

ai-docs

エクスプローラー