skill-creator

スキルの作成

Deepagents のスキルの場所

deepagents CLI は、優先度の低い順から高い順に、次の 5 つの場所からスキルを読み込みます。

#	ディレクトリ	スコープ	備考
0	<package>/built_in_skills/	組み込み	deepagents CLI に同梱されています
1	$DEEPAGENTS_HOME/<agent>/skills/	ユーザー（deepagents エイリアス）	deepagents skills create のデフォルトです
2	~/.agents/skills/	ユーザー	エージェントツール間で共有されます
3	.deepagents/skills/	プロジェクト（deepagents エイリアス）	deepagents skills create --project のデフォルトです
4	.agents/skills/	プロジェクト	エージェントツール間で共有されます

<agent> はエージェント設定名です（デフォルト：agent）。2 つのディレクトリに同じ名前のスキルがある場合は、優先度の高いバージョンが使用されます。プロジェクトのスキルはユーザーのスキルより優先され、ユーザーまたはプロジェクトのスキルは組み込みスキルより優先されます。

ディレクトリ構成の例：

$DEEPAGENTS_HOME/agent/skills/     # user skills (lowest precedence)
├── skill-name-1/
│   └── SKILL.md
└── ...

<project-root>/.deepagents/skills/   # project skills (higher precedence)
├── skill-name-2/
│   └── SKILL.md
└── ...

基本原則

簡潔さが重要です

コンテキストウィンドウは共有資源です。スキルは、システムプロンプト、会話履歴、ほかのスキルのメタデータ、実際のユーザーリクエストなど、エージェントに必要なすべてのものとコンテキストウィンドウを共有します。

デフォルトの前提：エージェントはすでに非常に優れた能力を備えています。 エージェントがすでに知っていることは追加せず、必要なコンテキストだけを加えてください。情報の一つひとつについて、「エージェントに本当にこの説明が必要か？」、「この段落はトークンを消費するだけの価値があるか？」と問い直してください。

冗長な説明より、簡潔な例を優先してください。

適切な自由度を設定する

タスクの脆弱性と変動性に合わせて、具体性のレベルを調整してください。

高い自由度（テキストベースの指示）：複数のアプローチが有効な場合、判断がコンテキストに左右される場合、またはヒューリスティックに沿って進める場合に使用します。

中程度の自由度（パラメーター付きの疑似コードまたはスクリプト）：推奨されるパターンがあり、ある程度の変更が許容される場合、または設定が動作に影響する場合に使用します。

低い自由度（特定のスクリプト、少数のパラメーター）：操作が脆弱でエラーが発生しやすい場合、一貫性が重要な場合、または特定の順序で実行する必要がある場合に使用します。

エージェントを道を進む存在として考えてみてください。崖のある狭い橋では具体的な安全策が必要ですが（低い自由度）、開けた場所では多くのルートを選べます（高い自由度）。

スキルの構成

すべてのスキルは、必須の SKILL.md ファイルと、任意で同梱するリソースで構成されます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必須）

すべての SKILL.md は、次の要素で構成されます。

• フロントマター（YAML）：name と description フィールドを含みます。エージェントがスキルをいつ使用するかを判断する際に読み取るのは、この 2 つのフィールドだけです。そのため、スキルの内容と使用すべき状況を、明確かつ包括的に記述することが非常に重要です。
• 本文（Markdown）：スキルの使用方法に関する指示とガイダンスを記述します。スキルが起動した後にのみ（起動しない場合もあります）読み込まれます。

同梱リソース（任意）

スクリプト（scripts/）

決定論的な信頼性が求められるタスクや、繰り返し書き直されるタスクに使用する実行可能なコード（Python/Bash など）です。

• 含める場合：同じコードを繰り返し書き直している場合、または決定論的な信頼性が必要な場合
• 例：PDF の回転タスク用の scripts/rotate_pdf.py
• 利点：トークン効率がよく、動作が決定的で、コンテキストに読み込まずに実行できる場合があります
• 注記：パッチ適用や環境固有の調整のために、エージェントがスクリプトを読み込む必要がある場合もあります

References (references/)

エージェントの作業や思考の指針として、必要に応じてコンテキストに読み込むドキュメントや参考資料です。

