skill-creator

スキル作成者

このスキルでは、効果的なスキルを作成するためのガイダンスを提供します。 例で使用している Unix シェルコマンドに相当する Windows PowerShell のコマンドは、references/windows.md に記載されています。

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供して OpenHands の機能を拡張する、モジュール式の自己完結型パッケージです。特定の領域やタスクに特化した「オンボーディングガイド」と考えてください。スキルによって、OpenHands は汎用エージェントから、どのモデルも完全には備えられない手順の知識を身につけた特化型エージェントへと変わります。

スキルが提供するもの

1. 専門的なワークフロー — 特定の領域における複数ステップの手順
2. ツール連携 — 特定のファイル形式や API を扱うための手順
3. 領域の専門知識 — 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース — 複雑で反復的なタスクに役立つスクリプト、リファレンス、アセット

スキルの構成

すべてのスキルは、必須の 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（必須）

メタデータの品質： YAML フロントマターの name と description によって、OpenHands がそのスキルを使用するタイミングが決まります。スキルの機能と使用するタイミングを具体的に記述してください。三人称で記述してください（例：「このスキルを使用してください」ではなく「このスキルは、次の場合に使用します」）。

スラッシュコマンドとキーワードによるトリガー： SKILL.md のフロントマターでは、キーワードによるアクティベーション用に任意の triggers: フィールドを指定できます（例：triggers: [docker, container]）。スラッシュコマンド（例：/codereview、/init）の場合は、SKILL.md でスラッシュトリガーを使うのではなく、プラグインの commands/ ディレクトリに commands/command-name.md ファイルを作成することをおすすめします。スラッシュトリガーは後方互換性のために引き続き機能しますが、commands/ 方式を優先するため非推奨となっています。詳しくは、プラグインガイドをご覧ください。

同梱リソース（任意）

スクリプト（scripts/）

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

• 含めるタイミング： 同じコードを繰り返し書き直す場合、または確定的な信頼性が必要な場合
• 例： PDF の回転タスク向けの scripts/rotate_pdf.py
• 利点： トークン効率がよく、動作が確定的で、コンテキストに読み込まずに実行できる場合があります
• 注： パッチ適用や環境固有の調整のため、OpenHands がスクリプトを読み込む必要がある場合もあります
• Python の依存関係： Python の依存関係をインストールする際は、pip や pip3 ではなく uv を使用してください。uv はクロスプラットフォーム対応で高速なうえ、環境間での pip／pip3 の名称の不一致を避けられます。例：uv venv .venv --quiet && uv pip install --quiet <package>

リファレンス（references/）

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

• 含めるタイミング： OpenHands が作業中に参照する必要のあるドキュメントがある場合
• 例： 財務スキーマ用の references/finance.md、企業の NDA テンプレート用の references/mnda.md、企業ポリシー用の references/policies.md、API 仕様用の references/api_docs.md
• 用途： データベーススキーマ、API ドキュメント、領域知識、企業ポリシー、詳細なワークフローガイド
• 利点： SKILL.md を簡潔に保てます。OpenHands が必要だと判断した場合にのみ読み込まれます
• ベストプラクティス： ファイルが大きい場合（10k 語を超える場合）は、SKILL.md に grep の検索パターンを記載してください
• 重複を避ける： 情報は SKILL.md とリファレンスファイルのどちらか一方に記載し、両方には記載しないでください。スキルの中核に当たる情報でない限り、詳細な情報はリファレンスファイルに記載してください。そうすることで SKILL.md を簡潔に保ちながら、コンテキストウィンドウを圧迫せずに情報を見つけやすくできます。SKILL.md には不可欠な手順の指示とワークフローのガイダンスのみを残し、詳細な参考情報、スキーマ、例はリファレンスファイルに移してください。

アセット（assets/）

コンテキストに読み込むことを目的とせず、OpenHands が生成する出力内で使用するファイルです。

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

段階的開示の設計原則

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

1. メタデータ（名前＋説明） - 常にコンテキスト内にあります（約 100 語）
2. SKILL.md の本文 - スキルが呼び出されたときに読み込まれます（5,000 語未満）
3. バンドルされたリソース - OpenHands が必要に応じて読み込みます（無制限*）

*スクリプトはコンテキストウィンドウに読み込まなくても実行できるため、無制限です。

スキルの作成プロセス

スキルを作成するには、「スキルの作成プロセス」の手順に沿って進めます。該当しない明確な理由がある場合に限り、手順を省略してください。

ステップ 1：具体例を使ってスキルを理解する

スキルの使用パターンがすでに明確に理解されている場合に限り、このステップを省略してください。既存のスキルを扱う場合でも、このステップには価値があります。

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

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

