Initial commit

2025-11-30 08:51:41 +08:00
commit e19586cfce
31 changed files with 7129 additions and 0 deletions
--- a/skills/element-definition-convention/SKILL.md
+++ b/skills/element-definition-convention/SKILL.md
@@ -0,0 +1,317 @@
+---
+name: element-definition-convention
+description: プラグイン要素の定義ルール（命名規則、必須項目、記述フォーマット）を定義する。プラグイン要素作成時、エージェント・スキル・コマンド定義時、またはユーザーが命名規則、フロントマター、必須項目、記述フォーマットに言及した際に使用する。
+---
+
+# Element Definition Convention
+
+## 概要
+
+このSkillは、プラグイン要素（エージェント、スキル、コマンド）の定義ルールを明確化する。命名規則、フロントマターの必須項目、必須セクション、ドキュメント記述フォーマットについて標準を定義し、一貫性のあるプラグイン要素の作成を実現することを目的とする。
+
+## 責任範囲
+
+このSkillは以下の範囲をカバーする:
+
+- プラグイン要素（エージェント、スキル、コマンド）の命名規則
+- フロントマターの必須項目と記述ルール
+- 必須セクション（概要、責任範囲、基本方針など）の定義
+- ドキュメント記述フォーマットと記述原則
+- チェックリストの作成ガイドライン
+
+## 基本方針
+
+- 命名はケバブケース（kebab-case）を使用する
+- フロントマターにはname、descriptionを必須とする
+- 必須セクションを統一し、一貫性を保つ
+- ドキュメントは日本語・常体で記述する
+- 簡潔で明確な文章を使用する
+- 箇条書きを活用して情報を整理する
+
+## 命名規則
+
+### エージェントの命名
+
+エージェントの役割を表す名前を使用する。
+
+**命名パターン:**
+
+- `[役割]-agent`の形式を使用する
+- 責任範囲が明確にわかる名前にする
+- ケバブケース（例: requirements-agent, design-agent）を使用する
+
+良い例:
+
+```text
+requirements-agent
+design-agent
+implementation-agent
+test-agent
+```
+
+悪い例:
+
+```text
+RequirementsAgent (キャメルケースは使用しない)
+req-agent (省略形は避ける)
+requirements_agent (スネークケースは使用しない)
+agent-requirements (順序が逆)
+```
+
+### スキルの命名
+
+スキルの目的を表す名前を使用する。
+
+**Workflow Skillの命名パターン:**
+
+- 動詞を含む名前にする（例: code-generator, api-designer）
+- 「何を生成するか」「何を設計するか」を明確にする
+- ケバブケース（例: database-schema-designer）を使用する
+
+**Convention Skillの命名パターン:**
+
+- 規約の対象を表す名前にする（例: coding-conventions, documentation-standards）
+- 複数形を使用することが多い（conventions, standards, guidelinesなど）
+- ケバブケース（例: security-guidelines）を使用する
+
+良い例（Workflow Skill）:
+
+```text
+code-generator
+api-designer
+database-schema-designer
+requirements-structurer
+```
+
+良い例（Convention Skill）:
+
+```text
+coding-conventions
+documentation-standards
+security-guidelines
+interaction-guidelines
+```
+
+悪い例:
+
+```text
+CodeGenerator (キャメルケースは使用しない)
+api_designer (スネークケースは使用しない)
+gen-code (省略形は避ける)
+generator (目的が不明確)
+```
+
+### コマンドの命名
+
+コマンドの機能を表す名前を使用する。
+
+**命名パターン:**
+
+- ユーザーが覚えやすい簡潔な名前にする
+- 動詞または名詞を使用する（例: requirements, design, generate）
+- ケバブケース（例: test-run）を使用する
+- 複数単語の場合は、意味が明確になるようにする
+
+良い例:
+
+```text
+requirements
+design
+task
+implement
+test-run
+generate-plugin
+```
+
+悪い例:
+
+```text
+req (省略形は避ける)
+RequirementsCommand (キャメルケースは使用しない)
+requirements_command (スネークケースは使用しない)
+command-requirements (順序が逆)
+```
+
+## フロントマターの定義
+
+すべてのプラグイン要素のマークダウンファイルには、フロントマターを記述する。
+
+**必須項目:**
+
+- `name`: 要素の名前（ケバブケース）
+- `description`: 要素の簡潔な説明（1行、50文字以内を目安）
+
+**フォーマット:**
+
+```markdown
+---
+name: 要素名（ケバブケース）
+description: 簡潔な説明（1行、50文字以内）
+---
+```
+
+良い例:
+
+```markdown
+---
+name: code-generator
+description: 設計仕様からソースコードを生成する
+---
+```
+
+悪い例:
+
+```markdown
+---
+name: CodeGenerator
+description: このスキルは、設計仕様書を入力として受け取り、それに基づいてソースコードを自動的に生成するための機能を提供します。生成されるコードは、プロジェクトのコーディング規約に準拠し、テストケースも含まれます。
+---
+（nameがキャメルケース、descriptionが長すぎる）
+```
+
+## 必須セクションの定義
+
+### エージェントの必須セクション
+
+1. **概要**: エージェントの目的と役割を簡潔に説明（1〜2段落）
+2. **責任範囲**: エージェントが責任を持つ範囲を箇条書き（3〜5項目）
+3. **基本方針**: エージェントの行動指針（該当する場合のみ）
+
+### スキルの必須セクション
+
+1. **概要**: スキルの目的と実行内容を簡潔に説明（1〜2段落）
+2. **責任範囲**: スキルがカバーする範囲を箇条書き（3〜5項目）
+3. **基本方針**: スキルの実行原則（該当する場合のみ）
+4. **ワークフロー/カテゴリ**:
+   - Workflow Skill: フェーズごとの実施内容
+   - Convention Skill: カテゴリ別の規約・ガイドライン
+5. **アウトプット**: スキルが生成する成果物（Workflow Skillの場合）
+6. **チェックリスト**: 各フェーズ/カテゴリのチェック項目
+
+### コマンドの必須セクション
+
+1. **概要**: コマンドの目的と機能を簡潔に説明（1〜2段落）
+2. **使用するエージェント**: コマンドが使用するエージェント
+3. **使用するスキル**: コマンドが使用するスキルのリスト
+4. **実行フロー**: スキルの実行順序とデータの受け渡し
+5. **成果物**: コマンド実行後の出力先とファイル構成
+
+## ドキュメント記述の原則
+
+プラグイン要素のドキュメント記述時は、以下の原則に従う:
+
+- 日本語・常体で記述する
+- 簡潔で明確な文章を使用する
+- 箇条書きを活用して情報を整理する
+- 具体例を記述する場合は、良い例/悪い例の形式を使用する
+
+良い例:
+
+```markdown
+## 概要
+
+このSkillは、設計仕様からソースコードを生成する。コーディング規約に準拠したコードを自動生成し、開発効率を向上させることを目的とする。
+
+## 責任範囲
+
+このSkillは以下の範囲をカバーする:
+
+- 設計仕様の解析とコード構造の決定
+- コーディング規約に準拠したソースコードの生成
+- 生成コードの検証とフォーマット
+```
+
+悪い例:
+
+```markdown
+## 概要
+
+このSkillは、設計仕様書を入力として受け取り、それに基づいてソースコードを自動的に生成するための機能を提供します。生成されるコードは、プロジェクトのコーディング規約に準拠し、テストケースも含まれます。また、コードレビューの観点からも最適化されており、保守性の高いコードを生成することができます。
+
+## 責任範囲
+
+このSkillは以下の範囲をカバーします:
+
+・設計仕様の解析
+・コード生成
+・検証
+```
+
+（文章が冗長、敬体を使用、箇条書きのマーカーが不統一）
+
+## チェックリストの作成ガイドライン
+
+### チェックリストの構成
+
+- フェーズごと/カテゴリごとにチェックリストを作成する
+- 最終確認用のチェックリストを含める
+- 具体的で検証可能な項目を記述する
+- 各項目は明確で検証可能にする（「〜を確認した」「〜が含まれている」のような表現）
+
+良い例:
+
+```markdown
+### フェーズ1完了時
+
+- [ ] 設計仕様書を読み込んだ
+- [ ] コード構造を決定した
+- [ ] 必要なファイルパスを特定した
+
+### 最終確認
+
+- [ ] 生成コードがコーディング規約に準拠している
+- [ ] すべてのファイルが正しいパスに配置されている
+- [ ] 構文エラーがない
+```
+
+悪い例:
+
+```markdown
+### チェックリスト
+
+- [ ] 設計仕様を確認
+- [ ] コード生成
+- [ ] 良いコードになっている
+```
+
+（フェーズ分けがない、項目が曖昧、検証不可能な表現）
+
+## チェックリスト
+
+### 命名規則確認時
+
+- [ ] ケバブケース（kebab-case）を使用している
+- [ ] エージェント名は責任範囲が明確である
+- [ ] スキル名は目的が明確である（Workflow Skillは動詞を含む、Convention Skillは規約の対象を表す）
+- [ ] コマンド名は簡潔で覚えやすい
+- [ ] 省略形を避けている
+
+### フロントマター作成時
+
+- [ ] nameフィールドがケバブケースで記述されている
+- [ ] descriptionフィールドが1行50文字以内である
+- [ ] descriptionが簡潔で要素の目的を明確に説明している
+
+### 必須セクション作成時
+
+- [ ] 概要セクションが1〜2段落で簡潔に記述されている
+- [ ] 責任範囲が箇条書きで3〜5項目記述されている
+- [ ] 基本方針が明確である（該当する場合）
+- [ ] ワークフロー/カテゴリが適切に構成されている
+- [ ] チェックリストが作成されている
+
+### ドキュメント記述確認時
+
+- [ ] 日本語・常体で記述されている
+- [ ] 簡潔で明確な文章を使用している
+- [ ] 箇条書きを活用して情報が整理されている
+- [ ] リストのインデントがスペース2個で統一されている
+- [ ] 良い例/悪い例が具体的で実用的である（該当する場合）
+
+### 最終確認
+
+- [ ] すべての命名規則が守られている
+- [ ] フロントマターが正しく記述されている
+- [ ] 必須セクションがすべて含まれている
+- [ ] ドキュメント記述の原則に従っている
+- [ ] チェックリストが適切に作成されている