skill-creator

スキルの作成

適切なタイミングで読み込まれ、モデルがすでに知っている内容を教えることなく、成果を自ら検証できるスキルを作成します。

使用するタイミング

次の場合に使用します。

• ユーザーがスキルディレクトリを作成する場合、または既存のスキルの改善、レビュー、分割を依頼する場合。
• スキルが頻繁にトリガーされすぎる、ほとんどトリガーされない、または兄弟スキルと競合する場合。
• bun run lint-skills が失敗した場合、またはプラグインやマーケットプレイスにスキルを登録する必要がある場合。
• ユーザーがスキルの skillgrade 評価を希望する場合。

次の場合は使用しないでください。

• ユーザーがアプリのドキュメント、README、変更履歴、マーケティング文書を作成している場合。
• ユーザーがスキルではないライブラリやプラグインのソースを編集している場合。

リファレンス一覧

トピックが該当する場合にのみリファレンスを読み込みます。

ファイル	読み込むタイミング
references/repo-layout.md	このリポジトリでスキルを追加、名前変更、登録するとき、plugins/ に同期するとき、または lint エラーを読むとき
references/authoring-patterns.md	本文を作成するとき：トリガー設計、リファレンス一覧、落とし穴、検証、バージョンタグ、サブエージェントのスキル、インラインスナップショット

手順

1. スキルの範囲を定める

• 次の形式で一文を書きます。「<具体的な状況>のときに読み込み、エージェントが<成果>を達成できるようにします。」
• 該当する可能性のある兄弟スキルを列挙します。それぞれを除外トリガーにします。
• 無関係なワークフローを2つ扱うスキルは分割します。1段落だけの簡素な内容になるなら統合します。
• 範囲、対象読者、優先する製品など、実際に判断が必要な点はユーザーに尋ねます。リポジトリを読めば確認できる点は尋ねないでください。

2. フロントマターを作成する

---
name: my-skill                      # lowercase, hyphenated, equals the folder name
description: <what it does>. Use when <symptoms, APIs, file names, error strings>. Do not use for <case> (sibling-skill).
---

• ルーターが参照するのは description のみです。コマンド名、設定キー、ファイル名、正確なエラー文字列など、具体的なトリガーを記載します。除外条件には兄弟スキルの名前を記載します。
• 1行に収め、1024文字以内にします（lint で両方が検証されます）。
• 任意の when_to_use: は、Claude Code のスキル一覧で description に追記されます。結合後のテキストは1536文字で切り捨てられるため、最も重要な使用ケースを先に記載します。他のエージェントはこれを無視するため、主要なトリガーを description から移さないでください。
• allowed-tools: は、スキルがインラインコマンドを実行する場合にのみ指定します。最小限にし、読み取り専用にしてください。

3. 簡潔な本文を書く

おおむね250行未満を目指します。次の順序で記載します。

1. 目的を一行で示し、バージョン行を添えます（「X 8.77、2026年10月に照合済み」）。
2. ## When to Use：TRIGGER の箇条書きと、兄弟スキル名を挙げる Do not use when のリスト。lint では ## When to Use 見出しが必須です。
3. ## Reference Index：各ファイルと、読み込むタイミングを記載した表。「トピックが該当する場合にのみリファレンスを読み込みます。」と記載します。
4. ## Procedure：番号付きの手順。編集前に調査し、大幅な変更を行う前に調査結果を報告します。
5. ## Traps：見落としやすい失敗を記載します。モデルがすでに知っている基本事項は省略します。
6. ## Verification：成功を証明する正確なコマンドや確認方法。
7. ## Error Handling：正確なエラー文字列と対応する修正方法。

詳細な表、長いコード、トピックごとの詳しい内容は、references/<topic>.md に移します。階層は1段階までにします。壊れやすいロジックや繰り返し使うロジックは scripts/ に配置します。

4. すべての事実を確認する

• コマンド、フラグ、設定キー、API はすべて、ソースコードまたは公式ドキュメントで確認します。記憶に頼らず、パッケージの --help、型定義、リポジトリを優先します。
• 時間とともに変わる情報にはバージョンを付記します（「Capacitor 8.5+」、「Xcode 27」、「CLI 8.77」）。対象の古いバージョンで任意の動作が利用できない可能性がある場合は、機能検出を条件にします。
• 事実を確認できない場合は「最新のドキュメントを確認」と記載し、推測しないでください。よく捏造されるものの実在しないコマンドがあれば列挙します。

