skill-gen

スキルジェネレーター

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

クイックスタート

新しいスキルを作成するには、ユーザーから次の情報を集めます。

1. このスキルは何をするものですか？
2. 短い名前（例：processing-pdfs、testing-code）
3. Claude はどのようなときにこのスキルを使うべきですか？
4. スクリプトが必要ですか？それとも手順だけで十分ですか？

ワークフロー

ステップ 1：要件を集める

• 目的：このスキルは何をしますか？
• トリガー：どのようなときに起動しますか？（キーワード、シナリオ）
• 複雑さ：手順のみですか？それともスクリプトやリファレンスが必要ですか？
• 自由度：厳密（正確な手順）ですか？それとも柔軟（一般的なガイダンス）ですか？

ステップ 2：スキルの構成を生成する

ディレクトリを作成します：~/.claude/skills/{skill-name}/

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

ステップ 3：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)
**Feature B**: See [references/feature-b.md](references/feature-b.md)

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

SKILL.md の下書きを作成したら、行数を数えます。500 行に近づく、または超える場合は、次の手順に従います。

1. ユーザーに伝える：「SKILL.md は {N} 行です。最適なパフォーマンスのために推奨される 500 行の上限を超えています。」
2. 分割可能なセクションを特定する：詳細なリファレンス、長い例、高度な機能、API ドキュメント
3. リファレンスファイルに移動する：references/{topic}.md — リンクは 1 階層の深さに保ちます
4. SKILL.md 内を短い概要とリンクに置き換える：

   **Advanced feature X**: See [references/feature-x.md](references/feature-x.md)
   

5. 目次を追加する：100 行を超えるリファレンスファイルには目次を追加します

500 行未満でも、セクションが独立していて特定のシナリオでのみ必要な場合は、分割することをおすすめします。

ステップ 5：検証する

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

命名規則

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

説明の規則

• 最大文字数：1024 文字。空であってはならず、XML タグを含めてはいけません
• 必ず三人称で記述する：「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.

description: Generates descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

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

基本原則

簡潔さ

コンテキストウィンドウは共有されます。情報を一つひとつ見直してください。

• 「Claude に本当にこの説明が必要ですか？」
• 「Claude はこれを知っていると想定できますか？」
• 「この段落はトークンを消費する価値がありますか？」

Claude がすでに持っていないコンテキストだけを追加します。

自由度の段階

タスクの壊れやすさに合わせて、具体性を調整します。

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

段階的開示

• SKILL.md = 概要とナビゲーション（目次）
• リファレンスファイル = 詳細な内容（必要に応じて読み込み）
• SKILL.md の本文は 500 行未満に保ちます
• リファレンスは SKILL.md から 1 階層の深さに保ちます（入れ子のリファレンスは禁止）
• 長いリファレンスファイル（100 行以上）には目次を付けます

用語の一貫性

用語を一つ選び、全体で使います。「API エンドポイント」／「URL」／「API ルート」／「パス」を混在させないでください。

パターン

チェックリストを使ったワークフロー

複雑な複数ステップの操作の場合：

## Workflow

Copy this checklist and track progress:

```
- [ ] Step 1: Analyze input
- [ ] Step 2: Generate plan
- [ ] Step 3: Validate plan
- [ ] Step 4: Execute
- [ ] Step 5: Verify output
```

フィードバックループ

バリデーターを実行 → エラーを修正 → 繰り返す：

1. Make changes
2. Validate: `python scripts/validate.py`
3. If validation fails: fix issues, return to step 2
4. Only proceed when validation passes

テンプレートパターン

要件の厳密さに合わせた出力形式のテンプレートを用意します。

例示パターン

出力品質に左右されるスキルでは、入力と出力のペアを示します。

条件付きワークフロー

判断ポイントを順に案内します。

**Creating new?** → Follow "Creation workflow"
**Editing existing?** → Follow "Editing workflow"

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

• エラーを明示的に処理する — Claude に丸投げしないでください
• 根拠のない定数を使わない — すべての値の根拠を示し、ドキュメントに記載してください
• 依存関係を列挙する — インストールするパッケージを指定してください
• 実行する意図を明確にする：
  • 「フィールドを抽出するには script.py を実行します」（実行）
  • 「アルゴリズムについては script.py を参照してください」（参考として読む）
• すべてのファイルパスでスラッシュを使用する（scripts/helper.py。scripts\helper.py ではありません）
• MCP ツールの参照 — 完全修飾名を使用します：ServerName:tool_name

アンチパターン

• Claude がすでに知っていることを説明する（PDF とは何か、ライブラリがどのように動作するかなど）
• ツールやライブラリの選択肢を提示しすぎる — 標準の選択肢を提示し、必要に応じて別の方法も選べるようにします
• 時間とともに変化する情報 — <details> タグを使った「古いパターン」セクションに記載します
• 参照を深くネストする（ファイル → ファイル → ファイル）
• Windows 形式のパス
• 明示的なインストール手順を示さずに、パッケージがインストール済みだと想定する

検証チェックリスト

品質の基本項目

• 名前：小文字、数字、ハイフンのみ、1～64 文字、予約語を含まない
• 説明：三人称で具体的に記述し、内容と使用するタイミングを含め、1024 文字未満にする
• SKILL.md の本文は 500 行未満
• 詳細は別ファイルに記載する（階層は 1 つまで）
• 時間とともに変化する情報を含まない
• 全体を通じて用語が統一されている
• 具体的な例がある（抽象的な例ではない）
• 適切に段階的な情報開示を行っている
• ワークフローに明確な手順がある

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

• スクリプトがエラーを明示的に処理する
• 根拠のない定数がない（すべての値に根拠がある）
• 必要なパッケージがインストール手順とともに記載されている
• すべてのパスでスラッシュを使用している
• 重要な操作に検証手順がある
• 品質が重要なタスクにフィードバックループがある

テスト

• 実際の使用シナリオでテスト済み
• 対象モデル全体で動作する（Haiku にはより詳しいガイダンスが必要で、Opus にはそれほど必要ありません）

さらに読む

評価駆動開発：references/eval-driven-development.md を参照してください。ビルド → テスト → 観察 → 改善のサイクル、2 つの Claude を使った反復開発、初回作成後にスキルを改善するための観察パターンについて説明しています。