初めてClaude Skillsを作るときに見る記事
はじめに
対象読者やClaude Skillsの簡単な説明
対象読者
- Claude Skillsが何なのかを調べている人
- 公式のベストプラクティスを踏襲したSkillsの使い方を知りたい人
当記事は公式のブログ記事やGithub Repositoryの情報を集めたものです。
細かい内容が気になる方は、記事の最後に引用を載せますので、そちらを参照してみてください。
いつSkillsを作るべきなのか
Skillsとは
公式のヘルプにはこのようにあります
Skillsは、Claudeが専門的なタスクのパフォーマンスを向上させるために動的に読み込む、指示、スクリプト、リソースのフォルダです。[1]
つまりSkillsとは何らかのコンテキストを保持している、ファイル群です。
何かしら専門的なタスクを行うときに、毎回具体的な指示を出すことを不要とすることで、コンテキストの節約やアウトプットの精度を良くすることができます。
ちなみにSkillsは Agent Skills と書かれている記事も多くあります。
おそらく正式名称はAgent Skillsなのだと思うのですが、公式でも記事の編集などが多く平仄がブレている印象です。
Skillsを作るべきタイミング
Start with use cases
Don't write skills speculatively. Build them when you have real, repeated tasks. The best skills solve problems you encounter regularly.
Before creating a skill, ask: Have I done this task at least five times? Will I do it at least ten more times? If yes, a skill makes sense.
Skillsは当てずっぽうで作るのではなく、実際のユースケースを元に作成してください。
それはあなたが繰り返し行っているタスクです。
スキルを作成するときに自分に訪ねて見てください。
このタスクを最低でも5回は行ったか。また将来的に後10回は行うだろうか。
その場合、スキルを作るのが正しいと言えます。
例えばClaude Codeで作業をするときに以下のような悩みにぶつかったことはないですか？
- ディレクトリ構成やコード規約が独自のもので、毎回追加の指示を出して修正をさせないといけない。
- 何かしらの調査タスクに対して、毎回アウトプットの形式がブレるので理解に時間がかかる。
- そもそも指示を出したいが、自分があまり内容を理解していない分野なので言語化が難しい。
このような場合Custom Skillsを作ることで無駄なやり取りやアウトプット企画の統一をすることで、より快適なAI駆動ライフを送ることができます。
Custom Slash Commandsと何が違うのか
Skillsを作ろうと思ったときに、これはCustom Slash Commandsで作ったほうがよいのか・・？と迷うことがあります。
違いが詳細に記載されています。[2]
Slash Commandsは
- よく使う簡単なプロンプト
- 簡単なリマインダーやテンプレート
- よく使う指示で一つのファイルに収まるもの
Skillsは
- 何ステップにも分かれる複雑なワークフロー
- スクリプトやユーティリティ(他のファイルなど)を利用できる
- 複数ファイルにまたがる知識の集合体
- チームで標準化したいワークフロー
また、Skillsは複数の記事で、繰り返し改善していきましょうといった内容が記載されています。[3]
これらを見る感じ、以下のような差分がありそうです。
| 比較項目 | Slash Commands | Skills |
|---|---|---|
| 複雑度 | シンプルなプロンプト | 複雑なマルチステップワークフロー |
| ファイル構成 | 単一ファイル（.md） | 複数ファイル可（フォルダ構成） |
| 外部リソース | 基本的に不可 | スクリプトやユーティリティを利用可能 |
| トリガー | 明示的（/commandで呼び出し） |
自動的（Claudeが文脈から判断） |
| チーム共有 | 可能だが個人用途が主 | チームでの標準化に最適 |
| 学習コスト | 低い | やや高い |
| メンテナンス | ほぼ不要 | 都度改善が必要 |
何が作れるのか
Skillsの作り方
公式ブログ[3]では、Skillsを作成するための5つのステップが紹介されています。以下はそのAI翻訳をベースにした内容です。
ステップ1: コア要件を理解する
コードを書く前に、スキルの目的を明確にしましょう。
例えば、「財務関係のことを手伝って」という曖昧なリクエストよりも、「PDFから財務データを抽出してCSV形式にフォーマットする」という方が効果的です。
これはSkillsがSlash Commandsと異なり、明確な呼び出しができない事による制約に関わってくる内容です。
Skillsのトリガーは明確にしないと、AIとの会話の中で呼び出すことが難しいです。
ステップ2: nameを書く
Skillsには3つの基本コンポーネントが必要です
- name（明確な識別子）
- description（起動条件）
- instructions（実行手順）
まずnameを決めましょう。
命名規則：
- 小文字とハイフンを使用
- 例：
pdf-editor、brand-guidelines - 短く、すぐに認識できるものにする
ステップ3: descriptionを書く（最重要）
悪い例：
This skill helps with PDFs and documents.
良い例：
Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale.
良い例には以下が含まれています：
- 具体的な動詞（extract、create、merge）
- 具体的なユースケース（フォーム入力、バッチ操作）
- 何をしないかの明確な境界線
name, descriptionはYAML Frontmatterと呼ばれるメタデータです。
Claudeはユーザーが出したプロンプトに対して、メタデータを参照しHITしたときにSKILL.mdの内容を読みだします。
そのため、メタデータは ClaudeがこのSkillsを呼び出すかどうか の観点で重要です。
name: guideline-deep-reading
description: "ユーザーが開発ガイドラインを理解したいときに使用する。社内の開発ガイドラインを構造を理解し、ユーザーライクな形でのアウトプットを提供する。社内の開発ガイドライン以外の公式ガイドラインの情報などは提供しない。"
ステップ4: メイン指示を書く
指示を明確な階層構造で構成します：
- Overview：スキルの目的
- Prerequisites：必要な前提条件
- Execution steps：順序立てた実行手順
- Concrete examples：正しい使用法を示す具体例
- Error handling：エラー処理のガイダンス
- Limitations：誤用を防ぐための制限事項
見やすさのために、ヘッダーと箇条書きを使ったマークダウン形式を使用してください。SKILL.mdファイルには、追加の明確性のための参考ドキュメントやアセットを含めることもできます。
ステップ5: スキルをアップロードする
Claude Code：
skills/ディレクトリを作成し、その中にSKILL.mdファイルを含むスキルフォルダを配置します：
my-project/
├── skills/
│ └── my-skill/
│ └── SKILL.md
ステップ6: テストと検証
デプロイ前に、3つのシナリオのテストマトリクスでスキルをテストします：
-
通常操作（Normal Operations）：スキルが完璧に処理すべき典型的なリクエストでテストします。例えば、財務分析スキルは決算報告書やSEC提出書類で機能する必要があります。
-
エッジケース（Edge Cases）：不完全または異常な入力でテストします。公式ガイドでは「スキルはこれらを適切に処理する必要があります。劣化しているが有用な出力を生成するか、続行するために何が必要かを説明するかのいずれかです」と述べています。
-
範囲外のリクエスト（Out-of-Scope Requests）：関連しているが異なるタスクに対してスキルが非アクティブのままであることを確認します。契約レビュースキルは雇用契約書では起動すべきではありません。
ステップ7: 使用状況に基づいて反復改善する
公式ガイドでは実世界での改善を強調しています：
「実世界での使用状況においてスキルがどのように機能するかを監視してください。トリガーが一貫していない場合はdescriptionを改善してください。出力が予期せず変動する場合は指示を明確にしてください。」
これはプロンプトエンジニアリングと同様で、スキルは理論的な最適化だけでなく、実際の適用を通じて改善されます。
どうやってつくるのか
前述の7ステップでSkillsを作成することもできますが、Claude CodeではAnthropicが公式に提供している skill-creator を使うことで、より簡単にSkillsを作成できます。
skill-creator を使うメリット：
- 公式がメンテナンスしている最新のSkills構造に準拠したテンプレートが自動生成される
- 必要な項目（name、description、instructions）が適切に配置された雛形が作成される
- ベストプラクティスに沿った構成になるため、学習コストが低い
インストール方法
Claude Codeで以下のコマンドを実行して、プラグインマーケットプレイスを登録します。
/plugin marketplace add anthropics/skills
次に、以下のいずれかの方法でスキルをインストールします。
GUIからインストールする場合:
- 「Browse and install plugins」を選択
-
anthropic-agent-skillsを選択 -
example-skillsを選択 - 「Install now」を選択
コマンドから直接インストールする場合:
/plugin install example-skills@anthropic-agent-skills
example-skillsの中にskill-creatorが含まれています。
使い方
Skillsは明示的に呼び出せないので、プロンプト内に以下のように入力などをすることで扱うことができます。
skill-creatorを使ってskillsを作りたい
appendix
skill-creatorの構成内容
skill-creatorの内部構造や記載内容を理解して、自作Skillsを作成するときの参考にしましょう。
SKILL.md[4]には以下のような段落構成で記載されています。
- Skill Creator (主題)
- About Skills
- Core Principles
- Skill Creation Process
これが先程示した、以下の順番にリンクしていることができます
Overview：スキルの目的 -> Skill Creator (主題), About Skills
Prerequisites：必要な前提条件 -> Core Principles
Execution steps：順序立てた実行手順 -> Skill Creation Process
Concrete examples：正しい使用法を示す具体例
Error handling：エラー処理のガイダンス
Limitations：誤用を防ぐための制限事項
skill-creatorのリソースファイル群
skill-creatorはreferences/とscripts/にリソースファイルを持っています。
それぞれどのようなことをやっているか説明します。
references/ - 参考資料
Skillsを作成する際に参照すべきドキュメントが格納されています。
-
output-patterns.md: 出力形式や品質基準を定義する際のパターン集
- テンプレートや例示を使った効果的な出力設計方法を説明
-
workflows.md: 複数ステップのワークフローや条件分岐の設計パターン
- 順次処理や条件付きロジックの実装方法を説明
これらのファイルは、SKILL.mdから必要に応じて読み込まれ、Skillsの設計に関するベストプラクティスを提供します。
scripts/ - スクリプト
Skillsの作成、検証、パッケージ化を支援する実行可能なPythonスクリプトが含まれています。
-
init_skill.py: 新しいSkillのテンプレートを生成
- 適切なディレクトリ構造とSKILL.mdの雛形を自動作成
-
package_skill.py: Skillsを配布可能な.skillファイルにパッケージ化
- 検証とパッケージングを自動実行
-
quick_validate.py: Skillsの構造と内容を検証
- YAML frontmatterやファイル構造の妥当性をチェック
これらのスクリプトにより、Skillsの作成プロセスが効率化され、一貫性のある品質が保たれます。
Discussion