Skill Creator

Deepagents のスキル配置

deepagents CLI は 5 つのソースからスキルを読み込みます。以下は優先順位が低い順から高い順に示されています:

#	ディレクトリ	スコープ	備考
0	<package>/built_in_skills/	ビルトイン	deepagents CLI に付属
1	~/.deepagents/<agent>/skills/	ユーザー (deepagents エイリアス)	deepagents skills create のデフォルト
2	~/.agents/skills/	ユーザー	エージェントツール全体で共有
3	.deepagents/skills/	プロジェクト (deepagents エイリアス)	deepagents skills create --project のデフォルト
4	.agents/skills/	プロジェクト	エージェントツール全体で共有

<agent> はエージェント設定名です（デフォルト: agent）。同じ名前のスキルを含むディレクトリが 2 つある場合、優先順位が高い方が使用されます。プロジェクトスキルはユーザースキルをオーバーライドし、ユーザーまたはプロジェクトスキルはビルトインスキルをオーバーライドします。

ディレクトリレイアウトの例:

~/.deepagents/agent/skills/     # ユーザースキル（優先順位が最も低い）
├── skill-name-1/
│   └── SKILL.md
└── ...

<project-root>/.deepagents/skills/   # プロジェクトスキル（優先順位が高い）
├── skill-name-2/
│   └── SKILL.md
└── ...

コア原則

簡潔性が鍵

コンテキストウィンドウは公共の資産です。スキルはシステムプロンプト、会話履歴、その他のスキルのメタデータ、および実際のユーザーリクエストと共にコンテキストウィンドウを共有します。

デフォルト前提: エージェントは既に非常に有能です。 エージェントが既に持っていない情報のみを追加してください。各情報に疑問を投げかけてください: 「エージェントは本当にこの説明が必要か?」および「このパラグラフはそのトークンコストに見合う価値があるか?」

詳細な説明よりも簡潔な例を優先してください。

適切な自由度の設定

タスクの脆弱性と可変性に応じて特異性のレベルを調整します:

高度な自由度（テキストベースの指示）: 複数のアプローチが有効である場合、決定がコンテキストに依存する場合、またはヒューリスティックがアプローチをガイドする場合に使用します。

中程度の自由度（疑似コードまたはパラメータ付きスクリプト）: 推奨パターンが存在する場合、ある程度の変動が許容される場合、または構成が動作に影響を与える場合に使用します。

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

エージェントを道を探索するものと考えてください: 崖のある狭い橋には特定のガードレール（低い自由度）が必要ですが、開かれたフィールドには多くのルートが可能です（高い自由度）。

スキルの構造

すべてのスキルは必須の SKILL.md ファイルとオプションのバンドルリソースで構成されます:

skill-name/
├── SKILL.md (必須)
│   ├── YAML frontmatter メタデータ (必須)
│   │   ├── name: (必須)
│   │   └── description: (必須)
│   └── Markdown 指示 (必須)
└── バンドルリソース (オプション)
    ├── scripts/          - 実行可能コード (Python/Bash など)
    ├── references/       - 必要に応じてコンテキストに読み込むドキュメント
    └── assets/           - 出力で使用されるファイル (テンプレート、アイコン、フォントなど)

SKILL.md (必須)

すべての SKILL.md は以下で構成されます:

• Frontmatter (YAML): name と description フィールドを含みます。これらはエージェントがスキルがいつ使用されるかを判断するために読む唯一のフィールドです。したがって、スキルが何であるか、いつ使用されるべきかについて明確かつ包括的に説明することが非常に重要です。
• 本文 (Markdown): スキルの使用方法に関する指示とガイダンス。スキルがトリガーされた後にのみロードされます（存在する場合）。

バンドルリソース (オプション)

スクリプト (scripts/)

決定論的信頼性を必要とするタスクまたは繰り返し書き直される実行可能コード (Python/Bash など)。

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

リファレンス (references/)

エージェントのプロセスと思考に知らせるために、必要に応じてコンテキストにロードすることを目的としたドキュメントと参考資料。

• 含める場合: エージェントが作業中に参照すべきドキュメントがある場合
• 例: 財務スキーマ用の references/finance.md、会社 NDA テンプレート用の references/mnda.md、会社ポリシー用の references/policies.md、API 仕様用の references/api_docs.md
• ユースケース: データベーススキーマ、API ドキュメント、ドメイン知識、会社ポリシー、詳細なワークフローガイド
• 利点: SKILL.md を簡潔に保ち、エージェントが必要と判断した場合のみロードされます
• ベストプラクティス: ファイルが大きい場合 (>10k 単語)、SKILL.md に検索パターンを含めます
• 重複を避ける: 情報は SKILL.md または参照ファイルのいずれかに存在する必要があり、両方ではありません。SKILL.md を簡潔に保ちながら情報を発見可能にするために、詳細情報については参照ファイルを優先します（コンテキストウィンドウを独占しません）。本当にスキルのコアでない限り、SKILL.md には本質的な手順の指示とワークフローガイダンスのみを保管します。詳細なリファレンス資料、スキーマ、例は参照ファイルに移動します。

アセット (assets/)

コンテキストに読み込むことは意図されていませんが、エージェントが生成する出力内で使用されるファイル。

• 含める場合: スキルが最終出力で使用されるファイルが必要な場合
• 例: ブランドアセット用の assets/logo.png、PowerPoint テンプレート用の assets/slides.pptx、HTML/React ボイラープレート用の assets/frontend-template/
• ユースケース: テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは変更されるサンプルドキュメント
• 利点: 出力リソースをドキュメントから分離し、ファイルをコンテキストに読み込まずに使用するエージェントを有効にします

スキルに含めないもの

