devetai/better-skill-gen

Better Skill Generator (better-skill-gen)

このスキルはメタスキルとして機能します。ユーザーからアイデア、問題、またはワークフローを受け取り、ユーザーと一緒に設計を確定し、選択された各プロバイダ向けの完全なスキルディレクトリを生成します。

プロバイダ	ディレクトリ（プロジェクトスコープ）	特徴
Codex および Antigravity	.agents/skills/<skill-name>/（共通で1つのバージョン）	name, descriptionのみ。Codexにはスキル呼び出しポリシー用の agents/openai.yaml が追加
Claude Code	.claude/skills/<skill-name>/	拡張frontmatterフィールドが多数追加。references/frontmatter-spec.md を参照

このファイルはCodexとAntigravityで共通です。このファイル内の scripts/...、references/... などのパスは、この SKILL.md が置かれているディレクトリからの相対パスです。「コマンドを実行する」とは、使用中のプロバイダのシェルコマンド実行ツール（Antigravityの run_command など）を使用することを意味します。

---

1. コア設計原則

1. 3レベルの段階的開示アーキテクチャ:
   • レベル1: メタデータ（起動時に常にロード）: YAML Frontmatter内の name、description。トークン消費が非常に少なく、description は 1,536文字未満に抑えます。
   • レベル2: 指示（スキルがアクティブになったときにのみロード）: SKILL.md の本文。必須で 500行未満。ワークフロー、コア原則、制約のみを含めます。
   • レベル3: リソース（実際に必要なときにのみロード）: templates/（出力テンプレート）、examples/（ゴールドスタンダードのサンプルテキスト）、references/（技術仕様）、scripts/（コンテキストを消費せずに重い処理を実行するbash/pythonコード）。
2. スキル目的の分類:
   • Reference Skills: コーディング規約、システム知識、デザインパターン。エージェントが背景知識として適用するためのもの。
   • Task Skills: アクションを実行するためのステップバイステップの手順。副作用（デプロイ、コミット、データ削除など）のあるタスクは、ユーザーが直接呼び出した場合にのみ実行する必要があります。.agents/skills/ バージョンでは両方の処理を行います：agents/openai.yaml を policy.allow_implicit_invocation: false で作成（Codex用）し、description に「ユーザーが直接要求した場合のみ使用」という文を追加します（Antigravity用。Antigravityには同等のフィールドはありません）。詳細は references/providers.md のセクション3を参照してください。
3. プロバイダ固有の機能: Claude Codeには、サブエージェント、パラメータ変数、SKILL.md 内へのシェルコマンド埋め込みがあります（references/frontmatter-spec.md を参照）。これらはClaude Codeバージョンでのみ使用します。他のプロバイダ向けのバージョンでは、references/providers.md のセクション3に従って変換します。
4. 検証、信頼しない（自己検証）:
   • 生成されるすべてのスキルには、標準の終了コード（0 = 合格、1 = 不合格）を持つ scripts/validate.sh を同梱する必要があります。
   • markdownlint標準に従って、lintルールを100%順守します。
5. Zero Workspace Pollution:
   • すべての設定ファイル、リソース、スクリプトは、各プロバイダのディレクトリ内のスキルのパッケージ化されたディレクトリにのみ配置されます。
   • すべてのサンプルドキュメントは、スキルの examples/ 内にのみ配置されます。プロジェクトの他のビジネスディレクトリ（src/、プロジェクトルートなど）にサンプルファイルを生成またはコピーしてはいけません。
   • テスト中の一時ファイルは、OSの一時ディレクトリ（またはユーザーの指示で指定された一時ディレクトリ）に書き込まれ、完了後すぐにクリーンアップされます。