• 「画像編集スキルでは、どのような機能に対応する必要がありますか？編集、回転、その他の機能でしょうか？」
• 「このスキルの使用例をいくつか教えていただけますか？」
• 「『この画像の赤目を修正して』や『この画像を回転して』のような依頼が考えられます。他にも想定している使い方はありますか？」
• 「どのようなユーザーの発言をきっかけに、このスキルを呼び出すべきでしょうか？」

ユーザーに負担をかけないよう、1 回のメッセージで質問しすぎないようにします。最も重要な質問から始め、効果を高めるために必要に応じて追加の質問をします。

スキルが対応すべき機能が明確になったら、このステップを終了します。

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

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

1. 例を最初から実行する方法を検討する
2. これらのワークフローを繰り返し実行する際に役立つスクリプト、参考資料、アセットを特定する

例： 「この PDF の回転を手伝って」のような依頼に対応する pdf-editor スキルを作成する場合、分析から次のことがわかります。

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

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

1. フロントエンドの Web アプリを作成するには、毎回同じ HTML/React のボイラープレートが必要です
2. ボイラープレートの HTML/React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキル内に保存すると役立ちます

例： 「今日ログインしたユーザー数は？」のような依頼に対応する big-query スキルを作成する場合、分析から次のことがわかります。

1. BigQuery にクエリを実行するたびに、テーブルスキーマとリレーションシップを再確認する必要があります
2. テーブルスキーマを記録した references/schema.md ファイルをスキル内に保存すると役立ちます

スキルの内容を決めるために、各具体例を分析して、含める再利用可能なリソース（スクリプト、参考資料、アセット）の一覧を作成します。

ステップ 3：スキルの構造を作成する

スキルのディレクトリ構造を作成します。

mkdir -p skill-name/{references,scripts,assets}
touch skill-name/SKILL.md

または、init_skill.py スクリプトを使用してテンプレートを生成します。

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

このスクリプトは、SKILL.md のテンプレートとサンプルのリソースディレクトリを含むスキルディレクトリを作成します。

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

新規作成したスキルでも既存のスキルでも、編集する際は、別の OpenHands インスタンスが使用するためにスキルを作成していることを念頭に置いてください。OpenHands にとって有益で、かつ自明ではない情報を含めることに重点を置いてください。別の OpenHands インスタンスがタスクをより効果的に実行するうえで役立つ手順に関する知識、ドメイン固有の詳細、再利用可能なアセットを検討してください。

再利用可能なスキルの内容から始める

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

また、スキルに不要なサンプルファイルやディレクトリは削除してください。実際に必要なディレクトリ（references/、scripts/、assets/）だけを作成します。

SKILL.md を更新する

文体： スキル全体を、二人称ではなく、命令形／不定詞形（動詞から始まる指示）で記述してください。客観的で指示的な表現を使用します（「X を達成するには、Y を実行する」のように、「X を実行するべきです」や「X を実行する必要がある場合は」ではなく記述します）。これにより、AI が読み取る際の一貫性と明瞭さが保たれます。

説明（フロントマター）： 具体的なトリガーフレーズを含め、三人称形式で記述します。

---
name: skill-name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", "specific phrase 3". Include exact phrases users would say that should trigger this skill. Be concrete and specific.
---

適切な説明の例：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", or mentions hook events (PreToolUse, PostToolUse, Stop).

不適切な説明の例：

description: Use this skill when working with hooks.  # Wrong person, vague
description: Load when user needs hook help.  # Not third person
description: Provides hook guidance.  # No trigger phrases

SKILL.md の本文を完成させるには、次の質問に答えてください。

1. スキルの目的は何ですか？数文で説明します。
2. いつスキルを使うべきですか？（具体的なトリガーを含め、フロントマターの説明に記載します）
3. OpenHands は実際にどのようにスキルを使うべきですか？OpenHands が使い方を理解できるよう、上記で作成した再利用可能なスキルの内容をすべて参照します。

SKILL.md は簡潔に保つ： 本文は 1,500～2,000 語を目安にしてください。詳細な内容は references/ に移動します。

• 詳細なパターン → references/patterns.md
• 高度な手法 → references/advanced.md
• 移行ガイド → references/migration.md
• API リファレンス → references/api-reference.md

SKILL.md でリソースを参照する：

## Additional Resources

### Reference Files

For detailed patterns and techniques, consult:
- **`references/patterns.md`** - Common patterns
- **`references/advanced.md`** - Advanced use cases

### Example Files

Working examples in `examples/`:
- **`example-script.sh`** - Working example

