skill-best-practices

---

スキルのベストプラクティス

参考：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf

手順

ステップ 1：ユースケースのカテゴリを特定する

構築するスキルの種類を判断します。

• ドキュメントとアセットの作成 — 一貫性のある出力（ドキュメント、デザイン、コード）
• ワークフローの自動化 — 一貫した方法論に基づく複数ステップのプロセス
• MCP の強化 — MCP ツールへのアクセスに基づくワークフローガイダンス

作成を始める前に、具体的なユースケースを 2～3 件定義します（下記の「計画」セクションを参照）。

ステップ 2：フォルダーと SKILL.md を作成する

• フォルダー名は kebab-case にします（例：my-skill-name）
• フォルダー内に SKILL.md を 1 つだけ作成します（大文字と小文字を区別します）
• name と description を含む YAML フロントマターを記述します（技術要件を参照）

ステップ 3：説明を記述する — ここが最も重要です

説明によって、Claude がスキルを読み込むタイミングが決まります。次の内容を含める必要があります。

• スキルが実行する 内容
• スキルを使用する タイミング（具体的なトリガーフレーズ）
• 任意：対象外とする条件（「次の場合は使用しないでください」など）

良い例と悪い例については、「効果的な説明の書き方」を参照してください。

ステップ 4：本文の指示を記述する

推奨テンプレートに従います：## Instructions → 番号付きの手順 → ## Examples → ## Troubleshooting。 具体的で実行可能な内容にします。詳細なドキュメントは references/ に移し、リンクします。

ステップ 5：CLAUDE.md と README.md を更新する

このリポジトリ内でスキルを作成または変更した後は、必ず両方のファイルにあるスキル一覧を更新します。

• CLAUDE.md — 「Included Skills」の下にあるスキル一覧（Trigger 列：発動条件を 1 行で説明）
• README.md — 「Enthaltene Skills」の下にあるスキル一覧（Beschreibung 列：ドイツ語で 1 行にまとめた説明）

両方のファイルの内容を常に一致させてください。この手順は必須であり、省略してはいけません。

また、このリポジトリでスキルを扱う際は、cc-best-practices スキルも呼び出し、コンテキスト管理とセッション管理がプロジェクトの標準に従っていることを確認してください。

ステップ 6：YAML と skills CLI との互換性を検証する

テストまたはコミットの前に、リポジトリのルートから検証スクリプトを実行します。

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh

続行する前に、FAIL と表示された行をすべて修正します。よくある問題：

• description にブロックスカラー（> または |）を使用している → 引用符で囲んだ 1 行の文字列に置き換える
• 親のマッピングキーの下にあるサブキーがインデントされていない → 2 つのスペースでインデントする

プッシュした後は、リモートチェックも実行し、npx skills add --list ですべてのスキルが見つかることを確認します。

bash .claude/skills/skill-best-practices/scripts/validate-skills.sh --remote

ステップ 7：トリガーと機能の動作をテストする

テストクエリを 10～20 件実行します。目標は、関連するクエリの約 90% でスキルが発動し、無関係なトピックでは一切発動しないことです。 トリガーが安定するまで説明を調整します（テスト方法を参照）。

ステップ 7：シグナルに基づいて反復する

• 発動が少なすぎる → 説明にトリガーフレーズを追加する
• 発動が多すぎる → 除外条件を追加して、対象範囲を狭める
• 指示が無視される → 重要な手順を先頭に移し、明確な表現を使う

---

例

例 1：新しいスキルを一から構築する

ユーザーの依頼：「Linear でスプリントを計画するスキルを作るのを手伝ってください」

実行内容：

1. カテゴリを特定する：ワークフローの自動化 + MCP の強化
2. ユースケースを定義する：トリガー＝「スプリントを計画」「スプリントのタスクを作成」、手順＝Linear のステータスを取得 → ベロシティを分析 → タスクを作成
3. linear-sprint-planner/SKILL.md フォルダーを作成する
4. 説明を記述する：「Linear のスプリント計画ワークフローを管理します。ユーザーが『スプリントを計画』『スプリントのタスクを作成』『イテレーションを設定』と言った場合に使用します。」
5. Linear MCP ツールの呼び出しを含む、手順を追った指示を記述する
6. トリガーフレーズを 10 件テストし、スキルが自動的に読み込まれない場合は説明を調整する

結果：スプリント計画の依頼で自動的に発動し、ユーザーが毎回手順を説明し直さなくてもワークフロー全体を実行する、実用的なスキルです。

例 2：既存のスキルをレビューする

ユーザー：「自分の SKILL.md をレビューして、改善点を提案してください」

アクション：

1. SKILL.md のフロントマターを読む — name（kebab-case になっているか？）、description（WHAT + WHEN が含まれているか？ 1024 文字未満か？ トリガーフレーズがあるか？）を確認します
2. 本文を確認する — 5,000 語未満か？ 指示は具体的で実行可能か？ トラブルシューティングのセクションはあるか？ 例はあるか？
3. トリガーをシミュレートする — description によって、適切なクエリで Claude がこのスキルを読み込むか？
4. 各基準について、結果を PASS / WARN / FAIL で報告する