5. コマンドの文脈に合わせる

• スキル本文では、標準的な npm / npx の例を使います。Capacitor と Capgo CLI の例では npx ...@latest を使います。
• bun / bunx は、このリポジトリ自体の開発・CI コマンド、または Bun 専用スキルでのみ使います。
• 別のリポジトリを編集するスキルでは、そのリポジトリの指示を読み、パッケージマネージャーの方針に従うようエージェントに伝えます。

6. シークレットを保持する

スキルがユーザーファイルを編集する場合は、ユーザーから提供されたトークン、キー、証明書、パスワードを、ユーザーから依頼されない限りプレースホルダーに置き換えないようエージェントに伝えてください。プレースホルダーは、新しい汎用例にのみ使用します。ユーザーから依頼されない限り、シークレットのローテーションを提案しないでください。

7. 登録と検証（このリポジトリ）

references/repo-layout.md に従います。skills/ に正規フォルダーを作成し、metadata.json を用意し、package.json の skills にエントリを追加します。さらに、プラグインフォルダーと .claude-plugin/marketplace.json を通じて公開し、その後 bun run sync-skills と bun run lint-skills を実行します。

8. 動作の後退を防ぐ必要がある場合は eval を追加する

skillgrade（eval.yaml + graders/）を使用します。構造には決定論的な grader を優先してください。定性的な判断にのみ LLM ルーブリックを使用します。bun run lint-skills-skillgrade で実行するか、lint 中に API キーとともに ENABLE_SKILLGRADE=1 を設定して実行します。

注意点

• 曖昧な説明（「X を支援します」）ではスキルは起動されません。範囲が広すぎる説明（「モバイルに関することなら何でも使用」）は、関連する別のスキルへのリクエストまで奪ってしまいます。
• 「references/ を参照」のように読み込み条件がないインデックス項目では、エージェントがすべてを読むか、何も読まないかのどちらかになります。必ずいつ読み込むかを記載してください。
• 古い情報は構造よりも早く陳腐化します。レビュー担当者が再確認すべき箇所を把握できるよう、バージョン行を先頭に置いてください。
• plugins/<plugin>/skills/ 内のミラーコピーを編集するのは誤りです。正規の skills/<name>/ を編集してから同期してください。
• インラインの !command`` スナップショットは読み込みのたびに実行されます。ガード（fs.existsSync）を設け、処理を高速にし、出力を短く、読み取り専用にしてください。

検証

1. bun run lint-skills が成功すること。名前とフォルダー名の一致、説明の長さ、## When to Use 見出し、metadata.json の有効性、マーケットプレイスへの公開、ミラーとのバイト単位の一致が検査されます。
2. wc -l skills/<name>/SKILL.md が約 250 行以下であり、references/ 内のすべてのファイルが Reference Index に記載されていること。
3. スキル内の各コマンドを grep し、ツールの --help またはソースと一致することを確認します。
4. 頭の中でルーティングをテストします。スキルが起動されるべき 3 つのプロンプトでは起動し、各関連スキル向けのプロンプトでは起動しないことを確認します。

エラー処理

Lint メッセージ	修正方法
<skill>: name "<x>" does not match folder name	frontmatter の name をディレクトリ名と一致させます
<skill>: description exceeds 1024 characters	冗長な箇所を削り、具体的な起動条件と否定条件は残します
<skill>: missing usage guidance	## When to Use 見出しを追加します
<skill>: missing metadata.json / invalid metadata.json	JSON を作成または修正します（references/repo-layout.md を参照）
claude marketplace: skill "<x>" is not exposed by any plugin	plugins/<plugin>/skills/<x>/ を作成し、bun run sync-skills を実行します
mirrored skills: ... (run bun run sync-skills)	bun run sync-skills を実行します。ミラーを手動で編集しないでください
<plugin>: unknown skill "<x>"	プラグインフォルダーに一致する skills/<x> がありません。正規のスキルを作成するか、フォルダーを削除します