skill-builder

スキルビルダー

統合型のセキュリティ優先スキルビルダーです。

このスキルには、意図的に明確な方針があります。

• よりシンプルな変更で解決できる場合は、新しいスキルを作らないでください。
• スキルを作成する場合は、簡潔で、テスト可能で、誤用されにくいものにしてください。
• ルーターは1つにまとめ、スキル間で説明が重複しないようにしてください。
• 対象環境で明示的に必要とされない限り、モデルやハーネスに依存しないようにしてください。

操作ルーター

ユーザーの意図	操作	出力
スキルを作成／構築／用意／新規作成する	CREATE	新しいスキルフォルダー + SKILL.md + 実際に必要な補助ファイルのみ
スキルを更新／変更／改善する	UPDATE	最小限の差分。スコープを維持
スキルを削除／取り除く	DELETE	スキルを削除 + 依存する参照を更新
スキルにコンテンツ／ルート／ワークフローを追加する	ADD	新しいルータ行 + 最小限のサポート手順
スキルを検証する	VALIDATE	証拠に基づく検証レポート + 修正
スキルの名前を変更する	RENAME	安全な名前変更 + 参照の更新

操作の選択ルール

依頼を解決できる最小の操作を選びます。

• CREATE — 新しいユーザー向け機能、または明確に異なる意図／説明の領域。
• UPDATE — 中核となるスコープを変えずに、既存のスキルを改善する。
• ADD — 現在のスコープ内に新しいルート、例、またはサブワークフローを追加する。
• RENAME — ほぼ同じ動作を維持しながら、識別子／パス／名前を変更する。
• DELETE — 代替、統合、または有用性の低下により、古くなった機能を削除する。
• VALIDATE — スコープを広げずに正確性を確認する。

判断に迷う場合は、CREATE ではなく UPDATE を既定とします。

「正しい」とは

このスキルでは、次の状態を「正しい」とします。

• Agent Skills 仕様で明示されている要件に準拠している。
• 段階的な開示を採用している。SKILL.md は簡潔にし、詳細なドキュメントは必要な場合にのみ用意する。
• 有効化の条件が曖昧でない。説明が具体的で、隣接するスキルと重複しない。
• 安全である。シークレットを含まず、破壊的なコマンドを既定で実行せず、明示的な確認境界がある。
• 直感に頼らず、検証の証拠を提示する。

フェーズ 0：第一原理の確認（必須）

CREATE または UPDATE の前に、必ず実施します。

1. QUESTION：どのような問題を、誰のために、どのように測定して解決しますか？
2. DELETE：既存のスキル、README のセクション、スクリプト、またはテンプレートで解決できますか？
3. SIMPLIFY：機能する最小限の変更は何ですか？
4. ACCELERATE：（2）と（3）の後にのみ実施します。
5. AUTOMATE：再利用される場合にのみ、新しいスキルを作成します。

「スキルは不要」という結論になった場合は、次のいずれかを提案します。

• README のセクション
• 小さなスクリプト
• ユーザーがコピーできる使用例
• 既存のスキルに対する的を絞った更新

フェーズ 1：対象の検出と名前

Agent Skills 仕様で必須

• スキルのディレクトリには SKILL.md が含まれている。
• SKILL.md は有効な YAML フロントマターで始まる。
• name は親ディレクトリの名前と一致する。
• description には、スキルの機能と使用するタイミングが記載されている。

このスキルで推奨

• SKILL.md はルーターと中核ルールに絞ります。
• references/、scripts/、assets/、または README.md は、実際の価値を加える場合にのみ追加します。
• 参照ファイルは SKILL.md から1階層以内に置きます。
• 標準外のメタデータは、新しいトップレベルフィールドを作るのではなく、metadata の下に置きます。

命名

• ケバブケースを使用します（my-skill-name）。
• 汎用的な名前（tools、helper）は避けます。
• 目的とする作業が明確に伝わる名前を優先します。

説明の設計

description フィールドは、主な検出手段です。

次の内容を含めてください。

• スキルが何をするか
• いつ使用するか
• ありそうなユーザーの表現、専門用語、類義語

移植性を損なう独自のトップレベル triggers フィールドには依存しないでください。トリガーの例を含める場合は、本文、metadata、または評価用フィクスチャに記載してください。

確認の境界

確認なしで安全に行える操作：

• 読み取り専用の調査
• コンテンツの下書き作成
• ローカルでの検証
• 差分の提案

以下の操作の前には確認が必要です：

• ファイルまたはフォルダーの削除
• スキルフォルダーの名前変更
• ユーザーが作成したコンテンツの上書き
• 検出動作を変える可能性のある、トリガーのセマンティクスの変更
• リポジトリのインデックスまたはカタログの編集
• 依存関係のインストール、またはネットワークを伴う副作用の実行

フェーズ 2：CREATE フロー

入力（最低限）

• 名前
• 目標と対象外の事項
• 何をするか、いつ使うかを網羅した説明の下書き
• 対象クライアントがサポートしている場合は、任意の機能制約

CREATE の手順

1. 対象リポジトリの既存の規約を調べます。
2. マイクロ仕様書を作成します。内容は、目標、対象外の事項、ルーター、安全の境界です。
3. /<skill-name>/SKILL.md を作成し、以下を含めます：
   • フロントマター（name、description、仕様でサポートされている任意のフィールド）
   • ルーターテーブル
   • 安全および確認に関するルール
   • 簡潔なワークフロー、または references/ へのリンク
