skill-creator

スキルクリエイター

このスキルは、既存のツールシステムを使用して効果的なスキルを作成するためのガイダンスを提供します。

スキルについて

スキルは、専門的な知識、ワークフロー、ツールを提供することでエージェントの機能を拡張する、モジュール式の自己完結型パッケージです。これらは汎用エージェントを、手続き的知識を備えた専門エージェントへと変革します。

スキルが提供するもの

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: ハイフン区切りのスキル名 (例: weather-api、pdf-editor)
• description: 重要 - 主要なトリガー機構
  • スキルが何をするかを明確に記述する必要があります
  • いつ使用するかを明示的に記載する必要があります
  • 具体的なトリガーシナリオとキーワードを含めてください
  • 「いつ使用するか」の情報はすべてここに記載し、本文には記載しないでください
  • 例: "PDF document processing with rotation, merging, splitting, and text extraction. Use when user needs to: (1) Rotate PDF pages, (2) Merge multiple PDFs, (3) Split PDF files, (4) Extract text from PDFs."

本文 (Markdown) - スキルがトリガーされた後に読み込まれます:

• 詳細な使用方法の指示
• スクリプトの呼び出し方法とリファレンスの読み方
• 例とベストプラクティス
• 命令形/不定詞形を使用してください (「X を使用して Y を行う」)

バンドルされたリソース

scripts/ - 含めるべき場合:

• コードが繰り返し書き直される
• 決定論的な実行が必要 (LLM のランダム性を避ける)
• 例: PDF の回転、画像処理
• 含める前にスクリプトをテストする必要があります

references/ - 含めるべき場合:

• ドキュメントが SKILL.md に入れるには大きすぎる場合のみ (>500 行)
• エージェントが参照する必要があるデータベーススキーマ、複雑な API 仕様
• エージェントは必要に応じてこれらのファイルをコンテキストに読み込みます
• 含めるべきでないもの: API リファレンスドキュメント、使用例、チュートリアル (代わりに SKILL.md に記載してください)
• 経験則: SKILL.md に収まる場合は、別のリファレンスファイルを作成しないでください

assets/ - 含めるべき場合:

• 出力で使用されるファイル (コンテキストには読み込まれません)
• テンプレート、アイコン、ボイラープレートコード
• 最終出力でコピーまたは変更されるもの

重要: ほとんどのスキルは3つすべてを必要としません。実際のニーズに基づいて選択してください。

含めるべきでないもの

補助的なドキュメントファイルを作成しないでください:

• README.md - 指示は SKILL.md に記載します
• INSTALLATION_GUIDE.md - セットアップ情報は SKILL.md に記載します
• CHANGELOG.md - ローカルスキルには不要です
• API_REFERENCE.md - API ドキュメントは SKILL.md に直接記載してください
• USAGE_EXAMPLES.md - 例は SKILL.md に直接記載してください
• その他のドキュメントファイル - 大きすぎる場合を除き、すべては SKILL.md に記載します

重要なルール: エージェントが実際に実行するファイル (スクリプト)、または SKILL.md に入れるには大きすぎるファイル (リファレンス) のみを作成してください。ドキュメント、例、ガイドはすべて SKILL.md に記載します。

スキルのインストール

インストール先ディレクトリ: <workspace>/skills/<name>/ (<workspace> は「Workspace」セクションのものです)。

ステップ 1 — スキルコンテンツを取得する

ソース	アクション
URL (単一ファイル)	curl または web_fetch でコンテンツを取得する
URL (zip/アーカイブ)	ダウンロードして一時ディレクトリに展開する
ローカルファイル (SKILL.md)	直接読み込む
ローカルアーカイブ (zip)	一時ディレクトリに展開する

ステップ 2 — 特定してインストールする

1. SKILL.md を探します（トップレベルにある場合も、サブディレクトリ内にある場合もあります）
2. YAML frontmatter から name を抽出します
3. スキルディレクトリ全体（SKILL.md および references/、scripts/、assets/ などのすべての兄弟ファイル・フォルダー）を <workspace>/skills/<name>/ にコピーします
4. インストール・セットアップ用のファイル（例: INSTALL.md）が存在する場合は、その指示に従います — 最終的な結果は <workspace>/skills/<name>/ に配置される必要があります