• 含めるタイミング：作業中にエージェントが参照するドキュメントがある場合
• 例：財務スキーマの references/finance.md、会社の NDA テンプレートの references/mnda.md、会社のポリシーの references/policies.md、API 仕様の references/api_docs.md
• ユースケース：データベーススキーマ、API ドキュメント、ドメイン知識、会社のポリシー、詳細なワークフローガイド
• メリット：SKILL.md を簡潔に保ち、エージェントが必要と判断した場合にのみ読み込めます
• ベストプラクティス：ファイルが大きい場合（10k 語を超える場合）は、SKILL.md に検索パターンを記載します
• 重複を避ける：情報は SKILL.md と references ファイルのどちらか一方に記載し、両方には記載しないでください。スキルの中核に関わる情報でない限り、詳細情報は references ファイルに記載してください。これにより、コンテキストウィンドウを使いすぎず、情報を見つけやすくしながら SKILL.md を簡潔に保てます。SKILL.md には必須の手順とワークフローのガイダンスのみを残し、詳細な参考資料、スキーマ、例は references ファイルに移してください。

Assets (assets/)

エージェントの出力に使用するファイルであり、コンテキストへの読み込みを目的としないファイルです。

• 含めるタイミング：スキルが最終出力で使用するファイルを必要とする場合
• 例：ブランド素材の assets/logo.png、PowerPoint テンプレートの assets/slides.pptx、HTML/React のひな形の assets/frontend-template/、タイポグラフィ用フォントの assets/font.ttf
• ユースケース：テンプレート、画像、アイコン、ひな形コード、フォント、コピーまたは編集するサンプル文書
• メリット：出力用リソースをドキュメントから分離でき、エージェントはコンテキストに読み込まずにファイルを使用できます

スキルに含めないもの

スキルには、その機能を直接支える必須ファイルのみを含めてください。README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md など、不要なドキュメントや補助ファイルは作成しないでください。

スキルに含めるのは、AI エージェントが目的の作業を行うために必要な情報のみです。作成に至った経緯の補足情報、セットアップやテストの手順、ユーザー向けドキュメントなどの補助的な内容は含めないでください。ドキュメントファイルを追加すると、雑然として混乱を招くだけです。

段階的開示の設計原則

スキルでは、コンテキストを効率的に管理するために、3 段階の読み込みシステムを使用します。

1. メタデータ（名前 + 説明） - 常にコンテキストに含まれます（約 100 語）
2. SKILL.md 本文 - スキルが起動したときに読み込まれます（5k 語未満）
3. バンドルされたリソース - エージェントが必要に応じて読み込みます（スクリプトはコンテキストウィンドウに読み込まずに実行できるため、制限はありません）

段階的な開示のパターン

コンテキストの肥大化を最小限に抑えるため、SKILL.md の本文は必要最小限にし、500 行未満に保ちます。10 MB を超える SKILL.md ファイルは、エージェントのランタイムによって警告なくスキップされます。行数の上限に近づいたら、内容を別のファイルに分割します。内容をほかのファイルに分割する場合は、SKILL.md からそれらのファイルを参照し、いつ読み込むべきかを明確に説明することが非常に重要です。そうすることで、スキルを読む人がそれらのファイルの存在と使いどころを把握できます。

重要な原則： スキルが複数のバリエーション、フレームワーク、またはオプションに対応している場合は、コアとなるワークフローと選択方法の説明だけを SKILL.md に残します。バリエーション固有の詳細（パターン、例、設定）は、別の参照ファイルに移します。

パターン 1：参照ファイルを用いた概要ガイド

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

エージェントは必要な場合にのみ FORMS.md、REFERENCE.md、または EXAMPLES.md を読み込みます。

パターン 2：ドメイン固有の整理

複数のドメインを扱うスキルでは、不要なコンテキストの読み込みを避けるため、ドメインごとに内容を整理します。

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

ユーザーが売上指標について尋ねた場合、エージェントは sales.md のみを読み込みます。

同様に、複数のフレームワークやバリエーションに対応するスキルでは、バリエーションごとに整理します。

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

ユーザーが AWS を選択した場合、エージェントは aws.md のみを読み込みます。

パターン 3：条件付きの詳細

基本的な内容を示し、高度な内容へのリンクを設けます。

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

ユーザーがこれらの機能を必要とする場合にのみ、エージェントは REDLINING.md または OOXML.md を読み込みます。

重要なガイドライン：

• 参照を深くネストしすぎない - SKILL.md から参照する階層は 1 段階に保ちます。すべての参照ファイルは SKILL.md から直接リンクしてください。
• 長い参照ファイルを構成する - 100 行を超えるファイルには、プレビュー時にエージェントが全体の範囲を確認できるよう、先頭に目次を含めます。

スキル作成プロセス

スキルの作成には、次の手順があります。