ステップ 5：検証とテスト

1. 構造を確認する： スキルディレクトリに SKILL.md が含まれていることを確認します
2. SKILL.md を検証する： name と description を含むフロントマターがあることを確認します
3. トリガーフレーズを確認する： 説明に具体的なユーザーの問い合わせが含まれていることを確認します
4. 文体を確認する： 本文が二人称ではなく、命令形／不定詞形で記述されていることを確認します
5. 段階的開示をテストする： SKILL.md が簡潔（約 1,500～2,000 語）で、詳細な内容が references/ にあることを確認します
6. 参照を確認する： 参照されているすべてのファイルが存在することを確認します
7. スクリプトを検証する： スクリプトに実行権限があり、正しく動作することを確認します

検証スクリプトを使用して、基本要件を確認します。

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

ステップ 6：反復する

スキルをテストした後、ユーザーから改善を求められることがあります。スキルの動作に関する記憶が新しいうちに、スキルを使用した直後にこうした要望が出ることがよくあります。

反復のワークフロー：

1. 実際のタスクでスキルを使う
2. 苦労した点や非効率な点に気づく
3. SKILL.md または同梱リソースのどこを更新すべきか特定する
4. 変更を実装し、再度テストする

よくある改善点：

• 説明内のトリガーフレーズを強化する
• SKILL.md の長いセクションを references/ に移動する
• 不足している例やスクリプトを追加する
• 曖昧な指示を明確にする
• エッジケースへの対応を追加する

実践における段階的開示

SKILL.md に含める内容

含める（スキルがトリガーされた際に常に読み込まれる内容）：

• 中核となる概念と概要
• 必須の手順とワークフロー
• クイックリファレンステーブル
• references/examples/scripts への参照
• 最も一般的なユースケース

3,000 語未満に抑え、できれば 1,500～2,000 語にする

references/ に含める内容

references/ に移動する（必要に応じて読み込む）：

• 詳細なパターンと高度なテクニック
• 包括的な API ドキュメント
• 移行ガイド
• エッジケースとトラブルシューティング
• 豊富な例と手順の解説

各リファレンスファイルは大きくてもかまいません（2,000～5,000 語以上）

scripts/ に含める内容

ユーティリティスクリプト：

• 検証ツール
• テスト用ヘルパー
• 解析ユーティリティ
• 自動化スクリプト

実行可能にし、ドキュメントを用意してください

文章作成のスタイル要件

命令形・不定詞形

二人称ではなく、動詞から始まる指示を書きます：

正しい例（命令形）：

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.

誤った例（二人称）：

You should create a hook by defining the event type.
You need to configure the MCP server.
You must validate settings before use.

説明文での三人称

フロントマターの説明には三人称を使用します：

正しい例：

description: This skill should be used when the user asks to "create X", "configure Y"...

誤った例：

description: Use this skill when you want to create X...
description: Load this skill when user asks...

客観的で手順を示す表現

誰が行うかではなく、何を行うかに焦点を当てます：

正しい例：

Parse the frontmatter using sed.
Extract fields with grep.
Validate values before use.

誤った例：

You can parse the frontmatter...
OpenHands should extract fields...
The user might validate values...

検証チェックリスト

スキルを完成させる前に、次の点を確認してください：

構成：

• 有効な YAML フロントマターを含む SKILL.md ファイルが存在する
• フロントマターに name と description フィールドがある
• Markdown 本文があり、十分な内容が含まれている
• 参照されているファイルが実際に存在する

説明の品質：

• 三人称を使用している（「このスキルは、次のような場合に使用します……」）
• ユーザーが使いそうな具体的なトリガーフレーズを含めている
• 具体的なシナリオを列挙している（「X を作成する」「Y を設定する」）
• 曖昧または一般的な表現ではない

内容の品質：

• SKILL.md の本文で命令形・不定詞形を使用している
• 本文の内容が絞り込まれて簡潔である（理想は1,500～2,000語、最大5,000語未満）
• 詳細な内容を references/ に移動している
• 例が完全で、動作する
• スクリプトが実行可能で、ドキュメントが用意されている

段階的な情報開示：

• SKILL.md に主要な概念を記載している
• 詳細なドキュメントを references/ に配置している
• ユーティリティを scripts/ に配置している
• SKILL.md からこれらのリソースを参照している

テスト：

• 想定されるユーザーのクエリに対してスキルが起動する
• 想定されるタスクに役立つ内容になっている
• ファイル間で情報が重複していない
• 必要に応じてリファレンスが読み込まれる

よくある間違いとその回避方法

間違い 1：トリガーの説明が不明瞭

❌ 悪い例：

