skill-creator

基本原則

簡潔さが鍵です。 コンテキストウィンドウは、システムプロンプト、スキル、会話履歴、そしてあなたの推論の間で共有されるリソースです。SKILL.md のすべての行は、他のあらゆるものと競合します。まだ知らないことだけを追加してください。システムプロンプトに表示されているツールパラメータを文書化したり、自分で把握できることを手順ごとに指定したりしないでください。ドメイン知識、解釈ガイド、意思決定フレームワーク、注意点に焦点を当ててください。

段階的な開示。 スキルは 3 つのレベルで読み込まれます。

1. 常にコンテキスト内 — 名前、絵文字、説明がすべての会話で <available_skills> に表示されます。これがどのスキルを有効化するかを判断する材料になります。説明は強力なトリガーでなければなりません。
2. 有効化時 — スキルが関連すると判断したときに、SKILL.md の本文全体が read_file を介して読み込まれます。ワークフロー、ガイドライン、決定木はここに置きます。
3. オンデマンド — scripts/、references/、assets/ は明示的に必要なときにのみ読み込まれます。重いコンテンツは本文ではなくここに置きます。

つまり、SKILL.md の本文はスリムに保ってください（500 行未満）。詳細な API ドキュメントは references/ に置きます。自動化は scripts/ に置きます。本文は百科事典ではなく、作業を始めるために必要なものであるべきです。

自由度。 指示の具体性をタスクの壊れやすさに合わせてください。

• 高い自由度（テキストによるガイダンス） — 複数のアプローチが有効な場合。手順ごとの HOW ではなく、WHAT と WHY を説明する自然言語で書きます。例:「資金調達率とソーシャルセンチメントを確認して市場のムードを測る。」
• 中程度の自由度（擬似コード + パラメータ） — 推奨されるパターンが存在するものの、詳細が変わりうる場合。主要なパラメータとともにアプローチを説明します。例:「期間 14 の RSI を使い、30 未満で買い、70 超で売る。」
• 低い自由度（scripts/ 内のスクリプト） — 操作が壊れやすく、正確な構文が必要、または繰り返しの定型的な処理である場合。コードはコンテキストに読み込むのではなく、実行される独立したスクリプトに置きます。例:正確なカラーコードと API 呼び出しを伴うチャート描画。

デフォルトの前提:あなたはすでに十分に賢いということです。まだ持っていないコンテキストだけを追加してください。

スキルの構造

my-skill/
├── SKILL.md          # Required: Frontmatter + instructions
├── scripts/          # Optional: Executable code (low freedom)
│   └── render.py     #   Run via bash, not loaded into context
├── references/       # Optional: Docs loaded on demand (medium freedom)
│   └── api-guide.md  #   Loaded via read_file when needed
└── assets/           # Optional: Templates, images, data files
    └── template.json #   NOT loaded into context, used in output

それぞれをいつ使うか:

ディレクトリ	コンテキストに読み込まれるか?	用途
SKILL.md 本文	有効化時	中核となるワークフロー、決定木、注意点
scripts/	決して読み込まれない（実行される）	壊れやすい操作、正確な構文、定型処理
references/	オンデマンド	詳細な API ドキュメント、長いガイド、参照テーブル
assets/	決して読み込まれない	テンプレート、画像、出力で使用するデータファイル

スキルの作成

ステップ 1: リクエストを理解する

スキャフォールドする前に、何を作ろうとしているのかを理解してください。

• どのような機能か? API 連携、ワークフロー自動化、知識ドメイン?
• 何がきっかけで起動するか? エージェントはいつこのスキルを有効化すべきか?（これが説明になります。）
• どの自由度レベルか? エージェントは即興で対応できるか、それとも正確なスクリプトが必要か?
• どのような依存関係があるか? API キー、バイナリ、Python パッケージ?

例:

• 「チャートを生成したい」 → スクリプトを伴うチャート作成スキル（低い自由度の描画）
• 「トレーディング戦略について考えたい」 → 知識スキル（高い自由度、対話的）
• 「Binance API と連携したい」 → 環境要件と参照ドキュメントを伴う API スキル

ステップ 2: スキャフォールド

init スクリプトを使用します:

python skills/skill-creator/scripts/init_skill.py my-new-skill --path ./workspace/skills

リソースディレクトリを指定する場合:

python skills/skill-creator/scripts/init_skill.py api-helper --path ./workspace/skills --resources scripts,references

サンプルファイルを指定する場合:

python skills/skill-creator/scripts/init_skill.py my-skill --path ./workspace/skills --resources scripts --examples

ステップ 3: 再利用可能な内容を計画する

書く前に、何をどこに置くかを決めてください。

• SKILL.md 本文:このスキルが有効化されるたびにエージェントが必要とする中核的な指示。決定木、解釈ガイド、「X 対 Y をいつ行うか」のロジック。
• scripts/:書かれたとおりに正確に実行されなければならないコード — 特定の認証を伴う API 呼び出し、正確なフォーマットでの描画、データ処理パイプライン。
• references/:エージェントがときどき必要とするかもしれない詳細なドキュメント — API エンドポイントの完全なリスト、スキーマ定義、トラブルシューティングガイド。
• assets/:エージェントが出力のためにコピー・変更する出力テンプレート、画像、設定ファイル。

ステップ 4: SKILL.md を作成する

まず内容を計画します — frontmatter のトリガー、本文の構造、自由度のレベルです。次に:

1. frontmatter — description (重要なトリガー) を更新し、requirements を追加し、絵文字を設定します
2. 本文 — ユーザーではなくエージェントに向けて書きます。箇条書きの壁よりも短い段落を。ヘッジ表現よりも意見を。

本文の設計パターン:

• ワークフローベース — ステップバイステップのプロセス (チャート作成: データ取得 → チャート設定 → レンダリング → 配信)
• タスクベース — ユーザーが尋ねそうな内容で整理 (トレーディング: 「コインを分析」/「戦略を比較」/「センチメントを確認」)
• リファレンス/ガイドライン — ルールとフレームワーク (戦略: 核心的な真実、会話スタイル、いつデータを取得するか)
• ケイパビリティベース — スキルができることで整理 (market-data: 価格ツール / デリバティブツール / ソーシャルツール)

ステップ 5: skill_manage による作成 / 更新

skill_manage が主要なワークフローです — frontmatter を検証し、セキュリティスキャンを実行し、キャッシュを自動的にリロードします。write_file を主な経路として使用しないでください。

新しいスキルの作成:

skill_manage(action="create", name="my-skill", content="---\nname: my-skill\n...")

既存スキルのパッチ適用 (的を絞った変更に推奨):

# Always read_file first to get exact whitespace/content
skill_manage(action="patch", name="my-skill", old_string="exact old text", new_string="new text")

既存スキルの完全な書き換え:

skill_manage(action="edit", name="my-skill", content="---\nname: my-skill\n...")

⚠️ 既知の落とし穴:

• スキルがすでに存在する場合、create はエラーになります → 代わりに edit または patch を使用してください。
• スキルが存在しない場合、edit/patch はエラーになります → 先に create を使用してください。
• patch は正確な old_string の一致 (空白を含む) を要求します → パッチ適用の前に必ず read_file を実行してください。
• execute() は **kwargs を受け入れる必要があります — unexpected keyword argument 'action' が表示される場合、それはツール実装のバグです (修正: def execute(self, **kwargs))。

フォールバックのみ — skill_manage が利用できない場合は、write_file + skill_refresh() を手動で使用してください。

ステップ 6: 検証

python skills/skill-creator/scripts/validate_skill.py ./workspace/skills/my-new-skill

skill_manage の後、検証は任意です (自動的にリロードされます) が、スキーマの問題を早期に発見するために実行してください。

frontmatter の形式

frontmatter は Star Child 固有のフィールドに metadata.starchild を使用します:

---
name: skill-name
version: 1.0.0
description: "What this skill does. Use when [specific trigger scenarios]."

metadata:
  starchild:
    emoji: "🔧"
    skillKey: skill-name
    requires:
      env: [API_KEY_NAME]
      bins: [python]
      anyBins: [curl, wget]
    install:
      - kind: pip
        package: pandas
      - kind: apt
        package: curl
        bins: [curl]

user-invocable: true
disable-model-invocation: false
---

フィールドリファレンス:

フィールド	場所	必須	目的
name	トップレベル	はい	スキル識別子 (小文字ハイフンケース)
version	トップレベル	はい	セマンティックバージョン (例: 1.0.0)。公開に必須。常に含めてください。
description	トップレベル	はい	トリガーテキスト — エージェントはいつこれを使うべきですか？
emoji	metadata.starchild	いいえ	表示用絵文字
skillKey	metadata.starchild	いいえ	重複排除キー
requires.env	metadata.starchild	いいえ	必須の環境変数
requires.bins	metadata.starchild	いいえ	必須のバイナリ (すべてが存在する必要があります)
requires.anyBins	metadata.starchild	いいえ	必須のバイナリ (いずれか 1 つ)
install	metadata.starchild	いいえ	依存関係のインストール方法 (pip、apt、npm など)
user-invocable	トップレベル	いいえ	ユーザーが /command でトリガーできるか (デフォルト: true)
disable-model-invocation	トップレベル	いいえ	<available_skills> から隠す (デフォルト: false)

オンチェーンスキル — ウォレットポリシーの前提条件

スキルが あらゆるオンチェーン操作 (トランザクションの送信、トークン承認、スワップ、ブリッジング、署名、入金、出金、スマートコントラクトの操作) を含む場合は、SKILL.md の上部付近に前提条件セクションを追加してください:

## Prerequisites — Wallet Policy
Before executing any [operation], the wallet policy must be active.
Load the **wallet-policy** skill and propose the standard wildcard
policy (deny key export + allow `*`). This covers all [skill-name]
operations across all chains.

これにより、エージェントはトランザクションを試みる 前に ウォレットポリシーを提案することが保証されます。これがない場合、最初のトランザクションはポリシー違反で失敗します。

含めるべきでないもの

• README.md — SKILL.md が読み物そのものです。重複させないでください。
• CHANGELOG.md — スキルはバージョン管理されたパッケージではありません。
• エージェントがすでに持っているドキュメント — システムプロンプトのツール説明を繰り返さないでください。
• 単純なタスクのステップバイステップ — エージェントは「ファイルを読んでから処理する」ことを自力で理解できます。
• 一般的なプログラミングのアドバイス — 「エラーハンドリングを使いましょう」はノイズです。具体的な落とし穴はシグナルです。

ベストプラクティス

1. 説明がトリガーになります。 これはエージェントがスキルを有効化するかどうかを判断する方法です。具体的なシナリオを挙げて「Use when...」を含めてください。悪い例:「Trading utilities.」良い例:「Test trading strategies against real historical data. Use when a strategy needs validation or before committing to a trade approach.」

2. ユーザーではなくエージェントに向けて書きます。 スキルは AI への指示です。直接的な表現を使ってください。「This skill can be used to generate charts.」ではなく「You generate charts」と書きます。

3. スクリプトは読み込まずに実行されます。 大規模な自動化に適しています。エージェントはカスタマイズが必要なときだけスクリプトを読み込むため、コンテキストをクリーンに保てます。

4. システムプロンプトを重複させないでください。 エージェントはすでにツール名と説明を認識しています。エージェントが持っていない知識に焦点を当ててください。解釈ガイド、判断ツリー、ドメイン固有の注意点などです。

5. 認証情報は最後に要求します。 まずスキルを設計し、その後でユーザーに API キーを尋ねてください。

6. リフレッシュの前には必ず検証する — validate_skill.py を実行して、問題を早期に発見してください。