skill-creator

Builder.io Fusion 用スキルの作成

プロジェクトで Builder.io Fusion ができることを拡張するスキルを作成、改善します。

作業内容

次のいずれかのワークフローでユーザーを支援します。

1. 新しいスキルを作成する — 意図を把握し、ディレクトリをひな形から作成して、SKILL.md を記述します
2. 既存のスキルを改善する — 内容を読み、問題を診断して、書き直します
3. 適切なツールを選ぶ — スキル、AGENTS.md、.builderrules のどれを使うべきか判断します

新しいスキルを作成する

ステップ 1：意図を把握する

ユーザーが必要としているものを理解するため、次の質問をします。ユーザーの技術レベルに合わせて表現を調整してください。技術に詳しくない場合は、専門用語を避け、判断を代行してください。

1. このスキルでは何をしますか？ どのようなタスクや知識を提供すべきですか？
2. どのようなときに起動しますか？ どのような発言や質問が、このスキルを有効にするべきですか？
3. 出力は何ですか？ ファイル、コード、レポート、ワークフローの手順などですか？
4. ユーザー固有の設定が必要ですか？（例：API キー、チャネル名、チームの設定）→ config.json パターンを使用します

ステップ 2：適切なツールを選ぶ

スキルを作成する前に、本当にスキルが適切か確認してください。

