---
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個で統一されている
- [ ] 良い例/悪い例が具体的で実用的である（該当する場合）

### 最終確認

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