6. ユーザーへの構造化された選択肢の提示:
   • ユーザーに提示するすべての選択肢（スコープ、プロバイダ、アイデアの不明点、設計の方向性）は、選択肢の形式で質問します。セッションで回答選択型のユーザー質問ツールが利用できる場合は、そのツールを使用します。それ以外の場合は、番号付きの選択肢をリストし、停止してユーザーの回答を待ちます。
   • 提示順序: (1) 作成するスキルの目的、(2) 質問の内容とその理由、(3) 各選択肢のメリット・デメリットを一文で説明した選択肢、(4) 推奨する選択肢（リストの先頭に配置し、「(推奨)」と記述）。
   • 1回のやり取りで最大4つの質問を行い、重要なポイントを先に質問します。常にユーザーが提示された選択肢とは異なる回答をできるようにします。
   • ユーザーの回答がない状態で、ユーザーに代わって選択してはいけません。
7. プロバイダごとに、そのプロバイダの標準に準拠したバージョンを作成:
   • 共有リソース（template.md、examples/、references/、scripts/）はそのままコピーします。SKILL.md（およびCodexの agents/openai.yaml）は個別に作成します：1つはClaude Code用、もう1つはCodexとAntigravityで共通のものです。
   • Codex / Antigravityバージョンは両方のプロバイダで正しく動作する必要があります：オープン標準のfrontmatterフィールドのみを使用し、Claude Codeのみが理解する変数やツールを使用せず、実行中のエージェントを「Claude」と呼んではいけません。Claudeは、スキルのトピックである場合にのみ言及されます。

---

2. 必要な入力

• 必須: 作成するスキルのアイデアまたはビジネス目標の説明。
• オプション: 固有の制約、使用するツール、タスクタイプまたは参照情報。
• 必須の質問（新しいスキルを作成するたびに）: スコープとプロバイダ（セクション2.1）、およびアイデア内の不明点（セクション2.2）。ユーザーがリクエストで既に明確に回答している質問はスキップします。
• 不明点を推測しない: アイデアが漠然としている場合は、分析して提案を行い（セクション2.2）、自分で埋めてからファイルを生成してはいけません。明白な慣例があるポイント（例：アイデアから推測される kebab-case の名前）のみ、自動的に設定することができ、設計概要でその旨を明示する必要があります。

2.1. 適用範囲（スコープ）とプロバイダの質問

ファイルを生成する前に、原則6に従って、同じやり取りで以下の2つの質問をします。

1. スコープ（複数選択可）：以下の表の3つの選択肢。project-shared が推奨です。
2. プロバイダ（複数選択可）：Codex、Claude Code、Antigravity。スキルがすべてのプロバイダで使用できる場合は、3つすべてを推奨します。スキルが特定のプロバイダにのみ意味がある場合（例：Claude Codeの設定ファイルのみをチェックする）、そのプロバイダのみを推奨し、理由を明確に説明します。

スコープ	意味	ルートディレクトリ	スクリプト実行時の変数
project-shared	現在のプロジェクト専用で、チーム全体で共有（gitにコミット）	プロジェクトルート	SCOPE=project（デフォルト）
project-personal	現在のプロジェクト専用で、このユーザーのみ（コミットしない）	プロジェクトルート	SCOPE=project、作成されたディレクトリを .git/info/exclude に追加
user-global	このユーザーのすべてのプロジェクト	$HOME	SCOPE=user

ルール:

• ユーザーが複数のスコープを選択した場合は、各スコープを順次デプロイします。
• プロジェクトディレクトリがgitリポジトリでない場合は、project-personal の選択肢を削除します。
• 選択されたスコープとプロバイダを、作成されたパスのリストとともに引き継ぎレポートに記録します。
• プロジェクト固有の内容を持つスキルで、ユーザーが user-global を選択した場合：作成前に1行の警告を表示します。

2.2. アイデアの分析と提案

スコープとプロバイダを取得した後、ファイルを作成する前にアイデアを分析します。

