skill-builder

スキルビルダー

適切な構造、見つけやすい説明、ベストプラクティスを備えた、本番品質の Claude Code 用スキルを作成します。

クイックリファレンス

説明の形式：[機能] + [使用するタイミング] + [ユーザーが使うトリガー語句]

名前のルール：小文字、数字、ハイフンのみ。最大 64 文字。スペースは使用不可。

説明のルール：最大 1024 文字。トリガー語句を含め、具体的に記述します。

スキル作成ワークフロー

フェーズ 1：要件の確認

AskUserQuestion を使用して、必要なものを把握します。

1. スキルには何をさせますか？

   • どのような機能や専門知識を提供する必要がありますか？
   • どのようなタスクを支援する必要がありますか？

2. どのようなときに有効化しますか？

   • どのような状況やコンテキストですか？
   • ユーザーはどのような言葉やフレーズを使いますか？
   • どのようなファイル形式や操作が対象ですか？

3. スコープの決定

   • 個人用スキル（~/.claude/skills/）— このユーザーのみが使用
   • プロジェクト用スキル（.claude/skills/）— git 経由でチームと共有

4. 構造の複雑さ

   • 単一ファイル（シンプルな手順や例）
   • 複数ファイル（スクリプト、テンプレート、詳細なドキュメント）

5. ツールの制限

   • フルアクセス（デフォルト）
   • 制限付き（読み取り専用または限定された範囲にするための allowed-tools フィールド）

フェーズ 2：説明の作成

説明によって見つけやすさが決まります。実績のある次の形式を使用してください。

[Specific operations] + [When to use] + [Trigger terms]

例の解説：

• ❌ 「ドキュメントを支援します」（曖昧すぎます）
• ✅ 「PDF ファイルからテキストや表を抽出し、フォームに入力し、ドキュメントを結合します。PDF ファイルを扱う場合や、ユーザーが PDF、フォーム、ドキュメントの抽出について言及した場合に使用します。」

重要な要素：

1. 具体的な操作：具体的なアクションを列挙します（抽出、分析、生成、検証）
2. 使用するタイミング：状況やコンテキストを示します（X を扱う場合、Y の間、Z のタスク向け）
3. トリガー語句：ユーザーが実際に使う言葉を挙げます（PDF、フォーム、コミットメッセージ、データ分析）

他のパターンについては、examples/descriptions.md を参照してください。

フェーズ 3：名前の検証

名前を検証して整形します。

• 小文字に変換する
• スペースをハイフンに置き換える
• 無効な文字を削除する（使用できるのは a-z、0-9、- のみ）
• 64 文字以内にする
• 分かりやすく簡潔な名前にする

例：

• "My PDF Tool" → "my-pdf-tool"
• "Code Reviewer!!!" → "code-reviewer"
• "data_analysis" → "data-analysis"

フェーズ 4：構造の計画

次の場合は単一ファイルにします。

• 手順や例が 1 つのファイルに無理なく収まる
• スクリプトやユーティリティが不要
• ワークフローがシンプル

次の場合は複数ファイルにします。

• 詳細なドキュメントがある（reference.md に分割）
• スクリプトやユーティリティが必要（scripts/ ディレクトリ）
• テンプレートやひな形がある（templates/ ディレクトリ）
• 多数の例がある（examples.md）

複雑なスキルに推奨される構造：

skill-name/
├── SKILL.md           # Core instructions (loaded first)
├── reference.md       # Detailed API/reference (loaded if needed)
├── examples.md        # Additional examples (loaded if needed)
├── scripts/           # Utility scripts
│   ├── helper.py
│   └── process.sh
└── templates/         # Template files
    └── template.txt

フェーズ 5：実装

ディレクトリの作成

# Personal Skill
mkdir -p ~/.claude/skills/skill-name

# Project Skill
mkdir -p .claude/skills/skill-name

# Multi-file structure
mkdir -p ~/.claude/skills/skill-name/{templates,scripts,examples}

SKILL.md の作成

テンプレートの構造：

---
name: skill-name
description: [Use the formula from Phase 2]
allowed-tools: Read, Grep, Glob  # Optional: only if restricting tools
---

# Skill Name

Brief introduction explaining what this Skill does.

## Quick Start

Provide the most common use case with a concrete example.

## Instructions

Step-by-step guidance for Claude:

1. [First step with specific actions]
2. [Second step with expected behavior]
3. [Continue pattern]

## Examples

Show concrete code examples:

```language
# Example code that demonstrates usage

ベストプラクティス

• 重要な原則やパターン
• 重要な考慮事項
• 避けるべきよくある落とし穴

要件

依存関係を列挙します。

pip install required-package

#### Add supporting files if multi-file

Reference from SKILL.md:
```markdown
For detailed API reference, see [reference.md](reference.md).