description: Provides guidance for working with hooks.

問題点： 曖昧で、具体的なトリガーフレーズがなく、三人称でもありません

✅ 良い例：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events. Provides comprehensive hooks API guidance.

良い理由： 三人称で、具体的なフレーズとシナリオが示されています

間違い 2：SKILL.md に詰め込みすぎる

❌ 悪い例：

skill-name/
└── SKILL.md  (8,000 words - everything in one file)

問題点： スキルの読み込み時にコンテキストが膨らみ、詳細な内容が常に読み込まれます

✅ 良い例：

skill-name/
├── SKILL.md  (1,800 words - core essentials)
└── references/
    ├── patterns.md (2,500 words)
    └── advanced.md (3,700 words)

良い理由： 段階的な情報開示により、詳細な内容は必要なときだけ読み込まれます

間違い 3：二人称で書く

❌ 悪い例：

You should start by reading the configuration file.
You need to validate the input.
You can use the grep tool to search.

問題点： 二人称であり、命令形ではありません

✅ 良い例：

Start by reading the configuration file.
Validate the input before processing.
Use the grep tool to search for patterns.

良い理由： 命令形で、直接的な指示になっています

間違い 4：リソースへの参照がない

❌ 悪い例：

# SKILL.md

[Core content]

[No mention of references/ or examples/]

問題点： OpenHands がリファレンスの存在を認識できません

✅ 良い例：

# SKILL.md

[Core content]

## Additional Resources

### Reference Files
- **`references/patterns.md`** - Detailed patterns
- **`references/advanced.md`** - Advanced techniques

### Scripts
- **`scripts/validate.sh`** - Validation utility

良い理由： OpenHands が追加情報の場所を把握できます

クイックリファレンス

最小限のスキル

skill-name/
└── SKILL.md

適している用途：複雑なリソースを必要としない、シンプルな知識

標準的なスキル（推奨）

skill-name/
├── SKILL.md
├── references/
│   └── detailed-guide.md
└── scripts/
    └── helper.py

適している用途：詳細なドキュメントを備えた、ほとんどのスキル

完全なスキル

skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── scripts/
│   └── validate.sh
└── assets/
    └── template.txt

適している用途：検証ユーティリティが必要な複雑な分野

ベストプラクティスのまとめ

✅ 推奨事項：

• 説明では三人称を使用します（「このスキルは、〜する場合に使用します」）
• 具体的なトリガーフレーズを含めます（「X を作成する」「Y を設定する」）
• SKILL.md は簡潔に保ちます（1,500～2,000 語）
• プログレッシブディスクロージャーを活用します（詳細は references/ に移動します）
• 命令形または不定詞形で記述します
• 補助ファイルを明確に参照します
• 動作する例を提示します
• よく使う操作のためのユーティリティスクリプトを作成します
• スクリプトで Python の依存関係をインストールする際は uv を使用します（uv venv .venv --quiet && uv pip install --quiet <pkg>）

❌ 避けるべき事項：

• 二人称をどこにも使用しないでください
• 曖昧なトリガー条件を設定しないでください
• すべてを SKILL.md に記述しないでください（references/ なしで 3,000 語を超えないようにします）
• 二人称で記述しないでください（「〜してください」など）
• リソースを参照しないままにしないでください
• 壊れた例や不完全な例を含めないでください
• 検証を省略しないでください
• pip や pip3 を直接使用しないでください。クロスプラットフォームの標準は uv です

その他のリソース

参照ファイル

詳しいパターンや手法については、以下を参照してください。

• references/workflows.md - 順次ワークフローと条件分岐ロジックのパターン
• references/output-patterns.md - 特定の出力形式向けのテンプレートと例のパターン

実装ワークフロー

スキルを作成するには：

1. ユースケースを理解する：スキルの具体的な使用例を特定します
2. リソースを計画する：必要なスクリプト、参照ファイル、アセットを決定します
3. 構成を作成する：mkdir -p skill-name/{references,scripts,assets}
4. SKILL.md を作成する：
   • 三人称の説明とトリガーフレーズを含む Frontmatter
   • 命令形で簡潔にまとめた本文（1,500～2,000 語）
   • 補助ファイルを参照
5. リソースを追加する：必要に応じて references/、scripts/、assets/ を作成します
6. 検証する：説明、文体、構成を確認します
7. テストする：想定されるトリガーでスキルが読み込まれることを確認します
8. 反復する：使用状況に基づいて改善します

必要なときに読み込まれ、的を絞ったガイダンスを提供する効果的なスキルを作成するため、明確なトリガー説明、プログレッシブディスクロージャー、命令形の文体を重視してください。