必要なもの	使用するもの	理由
再利用可能な AI 向けの指示やワークフロー	Skill（.builder/skills/<name>/SKILL.md）	必要なときだけ読み込まれるため、コンテキストを軽量に保てます。関連ファイルやスクリプトを同梱でき、段階的に情報を開示できます。
背景知識と関連ファイル	Skill	参照ドキュメントやスクリプトを指示とともに用意し、必要に応じて読み込めます
AI が常に把握しておくべき指示	AGENTS.md	システムプロンプトのようにコンテキストへ読み込まれます。プロジェクト全体で必須の規約に適しています。
ディレクトリ単位の簡易なルール	.builderrules または .builder/rules/*.mdc	特定のディレクトリに適用範囲を限定できる軽量なルールです
リンターで適用できるスタイルルール	リンター設定（ESLint、Prettier など）	機械的なチェックに AI のコンテキストを使わないでください

スキルを推奨される標準の選択肢とします。 AI のコンテキストに常に読み込まれる AGENTS.md とは異なり、スキルは関連する場合にのみ読み込まれます。そのため、コンテキストウィンドウを圧迫せずに多くのスキルを用意できます。AGENTS.md は、AI がすべての会話で本当に必要とする少数の指示に限って使用してください。

ステップ 3：スキルのひな形を作成する

.builder/skills/<name>/SKILL.md にスキルのディレクトリを作成します。

project/
└── .builder/
    └── skills/
        └── <skill-name>/
            └── SKILL.md

ファイルを書き込む前に：

• .builder/ または .builder/skills/ が存在しない場合は、ディレクトリを作成します
• 指定したパスにスキルがすでに存在する場合は、まず内容を読み、既存のスキルを更新するか、別の名前を選ぶかユーザーに尋ねます

命名規則：

• 小文字、数字、ハイフンのみを使用します（例：pdf-processor、deploy-staging）
• ハイフンの連続、先頭または末尾のハイフンは禁止です
• 64 文字以内にします
• ディレクトリ名がスキルの識別子になります
• 入れ子のパスはディレクトリで表します。office-word ではなく、.builder/skills/office/word/SKILL.md とします
• Builder.io のディレクトリと名前が重複しないようにします：rules、config、settings

ステップ 4：SKILL.md を記述する

すべての SKILL.md は、YAML フロントマターと Markdown 本文の 2 部構成です。

フロントマター

少なくとも name と description を含めます。

---
name: my-skill
description: >
  What the skill does AND when to use it. Include trigger
  keywords and phrases. This is what the AI reads to decide
  whether to load the skill.
---

各フィールドの詳細については、references/frontmatter-reference.md を参照してください。

説明の作成（重要）

説明は、スキルの中で最も重要な1行です。AIが適切なタイミングでスキルを読み込むかどうかを決定します。ここを間違えるとスキルは一度も起動せず、正しく書けば確実に起動します。

WHAT + WHEN のパターンを使います。 すべての説明には、次の両方が必要です。

• スキルが何をするか（WHAT）
• いつ使うか（具体的なトリガーとなる状況）

悪い例：

description: Helps with documents
# Too vague — the AI has no activation signal

description: Extract text from PDF files
# Only says WHAT, not WHEN — the AI must guess when to trigger

description: Use when the user says "create a PDF"
# Too narrow — misses related phrasings

良い例：

description: >
  Extract text and tables from PDF files, fill forms, merge
  documents. Use when working with PDF files or when the user
  mentions PDFs, forms, document extraction, or .pdf files.

description: >
  Generate commit messages by analyzing git diffs. Use when the
  user asks for help writing commit messages, reviewing staged
  changes, or preparing code for commit, even if they don't
  explicitly ask for a "commit message."

確実に起動させるためのヒント：

• 三人称で書きます（「ファイルを処理します」のように。「ファイルの処理をお手伝いします」ではありません）
• ファイル拡張子、分野の用語、くだけた言い換えを含めます
• 惜しいケースでのトリガーとして、「Xを明示的に依頼していない場合でも」を加えます
• 1024文字未満に収めます
• 説明は人間ではなくAIモデル向けです。トリガーの定義として考えてください
• AIエージェントはスキルを起動しない傾向があるため、起動する状況を具体的に示すようにします

本文の作成

Markdownの本文は、スキルの指示です。500行未満に収め、明確に構成します。

# Skill Title

## Quick Start
Immediate, actionable guidance.

## Instructions
Step-by-step procedures.

## Gotchas
Common failure points and how to avoid them.

## Examples
Concrete input/output pairs.

作成の原則：

• 当たり前のことは書かないでください。 AIはすでにコーディングの方法を知っています。AIの既定の動作から外すための内容、つまりプロジェクト固有の特徴、規約、注意点に集中してください。
• 「注意点」セクションを作成します。 これは、どのスキルでも最も価値の高い情報です。失敗につながる点を見つけたら記録し、時間をかけて更新してください。優れた「注意点」セクションは、何ページもの指示よりも役立ちます。
• 一つのやり方に縛らないでください。 スキルはさまざまな状況で再利用されます。厳格な手順書ではなく、AIに情報と柔軟性を与えてください。状況に合わせて対応できるようにします。
• 内容だけでなく理由も説明します。 「集計パイプラインがUTCを前提としているため、UTCタイムスタンプを使います」は、「必ずUTCタイムスタンプを使ってください」よりも効果的です。
• 小さく始めて、繰り返し改善します。 成功したスキルの多くは、数行と1つの注意点から始まりました。AIがエッジケースに遭遇するにつれて改善されてきました。最初から完璧なスキルを書こうとしないでください。

ステップ5：補足ファイルを追加する（必要な場合）

スキルはMarkdownファイルだけではなく、フォルダーです。段階的な情報開示にはファイルシステムを使います。

my-skill/
├── SKILL.md              # Required — main instructions (<500 lines)
├── references/            # Detailed docs, loaded on demand
│   └── api-docs.md
├── scripts/               # Executable helpers
│   └── validate.sh
└── assets/                # Templates, static files
    └── template.html

段階的な情報開示は、次の3つのレベルで機能します。

レベル	読み込まれる内容	タイミング	サイズ
メタデータ	name + description	常にコンテキスト内	約100トークン
指示	SKILL.md本文全体	スキルの起動時	500行未満
リソース	参照ファイル、スクリプト	AIが必要とするとき	無制限

ルール：

• SKILL.mdは500行未満に保ちます。400行に近づいたら、詳細な内容を参照ファイルに分割します。
• SKILL.mdから参照先へのリンクを記載します：「APIの詳細については、references/api-docs.mdを参照してください。」
• 参照ファイルは1階層までにします。別の参照ファイルを参照するファイルは作らないでください。深くネストした内容は、AIが一部しか読まない可能性があります。
• スキルが一貫した形式のファイルを生成する場合は、assets/にテンプレートを含めます。
• AIが定型コードを再構築するのではなく組み合わせて使えるよう、再利用可能なスクリプトを​​scripts/に含めます。

ステップ6：高度なパターン

ユーザー固有の設定に使うConfig.json

スキルでユーザーごとに異なるコンテキスト（APIキー、チャンネル名、チーム設定）が必要な場合：

my-skill/
├── SKILL.md
└── config.json

SKILL.mdには次のように指示します：「このスキルのディレクトリにconfig.jsonが存在しない場合は、ユーザーに［必要な設定］を尋ね、作業を進める前にconfig.jsonに保存してください。」

メモリとデータの保存

スキルは状態を保持できます。

• 追記専用のログファイル（例：朝会スキル用のstandups.log）
• JSONデータファイル
• SQLiteデータベースも使用できます

これにより、AIはセッションをまたいで過去の履歴を参照できます。

スキルの組み合わせ

指示内でほかのスキルを名前で参照します。インストールされていれば、AIがそれらを呼び出します。例：「検証後に変更をプッシュするには、/deployスキルを使います。」

ステップ 7：スキルをテストする

スキルを作成したら：

1. 新しいセッションを開始します。 スキルはセッション開始時に読み込まれるため、新しいスキルを読み込むには新しいセッションを開始します。
2. 内容のあるプロンプトを試します。 説明に合った複数ステップのプロンプトや専門的なプロンプトでテストします。プロンプトが具体的であるほど、スキルが呼び出されやすくなります。
3. 2～3 通りの表現を試します。 スキルの機能を誰かが依頼するときに使いそうな、異なる表現でテストします。
4. 失敗しやすいケースを確認します。 AI が以前に失敗したシナリオを、意図的に試します。

スキルが呼び出されない場合、説明に改善が必要な可能性があります。WHAT + WHEN のパターンを見直し、トリガーとなる用語を追加してください。

既存のスキルを改善する

ユーザーがスキルの改善を希望する場合：

1. 現在の SKILL.md を読む — 目的と構成を把握します
2. 問題を診断する：
   • 呼び出されない？ → 説明の WHAT + WHEN を改善する必要があります
   • 関係ないときに呼び出される？ → 説明が広すぎるため、WHEN の範囲を絞ります
   • 出力の質が低い？ → 手順に失敗しやすいケースや制約を追加します
   • 動作が遅い、またはコンテキストを使いすぎる？ → 段階的開示に分割します
3. 名前とディレクトリを維持する — ユーザーから依頼されない限り、名前を変更しません
4. 変更内容を示す — 書き込む前に、何を変更したか、なぜ変更したかを説明します

監査チェックリスト

このチェックリストを使って、スキルの品質を確認します：

• フロントマター： name と description を含む有効な YAML である
• 説明： WHAT + WHEN のパターンを使用し、1024 文字未満である
• 説明： 具体的なトリガー用語と状況を含んでいる
• 命名： ディレクトリ名は小文字とハイフンを使用し、name フィールドと一致する
• サイズ： SKILL.md が 500 行未満である
• 失敗しやすいケース： Gotchas セクションがある（または、時間をかけて追加する旨の記述がある）
• 段階的開示： 参照ファイルが SKILL.md から 1 階層の深さにある
• 明白な知識がない： AI がすでに知っていることを説明していない
• 柔軟性： 固定的なスクリプトではなく、AI が状況に合わせられる指示になっている
• パス： .builder/skills/<name>/SKILL.md にある

避けるべきアンチパターン

• 曖昧な説明 — 「コードを支援する」だけでは、いつ呼び出せばよいか AI に伝わりません
• 深すぎる参照のネスト — SKILL.md → A.md → B.md という構成は機能しません。参照は 1 階層にとどめます
• 明白なことを説明しすぎる — REST API とは何かを AI に教える必要はありません。独自の内容に注力します
• 型にはめすぎること — 厳格すぎる段階的なスクリプトは、状況が異なると機能しません。背景を説明し、AI が状況に合わせられるようにします
• デフォルトなしで選択肢を増やしすぎること — 「ライブラリ X、Y、Z のいずれかを使う」では、任意の選択を強いることになります。1 つを選び、代替案を記載します
• 本文に XML タグを使うこと — <section> タグではなく、標準的な Markdown 見出しを使います
• リンターで管理すべきスタイルルール — セミコロン、スペース、インポート順序はスキルではなく、ESLint/Prettier の設定で管理します

参照ファイル

各フィールドの詳細については、references/frontmatter-reference.md を参照してください。

さまざまな複雑さの完全なスキル例については、references/examples.md を参照してください。