スキル作成プロセス（ゼロから）

1. 理解する - 具体的なユースケースを明確にします
2. 計画する - 必要なスクリプト、リファレンス、アセットを特定します
3. 初期化する - init_skill.py を実行してテンプレートを作成します
4. 編集する - SKILL.md とリソースを実装します
5. 検証する（任意） - quick_validate.py を実行してフォーマットを確認します
6. 反復する - 実際の使用状況に基づいて改善します

スキルの命名

• 小文字、数字、ハイフンのみを使用します。ユーザーが指定したタイトルはハイフン区切りの形式に正規化します（例: 「Plan Mode」-> plan-mode）。
• 名前を生成するときは、64 文字未満（英字、数字、ハイフン）の名前を生成します。
• 動作を表す、短い動詞で始まるフレーズを優先します。
• 明確さやトリガーしやすさが向上する場合は、ツールごとに名前空間を分けます（例: gh-address-comments、linear-address-issue）。
• スキルのフォルダーには、スキル名とまったく同じ名前を付けます。

ステップバイステップガイド

ステップ 1: 具体的な例でスキルを理解する

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

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

たとえば、画像編集スキルを構築する場合、関連する質問には次のようなものがあります:

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

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

このステップは、スキルがサポートすべき機能について明確なイメージが得られた時点で完了します。

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

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

1. その例をゼロからどのように実行するかを考える
2. これらのワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットは何かを特定する

計画チェックリスト:

• ✅ 常に必要: 明確な説明と使用手順を含む SKILL.md
• ✅ scripts/: コードを実行する必要がある場合のみ (単に例として示すだけではない場合)
• ❌ references/: ほとんど必要ない - ドキュメントが 500 行を超え、SKILL.md に収まらない場合のみ
• ✅ assets/: ファイルが出力で使用される場合のみ (テンプレート、ボイラープレートなど)

例: 「この PDF を回転させてください」といったクエリを処理する pdf-editor スキルを構築する場合、分析結果は次のようになります。

1. PDF の回転には毎回同じコードを書き直す必要がある
2. scripts/rotate_pdf.py スクリプトをスキルに保存しておくと役立つ
3. ❌ references/api-docs.md を作成しない - 代わりに API 情報を SKILL.md に記載する

例: 「Todo アプリを作成してください」や「歩数を追跡するダッシュボードを作成してください」といったクエリ向けに frontend-webapp-builder スキルを設計する場合、分析結果は次のようになります。

1. フロントエンド Web アプリの作成には毎回同じボイラープレートの HTML/React が必要になる
2. ボイラープレートの HTML/React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに保存しておくと役立つ
3. ❌ references/usage-examples.md を作成しない - 代わりに例を SKILL.md に記載する

例: 「今日は何人のユーザーがログインしましたか？」といったクエリを処理する big-query スキルを構築する場合、分析結果は次のようになります。

1. BigQuery へのクエリには毎回テーブルスキーマとリレーションシップを再調査する必要がある
2. テーブルスキーマを文書化した references/schema.md ファイルをスキルに保存しておくと役立つ (スキーマが非常に大きい場合のみ)
3. ❌ 別途 references/query-examples.md を作成しない - 代わりに例を SKILL.md に記載する

スキルの内容を確定するには、各具体的な例を分析して、含めるべき再利用可能なリソース (スクリプト、リファレンス、アセット) のリストを作成します。分離する compelling な理由がない限り、デフォルトですべてを SKILL.md に入れてください。

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

この時点で、実際にスキルを作成します。

開発中のスキルがすでに存在し、イテレーションが必要な場合にのみ、このステップをスキップしてください。その場合は、次のステップに進みます。

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

使用方法:

scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]

例:

