Cursor rule

1---
2description: Guided end-to-end plugin creation workflow with component design,
3  implementation, and validation
4alwaysApply: true
5---
6 
7# Plugin Creation Workflow
8 
9Guide the user through creating a complete, high-quality Claude Code plugin from initial concept to tested implementation. Follow a systematic approach: understand requirements, design components, clarify details, implement following best practices, validate, and test.
10 
11## Core Principles
12 
13- **Ask clarifying questions**: Identify all ambiguities about plugin purpose, triggering, scope, and components. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding with implementation.
14- **Load relevant skills**: Use the Skill tool to load plugin-dev skills when needed (plugin-structure, hook-development, agent-development, etc.)
15- **Use specialized agents**: Leverage agent-creator, plugin-validator, and skill-reviewer agents for AI-assisted development
16- **Follow best practices**: Apply patterns from plugin-dev's own implementation
17- **Progressive disclosure**: Create lean skills with references/examples
18- **Use TodoWrite**: Track all progress throughout all phases
19 
20**Initial request:** $ARGUMENTS
21 
22---
23 
24## Phase 1: Discovery
25 
26**Goal**: Understand what plugin needs to be built and what problem it solves
27 
28**Actions**:
29 
301. Create todo list with all 7 phases
312. If plugin purpose is clear from arguments:
32   - Summarize understanding
33   - Identify plugin type (integration, workflow, analysis, toolkit, etc.)
343. If plugin purpose is unclear, ask user:
35   - What problem does this plugin solve?
36   - Who will use it and when?
37   - What should it do?
38   - Any similar plugins to reference?
394. Summarize understanding and confirm with user before proceeding
40 
41**Output**: Clear statement of plugin purpose and target users
42 
43---
44 
45## Phase 2: Component Planning
46 
47**Goal**: Determine what plugin components are needed
48 
49**MUST load plugin-structure skill** using Skill tool before this phase.
50 
51**Actions**:
52 
531. Load plugin-structure skill to understand component types
542. Analyze plugin requirements and determine needed components:
55   - **Skills**: Specialized knowledge OR user-initiated actions (deploy, configure, analyze). Skills are the preferred format for both — see note below.
56   - **Agents**: Autonomous tasks? (validation, generation, analysis)
57   - **Hooks**: Event-driven automation? (validation, notifications)
58   - **MCP**: External service integration? (databases, APIs)
59   - **Settings**: User configuration? (.local.md files)
60 
61   > **Note:** The `commands/` directory is a legacy format. For new plugins, user-invoked slash commands should be created as skills in `skills/<name>/SKILL.md`. Both are loaded identically — the only difference is file layout. `commands/` remains an acceptable legacy alternative.
62 
633. For each component type needed, identify:
64   - How many of each type
65   - What each one does
66   - Rough triggering/usage patterns
674. Present component plan to user as table:
68```
69   | Component Type | Count | Purpose |
70   |----------------|-------|---------|
71   | Skills         | 5     | Hook patterns, MCP usage, deploy, configure, validate |
72   | Agents         | 1     | Autonomous validation |
73   | Hooks          | 0     | Not needed |
74   | MCP            | 1     | Database integration |
75```
765. Get user confirmation or adjustments
77 
78**Output**: Confirmed list of components to create
79 
80---
81 
82## Phase 3: Detailed Design & Clarifying Questions
83 
84**Goal**: Specify each component in detail and resolve all ambiguities
85 
86**CRITICAL**: This is one of the most important phases. DO NOT SKIP.
87 
88**Actions**:
89 
901. For each component in the plan, identify underspecified aspects:
91   - **Skills**: What triggers them? What knowledge do they provide? How detailed? For user-invoked skills: what arguments, what tools, interactive or automated?
92   - **Agents**: When to trigger (proactive/reactive)? What tools? Output format?
93   - **Hooks**: Which events? Prompt or command based? Validation criteria?
94   - **MCP**: What server type? Authentication? Which tools?
95   - **Settings**: What fields? Required vs optional? Defaults?
96 
972. **Present all questions to user in organized sections** (one section per component type)
98 
993. **Wait for answers before proceeding to implementation**
100 
1014. If user says "whatever you think is best", provide specific recommendations and get explicit confirmation
102 
103**Example questions for a skill**:
104 
105- What specific user queries should trigger this skill?
106- Should it include utility scripts? What functionality?
107- How detailed should the core SKILL.md be vs references/?
108- Any real-world examples to include?
109 
110**Example questions for an agent**:
111 
112- Should this agent trigger proactively after certain actions, or only when explicitly requested?
113- What tools does it need (Read, Write, Bash, etc.)?
114- What should the output format be?
115- Any specific quality standards to enforce?
116 
117**Output**: Detailed specification for each component
118 
119---
120 
121## Phase 4: Plugin Structure Creation
122 
123**Goal**: Create plugin directory structure and manifest
124 
125**Actions**:
126 
1271. Determine plugin name (kebab-case, descriptive)
1282. Choose plugin location:
129   - Ask user: "Where should I create the plugin?"
130   - Offer options: current directory, ../new-plugin-name, custom path
1313. Create directory structure using bash:
132```bash
133   mkdir -p plugin-name/.claude-plugin
134   mkdir -p plugin-name/skills/&lt;skill-name&gt;   # one dir per skill, each with a SKILL.md
135   mkdir -p plugin-name/agents                # if needed
136   mkdir -p plugin-name/hooks                 # if needed
137   # Note: plugin-name/commands/ is a legacy alternative to skills/ — prefer skills/
138```
1394. Create plugin.json manifest using Write tool:
140```json
141   {
142     "name": "plugin-name",
143     "version": "0.1.0",
144     "description": "[brief description]",
145     "author": {
146       "name": "[author from user or default]",
147       "email": "[email or default]"
148     }
149   }
150```
1515. Create README.md template
1526. Create .gitignore if needed (for .claude/\*.local.md, etc.)
1537. Initialize git repo if creating new directory
154 
155**Output**: Plugin directory structure created and ready for components
156 
157---
158 
159## Phase 5: Component Implementation
160 
161**Goal**: Create each component following best practices
162 
163**LOAD RELEVANT SKILLS** before implementing each component type:
164 
165- Skills: Load skill-development skill
166- Legacy `commands/` format (only if user explicitly requests): Load command-development skill
167- Agents: Load agent-development skill
168- Hooks: Load hook-development skill
169- MCP: Load mcp-integration skill
170- Settings: Load plugin-settings skill
171 
172**Actions for each component**:
173 
174### For Skills:
175 
1761. Load skill-development skill using Skill tool
1772. For each skill:
178   - Ask user for concrete usage examples (or use from Phase 3)
179   - Plan resources (scripts/, references/, examples/)
180   - Create skill directory: `skills/<skill-name>/`
181   - Write `SKILL.md` with:
182     - Third-person description with specific trigger phrases
183     - Lean body (1,500-2,000 words) in imperative form
184     - References to supporting files
185   - For user-invoked skills (slash commands): include `description`, `argument-hint`, and `allowed-tools` frontmatter; write instructions FOR Claude (not TO user)
186   - Create reference files for detailed content
187   - Create example files for working code
188   - Create utility scripts if needed
1893. Use skill-reviewer agent to validate each skill
190 
191### For legacy `commands/` format (only if user explicitly requests):
192 
193> Prefer `skills/<name>/SKILL.md` for new plugins. Use `commands/` only when maintaining an existing plugin that already uses this layout.
194 
1951. Load command-development skill using Skill tool
1962. For each command:
197   - Write command markdown with frontmatter
198   - Include clear description and argument-hint
199   - Specify allowed-tools (minimal necessary)
200   - Write instructions FOR Claude (not TO user)
201   - Provide usage examples and tips
202   - Reference relevant skills if applicable
203 
204### For Agents:
205 
2061. Load agent-development skill using Skill tool
2072. For each agent, use agent-creator agent:
208   - Provide description of what agent should do
209   - Agent-creator generates: identifier, whenToUse with examples, systemPrompt
210   - Create agent markdown file with frontmatter and system prompt
211   - Add appropriate model, color, and tools
212   - Validate with validate-agent.sh script
213 
214### For Hooks:
215 
2161. Load hook-development skill using Skill tool
2172. For each hook:
218   - Create hooks/hooks.json with hook configuration
219   - Prefer prompt-based hooks for complex logic
220   - Use ${CLAUDE_PLUGIN_ROOT} for portability
221   - Create hook scripts if needed (in examples/ not scripts/)
222   - Test with validate-hook-schema.sh and test-hook.sh utilities
223 
224### For MCP:
225 
2261. Load mcp-integration skill using Skill tool
2272. Create .mcp.json configuration with:
228   - Server type (stdio for local, SSE for hosted)
229   - Command and args (with ${CLAUDE_PLUGIN_ROOT})
230   - extensionToLanguage mapping if LSP
231   - Environment variables as needed
2323. Document required env vars in README
2334. Provide setup instructions
234 
235### For Settings:
236 
2371. Load plugin-settings skill using Skill tool
2382. Create settings template in README
2393. Create example .claude/plugin-name.local.md file (as documentation)
2404. Implement settings reading in hooks/commands as needed
2415. Add to .gitignore: `.claude/*.local.md`
242 
243**Progress tracking**: Update todos as each component is completed
244 
245**Output**: All plugin components implemented
246 
247---
248 
249## Phase 6: Validation & Quality Check
250 
251**Goal**: Ensure plugin meets quality standards and works correctly
252 
253**Actions**:
254 
2551. **Run plugin-validator agent**:
256   - Use plugin-validator agent to comprehensively validate plugin
257   - Check: manifest, structure, naming, components, security
258   - Review validation report
259 
2602. **Fix critical issues**:
261   - Address any critical errors from validation
262   - Fix any warnings that indicate real problems
263 
2643. **Review with skill-reviewer** (if plugin has skills):
265   - For each skill, use skill-reviewer agent
266   - Check description quality, progressive disclosure, writing style
267   - Apply recommendations
268 
2694. **Test agent triggering** (if plugin has agents):
270   - For each agent, verify <example> blocks are clear
271   - Check triggering conditions are specific
272   - Run validate-agent.sh on agent files
273 
2745. **Test hook configuration** (if plugin has hooks):
275   - Run validate-hook-schema.sh on hooks/hooks.json
276   - Test hook scripts with test-hook.sh
277   - Verify ${CLAUDE_PLUGIN_ROOT} usage
278 
2796. **Present findings**:
280   - Summary of validation results
281   - Any remaining issues
282   - Overall quality assessment
283 
2847. **Ask user**: "Validation complete. Issues found: [count critical], [count warnings]. Would you like me to fix them now, or proceed to testing?"
285 
286**Output**: Plugin validated and ready for testing
287 
288---
289 
290## Phase 7: Testing & Verification
291 
292**Goal**: Test that plugin works correctly in Claude Code
293 
294**Actions**:
295 
2961. **Installation instructions**:
297   - Show user how to test locally:
298```bash
299     cc --plugin-dir /path/to/plugin-name
300```
301   - Or copy to `.claude-plugin/` for project testing
302 
3032. **Verification checklist** for user to perform:
304   - [ ] Skills load when triggered (ask questions with trigger phrases)
305   - [ ] User-invoked skills appear in `/help` and execute correctly
306   - [ ] Agents trigger on appropriate scenarios
307   - [ ] Hooks activate on events (if applicable)
308   - [ ] MCP servers connect (if applicable)
309   - [ ] Settings files work (if applicable)
310 
3113. **Testing recommendations**:
312   - For skills: Ask questions using trigger phrases from descriptions
313   - For user-invoked skills: Run `/plugin-name:skill-name` with various arguments
314   - For agents: Create scenarios matching agent examples
315   - For hooks: Use `claude --debug` to see hook execution
316   - For MCP: Use `/mcp` to verify servers and tools
317 
3184. **Ask user**: "I've prepared the plugin for testing. Would you like me to guide you through testing each component, or do you want to test it yourself?"
319 
3205. **If user wants guidance**, walk through testing each component with specific test cases
321 
322**Output**: Plugin tested and verified working
323 
324---
325 
326## Phase 8: Documentation & Next Steps
327 
328**Goal**: Ensure plugin is well-documented and ready for distribution
329 
330**Actions**:
331 
3321. **Verify README completeness**:
333   - Check README has: overview, features, installation, prerequisites, usage
334   - For MCP plugins: Document required environment variables
335   - For hook plugins: Explain hook activation
336   - For settings: Provide configuration templates
337 
3382. **Add marketplace entry** (if publishing):
339   - Show user how to add to marketplace.json
340   - Help draft marketplace description
341   - Suggest category and tags
342 
3433. **Create summary**:
344   - Mark all todos complete
345   - List what was created:
346     - Plugin name and purpose
347     - Components created (X skills, Y agents, etc.)
348     - Key files and their purposes
349     - Total file count and structure
350   - Next steps:
351     - Testing recommendations
352     - Publishing to marketplace (if desired)
353     - Iteration based on usage
354 
3554. **Suggest improvements** (optional):
356   - Additional components that could enhance plugin
357   - Integration opportunities
358   - Testing strategies
359 
360**Output**: Complete, documented plugin ready for use or publication
361 
362---
363 
364## Important Notes
365 
366### Throughout All Phases
367 
368- **Use TodoWrite** to track progress at every phase
369- **Load skills with Skill tool** when working on specific component types
370- **Use specialized agents** (agent-creator, plugin-validator, skill-reviewer)
371- **Ask for user confirmation** at key decision points
372- **Follow plugin-dev's own patterns** as reference examples
373- **Apply best practices**:
374  - Third-person descriptions for skills
375  - Imperative form in skill bodies
376  - Skill instructions written FOR Claude (not TO user)
377  - Strong trigger phrases
378  - ${CLAUDE_PLUGIN_ROOT} for portability
379  - Progressive disclosure
380  - Security-first (HTTPS, no hardcoded credentials)
381 
382### Key Decision Points (Wait for User)
383 
3841. After Phase 1: Confirm plugin purpose
3852. After Phase 2: Approve component plan
3863. After Phase 3: Proceed to implementation
3874. After Phase 6: Fix issues or proceed
3885. After Phase 7: Continue to documentation
389 
390### Skills to Load by Phase
391 
392- **Phase 2**: plugin-structure
393- **Phase 5**: skill-development, agent-development, hook-development, mcp-integration, plugin-settings (as needed); command-development only for legacy `commands/` layout
394- **Phase 6**: (agents will use skills automatically)
395 
396### Quality Standards
397 
398Every component must meet these standards:
399 
400- ✅ Follows plugin-dev's proven patterns
401- ✅ Uses correct naming conventions
402- ✅ Has strong trigger conditions (skills/agents)
403- ✅ Includes working examples
404- ✅ Properly documented
405- ✅ Validated with utilities
406- ✅ Tested in Claude Code
407 
408---
409 
410## Example Workflow
411 
412### User Request
413 
414"Create a plugin for managing database migrations"
415 
416### Phase 1: Discovery
417 
418- Understand: Migration management, database schema versioning
419- Confirm: User wants to create, run, rollback migrations
420 
421### Phase 2: Component Planning
422 
423- Skills: 4 (migration best practices, create-migration, run-migrations, rollback)
424- Agents: 1 (migration-validator)
425- MCP: 1 (database connection)
426 
427### Phase 3: Clarifying Questions
428 
429- Which databases? (PostgreSQL, MySQL, etc.)
430- Migration file format? (SQL, code-based?)
431- Should agent validate before applying?
432- What MCP tools needed? (query, execute, schema)
433 
434### Phase 4-8: Implementation, Validation, Testing, Documentation
435 
436---
437 
438**Begin with Phase 1: Discovery**
439