create-skill

スキルの作成

専門知識、ワークフロー、ツール連携によってエージェントの能力を拡張する、効果的なスキルの作成ガイドです。

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供することでエージェントの能力を拡張する、モジュール式の自己完結型パッケージです。特定の分野やタスクに関する「オンボーディングガイド」と考えてください。

スキルが提供するもの

1. 専門的なワークフロー - 特定分野向けの複数ステップの手順
2. ツール連携 - 特定のファイル形式や API の操作手順
3. 分野の専門知識 - 会社固有の知識、スキーマ、ビジネスロジック
4. バンドルされたリソース - 複雑で反復的なタスク向けのスクリプト、リファレンス、アセット

プログレッシブ・ディスクロージャーの原則

200 行ルールは重要です。 SKILL.md は 200 行未満にしてください。それ以上になる場合は、内容を references/ ファイルに分割します。

3 段階の読み込みシステム

1. メタデータ（name + description） - 常にコンテキストに含まれます（約 100 語）
2. SKILL.md の本文 - スキルが有効になったときに読み込まれます（200 行未満、最適なパフォーマンスのためには 500 行未満が理想です）
3. バンドルされたリソース - エージェントが必要に応じて読み込みます（上限なし）

プログレッシブ・ディスクロージャーが重要な理由

• 初期コンテキストの読み込みを 85% 削減
• 有効化時間を 500ms 以上から 100ms 未満に短縮
• エージェントは必要なものだけを、必要なときに読み込みます
• スキルの保守性が保たれ、焦点が明確になります

スキルの構成

skill-name/
├── SKILL.md (required, <200 lines)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code
    ├── references/       - Documentation loaded as needed
    └── assets/           - Files used in output

基本原則

簡潔さが重要

コンテキストウィンドウは共有リソースです。スキルは、エージェントが必要とするほかのすべての情報と、その領域を共有します。簡潔にまとめ、各情報について検討してください。

• エージェントに本当にこの説明が必要ですか？
• エージェントが知っていることとして扱えますか？
• この段落はトークンを消費するだけの価値がありますか？

適切な自由度を設定する

• 自由度が高い：複数の有効なアプローチを示すテキスト形式の指示
• 自由度が中程度：パラメーター付きの疑似コードやスクリプト
• 自由度が低い：壊れやすい操作向けの、パラメーターが少ない、またはない具体的なスクリプト

すべてのモデルでテストする

スキルはモデルへの追加要素として機能するため、その有効性は基盤となるモデルに左右されます。使用する予定のすべてのモデルでスキルをテストしてください。

リファレンス

詳しいガイダンスについては、以下を参照してください。

• references/progressive-disclosure.md - 200 行ルールとリファレンスのパターン
• references/skill-structure.md - SKILL.md の形式と frontmatter の詳細
• references/examples.md - 優れたスキルの例
• references/best-practices.md - 包括的なベストプラクティスガイド