4. 妥当な理由がある場合に限り、関連ファイルを追加します：
   • 人間向けのインストール方法や概要を記載する README.md
   • 詳細なワークフローを記載する references/
   • 実行可能なヘルパーを格納する scripts/
   • テンプレートやリソースを格納する assets/
5. 以下のエビデンスルールに従って検証します。
6. リポジトリでインデックスを管理している場合は、更新します。

出力契約（CREATE）

必ず以下を返します：

• 作成または編集したファイル
• 追加または変更した説明
• compatibility、metadata、allowed-tools などの任意フィールドを使用したかどうか
• 最小限のスモークテスト用プロンプト 1 つ
• 検証レポート：合否、エビデンス、残存リスク

フェーズ 3：UPDATE フロー

1. 現在のスキルを読みます。
2. 実際のユーザーの目標を特定します。
3. 目標を達成するために必要最小限の差分を適用します。
4. 検証を再実行します。
5. より広範な変更が明示的に依頼されていない限り、スコープと説明は維持します。

出力契約（UPDATE）

以下を返します：

• 変更したファイル
• 変更した動作
• 説明の変更：あり／なし
• 検証レポート
• リスクまたは今後の対応事項

フェーズ 4：DELETE フロー

1. 対象のスキルフォルダーを確認します。
2. 依存先（インデックス、参照、同階層のスキル）を特定します。
3. スキルを削除し、参照を更新します。
4. ロールバックの手順を提示します。

出力契約（DELETE）

以下を返します：

• 削除したパス
• 更新した参照
• ロールバックに関する注記
• 残存する壊れたリンクの検証／レポート

フェーズ 5：スキルへのコンテンツ追加

スキルを拡張する際のルール：

• 同じインストール環境内の複数のスキルで、説明の意図を重複させないでください。
• まず意図に基づいて振り分け、その後で詳細なセクションを読み込みます。
• SKILL.md は読みやすい状態に保ちます。表は簡潔にし、テンプレートは安定させ、詳細は references/ に記載します。

追加手順：

1. ルーターの行を 1 つ追加するか、範囲を厳密に限定したセクションを 1 つ追加します。
2. 必要最小限の手順を追加します。
3. 内容が増えた場合は、references/<topic>.md に分割します。
4. 例を追加または更新します。
5. 隣接するスキルとの重複がないか再確認します。

フェーズ 6：RENAME フロー

1. 変更前と変更後の名前を確認します。
2. フォルダーの名前を変更し、フロントマターの name を更新します。
3. 内部およびリポジトリレベルの参照を更新します。
4. リンク、名前とパスの一致、検出に関する文言を検証します。

出力契約（RENAME）

以下を返します：

• 旧名 → 新名
• 移動したパス
• 更新した参照
• 検証レポート

検証

検証要件

以下の 3 つの層すべてについてエビデンスを提示するまで、スキルは検証済みとはみなされません：

1. 仕様の検証 — 構造と YAML の正確性
2. トリガーの検証 — 説明が必要な場合にトリガーされ、類似しているが該当しない場合にはトリガーされないこと
3. 出力の検証 — 現実的なタスクにおいて、スキルが成果を改善または制約すること

スキル検証チェックリスト

• Frontmatter に有効な name と description が含まれています。
• Frontmatter は、見た目だけそれらしい Markdown メタデータではなく、有効な YAML です。
• name は親ディレクトリと一致しています。
• 説明には、何をするのか、いつ使うのかが明確に記されています。
• 追加の Frontmatter は、対象環境で明示的にサポートされている場合を除き、仕様でサポートされるフィールドの範囲内に収めます。
• ルーターが含まれています。
• 確認が必要となる境界が明確です。
• シークレットは含まれていません。対象のリポジトリが意図的にプライベートな場合を除き、非公開のパスも含まれていません。
• 対象範囲が定められていない破壊的な指示はありません。
• 段階的な情報開示が守られています。
• 隣接するスキルと照らし合わせて、トリガーの適切さを確認しています。

仕様の検証（推奨）

利用可能な場合：

skills-ref validate ./<skill-name>

利用できない場合は、references/validation.md のルールに従って手動で検証してください。

機能の安全性

• タスクを完了できる機能のうち、最小限の権限で済むものを優先してください。
• コマンドを実行する前に、内容を確認・検索してください。
• コマンドの実行が必要な場合は、対象範囲を厳密に限定してください。
• rm -rf、git reset --hard、push --force をデフォルトとして推奨しないでください。

テンプレート

スキルの Frontmatter

---
name: my-skill
description: Use this skill when you need to do X, Y, or Z. It handles A and B and is relevant when the user asks for C.
compatibility: Optional. Mention required runtimes, system tools, or environment assumptions.
metadata:
  version: "0.1"
allowed-tools: Optional experimental field. Only include it when the target client supports it and the skill benefits from a constrained tool list.
---

最小限のポータブルなスキル

1. Frontmatter
2. 目的と起動に関するガイダンス（1 段落）
3. ルーターテーブル
4. 安全性と確認のルール
5. 短いワークフロー
6. 必要な場合のみ references/ を追加

参考資料

• references/checklist.md（作成チェックリスト）
• references/templates.md（コピー＆ペースト用テンプレート）
• references/validation.md（仕様、トリガー、出力の検証）

このスキルの用途（実践例）

• 「新しいスキルをひな形から作成するスキルを作って」→ CREATE。
• 「このスキルを複数のエージェント製品でよりポータブルにして」→ UPDATE。
• 「参照を壊さずにこのスキルの名前を変更して」→ RENAME。
• 「このスキルが安定して起動するか確認して」→ VALIDATE。
• 「リポジトリ間でスキルの一貫性を高めて」→ 範囲に応じて UPDATE または ADD。