ベストプラクティス

Claude が発見して効果的に使用できる Skills を作成する方法を学びます。

良い Skills は簡潔で、構造が整っており、実際の使用でテストされています。このガイドでは、Claude が発見して効果的に使用できる Skills を作成するための実用的な決定事項を提供します。

Skills の仕組みの概念的な背景については、Skills の概要を参照してください。

基本原則

簡潔さが鍵

コンテキストウィンドウは共有リソースです。あなたの Skill は、Claude が知っておくべき他のすべてのものとコンテキストウィンドウを共有します：

システムプロンプト
会話履歴
他の Skills のメタデータ
実際のリクエスト

Skill のすべてのトークンに即座のコストがあるわけではありません。起動時には、すべての Skills のメタデータ（名前と説明）のみがプリロードされます。Claude は Skill が関連するようになったときにのみ SKILL.md を読み取り、必要な場合にのみ追加のファイルを読み取ります。ただし、SKILL.md で簡潔にすることは依然として重要です：Claude がロードすると、すべてのトークンが会話履歴や他のコンテキストと競合します。

デフォルトの前提：Claude はすでに非常にスマート

Claude がまだ持っていないコンテキストのみを追加します。各情報を検討してください：

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

良い例（簡潔、約 50 トークン）：

## PDF テキストを抽出
pdfplumber を使用してテキストを抽出：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()


**悪い例**（冗長すぎる、約 150 トークン）：

```markdown
## PDF テキストを抽出
PDF（Portable Document Format）ファイルは、テキスト、画像、その他のコンテンツを含む一般的なファイル形式です。PDF からテキストを抽出するには、ライブラリを使用する必要があります。PDF 処理に利用できるライブラリは多くありますが、使いやすく、ほとんどのケースをうまく処理するため、pdfplumber をお勧めします...

簡潔なバージョンは、Claude が PDF とは何か、ライブラリがどのように機能するかを知っていると想定しています。

適切な自由度を設定する

タスクの脆弱性と変動性に応じて特異性のレベルを合わせます。

高い自由度（テキストベースの指示）：

使用する場合：

複数のアプローチが有効
決定はコンテキストに依存
ヒューリスティックがアプローチをガイド

中程度の自由度（疑似コードまたはパラメータ付きスクリプト）：

使用する場合：

優先パターンが存在
いくつかの変動が許容可能
構成が動作に影響

低い自由度（特定のスクリプト、パラメータがほとんどまたはまったくない）：

使用する場合：

操作が脆弱でエラーが発生しやすい
一貫性が重要
特定のシーケンスに従う必要がある

使用予定のすべてのモデルでテスト

Skills はモデルへの追加として機能するため、効果は基礎となるモデルに依存します。使用予定のすべてのモデルで Skill をテストしてください。

モデル別のテスト考慮事項：

Claude Haiku（高速、経済的）：Skill は十分なガイダンスを提供していますか？
Claude Sonnet（バランス型）：Skill は明確で効率的ですか？
Claude Opus（強力な推論）：Skill は過度な説明を避けていますか？

Skill の構造

YAML Frontmatter：SKILL.md の frontmatter には 2 つのフィールドが必要です：

name：

最大 64 文字
小文字、数字、ハイフンのみ
XML タグは不可
予約語は不可：「anthropic」、「claude」

description：

空であってはなりません
最大 1024 文字
XML タグは不可
Skill が何をするか、いつ使用するかを説明する必要があります

命名規則

Skills を参照しやすく議論しやすくするために、一貫した命名パターンを使用します。Skill 名には動名詞形（動詞 + -ing）を使用することをお勧めします。

良い命名例（動名詞形）：

processing-pdfs
analyzing-spreadsheets
managing-databases
testing-code
writing-documentation

避けるべきもの：

曖昧な名前：helper、utils、tools
過度に一般的：documents、data、files
予約語：anthropic-helper、claude-tools

効果的な説明を書く

description フィールドは Skill の発見を可能にし、Skill が何をするか、いつ使用するかの両方を含める必要があります。

常に三人称で書く。説明はシステムプロンプトに注入され、一貫しない視点は発見の問題を引き起こす可能性があります。

良い：「Excel ファイルを処理してレポートを生成する」
避ける：「Excel ファイルの処理をお手伝いします」
避ける：「これを使用して Excel ファイルを処理できます」

段階的開示パターン

SKILL.md は、オンボーディングガイドの目次のように、必要に応じて Claude を詳細な資料に導くための概要として機能します。

実用的なガイダンス：

最適なパフォーマンスのために SKILL.md の本文を 500 行未満に保つ
この制限に近づいたら、コンテンツを別のファイルに分割

✓ 良い：scripts/helper.py、reference/guide.md
✗ 避ける：scripts\helper.py、reference\guide.md

生成されたコードより信頼性が高い
トークンの節約（コンテキストにコードを含める必要がない）
時間の節約（コード生成が不要）
使用間の一貫性を確保

技術的な注意事項

YAML frontmatter の要件

name：最大 64 文字、小文字/数字/ハイフンのみ、XML タグなし、予約語なし
description：最大 1024 文字、空でないこと、XML タグなし

✓ 説明が具体的でキーワードを含む
✓ 説明が Skill の機能と使用タイミングの両方を含む
✓ SKILL.md の本文が 500 行未満
✓ 追加の詳細が別のファイルにある（必要な場合）
✓ 時間に敏感な情報がない
✓ 全体を通して一貫した用語
✓ 例が抽象的ではなく具体的

コードとスクリプト

✓ スクリプトが Claude に丸投げせずに問題を解決
✓ エラー処理が明確で有用
✓ 「魔法の定数」がない（すべての値に理由がある）
✓ 必要なパッケージがリストされ検証済み
✓ Windows スタイルのパスがない

テスト

✓ 少なくとも 3 つの評価を作成
✓ Haiku、Sonnet、Opus でテスト
✓ 実際の使用シナリオでテスト

ベストプラクティス

基本原則

簡潔さが鍵

適切な自由度を設定する

使用予定のすべてのモデルでテスト

Skill の構造

命名規則

効果的な説明を書く

段階的開示パターン

深くネストされた参照を避ける

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

複雑なタスクにはワークフローを使用

フィードバックループを実装

コンテンツガイドライン

時間に敏感な情報を避ける

一貫した用語を使用

一般的なパターン

テンプレートパターン

例パターン

条件付きワークフローパターン

評価と反復

最初に評価を構築

Claude と反復的に Skills を開発

避けるべきアンチパターン

Windows スタイルのパスを避ける

多すぎるオプションを提供しない

上級：実行可能コードを含む Skills

問題を解決し、丸投げしない

ユーティリティスクリプトを提供

技術的な注意事項

YAML frontmatter の要件

トークン予算

効果的な Skills のチェックリスト

コア品質

コードとスクリプト

テスト

On this page