1. 理解した内容の要約: スキルが何を解決するか、誰が使用するか、いつアクティブになるか、出力は何か。
2. 設計上のポイントの特定: 各ポイントについて、ユーザーが述べたのか、エージェントが推測しているのかを明確に記録します。
   • スキルのタイプ：TaskかReferenceか。副作用はあるか。
   • アクティブ化の方法：description に従って自動か、ユーザーが直接呼び出した場合のみか、その両方か。アクティブ化フレーズと使用しないケース。
   • 入力、パラメータ、および不足時の処理方法。
   • 出力：形式、保存場所、template.md と scripts/validate.sh のテスト基準が必要かどうか。
   • 実行方法：指示のみか、スクリプトが必要か。使用するツール。
   • references/ に分離する部分。SKILL.md を500行未満に保つため。
3. 最適な方向性の提案: 複数の方法がある各ポイントについて、メリット・デメリットを含む2～3の方向性を示し、1つの推奨方向性を選択します。例：「スクリプト scripts/check.sh でチェックする（高速、正確、ただしbashが必要）」 vs 「エージェントが自分で読み取って評価する（柔軟だが、トークンを消費し、見落としがち）」。
4. ユーザーへの質問: 不明点と複数の方向性があるすべてのポイントを、原則6に従って質問にまとめます。
5. 設計の確定: 回答を受け取った後、設計概要（スキル名、タイプ、アクティブ化方法、作成するファイルのリスト、プロバイダ、スコープ、エージェントが自動的に設定した値）を作成します。回答によって新たな不明点が生じた場合は、さらに質問し、まだファイルは生成しません。

2.3. プロバイダの調査

特定のプロバイダ向けのバージョンを作成する前に、references/providers.md を読みます。

• 最終確認日 が30日以上前の場合、スキルにファイルにない機能が必要な場合、またはファイル内の情報が実際と矛盾している場合：そのファイルのセクション6の公式ドキュメントを参照し、ファイルを修正して最終確認日を更新し、scripts/sync-skill.sh better-skill-gen を使用して他のプロバイダにファイルをコピーします。
• Antigravityは、プロジェクトスコープではCodexと同じ .agents/skills/ を使用します（セクション5）。.agent/skills/ は作成しないでください。
• プロバイダの仕様を推測してはいけません。調査できないポイントは、ユーザーに明確に伝えて質問します。

---

3. 実行手順（ワークフロー）

flowchart TD
    A["ユーザーからのビジネスアイデア"] --> A2["0. スコープとプロバイダを質問"]
    A2 --> B["1. アイデアを分析、提案、不明点を質問"]
    B --> B2["2. プロバイダを調査"]
    B2 --> C["3. template.md と references/ を参照"]
    C --> D["4. オリジナルバージョンを生成"]
    D --> E["5. リソースを同期 & プロバイダごとに個別の SKILL.md を作成"]
    E --> F["6. scripts/validate.sh で自己検証"]
    F -->|合格| G["完了 & 引き継ぎ"]
    F -->|不合格| D

0. スコープとプロバイダを質問: セクション2.1を実行し、次のステップに進む前に回答を待ちます。
1. アイデアを分析: 設計が確定するまでセクション2.2を実行します。スキル名は kebab-case で付けます（64文字以下。anthropic-skills、synced、claude、anthropic は禁止）。
2. プロバイダを調査: 選択されたすべてのプロバイダについてセクション2.3を実行します。
3. 標準ドキュメントを参照: template.md（構造フレームワーク）、references/providers.md（プロバイダ間の違い）、references/frontmatter-spec.md（Claude Codeのフィールド）、examples/sample.md（記述スタイルとスクリプトロジック）を読みます。
4. オリジナルバージョンを生成: 最初に選択されたプロバイダのディレクトリに、すべてのコンポーネントを作成します。
   • SKILL.md: 安全なFrontmatter（quote/scalar block >-）、500行未満。
   • template.md（または templates/）:
   • examples/sample.md: プレースホルダーのない実際のサンプルテキスト。
   • references/（複雑な仕様/知識ドキュメントを分離する必要がある場合）
   • scripts/validate.sh: 結果の整合性をチェックするスクリプト。
   • 共有リソースはプロバイダに依存せずに記述します。スクリプトはスキルディレクトリからの相対パスで呼び出します。