1. 具体例を使ってスキルを理解する
2. 再利用可能なスキルの内容（スクリプト、参照ファイル、アセット）を計画する
3. スキルを初期化する（init_skill.py を実行する）
4. スキルを編集する（リソースを実装し、SKILL.md を作成する）
5. スキルを検証する（quick_validate.py を実行する）
6. 実際の使用状況に基づいて改善する

該当しない明確な理由がある場合にのみ手順を省略し、それ以外は順番どおりに進めてください。

手順 1：具体例を使ってスキルを理解する

スキルの使用パターンがすでに明確に理解されている場合にのみ、この手順を省略してください。既存のスキルを扱う場合でも、この手順は有益です。

効果的なスキルを作成するには、そのスキルがどのように使われるのかを具体例から明確に理解する必要があります。この理解は、ユーザーから直接得た例、または生成した例をユーザーのフィードバックで検証することで得られます。

たとえば、画像エディターのスキルを作成する場合、次のような質問が考えられます。

• 「画像エディターのスキルでは、どのような機能に対応する必要がありますか？ 編集、回転、それ以外にもありますか？」
• 「このスキルの使用例をいくつか挙げてもらえますか？」
• 「『この画像の赤目を補正して』や『この画像を回転して』といった依頼があると思います。ほかにも、このスキルがどのように使われると思いますか？」
• 「どのような依頼を受けたら、このスキルを起動すべきですか？」

ユーザーを圧倒しないよう、1 回のメッセージで質問しすぎないでください。最も重要な質問から始め、より効果的にするために必要に応じて追加で尋ねます。

このスキルが対応すべき機能を明確に把握できたら、この手順を完了します。

ステップ 2：再利用可能なスキルの内容を計画する

具体例を効果的なスキルにするには、各例を次の観点から分析します。

1. 例をゼロから実行する方法を検討する
2. こうしたワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定する

例：「この PDF を回転するのを手伝って」といったクエリに対応する pdf-editor スキルを構築する場合、分析から次のことが分かります。

1. PDF を回転するには、毎回同じコードを書き直す必要があります
2. スキルに保存する scripts/rotate_pdf.py スクリプトがあると便利です

例：「ToDo アプリを作って」や「歩数を記録するダッシュボードを作って」といったクエリに対応する frontend-webapp-builder スキルを設計する場合、分析から次のことが分かります。

1. フロントエンドのウェブアプリを書くには、毎回同じ HTML／React のボイラープレートが必要です
2. ボイラープレートの HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートがあると、スキルに保存するのに便利です

例：「今日ログインしたユーザーは何人ですか？」といったクエリに対応する big-query スキルを構築する場合、分析から次のことが分かります。

1. BigQuery へのクエリには、毎回テーブルのスキーマと関連性を再確認する必要があります
2. テーブルのスキーマを記載した references/schema.md ファイルがあると、スキルに保存するのに便利です

スキルに含める内容を決めるには、具体例をそれぞれ分析し、含める再利用可能なリソース（スクリプト、リファレンス、アセット）のリストを作成します。

ステップ 3：スキルを初期化する

ここから、実際にスキルを作成します。

開発するスキルがすでに存在し、反復やパッケージ化が必要な場合に限り、このステップをスキップしてください。その場合は次のステップに進みます。

新しいスキルを作成する方法は 2 つあります。

オプション A：init_skill.py（豊富な内容のスキルに推奨）

新しいスキルをゼロから作成する場合は、init_skill.py スクリプトを実行します。このスクリプトは、スキルに必要なものをすべて自動的に含む新しいテンプレートのスキルディレクトリを生成するため、スキル作成のプロセスが大幅に効率化され、信頼性も高まります。

使い方：

scripts/init_skill.py <skill-name> --path <output-directory>

Deepagents CLI の場合は、上記の「Deepagents のスキルの保存場所」に記載されているスキルディレクトリを使用します。

# User skills (default)
scripts/init_skill.py <skill-name> --path "${DEEPAGENTS_HOME:-$HOME/.deepagents}/agent/skills"

# Project skills
scripts/init_skill.py <skill-name> --path .deepagents/skills

スクリプトは次の処理を行います。

• 指定したパスにスキルディレクトリを作成します
• 適切なフロントマターと TODO プレースホルダーを含む SKILL.md テンプレートを生成します
• サンプルリソースディレクトリ scripts/、references/、assets/ を作成します
• 各ディレクトリに、カスタマイズまたは削除できるサンプルファイルを追加します

初期化後、必要に応じて、生成された SKILL.md とサンプルファイルをカスタマイズまたは削除してください。

オプション B：deepagents skills create（クイックスタート）