結果：優先順位を付けた改善点の一覧と、各問題に対する具体的な修正案です。

例 3：トリガーされないスキルのトラブルシューティング

ユーザー：「自分のスキルが自動で読み込まれず、いつも手動で呼び出す必要があります」

アクション：

1. description フィールドを読む — 曖昧すぎないか？（「プロジェクトを支援します」ではうまくいきません）
2. トリガーフレーズが不足していないか確認する — ユーザーが実際に使いそうな言葉が含まれているか？
3. Claude に尋ねる：「どんなときに [skill name] スキルを使いますか？」— Claude が description をそのまま引用するので、不足している点が明らかになります
4. 具体的なトリガーフレーズを加えて description を書き直し、再テストする

結果：具体的なトリガーを含む description に更新され、関連するクエリでスキルが自動的に読み込まれます。

---

スキルとは？

スキルとは、次の内容を含むフォルダーです。

• SKILL.md（必須）：YAML フロントマターを含む Markdown 形式の指示
• scripts/（任意）：実行可能なコード（Python、Bash など）
• references/（任意）：必要に応じて読み込まれるドキュメント
• assets/（任意）：出力で使用するテンプレート、フォント、アイコン

設計の基本原則

段階的な開示 — 3 つのレベルがあります。

1. YAML フロントマター：常にシステムプロンプトに含まれ、スキルを いつ 読み込むかを Claude に伝えます
2. SKILL.md 本文：関連する場合に読み込まれる、すべての指示です
3. references/ 内のリンクされたファイル：必要に応じて読み込まれます

組み合わせ可能性 — スキルは他のスキルと併用できます。排他的に使われることを前提にしないでください。

移植性 — Claude.ai、Claude Code、API で同じように動作します。

---

計画：ユースケースから始める

作成を始める前に、具体的なユースケースを 2～3 個定義します。

Use Case: <name>
Trigger: User says "<phrase>" or "<phrase>"
Steps:
  1. ...
  2. ...
Result: <expected outcome>

次の点を自問してください。

• ユーザーは何を達成したいのか？
• どのような複数ステップのワークフローが必要か？
• どのツール（組み込みまたは MCP）が必要か？
• どのようなドメイン知識を組み込むべきか？

3 つのスキルカテゴリー

カテゴリー	使用するタイミング	主な手法
ドキュメントとアセットの作成	一貫性のある高品質な出力（ドキュメント、デザイン、コード）	スタイルガイド、テンプレート、品質チェックリスト
ワークフローの自動化	一貫した手法で進める複数ステップのプロセス	検証ゲートを設けた段階的な手順、反復ループ
MCP の拡張	MCP ツールへのアクセスにワークフローのガイダンスを追加	MCP 呼び出しの順序付け、組み込みのドメイン知識

---

技術要件

ファイルとフォルダーの命名

• フォルダー：kebab-case のみ（notion-project-setup）— スペース、アンダースコア、大文字は使用しません
• ファイル：正確に SKILL.md（大文字と小文字を区別）— 別の表記は使用できません
• スキルフォルダー内に README.md を置かないでください（ドキュメントは SKILL.md または references/ に記載します）

YAML フロントマター

最小限の必須形式：

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

name（必須）：

• kebab-case。スペースや大文字は使用しません
• フォルダー名と一致している必要があります

description（必須）：

• スキルが何をするか、いつ使うか（トリガー条件）の両方を必ず含めます
• 1024 文字未満
• XML タグ（< または >）を含めません
• ユーザーが実際に使いそうな具体的なトリガーフレーズを含めます
• 関連する場合はファイルの種類に言及します

任意のフィールド：

license: MIT
compatibility: "Requires Python 3.10+"
metadata:
  author: Your Name
  version: 1.0.0
  mcp-server: server-name

セキュリティ上の制限 — フロントマターで禁止されている内容：

• XML の山括弧（< >）
• 「claude」または「anthropic」を含む名前（予約済み）

効果的な説明の書き方

構成：[何をするか] + [いつ使うか] + [主な機能]

良い例：

# Specific and actionable
description: Analyzes Figma design files and generates developer handoff docs.
  Use when user uploads .fig files, asks for "design specs", "component
  documentation", or "design-to-code handoff".

# Includes trigger phrases
description: Manages Linear project workflows including sprint planning and
  task creation. Use when user mentions "sprint", "Linear tasks", or asks
  to "create tickets".

悪い例：

# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user triggers
description: Implements the Project entity model with hierarchical relationships.

---

指示の書き方（SKILL.md の本文）

推奨される構成：

# Your Skill Name

## Instructions

### Step 1: [First Major Step]

Clear explanation of what happens.

### Step 2: ...

## Examples

### Example 1: [Common scenario]

User says: "..."
Actions:

1. ...
   Result: ...

## Troubleshooting

