# Skill Granularity Convention

> スキルの適切な粒度を定義（1スキル1目的、分割基準、結合基準）する。スキル設計時、粒度判断時、またはユーザーがスキル粒度、1スキル1目的、分割基準、結合基準、スキル設計原則に言及した際に使用する。

- Skill: `majiayu000/skill-granularity-convention` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/skill-granularity-convention`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/skill-granularity-convention/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/skill-granularity-convention

---


# Skill Granularity Convention

## 概要

このSkillは、スキルの適切な粒度を定義し、1スキル1目的の原則を明確化する。スキルを分割すべき基準、結合すべき基準、適切な粒度の判断方法について指針を提供し、保守性と再利用性の高いスキル設計を実現することを目的とする。

## 責任範囲

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

- 1スキル1目的の原則の定義
- スキル分割の基準と判断方法
- スキル結合の基準と判断方法
- 適切な粒度の判断指標
- 粒度判断のベストプラクティス

## 基本方針

- 1スキル1目的を厳守する
- 責任範囲を明確に定義する
- 複数の目的が含まれる場合は分割を検討する
- 過度に細分化しない（実用性を保つ）
- コンテキストサイズを最小化する
- 再利用性と保守性を重視する

## 1スキル1目的の原則

### 原則の定義

各スキルは、一つの明確な目的を持つべきである。

**目的の定義:**

- スキルが達成すべき具体的な成果物または作業内容
- 責任範囲セクションで明確に表現できる範囲
- ユーザーが「このスキルは〜をする」と一文で説明できる範囲

### 原則の適用

スキルの目的が明確であることを確認する:

- スキルのdescriptionが1行で簡潔に説明できる
- 責任範囲が3〜5項目で列挙できる
- ワークフローが2〜5フェーズで構成できる（Workflow Skillの場合）
- カテゴリが2〜5個で構成できる（Convention Skillの場合）

良い例:

```markdown
---
name: api-designer
description: RESTful API仕様を設計する
---

## 責任範囲

- エンドポイントの定義
- リクエスト/レスポンス形式の設計
- 認証・認可方式の設計
```

（目的が「API仕様を設計する」と明確）

悪い例:

```markdown
---
name: system-designer
description: システム全体を設計する
---

## 責任範囲

- アーキテクチャ設計
- データベース設計
- API設計
- UI/UX設計
- セキュリティ設計
- パフォーマンス設計
```

（目的が広すぎて、複数のスキルに分割すべき）

## スキル分割の基準

### 分割すべきケース

以下の場合は、スキルを分割することを検討する:

1. **複数の異なる目的が含まれる場合**
   - 一つのスキルで複数の成果物を生成する
   - 責任範囲が6項目以上ある
   - descriptionが2文以上必要になる

2. **ワークフローが複雑すぎる場合**
   - ワークフローのフェーズが6個以上ある
   - 各フェーズの実施内容が5項目以上ある
   - フェーズ間の依存関係が複雑である

3. **カテゴリが多すぎる場合**
   - カテゴリが6個以上ある（Convention Skillの場合）
   - 各カテゴリのルールが5項目以上ある
   - カテゴリ間の関連性が薄い

4. **規約部分が肥大化する場合**
   - Workflow Skillに含まれる規約が大量にある
   - 規約の説明が長く、ワークフローの理解を妨げる
   - 規約を他のスキルでも再利用したい

### 分割方法

#### パターン1: 目的別に分割

システム設計スキルを目的別に分割:

- アーキテクチャ設計スキル
- データベース設計スキル
- API設計スキル
- UI/UX設計スキル

#### パターン2: フェーズ別に分割

要件定義スキルをフェーズ別に分割:

- 要件収集スキル
- 要件整理スキル
- 要件検証スキル

#### パターン3: 規約を分離

コード生成スキルから規約を分離:

- コード生成スキル（Workflow Skill）
- コーディング規約スキル（Convention Skill）

良い例:

```text
分割前:
- system-designer（システム全体を設計する）

分割後:
- architecture-designer（システムアーキテクチャを設計する）
- database-schema-designer（データベーススキーマを設計する）
- api-designer（RESTful API仕様を設計する）
- ui-component-architect（UIコンポーネント構成を設計する）
```

悪い例:

```text
分割前:
- api-designer（RESTful API仕様を設計する）