Use the helper script:
```bash
python scripts/helper.py input.txt

### Phase 6: Validation

Before finalizing, check:

- [ ] Description follows formula (what + when + triggers)
- [ ] Description under 1024 characters
- [ ] Name is lowercase-with-hyphens, under 64 chars
- [ ] YAML has opening and closing `---`
- [ ] YAML uses spaces not tabs
- [ ] Instructions are clear and actionable
- [ ] Examples are concrete and tested
- [ ] Dependencies are documented
- [ ] Tool restrictions (if any) are appropriate

See [reference/validation-checklist.md](reference/validation-checklist.md) for complete checklist.

### Phase 7: Testing

1. **Restart Claude Code** (required for Skills to load)

2. **Test discovery**:
   - Ask using trigger terms from your description
   - Verify Skill activates automatically
   - Try variations of trigger phrases

3. **Test workflow**:
   - Follow instructions as Claude
   - Verify all examples work
   - Check edge cases

4. **Debug if needed**:
   ```bash
   # Check Skill was loaded
   # Ask: "What Skills are available?"

   # View Skill file
   cat ~/.claude/skills/skill-name/SKILL.md

   # Check for YAML syntax errors
   claude --debug

よくある問題と解決策

問題：スキルが有効化されない

原因：

1. 説明が曖昧すぎる
2. トリガー語句がユーザーの言葉と一致しない
3. YAML 構文エラー
4. Claude Code を再起動していない

解決策：

1. トリガー語句を具体的に含め、説明をより明確にする
2. 同義語や関連語を追加する
3. YAML を検証する（--- の区切り、タブではなくスペースを使用しているかを確認）
4. Claude Code を再起動する

問題：スキルが意図しないときに有効化される

原因：

1. 説明の範囲が広すぎる
2. 他のスキルと重複している

解決策：

1. 説明の範囲を狭める
2. コンテキスト（ファイル形式、操作など）を具体的にする
3. 焦点を絞ったスキルに分割することを検討する

問題：YAML 構文エラー

よくある間違い：

• 開始用の --- がない（1 行目）
• 終了用の --- がない（Markdown コンテンツの前）
• スペースではなくタブを使用している
• 特殊文字を含む文字列を引用符で囲んでいない

修正方法：

---
name: skill-name
description: Description text here
---

# Markdown starts here

反復と改善

Skillを使った後は、改善しましょう。

1. 有効化のパターンを追跡する：期待どおりに有効化されますか？
2. フィードバックを集める：わかりにくい点や不足している点はありませんか？
3. 説明を洗練させる：実際の使用状況からトリガー語を追加します
4. 例を増やす：遭遇した実際のシナリオを追加します
5. 手順を更新する：曖昧な手順を明確にします

教育原則

Skillを作成する際は、次の点を覚えておきましょう。

説明が重要な理由：Claudeは説明を使ってSkillを見つけます。曖昧な説明では、有効化されません。

複数ファイル構成が有効な理由：段階的に読み込めるからです。ClaudeはまずSKILL.mdを読み、必要に応じて補助ファイルを読み込みます。これにより、コンテキストを絞り込めます。

ツール制限が強力な理由：安全で、目的に集中したSkillを作成できます。読み取り専用の分析Skillであれば、誤ってファイルを変更することはありません。

トリガー語が重要な理由：ユーザーはSkillの存在を知りません。ユーザーは自然な言葉で質問します。トリガー語が、ユーザーの言葉とSkillを結びつけます。

クイックテンプレート

基本的なSkillのテンプレート：templates/basic-skill.md

高度な複数ファイルテンプレート：templates/advanced-skill.md

説明の例：examples/descriptions.md

優れたSkillを作るためのヒント

1. 説明を具体的にする - 正確な操作、ファイルの種類、シナリオを示します
2. 同義のトリガー語を含める - ユーザーによって表現は異なります
3. シンプルに始めて、後から拡張する - まずは単一ファイルで始め、必要に応じて複雑さを加えます
4. 実際のリクエストでテストする - ユーザーが実際に使いそうな言葉を使います
5. 依存関係を明確に記載する - パッケージがインストール済みだと決めつけないでください
6. 具体例を示す - 説明するだけでなく、例を示します
7. 実行可能な手順にする - 曖昧な指針ではなく、具体的な手順を示します
8. スコープを慎重に検討する - 実験には個人用、チームにはプロジェクト用を選びます
9. ツール制限を適切に使う - 分析やレビューには読み取り専用のSkillを使います
10. 使用状況に基づいて反復する - 実際の有効化パターンからトリガー語を洗練させます

次のステップ

Skillを作成した後は、次のことを行います。

1. チームと共有します（プロジェクト用Skillの場合は、gitにコミットします）
2. 他の人にも知っておいてほしいパターンであれば、プロジェクトのCLAUDE.mdに記載します
3. 関連するワークフロー向けに、関連Skillを作成します
4. より広く配布するために、複数のSkillをプラグインとしてまとめることを検討します

---

覚えておきましょう：優れたSkillには、トリガー語を含む具体的な説明があります。それが、使われるSkillと、決して有効化されないSkillの違いです。