### Error: [Common error message]

**Cause:** Why it happens
**Solution:** How to fix

指示を書く際のベストプラクティス

具体的で、実行可能な内容にする：

# Good
Run `python scripts/validate.py --input {filename}` to check data format.
If validation fails, common issues:
- Missing required fields (add to CSV)
- Invalid date formats (use YYYY-MM-DD)

# Bad
Validate the data before proceeding.

エラー処理を含める — よくあるエラーとその原因、解決策を記載します。

同梱リソースを明確に参照する：

Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns

段階的に情報を開示する — SKILL.md は中核となる指示に絞り、詳細なドキュメントは references/ に移してリンクします。SKILL.md は 5,000 語未満にしてください。

重要な検証では、言語による指示よりも同梱スクリプトを優先します。コードは決定的ですが、言語の解釈はそうではありません。

---

テスト方法

1. トリガーテスト

10～20 件のクエリを実行します。スキルは関連するクエリの約 90% でトリガーされ、無関係なトピックではトリガーされないようにします。

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"

Should NOT trigger:
- "What's the weather?"
- "Help me write Python code"

デバッグ： Claude に「[skill name] スキルはどのような場合に使いますか？」と尋ねます。Claude は説明をそのまま引用します。

2. 機能テスト

• 有効な出力が生成される
• API 呼び出しが成功する
• エラー処理が機能する
• エッジケースに対応している

3. パフォーマンスの比較

スキルを使う場合と使わない場合で、トークン数、ツール呼び出し数、やり取りの往復数を比較します。

プロのヒント： Claude が成功するまで、難易度の高いタスクを 1 つ選んで繰り返し改善し、うまくいった方法をスキルに取り込みます。

---

トラブルシューティング

スキルをアップロードできない

エラー	原因	修正方法
"Could not find SKILL.md"	ファイル名が間違っている	SKILL.md に正確に変更する
"Invalid frontmatter"	YAML の書式	--- 区切りを追加し、引用符を閉じる
"Invalid skill name"	名前にスペースまたは大文字が含まれている	ケバブケースを使用する

スキルがトリガーされない（トリガー不足）

• 説明が一般的すぎる
• ユーザーが実際に使うトリガーフレーズが不足している
• 関連するファイル形式への言及が不足している

修正方法： 説明に、より具体的なキーワードやフレーズを追加します。

スキルが頻繁にトリガーされる（過剰トリガー）

否定的なトリガーを追加し、対象範囲を絞り込みます。

description: Advanced data analysis for CSV files. Use for statistical modeling,
  regression, clustering. Do NOT use for simple data exploration.

指示に従わない

1. 冗長すぎる — 簡潔にまとめ、箇条書きを使い、詳細は references/ に移します
2. 指示が埋もれている — 重要な指示を冒頭に置き、## Critical 見出しを使います
3. 表現が曖昧 — 明確に記述します：「重要：X を呼び出す前に、次を確認してください……」
4. モデルが手を抜く — ユーザープロンプトに追加します（SKILL.md に追加するより効果的です）：「時間をかけ、速度より品質を重視し、検証手順を省略しないでください」

コンテキストが大きい／応答が遅い

• 詳細なドキュメントを references/ に移します
• SKILL.md を 5,000 語未満に保ちます
• 同時に有効にするスキルの数を減らします（20～50 を超える場合は見直してください）

---

ワークフローパターン

ほとんどのスキルタイプは、次の 5 つのパターンで対応できます：逐次オーケストレーション、複数の MCP との連携、反復的な改善、コンテキストを考慮したツール選択、ドメイン固有のインテリジェンスです。

各パターンの詳しい例と実装テンプレートについては、references/patterns.md を参照してください。

---

クイックチェックリスト

開始前：

• 具体的なユースケースを2～3個特定した
• ツール（組み込みまたはMCP）を特定した
• フォルダー構成を計画した

開発中：

• フォルダー名をケバブケースにした
• SKILL.md が存在する（スペルと大文字・小文字が完全に一致）
• YAMLフロントマターに --- 区切りがある
• name：ケバブケースで、スペースや大文字を含まない
• description に WHAT と WHEN が含まれている
• XMLタグ（< >）がどこにもない
• 手順が明確で実行可能である
• エラー処理を含めた
• 例を提示した
• 参照先を明確にリンクした

リポジトリの同期（このリポジトリでは必須）：

• CLAUDE.md のスキル一覧を更新した
• README.md のスキル一覧を更新した
• このセッション中に cc-best-practices スキルを読み込んだ
• validate-skills.sh を実行した — FAIL 行がない
• プッシュ後に validate-skills.sh --remote を実行した — すべてのスキルが npx skills で見つかる

アップロード前：

• 典型的なタスクでトリガーされる
• 言い換えられたリクエストでもトリガーされる
• 無関係なトピックではトリガーされない
• 機能テストに合格する

アップロード後：

• 実際の会話でテストする
• トリガーの過不足を監視する
• 説明と手順を繰り返し改善する