5. プロバイダごとにデプロイ:
   • 共有リソースをコピー: PROVIDERS="<選択されたプロバイダ>" bash scripts/sync-skill.sh <skill-name> を実行します。このスクリプトは、SKILL.md と agents/ を除くすべてのファイルをコピーし、SKILL.md が不足しているプロバイダに [TODO] を報告します。
   • 残りのディレクトリについて、references/providers.md のセクション3の変換表に従って、個別の SKILL.md を作成します。本文の文言を書き直し、frontmatterフィールドを削除するだけではいけません。CodexとAntigravityの両方が選択された場合、.agents/skills/ ディレクトリは1つだけで、スクリプトが自動的に統合します。
   • 副作用のあるスキル: .agents/skills/ バージョンでは、agents/openai.yaml を policy.allow_implicit_invocation: false で追加作成し、description に「ユーザーが直接要求した場合のみ使用」という文を追加します。
   • user-global スコープ: スクリプト実行時に SCOPE=user をさらに設定します。
   • project-personal スコープ: 作成したスキルディレクトリを .git/info/exclude に追加します（.gitignore は編集せず、コミットもしません）。
6. 自己検証:
   • PROVIDERS="<選択されたプロバイダ>" bash scripts/validate.sh <skill-name> を実行します（user-global の場合は SCOPE=user を追加）。
   • スクリプトは以下をチェックします：YAML frontmatterが有効か、markdownlint、SKILL.md が500行以下か、選択されたすべてのプロバイダに必須ファイルが揃っているか、Codex/Antigravityの SKILL.md にClaude Codeのみが理解するフィールドやトークンが残っていないか。
   • 各 [WARN] 行を読みます：Claudeがトピックであるために言及されている場合はそのままにし、そうでない場合は修正します。
   • エラーがある場合は、[PASS] を受け取るまで自分で修正します。

---

4. 制約 & 基準（ガードレール）

• 厳守ルール:
  • すべての選択肢は原則6に従って質問し、次のステップに進む前に回答を待ちます。
  • 新しいスキルを作成する前に、常にスコープとプロバイダを質問します（セクション2.1）。
  • 不明点を推測しない: ファイルを生成する前に、分析、提案、質問を行います（セクション2.2）。
  • プロバイダ向けのバージョンを作成する前に、プロバイダを調査します（セクション2.3）。仕様を推測してはいけません。
  • プロバイダ間で SKILL.md をそのままコピーしない: 各プロバイダに個別の標準準拠バージョンを作成します。validate.sh は選択されたすべてのプロバイダで [PASS] する必要があります。
  • Zero Workspace Pollution: サンプルドキュメントは examples/ 内にのみ配置します。スキルのパッケージ化されたディレクトリ外にファイルを作成してはいけません。
  • SKILL.md を500行未満に保つ: 詳細な内容は references/ または templates/ に移動します。
  • Frontmatterの標準化: description にコロン : が含まれる場合は、スカラー >- または引用符 "..." を使用します。
  • 生成されるすべてのMarkdownファイルでMarkdownlint（MD001 - MD047）に準拠します。
• 推奨事項:
  • 副作用のあるすべてのスキルについて、各プロバイダの方法（Codex: agents/openai.yaml、Antigravity: description 内の文）に従って、「ユーザーが呼び出した場合のみ実行」メカニズムを宣言します。
  • テンプレートでは、説明的な変数
  • 自動テスト中に生成された一時ファイルはすぐにクリーンアップします。
• 禁止事項:
  • 長い参照ドキュメント全体を SKILL.md に直接詰め込まないでください。
  • URLを生のまま、<> またはmarkdownリンクなしでmarkdownファイルに配置しないでください。
  • 64文字を超える、大文字または特殊文字を含むスキル名を使用しないでください。
  • Claude Code以外のプロバイダ向けのバージョンで、エージェントを「Claude」と呼んではいけません。

---