Element Definition Convention

Element Definition Convention

概要

このSkillは、プラグイン要素（エージェント、スキル、コマンド）の定義ルールを明確化する。命名規則、フロントマターの必須項目、必須セクション、ドキュメント記述フォーマットについて標準を定義し、一貫性のあるプラグイン要素の作成を実現することを目的とする。

責任範囲

このSkillは以下の範囲をカバーする:

• プラグイン要素（エージェント、スキル、コマンド）の命名規則
• フロントマターの必須項目と記述ルール
• 必須セクション（概要、責任範囲、基本方針など）の定義
• ドキュメント記述フォーマットと記述原則
• チェックリストの作成ガイドライン

基本方針

• 命名はケバブケース（kebab-case）を使用する
• フロントマターにはname、descriptionを必須とする
• 必須セクションを統一し、一貫性を保つ
• ドキュメントは日本語・常体で記述する
• 簡潔で明確な文章を使用する
• 箇条書きを活用して情報を整理する

命名規則

エージェントの命名

エージェントの役割を表す名前を使用する。

命名パターン:

• [役割]-agentの形式を使用する
• 責任範囲が明確にわかる名前にする
• ケバブケース（例: requirements-agent, design-agent）を使用する

良い例:

requirements-agent
design-agent
implementation-agent
test-agent

悪い例:

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）:

code-generator
api-designer
database-schema-designer
requirements-structurer

良い例（Convention Skill）:

coding-conventions
documentation-standards
security-guidelines
interaction-guidelines

悪い例:

CodeGenerator (キャメルケースは使用しない)
api_designer (スネークケースは使用しない)
gen-code (省略形は避ける)
generator (目的が不明確)

コマンドの命名

コマンドの機能を表す名前を使用する。

命名パターン:

• ユーザーが覚えやすい簡潔な名前にする
• 動詞または名詞を使用する（例: requirements, design, generate）
• ケバブケース（例: test-run）を使用する
• 複数単語の場合は、意味が明確になるようにする

良い例:

requirements
design
task
implement
test-run
generate-plugin

悪い例:

req (省略形は避ける)
RequirementsCommand (キャメルケースは使用しない)
requirements_command (スネークケースは使用しない)
command-requirements (順序が逆)

フロントマターの定義

すべてのプラグイン要素のマークダウンファイルには、フロントマターを記述する。

必須項目:

• name: 要素の名前（ケバブケース）
• description: 要素の簡潔な説明（1行、50文字以内を目安）

フォーマット:

---
name: 要素名（ケバブケース）
description: 簡潔な説明（1行、50文字以内）
---

良い例:

---
name: code-generator
description: 設計仕様からソースコードを生成する
---

悪い例:

---
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. 成果物: コマンド実行後の出力先とファイル構成

ドキュメント記述の原則

プラグイン要素のドキュメント記述時は、以下の原則に従う:

• 日本語・常体で記述する
• 簡潔で明確な文章を使用する
• 箇条書きを活用して情報を整理する
• 具体例を記述する場合は、良い例/悪い例の形式を使用する

良い例:

## 概要

このSkillは、設計仕様からソースコードを生成する。コーディング規約に準拠したコードを自動生成し、開発効率を向上させることを目的とする。

## 責任範囲

このSkillは以下の範囲をカバーする:

- 設計仕様の解析とコード構造の決定
- コーディング規約に準拠したソースコードの生成
- 生成コードの検証とフォーマット

悪い例:

## 概要

このSkillは、設計仕様書を入力として受け取り、それに基づいてソースコードを自動的に生成するための機能を提供します。生成されるコードは、プロジェクトのコーディング規約に準拠し、テストケースも含まれます。また、コードレビューの観点からも最適化されており、保守性の高いコードを生成することができます。

## 責任範囲

このSkillは以下の範囲をカバーします:

・設計仕様の解析
・コード生成
・検証

（文章が冗長、敬体を使用、箇条書きのマーカーが不統一）

チェックリストの作成ガイドライン

チェックリストの構成

• フェーズごと/カテゴリごとにチェックリストを作成する
• 最終確認用のチェックリストを含める
• 具体的で検証可能な項目を記述する
• 各項目は明確で検証可能にする（「〜を確認した」「〜が含まれている」のような表現）

良い例:

### フェーズ1完了時

- [ ] 設計仕様書を読み込んだ
- [ ] コード構造を決定した
- [ ] 必要なファイルパスを特定した

### 最終確認

- [ ] 生成コードがコーディング規約に準拠している
- [ ] すべてのファイルが正しいパスに配置されている
- [ ] 構文エラーがない

悪い例:

### チェックリスト

- [ ] 設計仕様を確認
- [ ] コード生成
- [ ] 良いコードになっている

（フェーズ分けがない、項目が曖昧、検証不可能な表現）

チェックリスト

命名規則確認時

• ケバブケース（kebab-case）を使用している
• エージェント名は責任範囲が明確である
• スキル名は目的が明確である（Workflow Skillは動詞を含む、Convention Skillは規約の対象を表す）
• コマンド名は簡潔で覚えやすい
• 省略形を避けている

フロントマター作成時

• nameフィールドがケバブケースで記述されている
• descriptionフィールドが1行50文字以内である
• descriptionが簡潔で要素の目的を明確に説明している

必須セクション作成時

• 概要セクションが1〜2段落で簡潔に記述されている
• 責任範囲が箇条書きで3〜5項目記述されている
• 基本方針が明確である（該当する場合）
• ワークフロー/カテゴリが適切に構成されている
• チェックリストが作成されている

ドキュメント記述確認時

• 日本語・常体で記述されている
• 簡潔で明確な文章を使用している
• 箇条書きを活用して情報が整理されている
• リストのインデントがスペース2個で統一されている
• 良い例/悪い例が具体的で実用的である（該当する場合）

最終確認

• すべての命名規則が守られている
• フロントマターが正しく記述されている
• 必須セクションがすべて含まれている
• ドキュメント記述の原則に従っている
• チェックリストが適切に作成されている