組み込みの CLI コマンドは、SKILL.md テンプレートだけを含む最小限のスキルを作成します。リソースディレクトリは作成されません。手順だけが必要で、スクリプト、リファレンス、アセットを同梱する必要がないシンプルなスキルには、この方法を使用してください。

# Create in user skills directory
deepagents skills create <skill-name>

# Create in project skills directory
deepagents skills create <skill-name> --project

スキルにリソース（scripts/、references/、assets/）を同梱する場合は、init_skill.py を使用してください。すばやく最小限のスキルを作成する場合は、deepagents skills create を使用してください。

ステップ 4：スキルを編集する

新しく生成したスキルでも既存のスキルでも、編集する際はエージェントが使用するために作成するスキルであることを忘れないでください。エージェントにとって有益で、すぐには分からない情報を含めましょう。エージェントがタスクをより効果的に実行するうえで役立つ、手順に関する知識、ドメイン固有の詳細、再利用可能なアセットについて検討してください。

実績のある設計パターンを学ぶ

順次的なワークフロー、条件分岐、出力形式に関する確立されたパターンについては、上記の「段階的開示の設計原則」と「コア原則」のセクションを参照してください。

再利用可能なスキルコンテンツから始める

実装を始めるには、上記で特定した再利用可能なリソース、つまり scripts/、references/、assets/ のファイルから始めます。このステップではユーザーからの入力が必要になる場合があることに注意してください。たとえば、brand-guidelines スキルを実装する場合、ユーザーは assets/ に保存するブランドアセットやテンプレート、または references/ に保存するドキュメントを提供する必要があるかもしれません。

追加したスクリプトは、実際に実行してテストし、バグがないことと、出力が期待どおりであることを確認する必要があります。類似したスクリプトが多数ある場合は、完了までの時間とのバランスをとりつつ、それらがすべて動作するという確信を得るために、代表的なサンプルのみをテストすれば十分です。

スキルに必要のないサンプルファイルやディレクトリは削除する必要があります。初期化スクリプトは構造を示すために scripts/、references/、assets/ にサンプルファイルを作成しますが、ほとんどのスキルはそれらすべてを必要としません。

SKILL.md を更新する

記述ガイドライン: 常に命令形/不定詞形を使用してください。

フロントマター

name と description を含む YAML フロントマターを記述します:

• name: スキル名
• description: これはスキルの主要なトリガー機構であり、エージェントがいつスキルを使用すべきかを理解する助けになります。
  • スキルが何を行うかと、いつ使用するかの具体的なトリガー/コンテキストの両方を含めてください。
  • 「いつ使用するか」の情報はすべてここに含めてください。本文には含めないでください。本文はトリガー後にのみ読み込まれるため、本文中の「このスキルをいつ使用するか」というセクションはエージェントにとって役に立ちません。
  • docx スキルの説明例: 「変更履歴、コメント、書式の保持、テキスト抽出をサポートする包括的なドキュメントの作成、編集、分析。(.docx ファイル) のプロフェッショナルなドキュメントを扱う際に使用します: (1) 新しいドキュメントの作成、(2) コンテンツの変更または編集、(3) 変更履歴の操作、(4) コメントの追加、その他のドキュメントタスク」

YAML フロントマターで許可されるその他のフィールドは、Agent Skills 仕様におけるオプションのプロパティである license、compatibility、allowed-tools、metadata のみです。これら以外のフィールドを含めないでください。

本文

スキルとそのバンドルされたリソースを使用するための手順を記述します。

ステップ 5: スキルを検証する

スキルの開発が完了したら、すべての要件を満たしていることを確認するために検証します:

scripts/quick_validate.py <path/to/skill-folder>

検証スクリプトは以下をチェックします:

• YAML フロントマターの形式と必須フィールド
• スキルの命名規則 (Unicode 小文字英数字とハイフン、最大 64 文字)
• 説明の完全性 (山かっこを含まない、最大 1024 文字)
• 必須フィールド: name と description
• 許可されるフロントマタープロパティのみ: name、description、license、compatibility、allowed-tools、metadata

検証が失敗した場合は、報告されたエラーを修正し、検証コマンドを再度実行してください。

ステップ 6: 反復する

スキルをテストした後、ユーザーは改善を要求する場合があります。これは多くの場合、スキルを使用した直後に、スキルがどのように機能したかについての新鮮なコンテキストを持った状態で起こります。

反復ワークフロー:

1. 実際のタスクでスキルを使用する
2. 困難や非効率な点に気づく
3. SKILL.md またはバンドルされたリソースをどのように更新すべきかを特定する
4. 変更を実装し、再度テストする