分割後:
- endpoint-designer（エンドポイントを設計する）
- request-designer（リクエスト形式を設計する）
- response-designer（レスポンス形式を設計する）
- auth-designer（認証方式を設計する）
```

（過度に細分化されており、実用性が低い）

## スキル結合の基準

### 結合すべきケース

以下の場合は、スキルを結合することを検討する:

1. **スキルが小さすぎる場合**
   - 責任範囲が1〜2項目しかない
   - ワークフローが1フェーズしかない
   - 単独では実用的でない

2. **スキル間の依存関係が強い場合**
   - 常に一緒に実行される
   - 一方のスキルの出力が他方の入力になる
   - 分離することで理解が困難になる

3. **重複が多い場合**
   - 複数のスキルで同じ規約やガイドラインを記述している
   - 同じ前提条件や制約事項を持っている
   - 統合することで重複を削減できる

### 結合方法

#### パターン1: 関連する作業を統合

エンドポイント設計、リクエスト設計、レスポンス設計を統合:

- API設計スキル（すべてを含む）

#### パターン2: 規約を直接記述

コード生成スキルに規約を直接記述:

- コード生成スキル（規約を含む）

良い例:

```text
結合前:
- endpoint-designer（エンドポイントを設計する）
- request-designer（リクエスト形式を設計する）
- response-designer（レスポンス形式を設計する）

結合後:
- api-designer（RESTful API仕様を設計する）
```

悪い例:

```text
結合前:
- architecture-designer（システムアーキテクチャを設計する）
- database-schema-designer（データベーススキーマを設計する）
- api-designer（RESTful API仕様を設計する）

結合後:
- system-designer（システム全体を設計する）
```

（目的が広すぎて、1スキル1目的の原則に反する）

## 適切な粒度の判断方法

### 判断指標

以下の指標を使用して、スキルの粒度が適切かどうかを判断する:

1. **descriptionの明確さ**
   - 1行50文字以内で説明できる → 適切
   - 2文以上必要 → 分割を検討

2. **責任範囲の項目数**
   - 3〜5項目 → 適切
   - 1〜2項目 → 結合を検討
   - 6項目以上 → 分割を検討

3. **ワークフローのフェーズ数（Workflow Skill）**
   - 2〜5フェーズ → 適切
   - 1フェーズ → 結合を検討
   - 6フェーズ以上 → 分割を検討

4. **カテゴリ数（Convention Skill）**
   - 2〜5カテゴリ → 適切
   - 1カテゴリ → 結合を検討
   - 6カテゴリ以上 → 分割を検討

5. **ドキュメントサイズ**
   - 200〜400行 → 適切
   - 200行未満 → 結合を検討
   - 400行以上 → 分割を検討

### 判断フロー

```text
1. descriptionが1行で説明できるか？
   ├─ はい → 2へ
   └─ いいえ → 分割を検討

2. 責任範囲が3〜5項目か？
   ├─ はい → 3へ
   ├─ いいえ（1〜2項目） → 結合を検討
   └─ いいえ（6項目以上） → 分割を検討

3. ワークフロー/カテゴリが2〜5個か？
   ├─ はい → 適切な粒度
   ├─ いいえ（1個） → 結合を検討
   └─ いいえ（6個以上） → 分割を検討
```

## ベストプラクティス

### 実用性を重視する

- 理論的に分割可能でも、実用性がなければ分割しない
- ユーザーが使いやすい粒度を優先する
- コマンドで組み合わせることを前提に設計する

### コンテキストサイズを最小化する

- 不要な情報を含めない
- 規約やガイドラインは必要最小限にする
- 他のスキルと重複する内容を避ける

### 再利用性を考慮する

- 複数のコマンドから使用されるスキルは独立させる
- 特定のコマンド専用のスキルは統合を検討する

### 保守性を確保する

- 変更頻度が異なる内容は分離する
- 安定した部分と変更される部分を分ける

## チェックリスト

### スキル作成時

- [ ] descriptionが1行50文字以内で説明できる
- [ ] 責任範囲が3〜5項目である
- [ ] ワークフロー/カテゴリが2〜5個である
- [ ] 1スキル1目的の原則を守っている
- [ ] 複数の異なる目的が含まれていない

### スキル分割検討時

- [ ] 複数の異なる目的が含まれているか確認した
- [ ] ワークフローが複雑すぎないか確認した
- [ ] カテゴリが多すぎないか確認した
- [ ] 規約部分が肥大化していないか確認した
- [ ] 分割後の各スキルが実用的であるか確認した

### スキル結合検討時

- [ ] スキルが小さすぎないか確認した
- [ ] スキル間の依存関係が強いか確認した
- [ ] 重複が多いか確認した
- [ ] 結合後も1スキル1目的の原則を守れるか確認した

### 粒度判断時

- [ ] descriptionの明確さを確認した
- [ ] 責任範囲の項目数を確認した
- [ ] ワークフロー/カテゴリ数を確認した
- [ ] ドキュメントサイズを確認した
- [ ] 実用性を考慮した

### 最終確認

- [ ] 適切な粒度になっている
- [ ] 1スキル1目的の原則が守られている
- [ ] 実用性がある
- [ ] コンテキストサイズが最小化されている
- [ ] 再利用性と保守性が確保されている