6.9 KiB
6.9 KiB
title, description, tags
| title | description | tags | ||||
|---|---|---|---|---|---|---|
| Plugin Design Document Template | Standard template for documenting plugin architecture and implementation plans |
|
Plugin Design Document Template
Metadata
Purpose: Provide standard structure for plugin design documentation Applies to: All new plugin development in marketplace Version: 1.0.0
Instructions
When to Use This Template
Use this template when:
- Designing a new plugin from scratch
- Documenting architecture decisions for a plugin
- Planning refactoring of an existing plugin
- Communicating plugin design to stakeholders
Template Sections
The design document should include these sections in order:
- Overview - Purpose, use cases, scope
- Architecture Decision - Pattern and rationale
- Component Design - Detailed breakdown of agents, skills, commands
- File Structure - Directory layout
- Token Budget Summary - Estimated token usage
- Implementation Checklist - Step-by-step tasks
- Next Steps - Immediate actions to take
Resources
Complete Design Document Template
# Plugin Design: [Plugin Name]
## Overview
**Purpose**: [5-10 word description]
**Use Cases**: [When users will invoke this]
**Scope**: [What's included and excluded]
## Architecture Decision
**Pattern**: [Single-purpose / Workflow orchestration / Agent + Skill integration]
**Rationale**: [Why this architecture fits the use case]
## Component Design
### Agents
#### [Agent Name] (`agents/agent-name.md`)
**Role**: [Expert persona and domain]
**Responsibilities**:
- [Responsibility 1]
- [Responsibility 2]
**Skills Used**:
- `skill-name-1` - When [condition]
- `skill-name-2` - When [condition]
**Token Budget**: ~[X] tokens
---
### Skills
#### [Skill Name] (`skills/skill-name.md`)
**Purpose**: [What knowledge this provides]
**Used By**: [Which agents/commands use this]
**Tier 1: Metadata** (~75 tokens)
- Title, description, tags
**Tier 2: Instructions** (~[X] tokens)
- [Core content outline]
**Tier 3: Resources** (~[X] tokens)
- [Detailed content outline]
**Token Budget**: ~[X] tokens (Tier 1+2 typically loaded)
---
### Commands
#### [Command Name] (`commands/command-name.md`)
**Purpose**: [What user action this enables]
**Parameters**:
- Standard output parameters (--format, --output)
- [Any custom parameters]
**Workflow**:
1. [Step 1]
2. Activate agent: `agent-name`
3. Agent activates skill: `skill-name`
4. [Processing]
5. Format output
**Token Budget**: ~[X] tokens (command) + ~[Y] tokens (agent) + ~[Z] tokens (skills)
**Total**: ~[X+Y+Z] tokens
---
## File Structure
plugin-name/ ├── .claude-plugin/ │ └── plugin.json ├── agents/ [if needed] │ └── agent-name.md ├── skills/ [if needed] │ ├── skill-name-1.md │ └── skill-name-2.md └── commands/ ├── command-1.md └── command-2.md
## Token Budget Summary
| Component | Typical Load | Max Load |
|-----------|--------------|----------|
| Agents | [X] tokens | [Y] tokens |
| Skills | [X] tokens | [Y] tokens |
| Commands | [X] tokens | [Y] tokens |
| **Total** | **[X] tokens** | **[Y] tokens** |
## Implementation Checklist
- [ ] Create plugin directory structure
- [ ] Write plugin.json
- [ ] Implement agents (if applicable)
- [ ] Implement skills with three-tier structure
- [ ] Implement commands with output parameters
- [ ] Add entry to marketplace.json
- [ ] Update root CLAUDE.md
- [ ] Test plugin installation
- [ ] Test command invocation
- [ ] Verify token usage
## Next Steps
1. **Create plugin structure**: `mkdir -p plugin-name/{.claude-plugin,agents,skills,commands}`
2. **Write plugin.json**: Define metadata and tags
3. **Implement components**: Start with commands, then agents, then skills
4. **Test iteratively**: Install and test each component as built
5. **Register in marketplace**: Add to marketplace.json when complete
Token Budget Estimation Guidelines
Agents:
- Minimal agent (role + basic approach): ~200-300 tokens
- Standard agent (role + detailed approach + skill activation): ~400-600 tokens
- Complex agent (multiple personas + decision frameworks): ~600-800 tokens
Skills (Instructions tier):
- Small skill (focused standards): ~300-500 tokens
- Medium skill (comprehensive guide): ~600-1000 tokens
- Large skill (reference material): ~1000-1500 tokens
Commands:
- Simple command (direct execution): ~200-400 tokens
- Standard command (parameter handling + workflow): ~400-600 tokens
- Complex command (multi-step orchestration): ~600-1000 tokens
Total Budget Targets:
- Simple plugin: 500-1500 tokens
- Standard plugin: 1500-3000 tokens
- Complex plugin: 3000-5000 tokens
- Avoid exceeding 5000 tokens for typical use case
Architecture Pattern Examples
Single-Purpose Pattern:
## Architecture Decision
**Pattern**: Single-Purpose Command
**Rationale**: This plugin performs one focused task (format code files). It doesn't require expert reasoning or multiple knowledge domains, so a single command without agents/skills is sufficient.
**Components**:
- 1 command: `format-code.md`
- 0 agents
- 0 skills (logic is simple enough to include in command)
Agent + Skills Pattern:
## Architecture Decision
**Pattern**: Agent + Multiple Skills
**Rationale**: This plugin requires expert judgment (security analysis) and references multiple knowledge domains (security standards, vulnerability patterns). An agent provides the expertise, while skills contain reusable security knowledge.
**Components**:
- 1 agent: `security-auditor.md`
- 3 skills: `security-standards.md`, `vulnerability-patterns.md`, `remediation-guide.md`
- 1 command: `audit-security.md`
Workflow Orchestration Pattern:
## Architecture Decision
**Pattern**: Workflow Orchestration
**Rationale**: This plugin coordinates a multi-step workflow (setup project, configure CI/CD, generate docs). Multiple commands handle different aspects, sharing common skills for consistency.
**Components**:
- 0 agents (no expert reasoning needed)
- 2 skills: `project-templates.md`, `configuration-standards.md`
- 4 commands: `setup-structure.md`, `configure-ci.md`, `generate-docs.md`, `full-setup.md`
Design Document Best Practices
Clarity:
- Use concrete examples, not abstract descriptions
- Specify actual file names, not placeholders
- Provide token estimates based on actual content planned
Completeness:
- Address all three layers (agents, skills, commands)
- Explain rationale for architectural choices
- Include both typical and maximum token budgets
Actionability:
- Implementation checklist should be specific
- Next steps should be immediately actionable
- File structure should be copy-paste ready
Realism:
- Don't over-architect simple plugins
- Token budgets should be achievable
- Component counts should match complexity