スキルには、その機能を直接サポートする本質的なファイルのみが含まれるべきです。以下を含む無関係なドキュメントまたは補助ファイルを作成しないでください:

• 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

## クイックスタート

pdfplumber でテキストを抽出します:
[コード例]

## 高度な機能

- **フォーム入力**: 完全なガイドについては [FORMS.md](FORMS.md) を参照してください
- **API リファレンス**: すべてのメソッドについては [REFERENCE.md](REFERENCE.md) を参照してください
- **例**: 一般的なパターンについては [EXAMPLES.md](EXAMPLES.md) を参照してください

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

パターン 2: ドメイン固有の組織

複数のドメインを持つスキルについて、コンテンツをドメイン別に整理して、無関係なコンテキストの読み込みを回避します:

bigquery-skill/
├── SKILL.md (概要とナビゲーション)
└── reference/
    ├── finance.md (収益、請求メトリクス)
    ├── sales.md (営業機会、パイプライン)
    ├── product.md (API 使用量、機能)
    └── marketing.md (キャンペーン、アトリビューション)

ユーザーが販売メトリクスについて質問した場合、エージェントは sales.md のみを読みます。

同様に、複数のフレームワークまたはバリエーションをサポートするスキルの場合、バリエーション別に整理します:

cloud-deploy/
├── SKILL.md (ワークフロー + プロバイダー選択)
└── references/
    ├── aws.md (AWS デプロイパターン)
    ├── gcp.md (GCP デプロイパターン)
    └── azure.md (Azure デプロイパターン)

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

パターン 3: 条件付き詳細

基本的なコンテンツを表示し、高度なコンテンツにリンク:

# DOCX Processing

## ドキュメント作成

新しいドキュメント用に docx-js を使用します。[DOCX-JS.md](DOCX-JS.md) を参照してください。

## ドキュメント編集

簡単な編集の場合、XML を直接変更します。

**変更追跡の場合**: [REDLINING.md](REDLINING.md) を参照してください
**OOXML 詳細の場合**: [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: 具体例でスキルを理解する

スキルの使用パターンが既に明確に理解されている場合にのみこのステップをスキップします。既存のスキルで作業する場合でも価値があります。

効果的なスキルを作成するには、スキルがどのように使用されるかについての具体例を明確に理解します。この理解は直接のユーザー例または検証されたユーザーフィードバックを持つ生成例から来ることができます。

たとえば、画像エディタスキルを構築する場合、関連する質問は以下を含みます:

• 「image-editor スキルはどのような機能をサポートすべきか? 編集、回転、他にも?」
• 「このスキルの使用方法の例を示してもらえますか?」
• 「『この画像から赤目を削除してください』や『この画像を回転してください』のようなことをユーザーが要求するのを想像できます。あなたが想像するこのスキルが使用されるその他の方法はありますか?」
• 「ユーザーがこのスキルをトリガーするために何を言うか?」

ユーザーを圧倒することを避けるため、単一のメッセージで多くの質問をしないでください。最も重要な質問から始め、より効果的にするために必要に応じてフォローアップしてください。

このステップを終了するのは、スキルがサポートすべき機能について明確な感覚がある場合です。

ステップ 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 のスキル配置」に記載されているスキルディレクトリのいずれかを使用します:

# ユーザースキル (デフォルト)
scripts/init_skill.py <skill-name> --path ~/.deepagents/agent/skills

# プロジェクトスキル
scripts/init_skill.py <skill-name> --path .deepagents/skills

スクリプト:

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

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

オプション B: deepagents skills create (クイックスタート)

ビルトイン CLI コマンドは、リソースディレクトリなしで、SKILL.md テンプレートのみを含む最小限のスキルを作成します。スクリプト、参照、またはアセットをバンドルせず、指示のみが必要な単純なスキルに使用します。

# ユーザースキルディレクトリに作成
deepagents skills create <skill-name>

# プロジェクトスキルディレクトリに作成
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 を更新する

ライティングガイドライン: 常に命令形/不定詞形を使用します。

Frontmatter

name と description で YAML frontmatter を記述します:

• name: スキル名
• description: これはスキルの主なトリガーメカニズムであり、エージェントがスキルをいつ使用するかを理解するのに役立ちます。
  • スキルが何をするかと、使用するときの具体的なトリガー/コンテキストを含めます。
  • すべての「いつ使用するか」情報をここに含めます - 本文には含めません。本文はトリガー後にのみロードされるため、本文内の「このスキルをいつ使用するか」セクションはエージェントに役立ちません。
  • docx スキル用の説明例: 「追跡変更、コメント、フォーマット保持、テキスト抽出をサポートする包括的なドキュメント作成、編集、分析です。プロフェッショナルドキュメント (.docx ファイル) を使用する場合に使用します。(1) 新しいドキュメントの作成、(2) コンテンツの変更または編集、(3) 追跡変更の処理、(4) コメントの追加、またはその他のドキュメントタスク」

YAML frontmatter では、name と description フィールドのみが許可されます。これらはエージェントスキル仕様に従うオプションプロパティです: license、compatibility、allowed-tools、metadata。これら以上のフィールドは含めないでください。

本文

スキルとそのバンドルリソースの使用方法に関する指示を記述します。

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

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

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

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

• YAML frontmatter フォーマットと必須フィールド
• スキル命名規約 (Unicode 小文字英数字とハイフン、最大 64 文字)
• 説明の完全性 (角括弧なし、最大 1024 文字)
• 必須フィールド: name と description
• 許可された frontmatter プロパティのみ: name、description、license、compatibility、allowed-tools、metadata

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

ステップ 6: 反復する

スキルをテストした後、ユーザーは改善をリクエストする場合があります。多くの場合、これはスキルを使用した直後に、スキルがどのように機能したかについて新しいコンテキストで発生します。

反復ワークフロー:

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