scripts/init_skill.py my-skill --path <workspace>/skills
scripts/init_skill.py my-skill --path <workspace>/skills --resources scripts,references
scripts/init_skill.py my-skill --path <workspace>/skills --resources scripts --examples

ここで <workspace> は、システムプロンプトの「Workspace」セクションに示されているワークスペースディレクトリです。

このスクリプトは次のことを行います。

• 指定されたパスにスキルディレクトリを作成する
• 適切な frontmatter と TODO プレースホルダーを含む SKILL.md テンプレートを生成する
• --resources に基づいてリソースディレクトリをオプションで作成する
• --examples が設定されている場合、サンプルファイルをオプションで追加する

初期化後は、SKILL.md をカスタマイズし、必要に応じてリソースを追加します。--examples を使用した場合は、プレースホルダーファイルを置き換えるか削除してください。

重要: スキルは常にワークスペースのスキルディレクトリ (<workspace>/skills) に作成し、プロジェクトディレクトリには作成しないでください。実際のワークスペースパスについては「Workspace」セクションを確認してください。

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

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

設計パターン

ワークフローパターン — 複雑なタスクでは、操作を順次ステップまたは条件分岐に分割します：

# Sequential: list numbered steps with scripts
1. Analyze the form (run analyze_form.py)
2. Create field mapping (edit fields.json)
3. Fill the form (run fill_form.py)

# Conditional: guide through decision points
1. Determine the modification type:
   **Creating new content?** → Follow "Creation workflow"
   **Editing existing content?** → Follow "Editing workflow"

出力パターン — 一貫した出力形式が重要な場合は、SKILL.md にテンプレートまたは入力/出力の例を提供し、エージェントが希望するスタイルに従えるようにします。

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

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

利用可能な基本ツール：

エージェントは、スキル内で活用できる以下のコアツールにアクセスできます：

• bash：シェルコマンドを実行します（curl、ls、grep、sed、awk、計算用の bc などに使用します）
• read：ファイルの内容を読み取ります
• write：ファイルを書き込みます
• edit：検索/置換でファイルを編集します

依存関係を最小限に抑える：

• ✅ HTTP API 呼び出しには bash + curl を優先 します（Python の依存関係は不要）
• ✅ テキスト処理には bash ツール（grep、sed、awk）を 使用 します
• ✅ スクリプトはシンプルに保つ - bash でできるなら Python は不要です（Python を使用する場合はパッケージ/バージョンを記載してください）

重要なガイドライン：

• scripts/：実行されるスクリプトのみを作成します。含める前にすべてのスクリプトをテストしてください。
• references/：ドキュメントが SKILL.md には大きすぎる場合（500 行超）にのみ作成します。ほとんどのスキルには必要ありません。
• assets/：出力で使用されるファイル（テンプレート、アイコンなど）のみを含めます。
• デフォルトのアプローチ：特別な理由がない限り、すべてを SKILL.md に記述します。

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

--examples を使用した場合は、スキルに不要なプレースホルダーファイルを削除してください。実際に必要なリソースディレクトリのみを作成してください。

SKILL.md を更新する

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

フロントマター

name、description、および任意の metadata を含む YAML フロントマターを記述します。

• name: スキル名
• description: これはスキルの主要なトリガーメカニズムであり、エージェントがスキルをいつ使用すべきかを理解するのに役立ちます。
  • スキルが何を行うかと、いつ使用するかの具体的なトリガーやコンテキストの両方を含めてください。
  • 「いつ使用するか」の情報はすべてここに含めてください。本文には含めないでください。本文はトリガー後にのみ読み込まれるため、本文中の「このスキルを使用する場合」セクションはエージェントには役立ちません。
  • docx スキルの説明例: 「追跡変更、コメント、書式保持、テキスト抽出をサポートする包括的なドキュメントの作成、編集、分析。エージェントがプロフェッショナルなドキュメント (.docx ファイル) を扱う必要がある場合に使用します: (1) 新しいドキュメントの作成、(2) コンテンツの変更または編集、(3) 追跡変更の操作、(4) コメントの追加、その他のドキュメントタスク」
