add-skill

スキルの追加

ユーザーの要件に基づいて、適切に構成された Claude Code スキルを作成します。

クイックモード

すばやく作成する場合は、ユーザーがすべての情報を一度に提供できます。

/add-skill name=my-skill purpose="Does X" trigger="when user asks for Y"

対話形式の質問をせずに解析して生成します。

ワークフロー

ステップ 1：最新のドキュメントを取得する

現在の仕様に準拠していることを確認するため、必ず最初に公式ドキュメントを取得します。

WebFetch: https://code.claude.com/docs/en/skills
Prompt: Extract skill file format, required fields, naming rules, and best practices

WebFetch に失敗した場合は、次の方法に切り替えます。

WebSearch: "Claude Code skills SKILL.md format site:code.claude.com"

ステップ 2：要件を収集する

ユーザーに質問するか、クイックモードの入力から解析します。

1. スコープ：グローバルスキルですか、それともリポジトリローカルスキルですか？
   • グローバル → ~/.claude/skills/{skill-name}/（すべてのプロジェクトで利用可能）
   • リポジトリローカル → .claude/skills/{skill-name}/（このリポジトリのみで利用可能。コードとともにコミットされます）
2. 名前：小文字とハイフンのみ（動名詞を推奨：processing-pdfs、testing-code）
3. 目的：何をするものですか？（1〜2 文）
4. トリガー：どのようなときに Claude が使用しますか？（キーワード、シナリオ）
5. 複雑さ：手順のみですか、それともスクリプトやリファレンスが必要ですか？
6. 自由度：厳密（手順を正確に指定）ですか、それとも柔軟（一般的なガイダンス）ですか？

ステップ 3：スキルの構成を作成する

{base-path}/skills/{skill-name}/
├── SKILL.md           # Required: Main instructions (<500 lines)
├── scripts/           # Optional: Executable code
│   └── main.py
└── references/        # Optional: Detailed docs (one level deep)
    └── examples.md

ステップ 4：SKILL.md を生成する

---
name: {skill-name}
description: {What it does in third person}. Use when {trigger conditions}.
---

# {Skill Title}

{Brief overview - assume Claude is smart, only add context it doesn't already have}

## Quick Start

{Minimal working example or first step}

## Instructions

{Step-by-step guidance with appropriate freedom level}

## Advanced Features

**Feature A**: See [references/feature-a.md](references/feature-a.md)

ステップ 5：行数を確認し、段階的開示を適用する

SKILL.md の下書きを作成したら、行数を数えます。500 行に近づくか、超える場合：

1. ユーザーに「SKILL.md は {N} 行で、推奨される 500 行の上限を超えています」と伝えます。
2. 分割できるセクションを特定します：詳細なリファレンス、長い例、高度な機能
3. リファレンスファイルに移します：references/{topic}.md（階層は 1 段階のみ）
4. SKILL.md の該当箇所を、短い要約とリンクに置き換えます。
5. 100 行を超えるリファレンスファイルには目次を追加します。

ステップ 6：検証する

仕上げる前に、検証チェックリストに沿って確認します。

ステップ 7：確認する

ls -la ~/.claude/skills/{skill-name}/
cat ~/.claude/skills/{skill-name}/SKILL.md

claude --debug を使ってテストし、読み込みエラーがないか確認します。

命名規則

• 長さ：1〜64 文字
• 形式：小文字、数字、ハイフンのみ
• 動名詞を推奨：processing-pdfs、testing-code、writing-documentation
• 使用可能な別形式：pdf-processing、process-pdfs
• 使用不可：- で始まる、または終わる名前、連続する --、予約語（anthropic、claude）、XML タグ
• 避ける名前：曖昧な名前（helper、utils、tools）、汎用的すぎる名前（documents、data）
• 一致させること：フォルダー名

説明の規則

• 最大文字数：1024 文字。空でないこと。XML タグを含めないこと
• 必ず三人称で記述：「I can help you」ではなく「Excel ファイルを処理します」
• 両方を含めること：何をするか、いつ使うか
• 具体的に記述すること：Claude は説明をもとに 100 個以上のスキルから選択します

良い例：

description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

悪い例：「ドキュメントを支援します」、「データを処理します」、「ファイルに関する作業をします」

基本原則

簡潔さ

それぞれの情報について、必要性を確認します。

• 「Claude は本当にこの説明を必要としていますか？」
• 「Claude が知っていることとして前提にできますか？」
• 「この段落はトークンを使うだけの価値がありますか？」

自由度

自由度	使用する場面	例
高（テキストによる指示）	複数の有効な方法がある	コードレビューのガイドライン
中（擬似コード／パラメーター）	推奨されるパターンがある	レポート生成テンプレート
低（正確なスクリプト）	壊れやすい操作、一貫性が重要	データベースのマイグレーション

用語の統一

用語を 1 つ選び、全体を通して使います。「API endpoint」／「URL」／「API route」を混在させないでください。

パターン

チェックリスト付きワークフロー

複雑な複数ステップの操作には、コピーして使えるチェックリストを用意します。

フィードバックループ

バリデーターを実行 → エラーを修正 → 合格するまで繰り返します。

条件分岐のあるワークフロー

判断ポイントに沿って案内します：新規作成ですか？ → 「作成ワークフロー」／既存のものを編集しますか？ → 「編集ワークフロー」

スクリプトのベストプラクティス

• エラーを明示的に処理します。Claude に丸投げしないでください
• 根拠のない定数を使わないでください。すべての値の根拠を示し、記録してください
• 依存関係とインストール手順を記載してください
• 実行の意図を明確にしてください。「script.py を実行する」（実行）と「script.py を参照する」（参照）のようにします
• すべてのファイルパスでスラッシュ / を使ってください
• MCP ツールを参照する場合は、完全修飾名を使ってください：ServerName:tool_name

アンチパターン

• Claude がすでに知っていることを説明する
• ツールやライブラリの選択肢を増やしすぎる。デフォルトを示し、必要に応じて別の選択肢を使えるようにしてください
• 時間の経過で古くなる情報。以前のパターンには <details> タグを使ってください
• 参照を深くネストする（ファイル → ファイル → ファイル）
• インストール手順を示さずに、パッケージがインストール済みだと想定する

検証チェックリスト

基本品質

• 名前：小文字、数字、ハイフンのみ、1～64 文字、予約語を含まない
• 説明：三人称で具体的に記述し、「何を」「いつ」を含め、1024 文字未満にする
• SKILL.md の本文を 500 行未満にする
• 詳細情報は別の参照ファイルに記載する（階層は 1 つまで）
• 時間の経過で古くなる情報がない
• 用語を全体で統一する
• 具体例を示す（抽象的な例ではなく）
• 適切に段階的開示を活用する

スクリプト（該当する場合）

• スクリプトがエラーを明示的に処理する
• 根拠のない定数を使わない（すべての値の根拠を示す）
• 必要なパッケージとインストール手順を記載する
• すべてのパスでスラッシュ / を使う

テスト

• 実際の使用シナリオでテスト済み
• 対象モデル全体で動作する（Haiku にはより詳しい指示が必要で、Opus にはより少ない指示で済む）

さらに読む

• 評価主導の開発：references/eval-driven-development.md を参照してください
• 例：references/examples.md を参照してください
• 公式ドキュメント：https://code.claude.com/docs/en/skills