• metadata: (任意) 要件と設定を指定します
  • requires.bins: 必要なバイナリ (例: ["curl", "jq"])
  • requires.env: 必要な環境変数 — すべて設定されている必要があります (例: ["MYAPI_KEY"])
  • requires.anyEnv: 代替の環境変数 — 少なくとも 1 つが設定されている必要があります (例: ["OPENAI_API_KEY", "LINKAI_API_KEY"])
  • requires.anyBins: 代替のバイナリ — 少なくとも 1 つが存在する必要があります
  • always: 要件に関係なく常に読み込むには true に設定します
  • emoji: スキルアイコン (任意)
  • category は設定しないでください — デフォルトで skill になり、システムによって管理されます

API キーの要件:

スキルに単一の API キーが必要な場合は、requires.env で宣言します:

---
name: my-search
description: Search using MyAPI
metadata:
  requires:
    bins: ["curl"]
    env: ["MYAPI_KEY"]
---

スキルが複数の API キープロバイダー (例: OpenAI または LinkAI) をサポートする場合は、requires.anyEnv を使用します:

---
name: my-vision
description: Analyze images using Vision API
metadata:
  requires:
    bins: ["curl"]
    anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"]
---

自動有効化ルール: スキルは、必要な環境変数が設定されていると自動的に有効になり、不足していると自動的に無効になります。手動での設定は不要です。

本文

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

スキルに API キーが必要な場合は、本文にセットアップ手順を含めます:

## Setup

This skill requires an API key from [Service Name].

1. Visit https://service.com to get an API key
2. Configure it using: `env_config(action="set", key="SERVICE_API_KEY", value="your-key")`
3. Or manually add to `~/cow/.env`: `SERVICE_API_KEY=your-key`
4. Restart the agent for changes to take effect

## Usage
...

bash スクリプトはキーを確認し、役立つエラーメッセージを提供する必要があります:

#!/usr/bin/env bash
if [ -z "${SERVICE_API_KEY:-}" ]; then
    echo "Error: SERVICE_API_KEY not set"
    echo "Please configure your API key first (see SKILL.md)"
    exit 1
fi

curl -H "Authorization: Bearer $SERVICE_API_KEY" ...

スクリプトパスの規約:

SKILL.md の手順を記述する際は、次の点に注意してください:

• スキルは <available_skills> に <base_dir> パスとともにリストされます
• スクリプトは次のように参照する必要があります: <base_dir>/scripts/script_name.sh
• AI は base_dir を認識し、完全なパスを構築できます

SKILL.md の手順例:

## Usage

Scripts are in this skill's base directory (shown in skill listing).

bash "<base_dir>/scripts/my_script.sh" <args>

ステップ 5: 検証 (任意)

スキルの形式を検証します:

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

例:

scripts/quick_validate.py <workspace>/skills/weather-api

検証チェック項目:

• YAML フロントマターの形式と必須フィールド
• スキルの命名規則 (ハイフンケース、小文字)
• 説明の完全性と品質
• ファイル構成

注: 検証は COW では任意です。主に形式の問題のトラブルシューティングに役立ちます。

ステップ 6: 反復

実際の使用に基づいて改善します:

1. 実際のタスクでスキルを使用する
2. 困難や非効率に気づく
3. SKILL.md またはリソースに必要な更新を特定する
4. 変更を実装し、再度テストする

段階的開示

スキルは 3 段階の読み込みを使用します:

1. メタデータ (name + description) - 常にコンテキスト内に存在 (~100 語)
2. SKILL.md 本文 - スキルがトリガーされたときに読み込まれる (5k 語未満)
3. リソース - エージェントが必要に応じて読み込む

ベストプラクティス:

• SKILL.md は 500 行未満に保つ
• 複雑な内容は references/ ファイルに分割する
• これらのファイルを SKILL.md で明確に参照する

パターン: 複数のバリアントやフレームワークを持つスキルの場合:

• コアワークフローを SKILL.md に保つ
• バリアント固有の詳細を別の参照ファイルに移動する
• エージェントは関連するファイルのみを読み込む

例:

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

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