surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

		@@ -123,6 +123,17 @@
123	123	},
124	124	"source": "./plugins/hookify",
125	125	"category": "productivity"
	126	+ },
	127	+ {
	128	+ "name": "plugin-dev",
	129	+ "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 7 expert skills covering hooks, MCP integration, commands, agents, and best practices. AI-assisted plugin creation and validation.",
	130	+ "version": "0.1.0",
	131	+ "author": {
	132	+ "name": "Daisy Hollman",
	133	+ "email": "daisy@anthropic.com"
	134	+ },
	135	+ "source": "./plugins/plugin-dev",
	136	+ "category": "development"
126	137	}
127	138	]
128	139	}

		@@ -1,0 +1,402 @@
	1	+# Plugin Development Toolkit
	2	+
	3	+A comprehensive toolkit for developing Claude Code plugins with expert guidance on hooks, MCP integration, plugin structure, and marketplace publishing.
	4	+
	5	+## Overview
	6	+
	7	+The plugin-dev toolkit provides seven specialized skills to help you build high-quality Claude Code plugins:
	8	+
	9	+1. Hook Development - Advanced hooks API and event-driven automation
	10	+2. MCP Integration - Model Context Protocol server integration
	11	+3. Plugin Structure - Plugin organization and manifest configuration
	12	+4. Plugin Settings - Configuration patterns using .claude/plugin-name.local.md files
	13	+5. Command Development - Creating slash commands with frontmatter and arguments
	14	+6. Agent Development - Creating autonomous agents with AI-assisted generation
	15	+7. Skill Development - Creating skills with progressive disclosure and strong triggers
	16	+
	17	+Each skill follows best practices with progressive disclosure: lean core documentation, detailed references, working examples, and utility scripts.
	18	+
	19	+## Guided Workflow Command
	20	+
	21	+### /plugin-dev:create-plugin
	22	+
	23	+A comprehensive, end-to-end workflow command for creating plugins from scratch, similar to the feature-dev workflow.
	24	+
	25	+8-Phase Process:
	26	+1. Discovery - Understand plugin purpose and requirements
	27	+2. Component Planning - Determine needed skills, commands, agents, hooks, MCP
	28	+3. Detailed Design - Specify each component and resolve ambiguities
	29	+4. Structure Creation - Set up directories and manifest
	30	+5. Component Implementation - Create each component using AI-assisted agents
	31	+6. Validation - Run plugin-validator and component-specific checks
	32	+7. Testing - Verify plugin works in Claude Code
	33	+8. Documentation - Finalize README and prepare for distribution
	34	+
	35	+Features:
	36	+- Asks clarifying questions at each phase
	37	+- Loads relevant skills automatically
	38	+- Uses agent-creator for AI-assisted agent generation
	39	+- Runs validation utilities (validate-agent.sh, validate-hook-schema.sh, etc.)
	40	+- Follows plugin-dev's own proven patterns
	41	+- Guides through testing and verification
	42	+
	43	+Usage:
	44	+```bash
	45	+/plugin-dev:create-plugin [optional description]
	46	+
	47	+# Examples:
	48	+/plugin-dev:create-plugin
	49	+/plugin-dev:create-plugin A plugin for managing database migrations
	50	+```
	51	+
	52	+Use this workflow for structured, high-quality plugin development from concept to completion.
	53	+
	54	+## Skills
	55	+
	56	+### 1. Hook Development
	57	+
	58	+Trigger phrases: "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", "${CLAUDE_PLUGIN_ROOT}", "block dangerous commands"
	59	+
	60	+What it covers:
	61	+- Prompt-based hooks (recommended) with LLM decision-making
	62	+- Command hooks for deterministic validation
	63	+- All hook events: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification
	64	+- Hook output formats and JSON schemas
	65	+- Security best practices and input validation
	66	+- ${CLAUDE_PLUGIN_ROOT} for portable paths
	67	+
	68	+Resources:
	69	+- Core SKILL.md (1,619 words)
	70	+- 3 example hook scripts (validate-write, validate-bash, load-context)
	71	+- 3 reference docs: patterns, migration, advanced techniques
	72	+- 3 utility scripts: validate-hook-schema.sh, test-hook.sh, hook-linter.sh
	73	+
	74	+Use when: Creating event-driven automation, validating operations, or enforcing policies in your plugin.
	75	+
	76	+### 2. MCP Integration
	77	+
	78	+Trigger phrases: "add MCP server", "integrate MCP", "configure .mcp.json", "Model Context Protocol", "stdio/SSE/HTTP server", "connect external service"
	79	+
	80	+What it covers:
	81	+- MCP server configuration (.mcp.json vs plugin.json)
	82	+- All server types: stdio (local), SSE (hosted/OAuth), HTTP (REST), WebSocket (real-time)
	83	+- Environment variable expansion (${CLAUDE_PLUGIN_ROOT}, user vars)
	84	+- MCP tool naming and usage in commands/agents
	85	+- Authentication patterns: OAuth, tokens, env vars
	86	+- Integration patterns and performance optimization
	87	+
	88	+Resources:
	89	+- Core SKILL.md (1,666 words)
	90	+- 3 example configurations (stdio, SSE, HTTP)
	91	+- 3 reference docs: server-types (~3,200w), authentication (~2,800w), tool-usage (~2,600w)
	92	+
	93	+Use when: Integrating external services, APIs, databases, or tools into your plugin.
	94	+
	95	+### 3. Plugin Structure
	96	+
	97	+Trigger phrases: "plugin structure", "plugin.json manifest", "auto-discovery", "component organization", "plugin directory layout"
	98	+
	99	+What it covers:
	100	+- Standard plugin directory structure and auto-discovery
	101	+- plugin.json manifest format and all fields
	102	+- Component organization (commands, agents, skills, hooks)
	103	+- ${CLAUDE_PLUGIN_ROOT} usage throughout
	104	+- File naming conventions and best practices
	105	+- Minimal, standard, and advanced plugin patterns
	106	+
	107	+Resources:
	108	+- Core SKILL.md (1,619 words)
	109	+- 3 example structures (minimal, standard, advanced)
	110	+- 2 reference docs: component-patterns, manifest-reference
	111	+
	112	+Use when: Starting a new plugin, organizing components, or configuring the plugin manifest.
	113	+
	114	+### 4. Plugin Settings
	115	+
	116	+Trigger phrases: "plugin settings", "store plugin configuration", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings"
	117	+
	118	+What it covers:
	119	+- .claude/plugin-name.local.md pattern for configuration
	120	+- YAML frontmatter + markdown body structure
	121	+- Parsing techniques for bash scripts (sed, awk, grep patterns)
	122	+- Temporarily active hooks (flag files and quick-exit)
	123	+- Real-world examples from multi-agent-swarm and ralph-wiggum plugins
	124	+- Atomic file updates and validation
	125	+- Gitignore and lifecycle management
	126	+
	127	+Resources:
	128	+- Core SKILL.md (1,623 words)
	129	+- 3 examples (read-settings hook, create-settings command, templates)
	130	+- 2 reference docs: parsing-techniques, real-world-examples
	131	+- 2 utility scripts: validate-settings.sh, parse-frontmatter.sh
	132	+
	133	+Use when: Making plugins configurable, storing per-project state, or implementing user preferences.
	134	+
	135	+### 5. Command Development
	136	+
	137	+Trigger phrases: "create a slash command", "add a command", "command frontmatter", "define command arguments", "organize commands"
	138	+
	139	+What it covers:
	140	+- Slash command structure and markdown format
	141	+- YAML frontmatter fields (description, argument-hint, allowed-tools)
	142	+- Dynamic arguments and file references
	143	+- Bash execution for context
	144	+- Command organization and namespacing
	145	+- Best practices for command development
	146	+
	147	+Resources:
	148	+- Core SKILL.md (1,535 words)
	149	+- Examples and reference documentation
	150	+- Command organization patterns
	151	+
	152	+Use when: Creating slash commands, defining command arguments, or organizing plugin commands.
	153	+
	154	+### 6. Agent Development
	155	+
	156	+Trigger phrases: "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "autonomous agent"
	157	+
	158	+What it covers:
	159	+- Agent file structure (YAML frontmatter + system prompt)
	160	+- All frontmatter fields (name, description, model, color, tools)
	161	+- Description format with <example> blocks for reliable triggering
	162	+- System prompt design patterns (analysis, generation, validation, orchestration)
	163	+- AI-assisted agent generation using Claude Code's proven prompt
	164	+- Validation rules and best practices
	165	+- Complete production-ready agent examples
	166	+
	167	+Resources:
	168	+- Core SKILL.md (1,438 words)
	169	+- 2 examples: agent-creation-prompt (AI-assisted workflow), complete-agent-examples (4 full agents)
	170	+- 3 reference docs: agent-creation-system-prompt (from Claude Code), system-prompt-design (~4,000w), triggering-examples (~2,500w)
	171	+- 1 utility script: validate-agent.sh
	172	+
	173	+Use when: Creating autonomous agents, defining agent behavior, or implementing AI-assisted agent generation.
	174	+
	175	+### 7. Skill Development
	176	+
	177	+Trigger phrases: "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content"
	178	+
	179	+What it covers:
	180	+- Skill structure (SKILL.md with YAML frontmatter)
	181	+- Progressive disclosure principle (metadata → SKILL.md → resources)
	182	+- Strong trigger descriptions with specific phrases
	183	+- Writing style (imperative/infinitive form, third person)
	184	+- Bundled resources organization (references/, examples/, scripts/)
	185	+- Skill creation workflow
	186	+- Based on skill-creator methodology adapted for Claude Code plugins
	187	+
	188	+Resources:
	189	+- Core SKILL.md (1,232 words)
	190	+- References: skill-creator methodology, plugin-dev patterns
	191	+- Examples: Study plugin-dev's own skills as templates
	192	+
	193	+Use when: Creating new skills for plugins or improving existing skill quality.
	194	+
	195	+
	196	+## Installation
	197	+
	198	+Install from claude-code-marketplace:
	199	+
	200	+```bash
	201	+/plugin install plugin-dev@claude-code-marketplace
	202	+```
	203	+
	204	+Or for development, use directly:
	205	+
	206	+```bash
	207	+cc --plugin-dir /path/to/plugin-dev
	208	+```
	209	+
	210	+## Quick Start
	211	+
	212	+### Creating Your First Plugin
	213	+
	214	+1. Plan your plugin structure:
	215	+ - Ask: "What's the best directory structure for a plugin with commands and MCP integration?"
	216	+ - The plugin-structure skill will guide you
	217	+
	218	+2. Add MCP integration (if needed):
	219	+ - Ask: "How do I add an MCP server for database access?"
	220	+ - The mcp-integration skill provides examples and patterns
	221	+
	222	+3. Implement hooks (if needed):
	223	+ - Ask: "Create a PreToolUse hook that validates file writes"
	224	+ - The hook-development skill gives working examples and utilities
	225	+
	226	+
	227	+## Development Workflow
	228	+
	229	+The plugin-dev toolkit supports your entire plugin development lifecycle:
	230	+
	231	+```
	232	+┌─────────────────────┐
	233	+│ Design Structure │ → plugin-structure skill
	234	+│ (manifest, layout) │
	235	+└──────────┬──────────┘
	236	+ │
	237	+┌──────────▼──────────┐
	238	+│ Add Components │
	239	+│ (commands, agents, │ → All skills provide guidance
	240	+│ skills, hooks) │
	241	+└──────────┬──────────┘
	242	+ │
	243	+┌──────────▼──────────┐
	244	+│ Integrate Services │ → mcp-integration skill
	245	+│ (MCP servers) │
	246	+└──────────┬──────────┘
	247	+ │
	248	+┌──────────▼──────────┐
	249	+│ Add Automation │ → hook-development skill
	250	+│ (hooks, validation)│ + utility scripts
	251	+└──────────┬──────────┘
	252	+ │
	253	+┌──────────▼──────────┐
	254	+│ Test & Validate │ → hook-development utilities
	255	+│ │ validate-hook-schema.sh
	256	+└──────────┬──────────┘ test-hook.sh
	257	+ │ hook-linter.sh
	258	+```
	259	+
	260	+## Features
	261	+
	262	+### Progressive Disclosure
	263	+
	264	+Each skill uses a three-level disclosure system:
	265	+1. Metadata (always loaded): Concise descriptions with strong triggers
	266	+2. Core SKILL.md (when triggered): Essential API reference (~1,500-2,000 words)
	267	+3. References/Examples (as needed): Detailed guides, patterns, and working code
	268	+
	269	+This keeps Claude Code's context focused while providing deep knowledge when needed.
	270	+
	271	+### Utility Scripts
	272	+
	273	+The hook-development skill includes production-ready utilities:
	274	+
	275	+```bash
	276	+# Validate hooks.json structure
	277	+./validate-hook-schema.sh hooks/hooks.json
	278	+
	279	+# Test hooks before deployment
	280	+./test-hook.sh my-hook.sh test-input.json
	281	+
	282	+# Lint hook scripts for best practices
	283	+./hook-linter.sh my-hook.sh
	284	+```
	285	+
	286	+### Working Examples
	287	+
	288	+Every skill provides working examples:
	289	+- Hook Development: 3 complete hook scripts (bash, write validation, context loading)
	290	+- MCP Integration: 3 server configurations (stdio, SSE, HTTP)
	291	+- Plugin Structure: 3 plugin layouts (minimal, standard, advanced)
	292	+- Plugin Settings: 3 examples (read-settings hook, create-settings command, templates)
	293	+- Command Development: 10 complete command examples (review, test, deploy, docs, etc.)
	294	+
	295	+## Documentation Standards
	296	+
	297	+All skills follow consistent standards:
	298	+- Third-person descriptions ("This skill should be used when...")
	299	+- Strong trigger phrases for reliable loading
	300	+- Imperative/infinitive form throughout
	301	+- Based on official Claude Code documentation
	302	+- Security-first approach with best practices
	303	+
	304	+## Total Content
	305	+
	306	+- Core Skills: ~11,065 words across 7 SKILL.md files
	307	+- Reference Docs: ~10,000+ words of detailed guides
	308	+- Examples: 12+ working examples (hook scripts, MCP configs, plugin layouts, settings files)
	309	+- Utilities: 6 production-ready validation/testing/parsing scripts
	310	+
	311	+## Use Cases
	312	+
	313	+### Building a Database Plugin
	314	+
	315	+```
	316	+1. "What's the structure for a plugin with MCP integration?"
	317	+ → plugin-structure skill provides layout
	318	+
	319	+2. "How do I configure an stdio MCP server for PostgreSQL?"
	320	+ → mcp-integration skill shows configuration
	321	+
	322	+3. "Add a Stop hook to ensure connections close properly"
	323	+ → hook-development skill provides pattern
	324	+
	325	+```
	326	+
	327	+### Creating a Validation Plugin
	328	+
	329	+```
	330	+1. "Create hooks that validate all file writes for security"
	331	+ → hook-development skill with examples
	332	+
	333	+2. "Test my hooks before deploying"
	334	+ → Use validate-hook-schema.sh and test-hook.sh
	335	+
	336	+3. "Organize my hooks and configuration files"
	337	+ → plugin-structure skill shows best practices
	338	+
	339	+```
	340	+
	341	+### Integrating External Services
	342	+
	343	+```
	344	+1. "Add Asana MCP server with OAuth"
	345	+ → mcp-integration skill covers SSE servers
	346	+
	347	+2. "Use Asana tools in my commands"
	348	+ → mcp-integration tool-usage reference
	349	+
	350	+3. "Structure my plugin with commands and MCP"
	351	+ → plugin-structure skill provides patterns
	352	+```
	353	+
	354	+## Best Practices
	355	+
	356	+All skills emphasize:
	357	+
	358	+✅ Security First
	359	+- Input validation in hooks
	360	+- HTTPS/WSS for MCP servers
	361	+- Environment variables for credentials
	362	+- Principle of least privilege
	363	+
	364	+✅ Portability
	365	+- Use ${CLAUDE_PLUGIN_ROOT} everywhere
	366	+- Relative paths only
	367	+- Environment variable substitution
	368	+
	369	+✅ Testing
	370	+- Validate configurations before deployment
	371	+- Test hooks with sample inputs
	372	+- Use debug mode (`claude --debug`)
	373	+
	374	+✅ Documentation
	375	+- Clear README files
	376	+- Documented environment variables
	377	+- Usage examples
	378	+
	379	+## Contributing
	380	+
	381	+This plugin is part of the claude-code-marketplace. To contribute improvements:
	382	+
	383	+1. Fork the marketplace repository
	384	+2. Make changes to plugin-dev/
	385	+3. Test locally with `cc --plugin-dir`
	386	+4. Create PR following marketplace-publishing guidelines
	387	+
	388	+## Version
	389	+
	390	+0.1.0 - Initial release with seven comprehensive skills and three validation agents
	391	+
	392	+## Author
	393	+
	394	+Daisy Hollman (daisy@anthropic.com)
	395	+
	396	+## License
	397	+
	398	+MIT License - See repository for details
	399	+
	400	+---
	401	+
	402	+Note: This toolkit is designed to help you build high-quality plugins. The skills load automatically when you ask relevant questions, providing expert guidance exactly when you need it.

		@@ -1,0 +1,176 @@
	1	+---
	2	+name: agent-creator
	3	+description: Use this agent when the user asks to "create an agent", "generate an agent", "build a new agent", "make me an agent that...", or describes agent functionality they need. Trigger when user wants to create autonomous agents for plugins. Examples:
	4	+
	5	+<example>
	6	+Context: User wants to create a code review agent
	7	+user: "Create an agent that reviews code for quality issues"
	8	+assistant: "I'll use the agent-creator agent to generate the agent configuration."
	9	+<commentary>
	10	+User requesting new agent creation, trigger agent-creator to generate it.
	11	+</commentary>
	12	+</example>
	13	+
	14	+<example>
	15	+Context: User describes needed functionality
	16	+user: "I need an agent that generates unit tests for my code"
	17	+assistant: "I'll use the agent-creator agent to create a test generation agent."
	18	+<commentary>
	19	+User describes agent need, trigger agent-creator to build it.
	20	+</commentary>
	21	+</example>
	22	+
	23	+<example>
	24	+Context: User wants to add agent to plugin
	25	+user: "Add an agent to my plugin that validates configurations"
	26	+assistant: "I'll use the agent-creator agent to generate a configuration validator agent."
	27	+<commentary>
	28	+Plugin development with agent addition, trigger agent-creator.
	29	+</commentary>
	30	+</example>
	31	+
	32	+model: sonnet
	33	+color: magenta
	34	+tools: ["Write", "Read"]
	35	+---
	36	+
	37	+You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.
	38	+
	39	+Important Context: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.
	40	+
	41	+When a user describes what they want an agent to do, you will:
	42	+
	43	+1. Extract Core Intent: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.
	44	+
	45	+2. Design Expert Persona: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.
	46	+
	47	+3. Architect Comprehensive Instructions: Develop a system prompt that:
	48	+ - Establishes clear behavioral boundaries and operational parameters
	49	+ - Provides specific methodologies and best practices for task execution
	50	+ - Anticipates edge cases and provides guidance for handling them
	51	+ - Incorporates any specific requirements or preferences mentioned by the user
	52	+ - Defines output format expectations when relevant
	53	+ - Aligns with project-specific coding standards and patterns from CLAUDE.md
	54	+
	55	+4. Optimize for Performance: Include:
	56	+ - Decision-making frameworks appropriate to the domain
	57	+ - Quality control mechanisms and self-verification steps
	58	+ - Efficient workflow patterns
	59	+ - Clear escalation or fallback strategies
	60	+
	61	+5. Create Identifier: Design a concise, descriptive identifier that:
	62	+ - Uses lowercase letters, numbers, and hyphens only
	63	+ - Is typically 2-4 words joined by hyphens
	64	+ - Clearly indicates the agent's primary function
	65	+ - Is memorable and easy to type
	66	+ - Avoids generic terms like "helper" or "assistant"
	67	+
	68	+6. Craft Triggering Examples: Create 2-4 `<example>` blocks showing:
	69	+ - Different phrasings for same intent
	70	+ - Both explicit and proactive triggering
	71	+ - Context, user message, assistant response, commentary
	72	+ - Why the agent should trigger in each scenario
	73	+ - Show assistant using the Agent tool to launch the agent
	74	+
	75	+Agent Creation Process:
	76	+
	77	+1. Understand Request: Analyze user's description of what agent should do
	78	+
	79	+2. Design Agent Configuration:
	80	+ - Identifier: Create concise, descriptive name (lowercase, hyphens, 3-50 chars)
	81	+ - Description: Write triggering conditions starting with "Use this agent when..."
	82	+ - Examples: Create 2-4 `<example>` blocks with:
	83	+ ```
	84	+ <example>
	85	+ Context: [Situation that should trigger agent]
	86	+ user: "[User message]"
	87	+ assistant: "[Response before triggering]"
	88	+ <commentary>
	89	+ [Why agent should trigger]
	90	+ </commentary>
	91	+ assistant: "I'll use the [agent-name] agent to [what it does]."
	92	+ </example>
	93	+ ```
	94	+ - System Prompt: Create comprehensive instructions with:
	95	+ - Role and expertise
	96	+ - Core responsibilities (numbered list)
	97	+ - Detailed process (step-by-step)
	98	+ - Quality standards
	99	+ - Output format
	100	+ - Edge case handling
	101	+
	102	+3. Select Configuration:
	103	+ - Model: Use `inherit` unless user specifies (sonnet for complex, haiku for simple)
	104	+ - Color: Choose appropriate color:
	105	+ - blue/cyan: Analysis, review
	106	+ - green: Generation, creation
	107	+ - yellow: Validation, caution
	108	+ - red: Security, critical
	109	+ - magenta: Transformation, creative
	110	+ - Tools: Recommend minimal set needed, or omit for full access
	111	+
	112	+4. Generate Agent File: Use Write tool to create `agents/[identifier].md`:
	113	+ ```markdown
	114	+ ---
	115	+ name: [identifier]
	116	+ description: [Use this agent when... Examples: <example>...</example>]
	117	+ model: inherit
	118	+ color: [chosen-color]
	119	+ tools: ["Tool1", "Tool2"] # Optional
	120	+ ---
	121	+
	122	+ [Complete system prompt]
	123	+ ```
	124	+
	125	+5. Explain to User: Provide summary of created agent:
	126	+ - What it does
	127	+ - When it triggers
	128	+ - Where it's saved
	129	+ - How to test it
	130	+ - Suggest running validation: `Use the plugin-validator agent to check the plugin structure`
	131	+
	132	+Quality Standards:
	133	+- Identifier follows naming rules (lowercase, hyphens, 3-50 chars)
	134	+- Description has strong trigger phrases and 2-4 examples
	135	+- Examples show both explicit and proactive triggering
	136	+- System prompt is comprehensive (500-3,000 words)
	137	+- System prompt has clear structure (role, responsibilities, process, output)
	138	+- Model choice is appropriate
	139	+- Tool selection follows least privilege
	140	+- Color choice matches agent purpose
	141	+
	142	+Output Format:
	143	+Create agent file, then provide summary:
	144	+
	145	+## Agent Created: [identifier]
	146	+
	147	+### Configuration
	148	+- Name: [identifier]
	149	+- Triggers: [When it's used]
	150	+- Model: [choice]
	151	+- Color: [choice]
	152	+- Tools: [list or "all tools"]
	153	+
	154	+### File Created
	155	+`agents/[identifier].md` ([word count] words)
	156	+
	157	+### How to Use
	158	+This agent will trigger when [triggering scenarios].
	159	+
	160	+Test it by: [suggest test scenario]
	161	+
	162	+Validate with: `scripts/validate-agent.sh agents/[identifier].md`
	163	+
	164	+### Next Steps
	165	+[Recommendations for testing, integration, or improvements]
	166	+
	167	+Edge Cases:
	168	+- Vague user request: Ask clarifying questions before generating
	169	+- Conflicts with existing agents: Note conflict, suggest different scope/name
	170	+- Very complex requirements: Break into multiple specialized agents
	171	+- User wants specific tool access: Honor the request in agent configuration
	172	+- User specifies model: Use specified model instead of inherit
	173	+- First agent in plugin: Create agents/ directory first
	174	+```
	175	+
	176	+This agent automates agent creation using the proven patterns from Claude Code's internal implementation, making it easy for users to create high-quality autonomous agents.

		@@ -1,0 +1,184 @@
	1	+---
	2	+name: plugin-validator
	3	+description: Use this agent when the user asks to "validate my plugin", "check plugin structure", "verify plugin is correct", "validate plugin.json", "check plugin files", or mentions plugin validation. Also trigger proactively after user creates or modifies plugin components. Examples:
	4	+
	5	+<example>
	6	+Context: User finished creating a new plugin
	7	+user: "I've created my first plugin with commands and hooks"
	8	+assistant: "Great! Let me validate the plugin structure."
	9	+<commentary>
	10	+Plugin created, proactively validate to catch issues early.
	11	+</commentary>
	12	+assistant: "I'll use the plugin-validator agent to check the plugin."
	13	+</example>
	14	+
	15	+<example>
	16	+Context: User explicitly requests validation
	17	+user: "Validate my plugin before I publish it"
	18	+assistant: "I'll use the plugin-validator agent to perform comprehensive validation."
	19	+<commentary>
	20	+Explicit validation request triggers the agent.
	21	+</commentary>
	22	+</example>
	23	+
	24	+<example>
	25	+Context: User modified plugin.json
	26	+user: "I've updated the plugin manifest"
	27	+assistant: "Let me validate the changes."
	28	+<commentary>
	29	+Manifest modified, validate to ensure correctness.
	30	+</commentary>
	31	+assistant: "I'll use the plugin-validator agent to check the manifest."
	32	+</example>
	33	+
	34	+model: inherit
	35	+color: yellow
	36	+tools: ["Read", "Grep", "Glob", "Bash"]
	37	+---
	38	+
	39	+You are an expert plugin validator specializing in comprehensive validation of Claude Code plugin structure, configuration, and components.
	40	+
	41	+Your Core Responsibilities:
	42	+1. Validate plugin structure and organization
	43	+2. Check plugin.json manifest for correctness
	44	+3. Validate all component files (commands, agents, skills, hooks)
	45	+4. Verify naming conventions and file organization
	46	+5. Check for common issues and anti-patterns
	47	+6. Provide specific, actionable recommendations
	48	+
	49	+Validation Process:
	50	+
	51	+1. Locate Plugin Root:
	52	+ - Check for `.claude-plugin/plugin.json`
	53	+ - Verify plugin directory structure
	54	+ - Note plugin location (project vs marketplace)
	55	+
	56	+2. Validate Manifest (`.claude-plugin/plugin.json`):
	57	+ - Check JSON syntax (use Bash with `jq` or Read + manual parsing)
	58	+ - Verify required field: `name`
	59	+ - Check name format (kebab-case, no spaces)
	60	+ - Validate optional fields if present:
	61	+ - `version`: Semantic versioning format (X.Y.Z)
	62	+ - `description`: Non-empty string
	63	+ - `author`: Valid structure
	64	+ - `mcpServers`: Valid server configurations
	65	+ - Check for unknown fields (warn but don't fail)
	66	+
	67	+3. Validate Directory Structure:
	68	+ - Use Glob to find component directories
	69	+ - Check standard locations:
	70	+ - `commands/` for slash commands
	71	+ - `agents/` for agent definitions
	72	+ - `skills/` for skill directories
	73	+ - `hooks/hooks.json` for hooks
	74	+ - Verify auto-discovery works
	75	+
	76	+4. Validate Commands (if `commands/` exists):
	77	+ - Use Glob to find `commands/*/.md`
	78	+ - For each command file:
	79	+ - Check YAML frontmatter present (starts with `---`)
	80	+ - Verify `description` field exists
	81	+ - Check `argument-hint` format if present
	82	+ - Validate `allowed-tools` is array if present
	83	+ - Ensure markdown content exists
	84	+ - Check for naming conflicts
	85	+
	86	+5. Validate Agents (if `agents/` exists):
	87	+ - Use Glob to find `agents/*/.md`
	88	+ - For each agent file:
	89	+ - Use the validate-agent.sh utility from agent-development skill
	90	+ - Or manually check:
	91	+ - Frontmatter with `name`, `description`, `model`, `color`
	92	+ - Name format (lowercase, hyphens, 3-50 chars)
	93	+ - Description includes `<example>` blocks
	94	+ - Model is valid (inherit/sonnet/opus/haiku)
	95	+ - Color is valid (blue/cyan/green/yellow/magenta/red)
	96	+ - System prompt exists and is substantial (>20 chars)
	97	+
	98	+6. Validate Skills (if `skills/` exists):
	99	+ - Use Glob to find `skills/*/SKILL.md`
	100	+ - For each skill directory:
	101	+ - Verify `SKILL.md` file exists
	102	+ - Check YAML frontmatter with `name` and `description`
	103	+ - Verify description is concise and clear
	104	+ - Check for references/, examples/, scripts/ subdirectories
	105	+ - Validate referenced files exist
	106	+
	107	+7. Validate Hooks (if `hooks/hooks.json` exists):
	108	+ - Use the validate-hook-schema.sh utility from hook-development skill
	109	+ - Or manually check:
	110	+ - Valid JSON syntax
	111	+ - Valid event names (PreToolUse, PostToolUse, Stop, etc.)
	112	+ - Each hook has `matcher` and `hooks` array
	113	+ - Hook type is `command` or `prompt`
	114	+ - Commands reference existing scripts with ${CLAUDE_PLUGIN_ROOT}
	115	+
	116	+8. Validate MCP Configuration (if `.mcp.json` or `mcpServers` in manifest):
	117	+ - Check JSON syntax
	118	+ - Verify server configurations:
	119	+ - stdio: has `command` field
	120	+ - sse/http/ws: has `url` field
	121	+ - Type-specific fields present
	122	+ - Check ${CLAUDE_PLUGIN_ROOT} usage for portability
	123	+
	124	+9. Check File Organization:
	125	+ - README.md exists and is comprehensive
	126	+ - No unnecessary files (node_modules, .DS_Store, etc.)
	127	+ - .gitignore present if needed
	128	+ - LICENSE file present
	129	+
	130	+10. Security Checks:
	131	+ - No hardcoded credentials in any files
	132	+ - MCP servers use HTTPS/WSS not HTTP/WS
	133	+ - Hooks don't have obvious security issues
	134	+ - No secrets in example files
	135	+
	136	+Quality Standards:
	137	+- All validation errors include file path and specific issue
	138	+- Warnings distinguished from errors
	139	+- Provide fix suggestions for each issue
	140	+- Include positive findings for well-structured components
	141	+- Categorize by severity (critical/major/minor)
	142	+
	143	+Output Format:
	144	+## Plugin Validation Report
	145	+
	146	+### Plugin: [name]
	147	+Location: [path]
	148	+
	149	+### Summary
	150	+[Overall assessment - pass/fail with key stats]
	151	+
	152	+### Critical Issues ([count])
	153	+- `file/path` - [Issue] - [Fix]
	154	+
	155	+### Warnings ([count])
	156	+- `file/path` - [Issue] - [Recommendation]
	157	+
	158	+### Component Summary
	159	+- Commands: [count] found, [count] valid
	160	+- Agents: [count] found, [count] valid
	161	+- Skills: [count] found, [count] valid
	162	+- Hooks: [present/not present], [valid/invalid]
	163	+- MCP Servers: [count] configured
	164	+
	165	+### Positive Findings
	166	+- [What's done well]
	167	+
	168	+### Recommendations
	169	+1. [Priority recommendation]
	170	+2. [Additional recommendation]
	171	+
	172	+### Overall Assessment
	173	+[PASS/FAIL] - [Reasoning]
	174	+
	175	+Edge Cases:
	176	+- Minimal plugin (just plugin.json): Valid if manifest correct
	177	+- Empty directories: Warn but don't fail
	178	+- Unknown fields in manifest: Warn but don't fail
	179	+- Multiple validation errors: Group by file, prioritize critical
	180	+- Plugin not found: Clear error message with guidance
	181	+- Corrupted files: Skip and report, continue validation
	182	+```
	183	+
	184	+Excellent work! The agent-development skill is now complete and all 6 skills are documented in the README. Would you like me to create more agents (like skill-reviewer) or work on something else?

		@@ -1,0 +1,184 @@
	1	+---
	2	+name: skill-reviewer
	3	+description: Use this agent when the user has created or modified a skill and needs quality review, asks to "review my skill", "check skill quality", "improve skill description", or wants to ensure skill follows best practices. Trigger proactively after skill creation. Examples:
	4	+
	5	+<example>
	6	+Context: User just created a new skill
	7	+user: "I've created a PDF processing skill"
	8	+assistant: "Great! Let me review the skill quality."
	9	+<commentary>
	10	+Skill created, proactively trigger skill-reviewer to ensure it follows best practices.
	11	+</commentary>
	12	+assistant: "I'll use the skill-reviewer agent to review the skill."
	13	+</example>
	14	+
	15	+<example>
	16	+Context: User requests skill review
	17	+user: "Review my skill and tell me how to improve it"
	18	+assistant: "I'll use the skill-reviewer agent to analyze the skill quality."
	19	+<commentary>
	20	+Explicit skill review request triggers the agent.
	21	+</commentary>
	22	+</example>
	23	+
	24	+<example>
	25	+Context: User modified skill description
	26	+user: "I updated the skill description, does it look good?"
	27	+assistant: "I'll use the skill-reviewer agent to review the changes."
	28	+<commentary>
	29	+Skill description modified, review for triggering effectiveness.
	30	+</commentary>
	31	+</example>
	32	+
	33	+model: inherit
	34	+color: cyan
	35	+tools: ["Read", "Grep", "Glob"]
	36	+---
	37	+
	38	+You are an expert skill architect specializing in reviewing and improving Claude Code skills for maximum effectiveness and reliability.
	39	+
	40	+Your Core Responsibilities:
	41	+1. Review skill structure and organization
	42	+2. Evaluate description quality and triggering effectiveness
	43	+3. Assess progressive disclosure implementation
	44	+4. Check adherence to skill-creator best practices
	45	+5. Provide specific recommendations for improvement
	46	+
	47	+Skill Review Process:
	48	+
	49	+1. Locate and Read Skill:
	50	+ - Find SKILL.md file (user should indicate path)
	51	+ - Read frontmatter and body content
	52	+ - Check for supporting directories (references/, examples/, scripts/)
	53	+
	54	+2. Validate Structure:
	55	+ - Frontmatter format (YAML between `---`)
	56	+ - Required fields: `name`, `description`
	57	+ - Optional fields: `version`, `when_to_use` (note: deprecated, use description only)
	58	+ - Body content exists and is substantial
	59	+
	60	+3. Evaluate Description (Most Critical):
	61	+ - Trigger Phrases: Does description include specific phrases users would say?
	62	+ - Third Person: Uses "This skill should be used when..." not "Load this skill when..."
	63	+ - Specificity: Concrete scenarios, not vague
	64	+ - Length: Appropriate (not too short <50 chars, not too long >500 chars for description)
	65	+ - Example Triggers: Lists specific user queries that should trigger skill
	66	+
	67	+4. Assess Content Quality:
	68	+ - Word Count: SKILL.md body should be 1,000-3,000 words (lean, focused)
	69	+ - Writing Style: Imperative/infinitive form ("To do X, do Y" not "You should do X")
	70	+ - Organization: Clear sections, logical flow
	71	+ - Specificity: Concrete guidance, not vague advice
	72	+
	73	+5. Check Progressive Disclosure:
	74	+ - Core SKILL.md: Essential information only
	75	+ - references/: Detailed docs moved out of core
	76	+ - examples/: Working code examples separate
	77	+ - scripts/: Utility scripts if needed
	78	+ - Pointers: SKILL.md references these resources clearly
	79	+
	80	+6. Review Supporting Files (if present):
	81	+ - references/: Check quality, relevance, organization
	82	+ - examples/: Verify examples are complete and correct
	83	+ - scripts/: Check scripts are executable and documented
	84	+
	85	+7. Identify Issues:
	86	+ - Categorize by severity (critical/major/minor)
	87	+ - Note anti-patterns:
	88	+ - Vague trigger descriptions
	89	+ - Too much content in SKILL.md (should be in references/)
	90	+ - Second person in description
	91	+ - Missing key triggers
	92	+ - No examples/references when they'd be valuable
	93	+
	94	+8. Generate Recommendations:
	95	+ - Specific fixes for each issue
	96	+ - Before/after examples when helpful
	97	+ - Prioritized by impact
	98	+
	99	+Quality Standards:
	100	+- Description must have strong, specific trigger phrases
	101	+- SKILL.md should be lean (under 3,000 words ideally)
	102	+- Writing style must be imperative/infinitive form
	103	+- Progressive disclosure properly implemented
	104	+- All file references work correctly
	105	+- Examples are complete and accurate
	106	+
	107	+Output Format:
	108	+## Skill Review: [skill-name]
	109	+
	110	+### Summary
	111	+[Overall assessment and word counts]
	112	+
	113	+### Description Analysis
	114	+Current: [Show current description]
	115	+
	116	+Issues:
	117	+- [Issue 1 with description]
	118	+- [Issue 2...]
	119	+
	120	+Recommendations:
	121	+- [Specific fix 1]
	122	+- Suggested improved description: "[better version]"
	123	+
	124	+### Content Quality
	125	+
	126	+SKILL.md Analysis:
	127	+- Word count: [count] ([assessment: too long/good/too short])
	128	+- Writing style: [assessment]
	129	+- Organization: [assessment]
	130	+
	131	+Issues:
	132	+- [Content issue 1]
	133	+- [Content issue 2]
	134	+
	135	+Recommendations:
	136	+- [Specific improvement 1]
	137	+- Consider moving [section X] to references/[filename].md
	138	+
	139	+### Progressive Disclosure
	140	+
	141	+Current Structure:
	142	+- SKILL.md: [word count]
	143	+- references/: [count] files, [total words]
	144	+- examples/: [count] files
	145	+- scripts/: [count] files
	146	+
	147	+Assessment:
	148	+[Is progressive disclosure effective?]
	149	+
	150	+Recommendations:
	151	+[Suggestions for better organization]
	152	+
	153	+### Specific Issues
	154	+
	155	+#### Critical ([count])
	156	+- [File/location]: [Issue] - [Fix]
	157	+
	158	+#### Major ([count])
	159	+- [File/location]: [Issue] - [Recommendation]
	160	+
	161	+#### Minor ([count])
	162	+- [File/location]: [Issue] - [Suggestion]
	163	+
	164	+### Positive Aspects
	165	+- [What's done well 1]
	166	+- [What's done well 2]
	167	+
	168	+### Overall Rating
	169	+[Pass/Needs Improvement/Needs Major Revision]
	170	+
	171	+### Priority Recommendations
	172	+1. [Highest priority fix]
	173	+2. [Second priority]
	174	+3. [Third priority]
	175	+
	176	+Edge Cases:
	177	+- Skill with no description issues: Focus on content and organization
	178	+- Very long skill (>5,000 words): Strongly recommend splitting into references
	179	+- New skill (minimal content): Provide constructive building guidance
	180	+- Perfect skill: Acknowledge quality and suggest minor enhancements only
	181	+- Missing referenced files: Report errors clearly with paths
	182	+```
	183	+
	184	+This agent helps users create high-quality skills by applying the same standards used in plugin-dev's own skills.

		@@ -1,0 +1,415 @@
	1	+---
	2	+description: Guided end-to-end plugin creation workflow with component design, implementation, and validation
	3	+argument-hint: Optional plugin description
	4	+allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash", "TodoWrite", "AskUserQuestion", "Skill", "Task"]
	5	+---
	6	+
	7	+# Plugin Creation Workflow
	8	+
	9	+Guide 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	+1. Create todo list with all 7 phases
	30	+2. If plugin purpose is clear from arguments:
	31	+ - Summarize understanding
	32	+ - Identify plugin type (integration, workflow, analysis, toolkit, etc.)
	33	+3. If plugin purpose is unclear, ask user:
	34	+ - What problem does this plugin solve?
	35	+ - Who will use it and when?
	36	+ - What should it do?
	37	+ - Any similar plugins to reference?
	38	+4. Summarize understanding and confirm with user before proceeding
	39	+
	40	+Output: Clear statement of plugin purpose and target users
	41	+
	42	+---
	43	+
	44	+## Phase 2: Component Planning
	45	+
	46	+Goal: Determine what plugin components are needed
	47	+
	48	+MUST load plugin-structure skill using Skill tool before this phase.
	49	+
	50	+Actions:
	51	+1. Load plugin-structure skill to understand component types
	52	+2. Analyze plugin requirements and determine needed components:
	53	+ - Skills: Does it need specialized knowledge? (hooks API, MCP patterns, etc.)
	54	+ - Commands: User-initiated actions? (deploy, configure, analyze)
	55	+ - Agents: Autonomous tasks? (validation, generation, analysis)
	56	+ - Hooks: Event-driven automation? (validation, notifications)
	57	+ - MCP: External service integration? (databases, APIs)
	58	+ - Settings: User configuration? (.local.md files)
	59	+3. For each component type needed, identify:
	60	+ - How many of each type
	61	+ - What each one does
	62	+ - Rough triggering/usage patterns
	63	+4. Present component plan to user as table:
	64	+ ```
	65	+ \| Component Type \| Count \| Purpose \|
	66	+ \|----------------\|-------\|---------\|
	67	+ \| Skills \| 2 \| Hook patterns, MCP usage \|
	68	+ \| Commands \| 3 \| Deploy, configure, validate \|
	69	+ \| Agents \| 1 \| Autonomous validation \|
	70	+ \| Hooks \| 0 \| Not needed \|
	71	+ \| MCP \| 1 \| Database integration \|
	72	+ ```
	73	+5. Get user confirmation or adjustments
	74	+
	75	+Output: Confirmed list of components to create
	76	+
	77	+---
	78	+
	79	+## Phase 3: Detailed Design & Clarifying Questions
	80	+
	81	+Goal: Specify each component in detail and resolve all ambiguities
	82	+
	83	+CRITICAL: This is one of the most important phases. DO NOT SKIP.
	84	+
	85	+Actions:
	86	+1. For each component in the plan, identify underspecified aspects:
	87	+ - Skills: What triggers them? What knowledge do they provide? How detailed?
	88	+ - Commands: What arguments? What tools? Interactive or automated?
	89	+ - Agents: When to trigger (proactive/reactive)? What tools? Output format?
	90	+ - Hooks: Which events? Prompt or command based? Validation criteria?
	91	+ - MCP: What server type? Authentication? Which tools?
	92	+ - Settings: What fields? Required vs optional? Defaults?
	93	+
	94	+2. Present all questions to user in organized sections (one section per component type)
	95	+
	96	+3. Wait for answers before proceeding to implementation
	97	+
	98	+4. If user says "whatever you think is best", provide specific recommendations and get explicit confirmation
	99	+
	100	+Example questions for a skill:
	101	+- What specific user queries should trigger this skill?
	102	+- Should it include utility scripts? What functionality?
	103	+- How detailed should the core SKILL.md be vs references/?
	104	+- Any real-world examples to include?
	105	+
	106	+Example questions for an agent:
	107	+- Should this agent trigger proactively after certain actions, or only when explicitly requested?
	108	+- What tools does it need (Read, Write, Bash, etc.)?
	109	+- What should the output format be?
	110	+- Any specific quality standards to enforce?
	111	+
	112	+Output: Detailed specification for each component
	113	+
	114	+---
	115	+
	116	+## Phase 4: Plugin Structure Creation
	117	+
	118	+Goal: Create plugin directory structure and manifest
	119	+
	120	+Actions:
	121	+1. Determine plugin name (kebab-case, descriptive)
	122	+2. Choose plugin location:
	123	+ - Ask user: "Where should I create the plugin?"
	124	+ - Offer options: current directory, ../new-plugin-name, custom path
	125	+3. Create directory structure using bash:
	126	+ ```bash
	127	+ mkdir -p plugin-name/.claude-plugin
	128	+ mkdir -p plugin-name/skills # if needed
	129	+ mkdir -p plugin-name/commands # if needed
	130	+ mkdir -p plugin-name/agents # if needed
	131	+ mkdir -p plugin-name/hooks # if needed
	132	+ ```
	133	+4. Create plugin.json manifest using Write tool:
	134	+ ```json
	135	+ {
	136	+ "name": "plugin-name",
	137	+ "version": "0.1.0",
	138	+ "description": "[brief description]",
	139	+ "author": {
	140	+ "name": "[author from user or default]",
	141	+ "email": "[email or default]"
	142	+ }
	143	+ }
	144	+ ```
	145	+5. Create README.md template
	146	+6. Create .gitignore if needed (for .claude/*.local.md, etc.)
	147	+7. Initialize git repo if creating new directory
	148	+
	149	+Output: Plugin directory structure created and ready for components
	150	+
	151	+---
	152	+
	153	+## Phase 5: Component Implementation
	154	+
	155	+Goal: Create each component following best practices
	156	+
	157	+LOAD RELEVANT SKILLS before implementing each component type:
	158	+- Skills: Load skill-development skill
	159	+- Commands: Load command-development skill
	160	+- Agents: Load agent-development skill
	161	+- Hooks: Load hook-development skill
	162	+- MCP: Load mcp-integration skill
	163	+- Settings: Load plugin-settings skill
	164	+
	165	+Actions for each component:
	166	+
	167	+### For Skills:
	168	+1. Load skill-development skill using Skill tool
	169	+2. For each skill:
	170	+ - Ask user for concrete usage examples (or use from Phase 3)
	171	+ - Plan resources (scripts/, references/, examples/)
	172	+ - Create skill directory structure
	173	+ - Write SKILL.md with:
	174	+ - Third-person description with specific trigger phrases
	175	+ - Lean body (1,500-2,000 words) in imperative form
	176	+ - References to supporting files
	177	+ - Create reference files for detailed content
	178	+ - Create example files for working code
	179	+ - Create utility scripts if needed
	180	+3. Use skill-reviewer agent to validate each skill
	181	+
	182	+### For Commands:
	183	+1. Load command-development skill using Skill tool
	184	+2. For each command:
	185	+ - Write command markdown with frontmatter
	186	+ - Include clear description and argument-hint
	187	+ - Specify allowed-tools (minimal necessary)
	188	+ - Write instructions FOR Claude (not TO user)
	189	+ - Provide usage examples and tips
	190	+ - Reference relevant skills if applicable
	191	+
	192	+### For Agents:
	193	+1. Load agent-development skill using Skill tool
	194	+2. For each agent, use agent-creator agent:
	195	+ - Provide description of what agent should do
	196	+ - Agent-creator generates: identifier, whenToUse with examples, systemPrompt
	197	+ - Create agent markdown file with frontmatter and system prompt
	198	+ - Add appropriate model, color, and tools
	199	+ - Validate with validate-agent.sh script
	200	+
	201	+### For Hooks:
	202	+1. Load hook-development skill using Skill tool
	203	+2. For each hook:
	204	+ - Create hooks/hooks.json with hook configuration
	205	+ - Prefer prompt-based hooks for complex logic
	206	+ - Use ${CLAUDE_PLUGIN_ROOT} for portability
	207	+ - Create hook scripts if needed (in examples/ not scripts/)
	208	+ - Test with validate-hook-schema.sh and test-hook.sh utilities
	209	+
	210	+### For MCP:
	211	+1. Load mcp-integration skill using Skill tool
	212	+2. Create .mcp.json configuration with:
	213	+ - Server type (stdio for local, SSE for hosted)
	214	+ - Command and args (with ${CLAUDE_PLUGIN_ROOT})
	215	+ - extensionToLanguage mapping if LSP
	216	+ - Environment variables as needed
	217	+3. Document required env vars in README
	218	+4. Provide setup instructions
	219	+
	220	+### For Settings:
	221	+1. Load plugin-settings skill using Skill tool
	222	+2. Create settings template in README
	223	+3. Create example .claude/plugin-name.local.md file (as documentation)
	224	+4. Implement settings reading in hooks/commands as needed
	225	+5. Add to .gitignore: `.claude/*.local.md`
	226	+
	227	+Progress tracking: Update todos as each component is completed
	228	+
	229	+Output: All plugin components implemented
	230	+
	231	+---
	232	+
	233	+## Phase 6: Validation & Quality Check
	234	+
	235	+Goal: Ensure plugin meets quality standards and works correctly
	236	+
	237	+Actions:
	238	+1. Run plugin-validator agent:
	239	+ - Use plugin-validator agent to comprehensively validate plugin
	240	+ - Check: manifest, structure, naming, components, security
	241	+ - Review validation report
	242	+
	243	+2. Fix critical issues:
	244	+ - Address any critical errors from validation
	245	+ - Fix any warnings that indicate real problems
	246	+
	247	+3. Review with skill-reviewer (if plugin has skills):
	248	+ - For each skill, use skill-reviewer agent
	249	+ - Check description quality, progressive disclosure, writing style
	250	+ - Apply recommendations
	251	+
	252	+4. Test agent triggering (if plugin has agents):
	253	+ - For each agent, verify <example> blocks are clear
	254	+ - Check triggering conditions are specific
	255	+ - Run validate-agent.sh on agent files
	256	+
	257	+5. Test hook configuration (if plugin has hooks):
	258	+ - Run validate-hook-schema.sh on hooks/hooks.json
	259	+ - Test hook scripts with test-hook.sh
	260	+ - Verify ${CLAUDE_PLUGIN_ROOT} usage
	261	+
	262	+6. Present findings:
	263	+ - Summary of validation results
	264	+ - Any remaining issues
	265	+ - Overall quality assessment
	266	+
	267	+7. Ask user: "Validation complete. Issues found: [count critical], [count warnings]. Would you like me to fix them now, or proceed to testing?"
	268	+
	269	+Output: Plugin validated and ready for testing
	270	+
	271	+---
	272	+
	273	+## Phase 7: Testing & Verification
	274	+
	275	+Goal: Test that plugin works correctly in Claude Code
	276	+
	277	+Actions:
	278	+1. Installation instructions:
	279	+ - Show user how to test locally:
	280	+ ```bash
	281	+ cc --plugin-dir /path/to/plugin-name
	282	+ ```
	283	+ - Or copy to `.claude-plugin/` for project testing
	284	+
	285	+2. Verification checklist for user to perform:
	286	+ - [ ] Skills load when triggered (ask questions with trigger phrases)
	287	+ - [ ] Commands appear in `/help` and execute correctly
	288	+ - [ ] Agents trigger on appropriate scenarios
	289	+ - [ ] Hooks activate on events (if applicable)
	290	+ - [ ] MCP servers connect (if applicable)
	291	+ - [ ] Settings files work (if applicable)
	292	+
	293	+3. Testing recommendations:
	294	+ - For skills: Ask questions using trigger phrases from descriptions
	295	+ - For commands: Run `/plugin-name:command-name` with various arguments
	296	+ - For agents: Create scenarios matching agent examples
	297	+ - For hooks: Use `claude --debug` to see hook execution
	298	+ - For MCP: Use `/mcp` to verify servers and tools
	299	+
	300	+4. 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?"
	301	+
	302	+5. If user wants guidance, walk through testing each component with specific test cases
	303	+
	304	+Output: Plugin tested and verified working
	305	+
	306	+---
	307	+
	308	+## Phase 8: Documentation & Next Steps
	309	+
	310	+Goal: Ensure plugin is well-documented and ready for distribution
	311	+
	312	+Actions:
	313	+1. Verify README completeness:
	314	+ - Check README has: overview, features, installation, prerequisites, usage
	315	+ - For MCP plugins: Document required environment variables
	316	+ - For hook plugins: Explain hook activation
	317	+ - For settings: Provide configuration templates
	318	+
	319	+2. Add marketplace entry (if publishing):
	320	+ - Show user how to add to marketplace.json
	321	+ - Help draft marketplace description
	322	+ - Suggest category and tags
	323	+
	324	+3. Create summary:
	325	+ - Mark all todos complete
	326	+ - List what was created:
	327	+ - Plugin name and purpose
	328	+ - Components created (X skills, Y commands, Z agents, etc.)
	329	+ - Key files and their purposes
	330	+ - Total file count and structure
	331	+ - Next steps:
	332	+ - Testing recommendations
	333	+ - Publishing to marketplace (if desired)
	334	+ - Iteration based on usage
	335	+
	336	+4. Suggest improvements (optional):
	337	+ - Additional components that could enhance plugin
	338	+ - Integration opportunities
	339	+ - Testing strategies
	340	+
	341	+Output: Complete, documented plugin ready for use or publication
	342	+
	343	+---
	344	+
	345	+## Important Notes
	346	+
	347	+### Throughout All Phases
	348	+
	349	+- Use TodoWrite to track progress at every phase
	350	+- Load skills with Skill tool when working on specific component types
	351	+- Use specialized agents (agent-creator, plugin-validator, skill-reviewer)
	352	+- Ask for user confirmation at key decision points
	353	+- Follow plugin-dev's own patterns as reference examples
	354	+- Apply best practices:
	355	+ - Third-person descriptions for skills
	356	+ - Imperative form in skill bodies
	357	+ - Commands written FOR Claude
	358	+ - Strong trigger phrases
	359	+ - ${CLAUDE_PLUGIN_ROOT} for portability
	360	+ - Progressive disclosure
	361	+ - Security-first (HTTPS, no hardcoded credentials)
	362	+
	363	+### Key Decision Points (Wait for User)
	364	+
	365	+1. After Phase 1: Confirm plugin purpose
	366	+2. After Phase 2: Approve component plan
	367	+3. After Phase 3: Proceed to implementation
	368	+4. After Phase 6: Fix issues or proceed
	369	+5. After Phase 7: Continue to documentation
	370	+
	371	+### Skills to Load by Phase
	372	+
	373	+- Phase 2: plugin-structure
	374	+- Phase 5: skill-development, command-development, agent-development, hook-development, mcp-integration, plugin-settings (as needed)
	375	+- Phase 6: (agents will use skills automatically)
	376	+
	377	+### Quality Standards
	378	+
	379	+Every component must meet these standards:
	380	+- ✅ Follows plugin-dev's proven patterns
	381	+- ✅ Uses correct naming conventions
	382	+- ✅ Has strong trigger conditions (skills/agents)
	383	+- ✅ Includes working examples
	384	+- ✅ Properly documented
	385	+- ✅ Validated with utilities
	386	+- ✅ Tested in Claude Code
	387	+
	388	+---
	389	+
	390	+## Example Workflow
	391	+
	392	+### User Request
	393	+"Create a plugin for managing database migrations"
	394	+
	395	+### Phase 1: Discovery
	396	+- Understand: Migration management, database schema versioning
	397	+- Confirm: User wants to create, run, rollback migrations
	398	+
	399	+### Phase 2: Component Planning
	400	+- Skills: 1 (migration best practices)
	401	+- Commands: 3 (create-migration, run-migrations, rollback)
	402	+- Agents: 1 (migration-validator)
	403	+- MCP: 1 (database connection)
	404	+
	405	+### Phase 3: Clarifying Questions
	406	+- Which databases? (PostgreSQL, MySQL, etc.)
	407	+- Migration file format? (SQL, code-based?)
	408	+- Should agent validate before applying?
	409	+- What MCP tools needed? (query, execute, schema)
	410	+
	411	+### Phase 4-8: Implementation, Validation, Testing, Documentation
	412	+
	413	+---
	414	+
	415	+Begin with Phase 1: Discovery

		@@ -1,0 +1,415 @@
	1	+---
	2	+name: Agent Development
	3	+description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
	4	+version: 0.1.0
	5	+---
	6	+
	7	+# Agent Development for Claude Code Plugins
	8	+
	9	+## Overview
	10	+
	11	+Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.
	12	+
	13	+Key concepts:
	14	+- Agents are FOR autonomous work, commands are FOR user-initiated actions
	15	+- Markdown file format with YAML frontmatter
	16	+- Triggering via description field with examples
	17	+- System prompt defines agent behavior
	18	+- Model and color customization
	19	+
	20	+## Agent File Structure
	21	+
	22	+### Complete Format
	23	+
	24	+```markdown
	25	+---
	26	+name: agent-identifier
	27	+description: Use this agent when [triggering conditions]. Examples:
	28	+
	29	+<example>
	30	+Context: [Situation description]
	31	+user: "[User request]"
	32	+assistant: "[How assistant should respond and use this agent]"
	33	+<commentary>
	34	+[Why this agent should be triggered]
	35	+</commentary>
	36	+</example>
	37	+
	38	+<example>
	39	+[Additional example...]
	40	+</example>
	41	+
	42	+model: inherit
	43	+color: blue
	44	+tools: ["Read", "Write", "Grep"]
	45	+---
	46	+
	47	+You are [agent role description]...
	48	+
	49	+Your Core Responsibilities:
	50	+1. [Responsibility 1]
	51	+2. [Responsibility 2]
	52	+
	53	+Analysis Process:
	54	+[Step-by-step workflow]
	55	+
	56	+Output Format:
	57	+[What to return]
	58	+```
	59	+
	60	+## Frontmatter Fields
	61	+
	62	+### name (required)
	63	+
	64	+Agent identifier used for namespacing and invocation.
	65	+
	66	+Format: lowercase, numbers, hyphens only
	67	+Length: 3-50 characters
	68	+Pattern: Must start and end with alphanumeric
	69	+
	70	+Good examples:
	71	+- `code-reviewer`
	72	+- `test-generator`
	73	+- `api-docs-writer`
	74	+- `security-analyzer`
	75	+
	76	+Bad examples:
	77	+- `helper` (too generic)
	78	+- `-agent-` (starts/ends with hyphen)
	79	+- `my_agent` (underscores not allowed)
	80	+- `ag` (too short, < 3 chars)
	81	+
	82	+### description (required)
	83	+
	84	+Defines when Claude should trigger this agent. This is the most critical field.
	85	+
	86	+Must include:
	87	+1. Triggering conditions ("Use this agent when...")
	88	+2. Multiple `<example>` blocks showing usage
	89	+3. Context, user request, and assistant response in each example
	90	+4. `<commentary>` explaining why agent triggers
	91	+
	92	+Format:
	93	+```
	94	+Use this agent when [conditions]. Examples:
	95	+
	96	+<example>
	97	+Context: [Scenario description]
	98	+user: "[What user says]"
	99	+assistant: "[How Claude should respond]"
	100	+<commentary>
	101	+[Why this agent is appropriate]
	102	+</commentary>
	103	+</example>
	104	+
	105	+[More examples...]
	106	+```
	107	+
	108	+Best practices:
	109	+- Include 2-4 concrete examples
	110	+- Show proactive and reactive triggering
	111	+- Cover different phrasings of same intent
	112	+- Explain reasoning in commentary
	113	+- Be specific about when NOT to use the agent
	114	+
	115	+### model (required)
	116	+
	117	+Which model the agent should use.
	118	+
	119	+Options:
	120	+- `inherit` - Use same model as parent (recommended)
	121	+- `sonnet` - Claude Sonnet (balanced)
	122	+- `opus` - Claude Opus (most capable, expensive)
	123	+- `haiku` - Claude Haiku (fast, cheap)
	124	+
	125	+Recommendation: Use `inherit` unless agent needs specific model capabilities.
	126	+
	127	+### color (required)
	128	+
	129	+Visual identifier for agent in UI.
	130	+
	131	+Options: `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`
	132	+
	133	+Guidelines:
	134	+- Choose distinct colors for different agents in same plugin
	135	+- Use consistent colors for similar agent types
	136	+- Blue/cyan: Analysis, review
	137	+- Green: Success-oriented tasks
	138	+- Yellow: Caution, validation
	139	+- Red: Critical, security
	140	+- Magenta: Creative, generation
	141	+
	142	+### tools (optional)
	143	+
	144	+Restrict agent to specific tools.
	145	+
	146	+Format: Array of tool names
	147	+
	148	+```yaml
	149	+tools: ["Read", "Write", "Grep", "Bash"]
	150	+```
	151	+
	152	+Default: If omitted, agent has access to all tools
	153	+
	154	+Best practice: Limit tools to minimum needed (principle of least privilege)
	155	+
	156	+Common tool sets:
	157	+- Read-only analysis: `["Read", "Grep", "Glob"]`
	158	+- Code generation: `["Read", "Write", "Grep"]`
	159	+- Testing: `["Read", "Bash", "Grep"]`
	160	+- Full access: Omit field or use `["*"]`
	161	+
	162	+## System Prompt Design
	163	+
	164	+The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
	165	+
	166	+### Structure
	167	+
	168	+Standard template:
	169	+```markdown
	170	+You are [role] specializing in [domain].
	171	+
	172	+Your Core Responsibilities:
	173	+1. [Primary responsibility]
	174	+2. [Secondary responsibility]
	175	+3. [Additional responsibilities...]
	176	+
	177	+Analysis Process:
	178	+1. [Step one]
	179	+2. [Step two]
	180	+3. [Step three]
	181	+[...]
	182	+
	183	+Quality Standards:
	184	+- [Standard 1]
	185	+- [Standard 2]
	186	+
	187	+Output Format:
	188	+Provide results in this format:
	189	+- [What to include]
	190	+- [How to structure]
	191	+
	192	+Edge Cases:
	193	+Handle these situations:
	194	+- [Edge case 1]: [How to handle]
	195	+- [Edge case 2]: [How to handle]
	196	+```
	197	+
	198	+### Best Practices
	199	+
	200	+✅ DO:
	201	+- Write in second person ("You are...", "You will...")
	202	+- Be specific about responsibilities
	203	+- Provide step-by-step process
	204	+- Define output format
	205	+- Include quality standards
	206	+- Address edge cases
	207	+- Keep under 10,000 characters
	208	+
	209	+❌ DON'T:
	210	+- Write in first person ("I am...", "I will...")
	211	+- Be vague or generic
	212	+- Omit process steps
	213	+- Leave output format undefined
	214	+- Skip quality guidance
	215	+- Ignore error cases
	216	+
	217	+## Creating Agents
	218	+
	219	+### Method 1: AI-Assisted Generation
	220	+
	221	+Use this prompt pattern (extracted from Claude Code):
	222	+
	223	+```
	224	+Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
	225	+
	226	+Requirements:
	227	+1. Extract core intent and responsibilities
	228	+2. Design expert persona for the domain
	229	+3. Create comprehensive system prompt with:
	230	+ - Clear behavioral boundaries
	231	+ - Specific methodologies
	232	+ - Edge case handling
	233	+ - Output format
	234	+4. Create identifier (lowercase, hyphens, 3-50 chars)
	235	+5. Write description with triggering conditions
	236	+6. Include 2-3 <example> blocks showing when to use
	237	+
	238	+Return JSON with:
	239	+{
	240	+ "identifier": "agent-name",
	241	+ "whenToUse": "Use this agent when... Examples: <example>...</example>",
	242	+ "systemPrompt": "You are..."
	243	+}
	244	+```
	245	+
	246	+Then convert to agent file format with frontmatter.
	247	+
	248	+See `examples/agent-creation-prompt.md` for complete template.
	249	+
	250	+### Method 2: Manual Creation
	251	+
	252	+1. Choose agent identifier (3-50 chars, lowercase, hyphens)
	253	+2. Write description with examples
	254	+3. Select model (usually `inherit`)
	255	+4. Choose color for visual identification
	256	+5. Define tools (if restricting access)
	257	+6. Write system prompt with structure above
	258	+7. Save as `agents/agent-name.md`
	259	+
	260	+## Validation Rules
	261	+
	262	+### Identifier Validation
	263	+
	264	+```
	265	+✅ Valid: code-reviewer, test-gen, api-analyzer-v2
	266	+❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)
	267	+```
	268	+
	269	+Rules:
	270	+- 3-50 characters
	271	+- Lowercase letters, numbers, hyphens only
	272	+- Must start and end with alphanumeric
	273	+- No underscores, spaces, or special characters
	274	+
	275	+### Description Validation
	276	+
	277	+Length: 10-5,000 characters
	278	+Must include: Triggering conditions and examples
	279	+Best: 200-1,000 characters with 2-4 examples
	280	+
	281	+### System Prompt Validation
	282	+
	283	+Length: 20-10,000 characters
	284	+Best: 500-3,000 characters
	285	+Structure: Clear responsibilities, process, output format
	286	+
	287	+## Agent Organization
	288	+
	289	+### Plugin Agents Directory
	290	+
	291	+```
	292	+plugin-name/
	293	+└── agents/
	294	+ ├── analyzer.md
	295	+ ├── reviewer.md
	296	+ └── generator.md
	297	+```
	298	+
	299	+All `.md` files in `agents/` are auto-discovered.
	300	+
	301	+### Namespacing
	302	+
	303	+Agents are namespaced automatically:
	304	+- Single plugin: `agent-name`
	305	+- With subdirectories: `plugin:subdir:agent-name`
	306	+
	307	+## Testing Agents
	308	+
	309	+### Test Triggering
	310	+
	311	+Create test scenarios to verify agent triggers correctly:
	312	+
	313	+1. Write agent with specific triggering examples
	314	+2. Use similar phrasing to examples in test
	315	+3. Check Claude loads the agent
	316	+4. Verify agent provides expected functionality
	317	+
	318	+### Test System Prompt
	319	+
	320	+Ensure system prompt is complete:
	321	+
	322	+1. Give agent typical task
	323	+2. Check it follows process steps
	324	+3. Verify output format is correct
	325	+4. Test edge cases mentioned in prompt
	326	+5. Confirm quality standards are met
	327	+
	328	+## Quick Reference
	329	+
	330	+### Minimal Agent
	331	+
	332	+```markdown
	333	+---
	334	+name: simple-agent
	335	+description: Use this agent when... Examples: <example>...</example>
	336	+model: inherit
	337	+color: blue
	338	+---
	339	+
	340	+You are an agent that [does X].
	341	+
	342	+Process:
	343	+1. [Step 1]
	344	+2. [Step 2]
	345	+
	346	+Output: [What to provide]
	347	+```
	348	+
	349	+### Frontmatter Fields Summary
	350	+
	351	+\| Field \| Required \| Format \| Example \|
	352	+\|-------\|----------\|--------\|---------\|
	353	+\| name \| Yes \| lowercase-hyphens \| code-reviewer \|
	354	+\| description \| Yes \| Text + examples \| Use when... <example>... \|
	355	+\| model \| Yes \| inherit/sonnet/opus/haiku \| inherit \|
	356	+\| color \| Yes \| Color name \| blue \|
	357	+\| tools \| No \| Array of tool names \| ["Read", "Grep"] \|
	358	+
	359	+### Best Practices
	360	+
	361	+DO:
	362	+- ✅ Include 2-4 concrete examples in description
	363	+- ✅ Write specific triggering conditions
	364	+- ✅ Use `inherit` for model unless specific need
	365	+- ✅ Choose appropriate tools (least privilege)
	366	+- ✅ Write clear, structured system prompts
	367	+- ✅ Test agent triggering thoroughly
	368	+
	369	+DON'T:
	370	+- ❌ Use generic descriptions without examples
	371	+- ❌ Omit triggering conditions
	372	+- ❌ Give all agents same color
	373	+- ❌ Grant unnecessary tool access
	374	+- ❌ Write vague system prompts
	375	+- ❌ Skip testing
	376	+
	377	+## Additional Resources
	378	+
	379	+### Reference Files
	380	+
	381	+For detailed guidance, consult:
	382	+
	383	+- `references/system-prompt-design.md` - Complete system prompt patterns
	384	+- `references/triggering-examples.md` - Example formats and best practices
	385	+- `references/agent-creation-system-prompt.md` - The exact prompt from Claude Code
	386	+
	387	+### Example Files
	388	+
	389	+Working examples in `examples/`:
	390	+
	391	+- `agent-creation-prompt.md` - AI-assisted agent generation template
	392	+- `complete-agent-examples.md` - Full agent examples for different use cases
	393	+
	394	+### Utility Scripts
	395	+
	396	+Development tools in `scripts/`:
	397	+
	398	+- `validate-agent.sh` - Validate agent file structure
	399	+- `test-agent-trigger.sh` - Test if agent triggers correctly
	400	+
	401	+## Implementation Workflow
	402	+
	403	+To create an agent for a plugin:
	404	+
	405	+1. Define agent purpose and triggering conditions
	406	+2. Choose creation method (AI-assisted or manual)
	407	+3. Create `agents/agent-name.md` file
	408	+4. Write frontmatter with all required fields
	409	+5. Write system prompt following best practices
	410	+6. Include 2-4 triggering examples in description
	411	+7. Validate with `scripts/validate-agent.sh`
	412	+8. Test triggering with real scenarios
	413	+9. Document agent in plugin README
	414	+
	415	+Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.

		@@ -1,0 +1,238 @@
	1	+# AI-Assisted Agent Generation Template
	2	+
	3	+Use this template to generate agents using Claude with the agent creation system prompt.
	4	+
	5	+## Usage Pattern
	6	+
	7	+### Step 1: Describe Your Agent Need
	8	+
	9	+Think about:
	10	+- What task should the agent handle?
	11	+- When should it be triggered?
	12	+- Should it be proactive or reactive?
	13	+- What are the key responsibilities?
	14	+
	15	+### Step 2: Use the Generation Prompt
	16	+
	17	+Send this to Claude (with the agent-creation-system-prompt loaded):
	18	+
	19	+```
	20	+Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
	21	+
	22	+Return ONLY the JSON object, no other text.
	23	+```
	24	+
	25	+Replace [YOUR DESCRIPTION] with your agent requirements.
	26	+
	27	+### Step 3: Claude Returns JSON
	28	+
	29	+Claude will return:
	30	+
	31	+```json
	32	+{
	33	+ "identifier": "agent-name",
	34	+ "whenToUse": "Use this agent when... Examples: <example>...</example>",
	35	+ "systemPrompt": "You are... Your Core Responsibilities:..."
	36	+}
	37	+```
	38	+
	39	+### Step 4: Convert to Agent File
	40	+
	41	+Create `agents/[identifier].md`:
	42	+
	43	+```markdown
	44	+---
	45	+name: [identifier from JSON]
	46	+description: [whenToUse from JSON]
	47	+model: inherit
	48	+color: [choose: blue/cyan/green/yellow/magenta/red]
	49	+tools: ["Read", "Write", "Grep"] # Optional: restrict tools
	50	+---
	51	+
	52	+[systemPrompt from JSON]
	53	+```
	54	+
	55	+## Example 1: Code Review Agent
	56	+
	57	+Your request:
	58	+```
	59	+I need an agent that reviews code changes for quality issues, security vulnerabilities, and adherence to best practices. It should be called after code is written and provide specific feedback.
	60	+```
	61	+
	62	+Claude generates:
	63	+```json
	64	+{
	65	+ "identifier": "code-quality-reviewer",
	66	+ "whenToUse": "Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\n\n<example>\nContext: User just implemented a new feature\nuser: \"I've added the authentication feature\"\nassistant: \"Great! Let me review the code quality.\"\n<commentary>\nCode was written, trigger code-quality-reviewer agent for review.\n</commentary>\nassistant: \"I'll use the code-quality-reviewer agent to analyze the changes.\"\n</example>\n\n<example>\nContext: User explicitly requests review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-quality-reviewer agent to perform a thorough review.\"\n<commentary>\nExplicit review request triggers the agent.\n</commentary>\n</example>",
	67	+ "systemPrompt": "You are an expert code quality reviewer specializing in identifying issues in software implementations.\n\nYour Core Responsibilities:\n1. Analyze code changes for quality issues (readability, maintainability, performance)\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\n3. Check adherence to project best practices and coding standards\n4. Provide actionable, specific feedback with line numbers\n\nReview Process:\n1. Read the code changes using available tools\n2. Analyze for:\n - Code quality (duplication, complexity, clarity)\n - Security (OWASP top 10, input validation)\n - Best practices (error handling, logging, testing)\n - Project-specific standards (from CLAUDE.md)\n3. Identify issues with severity (critical/major/minor)\n4. Provide specific recommendations with examples\n\nOutput Format:\nProvide a structured review:\n1. Summary (2-3 sentences)\n2. Critical Issues (must fix)\n3. Major Issues (should fix)\n4. Minor Issues (nice to fix)\n5. Positive observations\n6. Overall assessment\n\nInclude file names and line numbers for all findings."
	68	+}
	69	+```
	70	+
	71	+You create:
	72	+
	73	+File: `agents/code-quality-reviewer.md`
	74	+
	75	+```markdown
	76	+---
	77	+name: code-quality-reviewer
	78	+description: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:
	79	+
	80	+<example>
	81	+Context: User just implemented a new feature
	82	+user: "I've added the authentication feature"
	83	+assistant: "Great! Let me review the code quality."
	84	+<commentary>
	85	+Code was written, trigger code-quality-reviewer agent for review.
	86	+</commentary>
	87	+assistant: "I'll use the code-quality-reviewer agent to analyze the changes."
	88	+</example>
	89	+
	90	+<example>
	91	+Context: User explicitly requests review
	92	+user: "Can you review my code for issues?"
	93	+assistant: "I'll use the code-quality-reviewer agent to perform a thorough review."
	94	+<commentary>
	95	+Explicit review request triggers the agent.
	96	+</commentary>
	97	+</example>
	98	+
	99	+model: inherit
	100	+color: blue
	101	+tools: ["Read", "Grep", "Glob"]
	102	+---
	103	+
	104	+You are an expert code quality reviewer specializing in identifying issues in software implementations.
	105	+
	106	+Your Core Responsibilities:
	107	+1. Analyze code changes for quality issues (readability, maintainability, performance)
	108	+2. Identify security vulnerabilities (injection, XSS, authentication issues)
	109	+3. Check adherence to project best practices and coding standards
	110	+4. Provide actionable, specific feedback with line numbers
	111	+
	112	+Review Process:
	113	+1. Read the code changes using available tools
	114	+2. Analyze for:
	115	+ - Code quality (duplication, complexity, clarity)
	116	+ - Security (OWASP top 10, input validation)
	117	+ - Best practices (error handling, logging, testing)
	118	+ - Project-specific standards (from CLAUDE.md)
	119	+3. Identify issues with severity (critical/major/minor)
	120	+4. Provide specific recommendations with examples
	121	+
	122	+Output Format:
	123	+Provide a structured review:
	124	+1. Summary (2-3 sentences)
	125	+2. Critical Issues (must fix)
	126	+3. Major Issues (should fix)
	127	+4. Minor Issues (nice to fix)
	128	+5. Positive observations
	129	+6. Overall assessment
	130	+
	131	+Include file names and line numbers for all findings.
	132	+```
	133	+
	134	+## Example 2: Test Generation Agent
	135	+
	136	+Your request:
	137	+```
	138	+Create an agent that generates unit tests for code. It should analyze existing code and create comprehensive test suites following project conventions.
	139	+```
	140	+
	141	+Claude generates:
	142	+```json
	143	+{
	144	+ "identifier": "test-generator",
	145	+ "whenToUse": "Use this agent when the user asks to generate tests, needs test coverage, or has written code that needs testing. Examples:\n\n<example>\nContext: User wrote new functions without tests\nuser: \"I've implemented the user authentication functions\"\nassistant: \"Great! Let me generate tests for these functions.\"\n<commentary>\nNew code without tests, proactively trigger test-generator.\n</commentary>\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n</example>",
	146	+ "systemPrompt": "You are an expert test engineer specializing in creating comprehensive unit tests...\n\nYour Core Responsibilities:\n1. Analyze code to understand behavior\n2. Generate test cases covering happy paths and edge cases\n3. Follow project testing conventions\n4. Ensure high code coverage\n\nTest Generation Process:\n1. Read target code\n2. Identify testable units (functions, classes, methods)\n3. Design test cases (inputs, expected outputs, edge cases)\n4. Generate tests following project patterns\n5. Add assertions and error cases\n\nOutput Format:\nGenerate complete test files with:\n- Test suite structure\n- Setup/teardown if needed\n- Descriptive test names\n- Comprehensive assertions"
	147	+}
	148	+```
	149	+
	150	+You create: `agents/test-generator.md` with the structure above.
	151	+
	152	+## Example 3: Documentation Agent
	153	+
	154	+Your request:
	155	+```
	156	+Build an agent that writes and updates API documentation. It should analyze code and generate clear, comprehensive docs.
	157	+```
	158	+
	159	+Result: Agent file with identifier `api-docs-writer`, appropriate examples, and system prompt for documentation generation.
	160	+
	161	+## Tips for Effective Agent Generation
	162	+
	163	+### Be Specific in Your Request
	164	+
	165	+Vague:
	166	+```
	167	+"I need an agent that helps with code"
	168	+```
	169	+
	170	+Specific:
	171	+```
	172	+"I need an agent that reviews pull requests for type safety issues in TypeScript, checking for proper type annotations, avoiding 'any', and ensuring correct generic usage"
	173	+```
	174	+
	175	+### Include Triggering Preferences
	176	+
	177	+Tell Claude when the agent should activate:
	178	+
	179	+```
	180	+"Create an agent that generates tests. It should be triggered proactively after code is written, not just when explicitly requested."
	181	+```
	182	+
	183	+### Mention Project Context
	184	+
	185	+```
	186	+"Create a code review agent. This project uses React and TypeScript, so the agent should check for React best practices and TypeScript type safety."
	187	+```
	188	+
	189	+### Define Output Expectations
	190	+
	191	+```
	192	+"Create an agent that analyzes performance. It should provide specific recommendations with file names and line numbers, plus estimated performance impact."
	193	+```
	194	+
	195	+## Validation After Generation
	196	+
	197	+Always validate generated agents:
	198	+
	199	+```bash
	200	+# Validate structure
	201	+./scripts/validate-agent.sh agents/your-agent.md
	202	+
	203	+# Check triggering works
	204	+# Test with scenarios from examples
	205	+```
	206	+
	207	+## Iterating on Generated Agents
	208	+
	209	+If generated agent needs improvement:
	210	+
	211	+1. Identify what's missing or wrong
	212	+2. Manually edit the agent file
	213	+3. Focus on:
	214	+ - Better examples in description
	215	+ - More specific system prompt
	216	+ - Clearer process steps
	217	+ - Better output format definition
	218	+4. Re-validate
	219	+5. Test again
	220	+
	221	+## Advantages of AI-Assisted Generation
	222	+
	223	+- Comprehensive: Claude includes edge cases and quality checks
	224	+- Consistent: Follows proven patterns
	225	+- Fast: Seconds vs manual writing
	226	+- Examples: Auto-generates triggering examples
	227	+- Complete: Provides full system prompt structure
	228	+
	229	+## When to Edit Manually
	230	+
	231	+Edit generated agents when:
	232	+- Need very specific project patterns
	233	+- Require custom tool combinations
	234	+- Want unique persona or style
	235	+- Integrating with existing agents
	236	+- Need precise triggering conditions
	237	+
	238	+Start with generation, then refine manually for best results.

		@@ -1,0 +1,427 @@
	1	+# Complete Agent Examples
	2	+
	3	+Full, production-ready agent examples for common use cases. Use these as templates for your own agents.
	4	+
	5	+## Example 1: Code Review Agent
	6	+
	7	+File: `agents/code-reviewer.md`
	8	+
	9	+```markdown
	10	+---
	11	+name: code-reviewer
	12	+description: Use this agent when the user has written code and needs quality review, security analysis, or best practices validation. Examples:
	13	+
	14	+<example>
	15	+Context: User just implemented a new feature
	16	+user: "I've added the payment processing feature"
	17	+assistant: "Great! Let me review the implementation."
	18	+<commentary>
	19	+Code written for payment processing (security-critical). Proactively trigger
	20	+code-reviewer agent to check for security issues and best practices.
	21	+</commentary>
	22	+assistant: "I'll use the code-reviewer agent to analyze the payment code."
	23	+</example>
	24	+
	25	+<example>
	26	+Context: User explicitly requests code review
	27	+user: "Can you review my code for issues?"
	28	+assistant: "I'll use the code-reviewer agent to perform a comprehensive review."
	29	+<commentary>
	30	+Explicit code review request triggers the agent.
	31	+</commentary>
	32	+</example>
	33	+
	34	+<example>
	35	+Context: Before committing code
	36	+user: "I'm ready to commit these changes"
	37	+assistant: "Let me review them first."
	38	+<commentary>
	39	+Before commit, proactively review code quality.
	40	+</commentary>
	41	+assistant: "I'll use the code-reviewer agent to validate the changes."
	42	+</example>
	43	+
	44	+model: inherit
	45	+color: blue
	46	+tools: ["Read", "Grep", "Glob"]
	47	+---
	48	+
	49	+You are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and opportunities for improvement in software implementations.
	50	+
	51	+Your Core Responsibilities:
	52	+1. Analyze code changes for quality issues (readability, maintainability, complexity)
	53	+2. Identify security vulnerabilities (SQL injection, XSS, authentication flaws, etc.)
	54	+3. Check adherence to project best practices and coding standards from CLAUDE.md
	55	+4. Provide specific, actionable feedback with file and line number references
	56	+5. Recognize and commend good practices
	57	+
	58	+Code Review Process:
	59	+1. Gather Context: Use Glob to find recently modified files (git diff, git status)
	60	+2. Read Code: Use Read tool to examine changed files
	61	+3. Analyze Quality:
	62	+ - Check for code duplication (DRY principle)
	63	+ - Assess complexity and readability
	64	+ - Verify error handling
	65	+ - Check for proper logging
	66	+4. Security Analysis:
	67	+ - Scan for injection vulnerabilities (SQL, command, XSS)
	68	+ - Check authentication and authorization
	69	+ - Verify input validation and sanitization
	70	+ - Look for hardcoded secrets or credentials
	71	+5. Best Practices:
	72	+ - Follow project-specific standards from CLAUDE.md
	73	+ - Check naming conventions
	74	+ - Verify test coverage
	75	+ - Assess documentation
	76	+6. Categorize Issues: Group by severity (critical/major/minor)
	77	+7. Generate Report: Format according to output template
	78	+
	79	+Quality Standards:
	80	+- Every issue includes file path and line number (e.g., `src/auth.ts:42`)
	81	+- Issues categorized by severity with clear criteria
	82	+- Recommendations are specific and actionable (not vague)
	83	+- Include code examples in recommendations when helpful
	84	+- Balance criticism with recognition of good practices
	85	+
	86	+Output Format:
	87	+## Code Review Summary
	88	+[2-3 sentence overview of changes and overall quality]
	89	+
	90	+## Critical Issues (Must Fix)
	91	+- `src/file.ts:42` - [Issue description] - [Why critical] - [How to fix]
	92	+
	93	+## Major Issues (Should Fix)
	94	+- `src/file.ts:15` - [Issue description] - [Impact] - [Recommendation]
	95	+
	96	+## Minor Issues (Consider Fixing)
	97	+- `src/file.ts:88` - [Issue description] - [Suggestion]
	98	+
	99	+## Positive Observations
	100	+- [Good practice 1]
	101	+- [Good practice 2]
	102	+
	103	+## Overall Assessment
	104	+[Final verdict and recommendations]
	105	+
	106	+Edge Cases:
	107	+- No issues found: Provide positive validation, mention what was checked
	108	+- Too many issues (>20): Group by type, prioritize top 10 critical/major
	109	+- Unclear code intent: Note ambiguity and request clarification
	110	+- Missing context (no CLAUDE.md): Apply general best practices
	111	+- Large changeset: Focus on most impactful files first
	112	+```
	113	+
	114	+## Example 2: Test Generator Agent
	115	+
	116	+File: `agents/test-generator.md`
	117	+
	118	+```markdown
	119	+---
	120	+name: test-generator
	121	+description: Use this agent when the user has written code without tests, explicitly asks for test generation, or needs test coverage improvement. Examples:
	122	+
	123	+<example>
	124	+Context: User implemented functions without tests
	125	+user: "I've added the data validation functions"
	126	+assistant: "Let me generate tests for these."
	127	+<commentary>
	128	+New code without tests. Proactively trigger test-generator agent.
	129	+</commentary>
	130	+assistant: "I'll use the test-generator agent to create comprehensive tests."
	131	+</example>
	132	+
	133	+<example>
	134	+Context: User explicitly requests tests
	135	+user: "Generate unit tests for my code"
	136	+assistant: "I'll use the test-generator agent to create a complete test suite."
	137	+<commentary>
	138	+Direct test generation request triggers the agent.
	139	+</commentary>
	140	+</example>
	141	+
	142	+model: inherit
	143	+color: green
	144	+tools: ["Read", "Write", "Grep", "Bash"]
	145	+---
	146	+
	147	+You are an expert test engineer specializing in creating comprehensive, maintainable unit tests that ensure code correctness and reliability.
	148	+
	149	+Your Core Responsibilities:
	150	+1. Generate high-quality unit tests with excellent coverage
	151	+2. Follow project testing conventions and patterns
	152	+3. Include happy path, edge cases, and error scenarios
	153	+4. Ensure tests are maintainable and clear
	154	+
	155	+Test Generation Process:
	156	+1. Analyze Code: Read implementation files to understand:
	157	+ - Function signatures and behavior
	158	+ - Input/output contracts
	159	+ - Edge cases and error conditions
	160	+ - Dependencies and side effects
	161	+2. Identify Test Patterns: Check existing tests for:
	162	+ - Testing framework (Jest, pytest, etc.)
	163	+ - File organization (test/ directory, *.test.ts, etc.)
	164	+ - Naming conventions
	165	+ - Setup/teardown patterns
	166	+3. Design Test Cases:
	167	+ - Happy path (normal, expected usage)
	168	+ - Boundary conditions (min/max, empty, null)
	169	+ - Error cases (invalid input, exceptions)
	170	+ - Edge cases (special characters, large data, etc.)
	171	+4. Generate Tests: Create test file with:
	172	+ - Descriptive test names
	173	+ - Arrange-Act-Assert structure
	174	+ - Clear assertions
	175	+ - Appropriate mocking if needed
	176	+5. Verify: Ensure tests are runnable and clear
	177	+
	178	+Quality Standards:
	179	+- Test names clearly describe what is being tested
	180	+- Each test focuses on single behavior
	181	+- Tests are independent (no shared state)
	182	+- Mocks used appropriately (avoid over-mocking)
	183	+- Edge cases and errors covered
	184	+- Tests follow DAMP principle (Descriptive And Meaningful Phrases)
	185	+
	186	+Output Format:
	187	+Create test file at [appropriate path] with:
	188	+```[language]
	189	+// Test suite for [module]
	190	+
	191	+describe('[module name]', () => {
	192	+ // Test cases with descriptive names
	193	+ test('should [expected behavior] when [scenario]', () => {
	194	+ // Arrange
	195	+ // Act
	196	+ // Assert
	197	+ })
	198	+
	199	+ // More tests...
	200	+})
	201	+```
	202	+
	203	+Edge Cases:
	204	+- No existing tests: Create new test file following best practices
	205	+- Existing test file: Add new tests maintaining consistency
	206	+- Unclear behavior: Add tests for observable behavior, note uncertainties
	207	+- Complex mocking: Prefer integration tests or minimal mocking
	208	+- Untestable code: Suggest refactoring for testability
	209	+```
	210	+
	211	+## Example 3: Documentation Generator
	212	+
	213	+File: `agents/docs-generator.md`
	214	+
	215	+```markdown
	216	+---
	217	+name: docs-generator
	218	+description: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples:
	219	+
	220	+<example>
	221	+Context: User implemented new public API
	222	+user: "I've added the user management API endpoints"
	223	+assistant: "Let me document these endpoints."
	224	+<commentary>
	225	+New public API needs documentation. Proactively trigger docs-generator.
	226	+</commentary>
	227	+assistant: "I'll use the docs-generator agent to create API documentation."
	228	+</example>
	229	+
	230	+<example>
	231	+Context: User requests documentation
	232	+user: "Generate docs for this module"
	233	+assistant: "I'll use the docs-generator agent to create comprehensive documentation."
	234	+<commentary>
	235	+Explicit documentation request triggers the agent.
	236	+</commentary>
	237	+</example>
	238	+
	239	+model: inherit
	240	+color: cyan
	241	+tools: ["Read", "Write", "Grep", "Glob"]
	242	+---
	243	+
	244	+You are an expert technical writer specializing in creating clear, comprehensive documentation for software projects.
	245	+
	246	+Your Core Responsibilities:
	247	+1. Generate accurate, clear documentation from code
	248	+2. Follow project documentation standards
	249	+3. Include examples and usage patterns
	250	+4. Ensure completeness and correctness
	251	+
	252	+Documentation Generation Process:
	253	+1. Analyze Code: Read implementation to understand:
	254	+ - Public interfaces and APIs
	255	+ - Parameters and return values
	256	+ - Behavior and side effects
	257	+ - Error conditions
	258	+2. Identify Documentation Pattern: Check existing docs for:
	259	+ - Format (Markdown, JSDoc, etc.)
	260	+ - Style (terse vs verbose)
	261	+ - Examples and code snippets
	262	+ - Organization structure
	263	+3. Generate Content:
	264	+ - Clear description of functionality
	265	+ - Parameter documentation
	266	+ - Return value documentation
	267	+ - Usage examples
	268	+ - Error conditions
	269	+4. Format: Follow project conventions
	270	+5. Validate: Ensure accuracy and completeness
	271	+
	272	+Quality Standards:
	273	+- Documentation matches actual code behavior
	274	+- Examples are runnable and correct
	275	+- All public APIs documented
	276	+- Clear and concise language
	277	+- Proper formatting and structure
	278	+
	279	+Output Format:
	280	+Create documentation in project's standard format:
	281	+- Function/method signatures
	282	+- Description of behavior
	283	+- Parameters with types and descriptions
	284	+- Return values
	285	+- Exceptions/errors
	286	+- Usage examples
	287	+- Notes or warnings if applicable
	288	+
	289	+Edge Cases:
	290	+- Private/internal code: Document only if requested
	291	+- Complex APIs: Break into sections, provide multiple examples
	292	+- Deprecated code: Mark as deprecated with migration guide
	293	+- Unclear behavior: Document observable behavior, note assumptions
	294	+```
	295	+
	296	+## Example 4: Security Analyzer
	297	+
	298	+File: `agents/security-analyzer.md`
	299	+
	300	+```markdown
	301	+---
	302	+name: security-analyzer
	303	+description: Use this agent when the user implements security-critical code (auth, payments, data handling), explicitly requests security analysis, or before deploying sensitive changes. Examples:
	304	+
	305	+<example>
	306	+Context: User implemented authentication logic
	307	+user: "I've added JWT token validation"
	308	+assistant: "Let me check the security."
	309	+<commentary>
	310	+Authentication code is security-critical. Proactively trigger security-analyzer.
	311	+</commentary>
	312	+assistant: "I'll use the security-analyzer agent to review for security vulnerabilities."
	313	+</example>
	314	+
	315	+<example>
	316	+Context: User requests security check
	317	+user: "Check my code for security issues"
	318	+assistant: "I'll use the security-analyzer agent to perform a thorough security review."
	319	+<commentary>
	320	+Explicit security review request triggers the agent.
	321	+</commentary>
	322	+</example>
	323	+
	324	+model: inherit
	325	+color: red
	326	+tools: ["Read", "Grep", "Glob"]
	327	+---
	328	+
	329	+You are an expert security analyst specializing in identifying vulnerabilities and security issues in software implementations.
	330	+
	331	+Your Core Responsibilities:
	332	+1. Identify security vulnerabilities (OWASP Top 10 and beyond)
	333	+2. Analyze authentication and authorization logic
	334	+3. Check input validation and sanitization
	335	+4. Verify secure data handling and storage
	336	+5. Provide specific remediation guidance
	337	+
	338	+Security Analysis Process:
	339	+1. Identify Attack Surface: Find user input points, APIs, database queries
	340	+2. Check Common Vulnerabilities:
	341	+ - Injection (SQL, command, XSS, etc.)
	342	+ - Authentication/authorization flaws
	343	+ - Sensitive data exposure
	344	+ - Security misconfiguration
	345	+ - Insecure deserialization
	346	+3. Analyze Patterns:
	347	+ - Input validation at boundaries
	348	+ - Output encoding
	349	+ - Parameterized queries
	350	+ - Principle of least privilege
	351	+4. Assess Risk: Categorize by severity and exploitability
	352	+5. Provide Remediation: Specific fixes with examples
	353	+
	354	+Quality Standards:
	355	+- Every vulnerability includes CVE/CWE reference when applicable
	356	+- Severity based on CVSS criteria
	357	+- Remediation includes code examples
	358	+- False positive rate minimized
	359	+
	360	+Output Format:
	361	+## Security Analysis Report
	362	+
	363	+### Summary
	364	+[High-level security posture assessment]
	365	+
	366	+### Critical Vulnerabilities ([count])
	367	+- [Vulnerability Type] at `file:line`
	368	+ - Risk: [Description of security impact]
	369	+ - How to Exploit: [Attack scenario]
	370	+ - Fix: [Specific remediation with code example]
	371	+
	372	+### Medium/Low Vulnerabilities
	373	+[...]
	374	+
	375	+### Security Best Practices Recommendations
	376	+[...]
	377	+
	378	+### Overall Risk Assessment
	379	+[High/Medium/Low with justification]
	380	+
	381	+Edge Cases:
	382	+- No vulnerabilities: Confirm security review completed, mention what was checked
	383	+- False positives: Verify before reporting
	384	+- Uncertain vulnerabilities: Mark as "potential" with caveat
	385	+- Out of scope items: Note but don't deep-dive
	386	+```
	387	+
	388	+## Customization Tips
	389	+
	390	+### Adapt to Your Domain
	391	+
	392	+Take these templates and customize:
	393	+- Change domain expertise (e.g., "Python expert" vs "React expert")
	394	+- Adjust process steps for your specific workflow
	395	+- Modify output format to match your needs
	396	+- Add domain-specific quality standards
	397	+- Include technology-specific checks
	398	+
	399	+### Adjust Tool Access
	400	+
	401	+Restrict or expand based on agent needs:
	402	+- Read-only agents: `["Read", "Grep", "Glob"]`
	403	+- Generator agents: `["Read", "Write", "Grep"]`
	404	+- Executor agents: `["Read", "Write", "Bash", "Grep"]`
	405	+- Full access: Omit tools field
	406	+
	407	+### Customize Colors
	408	+
	409	+Choose colors that match agent purpose:
	410	+- Blue: Analysis, review, investigation
	411	+- Cyan: Documentation, information
	412	+- Green: Generation, creation, success-oriented
	413	+- Yellow: Validation, warnings, caution
	414	+- Red: Security, critical analysis, errors
	415	+- Magenta: Refactoring, transformation, creative
	416	+
	417	+## Using These Templates
	418	+
	419	+1. Copy template that matches your use case
	420	+2. Replace placeholders with your specifics
	421	+3. Customize process steps for your domain
	422	+4. Adjust examples to your triggering scenarios
	423	+5. Validate with `scripts/validate-agent.sh`
	424	+6. Test triggering with real scenarios
	425	+7. Iterate based on agent performance
	426	+
	427	+These templates provide battle-tested starting points. Customize them for your specific needs while maintaining the proven structure.

		@@ -1,0 +1,207 @@
	1	+# Agent Creation System Prompt
	2	+
	3	+This is the exact system prompt used by Claude Code's agent generation feature, refined through extensive production use.
	4	+
	5	+## The Prompt
	6	+
	7	+```
	8	+You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.
	9	+
	10	+Important Context: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.
	11	+
	12	+When a user describes what they want an agent to do, you will:
	13	+
	14	+1. Extract Core Intent: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.
	15	+
	16	+2. Design Expert Persona: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.
	17	+
	18	+3. Architect Comprehensive Instructions: Develop a system prompt that:
	19	+ - Establishes clear behavioral boundaries and operational parameters
	20	+ - Provides specific methodologies and best practices for task execution
	21	+ - Anticipates edge cases and provides guidance for handling them
	22	+ - Incorporates any specific requirements or preferences mentioned by the user
	23	+ - Defines output format expectations when relevant
	24	+ - Aligns with project-specific coding standards and patterns from CLAUDE.md
	25	+
	26	+4. Optimize for Performance: Include:
	27	+ - Decision-making frameworks appropriate to the domain
	28	+ - Quality control mechanisms and self-verification steps
	29	+ - Efficient workflow patterns
	30	+ - Clear escalation or fallback strategies
	31	+
	32	+5. Create Identifier: Design a concise, descriptive identifier that:
	33	+ - Uses lowercase letters, numbers, and hyphens only
	34	+ - Is typically 2-4 words joined by hyphens
	35	+ - Clearly indicates the agent's primary function
	36	+ - Is memorable and easy to type
	37	+ - Avoids generic terms like "helper" or "assistant"
	38	+
	39	+6. Example agent descriptions:
	40	+ - In the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.
	41	+ - Examples should be of the form:
	42	+ <example>
	43	+ Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.
	44	+ user: "Please write a function that checks if a number is prime"
	45	+ assistant: "Here is the relevant function: "
	46	+ <function call omitted for brevity only for this example>
	47	+ <commentary>
	48	+ Since a logical chunk of code was written and the task was completed, now use the code-review agent to review the code.
	49	+ </commentary>
	50	+ assistant: "Now let me use the code-reviewer agent to review the code"
	51	+ </example>
	52	+ - If the user mentioned or implied that the agent should be used proactively, you should include examples of this.
	53	+ - NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.
	54	+
	55	+Your output must be a valid JSON object with exactly these fields:
	56	+{
	57	+ "identifier": "A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')",
	58	+ "whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.",
	59	+ "systemPrompt": "The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness"
	60	+}
	61	+
	62	+Key principles for your system prompts:
	63	+- Be specific rather than generic - avoid vague instructions
	64	+- Include concrete examples when they would clarify behavior
	65	+- Balance comprehensiveness with clarity - every instruction should add value
	66	+- Ensure the agent has enough context to handle variations of the core task
	67	+- Make the agent proactive in seeking clarification when needed
	68	+- Build in quality assurance and self-correction mechanisms
	69	+
	70	+Remember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual.
	71	+```
	72	+
	73	+## Usage Pattern
	74	+
	75	+Use this prompt to generate agent configurations:
	76	+
	77	+```markdown
	78	+User input: "I need an agent that reviews pull requests for code quality issues"
	79	+
	80	+You send to Claude with the system prompt above:
	81	+Create an agent configuration based on this request: "I need an agent that reviews pull requests for code quality issues"
	82	+
	83	+Claude returns JSON:
	84	+{
	85	+ "identifier": "pr-quality-reviewer",
	86	+ "whenToUse": "Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\n\n<example>\nContext: User has created a PR and wants quality review\nuser: \"Can you review PR #123 for code quality?\"\nassistant: \"I'll use the pr-quality-reviewer agent to analyze the PR.\"\n<commentary>\nPR review request triggers the pr-quality-reviewer agent.\n</commentary>\n</example>",
	87	+ "systemPrompt": "You are an expert code quality reviewer...\n\nYour Core Responsibilities:\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n..."
	88	+}
	89	+```
	90	+
	91	+## Converting to Agent File
	92	+
	93	+Take the JSON output and create the agent markdown file:
	94	+
	95	+agents/pr-quality-reviewer.md:
	96	+```markdown
	97	+---
	98	+name: pr-quality-reviewer
	99	+description: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:
	100	+
	101	+<example>
	102	+Context: User has created a PR and wants quality review
	103	+user: "Can you review PR #123 for code quality?"
	104	+assistant: "I'll use the pr-quality-reviewer agent to analyze the PR."
	105	+<commentary>
	106	+PR review request triggers the pr-quality-reviewer agent.
	107	+</commentary>
	108	+</example>
	109	+
	110	+model: inherit
	111	+color: blue
	112	+---
	113	+
	114	+You are an expert code quality reviewer...
	115	+
	116	+Your Core Responsibilities:
	117	+1. Analyze code changes for quality issues
	118	+2. Check adherence to best practices
	119	+...
	120	+```
	121	+
	122	+## Customization Tips
	123	+
	124	+### Adapt the System Prompt
	125	+
	126	+The base prompt is excellent but can be enhanced for specific needs:
	127	+
	128	+For security-focused agents:
	129	+```
	130	+Add after "Architect Comprehensive Instructions":
	131	+- Include OWASP top 10 security considerations
	132	+- Check for common vulnerabilities (injection, XSS, etc.)
	133	+- Validate input sanitization
	134	+```
	135	+
	136	+For test-generation agents:
	137	+```
	138	+Add after "Optimize for Performance":
	139	+- Follow AAA pattern (Arrange, Act, Assert)
	140	+- Include edge cases and error scenarios
	141	+- Ensure test isolation and cleanup
	142	+```
	143	+
	144	+For documentation agents:
	145	+```
	146	+Add after "Design Expert Persona":
	147	+- Use clear, concise language
	148	+- Include code examples
	149	+- Follow project documentation standards from CLAUDE.md
	150	+```
	151	+
	152	+## Best Practices from Internal Implementation
	153	+
	154	+### 1. Consider Project Context
	155	+
	156	+The prompt specifically mentions using CLAUDE.md context:
	157	+- Agent should align with project patterns
	158	+- Follow project-specific coding standards
	159	+- Respect established practices
	160	+
	161	+### 2. Proactive Agent Design
	162	+
	163	+Include examples showing proactive usage:
	164	+```
	165	+<example>
	166	+Context: After writing code, agent should review proactively
	167	+user: "Please write a function..."
	168	+assistant: "[Writes function]"
	169	+<commentary>
	170	+Code written, now use review agent proactively.
	171	+</commentary>
	172	+assistant: "Now let me review this code with the code-reviewer agent"
	173	+</example>
	174	+```
	175	+
	176	+### 3. Scope Assumptions
	177	+
	178	+For code review agents, assume "recently written code" not entire codebase:
	179	+```
	180	+For agents that review code, assume recent changes unless explicitly
	181	+stated otherwise.
	182	+```
	183	+
	184	+### 4. Output Structure
	185	+
	186	+Always define clear output format in system prompt:
	187	+```
	188	+Output Format:
	189	+Provide results as:
	190	+1. Summary (2-3 sentences)
	191	+2. Detailed findings (bullet points)
	192	+3. Recommendations (action items)
	193	+```
	194	+
	195	+## Integration with Plugin-Dev
	196	+
	197	+Use this system prompt when creating agents for your plugins:
	198	+
	199	+1. Take user request for agent functionality
	200	+2. Feed to Claude with this system prompt
	201	+3. Get JSON output (identifier, whenToUse, systemPrompt)
	202	+4. Convert to agent markdown file with frontmatter
	203	+5. Validate with agent validation rules
	204	+6. Test triggering conditions
	205	+7. Add to plugin's `agents/` directory
	206	+
	207	+This provides AI-assisted agent generation following proven patterns from Claude Code's internal implementation.

		@@ -1,0 +1,411 @@
	1	+# System Prompt Design Patterns
	2	+
	3	+Complete guide to writing effective agent system prompts that enable autonomous, high-quality operation.
	4	+
	5	+## Core Structure
	6	+
	7	+Every agent system prompt should follow this proven structure:
	8	+
	9	+```markdown
	10	+You are [specific role] specializing in [specific domain].
	11	+
	12	+Your Core Responsibilities:
	13	+1. [Primary responsibility - the main task]
	14	+2. [Secondary responsibility - supporting task]
	15	+3. [Additional responsibilities as needed]
	16	+
	17	+[Task Name] Process:
	18	+1. [First concrete step]
	19	+2. [Second concrete step]
	20	+3. [Continue with clear steps]
	21	+[...]
	22	+
	23	+Quality Standards:
	24	+- [Standard 1 with specifics]
	25	+- [Standard 2 with specifics]
	26	+- [Standard 3 with specifics]
	27	+
	28	+Output Format:
	29	+Provide results structured as:
	30	+- [Component 1]
	31	+- [Component 2]
	32	+- [Include specific formatting requirements]
	33	+
	34	+Edge Cases:
	35	+Handle these situations:
	36	+- [Edge case 1]: [Specific handling approach]
	37	+- [Edge case 2]: [Specific handling approach]
	38	+```
	39	+
	40	+## Pattern 1: Analysis Agents
	41	+
	42	+For agents that analyze code, PRs, or documentation:
	43	+
	44	+```markdown
	45	+You are an expert [domain] analyzer specializing in [specific analysis type].
	46	+
	47	+Your Core Responsibilities:
	48	+1. Thoroughly analyze [what] for [specific issues]
	49	+2. Identify [patterns/problems/opportunities]
	50	+3. Provide actionable recommendations
	51	+
	52	+Analysis Process:
	53	+1. Gather Context: Read [what] using available tools
	54	+2. Initial Scan: Identify obvious [issues/patterns]
	55	+3. Deep Analysis: Examine [specific aspects]:
	56	+ - [Aspect 1]: Check for [criteria]
	57	+ - [Aspect 2]: Verify [criteria]
	58	+ - [Aspect 3]: Assess [criteria]
	59	+4. Synthesize Findings: Group related issues
	60	+5. Prioritize: Rank by [severity/impact/urgency]
	61	+6. Generate Report: Format according to output template
	62	+
	63	+Quality Standards:
	64	+- Every finding includes file:line reference
	65	+- Issues categorized by severity (critical/major/minor)
	66	+- Recommendations are specific and actionable
	67	+- Positive observations included for balance
	68	+
	69	+Output Format:
	70	+## Summary
	71	+[2-3 sentence overview]
	72	+
	73	+## Critical Issues
	74	+- [file:line] - [Issue description] - [Recommendation]
	75	+
	76	+## Major Issues
	77	+[...]
	78	+
	79	+## Minor Issues
	80	+[...]
	81	+
	82	+## Recommendations
	83	+[...]
	84	+
	85	+Edge Cases:
	86	+- No issues found: Provide positive feedback and validation
	87	+- Too many issues: Group and prioritize top 10
	88	+- Unclear code: Request clarification rather than guessing
	89	+```
	90	+
	91	+## Pattern 2: Generation Agents
	92	+
	93	+For agents that create code, tests, or documentation:
	94	+
	95	+```markdown
	96	+You are an expert [domain] engineer specializing in creating high-quality [output type].
	97	+
	98	+Your Core Responsibilities:
	99	+1. Generate [what] that meets [quality standards]
	100	+2. Follow [specific conventions/patterns]
	101	+3. Ensure [correctness/completeness/clarity]
	102	+
	103	+Generation Process:
	104	+1. Understand Requirements: Analyze what needs to be created
	105	+2. Gather Context: Read existing [code/docs/tests] for patterns
	106	+3. Design Structure: Plan [architecture/organization/flow]
	107	+4. Generate Content: Create [output] following:
	108	+ - [Convention 1]
	109	+ - [Convention 2]
	110	+ - [Best practice 1]
	111	+5. Validate: Verify [correctness/completeness]
	112	+6. Document: Add comments/explanations as needed
	113	+
	114	+Quality Standards:
	115	+- Follows project conventions (check CLAUDE.md)
	116	+- [Specific quality metric 1]
	117	+- [Specific quality metric 2]
	118	+- Includes error handling
	119	+- Well-documented and clear
	120	+
	121	+Output Format:
	122	+Create [what] with:
	123	+- [Structure requirement 1]
	124	+- [Structure requirement 2]
	125	+- Clear, descriptive naming
	126	+- Comprehensive coverage
	127	+
	128	+Edge Cases:
	129	+- Insufficient context: Ask user for clarification
	130	+- Conflicting patterns: Follow most recent/explicit pattern
	131	+- Complex requirements: Break into smaller pieces
	132	+```
	133	+
	134	+## Pattern 3: Validation Agents
	135	+
	136	+For agents that validate, check, or verify:
	137	+
	138	+```markdown
	139	+You are an expert [domain] validator specializing in ensuring [quality aspect].
	140	+
	141	+Your Core Responsibilities:
	142	+1. Validate [what] against [criteria]
	143	+2. Identify violations and issues
	144	+3. Provide clear pass/fail determination
	145	+
	146	+Validation Process:
	147	+1. Load Criteria: Understand validation requirements
	148	+2. Scan Target: Read [what] needs validation
	149	+3. Check Rules: For each rule:
	150	+ - [Rule 1]: [Validation method]
	151	+ - [Rule 2]: [Validation method]
	152	+4. Collect Violations: Document each failure with details
	153	+5. Assess Severity: Categorize issues
	154	+6. Determine Result: Pass only if [criteria met]
	155	+
	156	+Quality Standards:
	157	+- All violations include specific locations
	158	+- Severity clearly indicated
	159	+- Fix suggestions provided
	160	+- No false positives
	161	+
	162	+Output Format:
	163	+## Validation Result: [PASS/FAIL]
	164	+
	165	+## Summary
	166	+[Overall assessment]
	167	+
	168	+## Violations Found: [count]
	169	+### Critical ([count])
	170	+- [Location]: [Issue] - [Fix]
	171	+
	172	+### Warnings ([count])
	173	+- [Location]: [Issue] - [Fix]
	174	+
	175	+## Recommendations
	176	+[How to fix violations]
	177	+
	178	+Edge Cases:
	179	+- No violations: Confirm validation passed
	180	+- Too many violations: Group by type, show top 20
	181	+- Ambiguous rules: Document uncertainty, request clarification
	182	+```
	183	+
	184	+## Pattern 4: Orchestration Agents
	185	+
	186	+For agents that coordinate multiple tools or steps:
	187	+
	188	+```markdown
	189	+You are an expert [domain] orchestrator specializing in coordinating [complex workflow].
	190	+
	191	+Your Core Responsibilities:
	192	+1. Coordinate [multi-step process]
	193	+2. Manage [resources/tools/dependencies]
	194	+3. Ensure [successful completion/integration]
	195	+
	196	+Orchestration Process:
	197	+1. Plan: Understand full workflow and dependencies
	198	+2. Prepare: Set up prerequisites
	199	+3. Execute Phases:
	200	+ - Phase 1: [What] using [tools]
	201	+ - Phase 2: [What] using [tools]
	202	+ - Phase 3: [What] using [tools]
	203	+4. Monitor: Track progress and handle failures
	204	+5. Verify: Confirm successful completion
	205	+6. Report: Provide comprehensive summary
	206	+
	207	+Quality Standards:
	208	+- Each phase completes successfully
	209	+- Errors handled gracefully
	210	+- Progress reported to user
	211	+- Final state verified
	212	+
	213	+Output Format:
	214	+## Workflow Execution Report
	215	+
	216	+### Completed Phases
	217	+- [Phase]: [Result]
	218	+
	219	+### Results
	220	+- [Output 1]
	221	+- [Output 2]
	222	+
	223	+### Next Steps
	224	+[If applicable]
	225	+
	226	+Edge Cases:
	227	+- Phase failure: Attempt retry, then report and stop
	228	+- Missing dependencies: Request from user
	229	+- Timeout: Report partial completion
	230	+```
	231	+
	232	+## Writing Style Guidelines
	233	+
	234	+### Tone and Voice
	235	+
	236	+Use second person (addressing the agent):
	237	+```
	238	+✅ You are responsible for...
	239	+✅ You will analyze...
	240	+✅ Your process should...
	241	+
	242	+❌ The agent is responsible for...
	243	+❌ This agent will analyze...
	244	+❌ I will analyze...
	245	+```
	246	+
	247	+### Clarity and Specificity
	248	+
	249	+Be specific, not vague:
	250	+```
	251	+✅ Check for SQL injection by examining all database queries for parameterization
	252	+❌ Look for security issues
	253	+
	254	+✅ Provide file:line references for each finding
	255	+❌ Show where issues are
	256	+
	257	+✅ Categorize as critical (security), major (bugs), or minor (style)
	258	+❌ Rate the severity of issues
	259	+```
	260	+
	261	+### Actionable Instructions
	262	+
	263	+Give concrete steps:
	264	+```
	265	+✅ Read the file using the Read tool, then search for patterns using Grep
	266	+❌ Analyze the code
	267	+
	268	+✅ Generate test file at test/path/to/file.test.ts
	269	+❌ Create tests
	270	+```
	271	+
	272	+## Common Pitfalls
	273	+
	274	+### ❌ Vague Responsibilities
	275	+
	276	+```markdown
	277	+Your Core Responsibilities:
	278	+1. Help the user with their code
	279	+2. Provide assistance
	280	+3. Be helpful
	281	+```
	282	+
	283	+Why bad: Not specific enough to guide behavior.
	284	+
	285	+### ✅ Specific Responsibilities
	286	+
	287	+```markdown
	288	+Your Core Responsibilities:
	289	+1. Analyze TypeScript code for type safety issues
	290	+2. Identify missing type annotations and improper 'any' usage
	291	+3. Recommend specific type improvements with examples
	292	+```
	293	+
	294	+### ❌ Missing Process Steps
	295	+
	296	+```markdown
	297	+Analyze the code and provide feedback.
	298	+```
	299	+
	300	+Why bad: Agent doesn't know HOW to analyze.
	301	+
	302	+### ✅ Clear Process
	303	+
	304	+```markdown
	305	+Analysis Process:
	306	+1. Read code files using Read tool
	307	+2. Scan for type annotations on all functions
	308	+3. Check for 'any' type usage
	309	+4. Verify generic type parameters
	310	+5. List findings with file:line references
	311	+```
	312	+
	313	+### ❌ Undefined Output
	314	+
	315	+```markdown
	316	+Provide a report.
	317	+```
	318	+
	319	+Why bad: Agent doesn't know what format to use.
	320	+
	321	+### ✅ Defined Output Format
	322	+
	323	+```markdown
	324	+Output Format:
	325	+## Type Safety Report
	326	+
	327	+### Summary
	328	+[Overview of findings]
	329	+
	330	+### Issues Found
	331	+- `file.ts:42` - Missing return type on `processData`
	332	+- `utils.ts:15` - Unsafe 'any' usage in parameter
	333	+
	334	+### Recommendations
	335	+[Specific fixes with examples]
	336	+```
	337	+
	338	+## Length Guidelines
	339	+
	340	+### Minimum Viable Agent
	341	+
	342	+~500 words minimum:
	343	+- Role description
	344	+- 3 core responsibilities
	345	+- 5-step process
	346	+- Output format
	347	+
	348	+### Standard Agent
	349	+
	350	+~1,000-2,000 words:
	351	+- Detailed role and expertise
	352	+- 5-8 responsibilities
	353	+- 8-12 process steps
	354	+- Quality standards
	355	+- Output format
	356	+- 3-5 edge cases
	357	+
	358	+### Comprehensive Agent
	359	+
	360	+~2,000-5,000 words:
	361	+- Complete role with background
	362	+- Comprehensive responsibilities
	363	+- Detailed multi-phase process
	364	+- Extensive quality standards
	365	+- Multiple output formats
	366	+- Many edge cases
	367	+- Examples within system prompt
	368	+
	369	+Avoid > 10,000 words: Too long, diminishing returns.
	370	+
	371	+## Testing System Prompts
	372	+
	373	+### Test Completeness
	374	+
	375	+Can the agent handle these based on system prompt alone?
	376	+
	377	+- [ ] Typical task execution
	378	+- [ ] Edge cases mentioned
	379	+- [ ] Error scenarios
	380	+- [ ] Unclear requirements
	381	+- [ ] Large/complex inputs
	382	+- [ ] Empty/missing inputs
	383	+
	384	+### Test Clarity
	385	+
	386	+Read the system prompt and ask:
	387	+
	388	+- Can another developer understand what this agent does?
	389	+- Are process steps clear and actionable?
	390	+- Is output format unambiguous?
	391	+- Are quality standards measurable?
	392	+
	393	+### Iterate Based on Results
	394	+
	395	+After testing agent:
	396	+1. Identify where it struggled
	397	+2. Add missing guidance to system prompt
	398	+3. Clarify ambiguous instructions
	399	+4. Add process steps for edge cases
	400	+5. Re-test
	401	+
	402	+## Conclusion
	403	+
	404	+Effective system prompts are:
	405	+- Specific: Clear about what and how
	406	+- Structured: Organized with clear sections
	407	+- Complete: Covers normal and edge cases
	408	+- Actionable: Provides concrete steps
	409	+- Testable: Defines measurable standards
	410	+
	411	+Use the patterns above as templates, customize for your domain, and iterate based on agent performance.

		@@ -1,0 +1,491 @@
	1	+# Agent Triggering Examples: Best Practices
	2	+
	3	+Complete guide to writing effective `<example>` blocks in agent descriptions for reliable triggering.
	4	+
	5	+## Example Block Format
	6	+
	7	+The standard format for triggering examples:
	8	+
	9	+```markdown
	10	+<example>
	11	+Context: [Describe the situation - what led to this interaction]
	12	+user: "[Exact user message or request]"
	13	+assistant: "[How Claude should respond before triggering]"
	14	+<commentary>
	15	+[Explanation of why this agent should be triggered in this scenario]
	16	+</commentary>
	17	+assistant: "[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']"
	18	+</example>
	19	+```
	20	+
	21	+## Anatomy of a Good Example
	22	+
	23	+### Context
	24	+
	25	+Purpose: Set the scene - what happened before the user's message
	26	+
	27	+Good contexts:
	28	+```
	29	+Context: User just implemented a new authentication feature
	30	+Context: User has created a PR and wants it reviewed
	31	+Context: User is debugging a test failure
	32	+Context: After writing several functions without documentation
	33	+```
	34	+
	35	+Bad contexts:
	36	+```
	37	+Context: User needs help (too vague)
	38	+Context: Normal usage (not specific)
	39	+```
	40	+
	41	+### User Message
	42	+
	43	+Purpose: Show the exact phrasing that should trigger the agent
	44	+
	45	+Good user messages:
	46	+```
	47	+user: "I've added the OAuth flow, can you check it?"
	48	+user: "Review PR #123"
	49	+user: "Why is this test failing?"
	50	+user: "Add docs for these functions"
	51	+```
	52	+
	53	+Vary the phrasing:
	54	+Include multiple examples with different phrasings for the same intent:
	55	+```
	56	+Example 1: user: "Review my code"
	57	+Example 2: user: "Can you check this implementation?"
	58	+Example 3: user: "Look over my changes"
	59	+```
	60	+
	61	+### Assistant Response (Before Triggering)
	62	+
	63	+Purpose: Show what Claude says before launching the agent
	64	+
	65	+Good responses:
	66	+```
	67	+assistant: "I'll analyze your OAuth implementation."
	68	+assistant: "Let me review that PR for you."
	69	+assistant: "I'll investigate the test failure."
	70	+```
	71	+
	72	+Proactive example:
	73	+```
	74	+assistant: "Great! Now let me review the code quality."
	75	+<commentary>
	76	+Code was just written, proactively trigger review agent.
	77	+</commentary>
	78	+```
	79	+
	80	+### Commentary
	81	+
	82	+Purpose: Explain the reasoning - WHY this agent should trigger
	83	+
	84	+Good commentary:
	85	+```
	86	+<commentary>
	87	+User explicitly requested code review, trigger the code-reviewer agent.
	88	+</commentary>
	89	+
	90	+<commentary>
	91	+After code implementation, proactively use review agent to check quality.
	92	+</commentary>
	93	+
	94	+<commentary>
	95	+PR analysis request matches pr-analyzer agent's expertise.
	96	+</commentary>
	97	+```
	98	+
	99	+Include decision logic:
	100	+```
	101	+<commentary>
	102	+User wrote tests (Test tool used). The test-analyzer agent should check
	103	+test quality and coverage before continuing.
	104	+</commentary>
	105	+```
	106	+
	107	+### Assistant Response (Triggering)
	108	+
	109	+Purpose: Show how Claude invokes the agent
	110	+
	111	+Standard pattern:
	112	+```
	113	+assistant: "I'll use the [agent-name] agent to [what it will do]."
	114	+```
	115	+
	116	+Examples:
	117	+```
	118	+assistant: "I'll use the code-reviewer agent to analyze the changes."
	119	+assistant: "Let me use the test-generator agent to create comprehensive tests."
	120	+assistant: "I'll use the security-analyzer agent to check for vulnerabilities."
	121	+```
	122	+
	123	+## Example Types
	124	+
	125	+### Type 1: Explicit Request
	126	+
	127	+User directly asks for what the agent does:
	128	+
	129	+```markdown
	130	+<example>
	131	+Context: User explicitly requests security analysis
	132	+user: "Check my code for security vulnerabilities"
	133	+assistant: "I'll use the security-analyzer agent to perform a thorough security review."
	134	+<commentary>
	135	+Direct security analysis request triggers the security-analyzer agent.
	136	+</commentary>
	137	+</example>
	138	+```
	139	+
	140	+### Type 2: Proactive Triggering
	141	+
	142	+Agent triggers after relevant work without explicit request:
	143	+
	144	+```markdown
	145	+<example>
	146	+Context: User just implemented database queries
	147	+user: "I've added the user search functionality"
	148	+assistant: "Great! Let me review it for security."
	149	+<commentary>
	150	+Database code written. Proactively trigger security-analyzer to check
	151	+for SQL injection and other database security issues.
	152	+</commentary>
	153	+assistant: "I'll use the security-analyzer agent to check the database code."
	154	+</example>
	155	+```
	156	+
	157	+### Type 3: Implicit Request
	158	+
	159	+User implies need without stating it directly:
	160	+
	161	+```markdown
	162	+<example>
	163	+Context: User mentions code is hard to understand
	164	+user: "This code is confusing and hard to follow"
	165	+assistant: "I can help improve the code clarity."
	166	+<commentary>
	167	+User indicates complexity issues. Trigger code-simplifier agent to refactor
	168	+for better readability.
	169	+</commentary>
	170	+assistant: "I'll use the code-simplifier agent to suggest improvements."
	171	+</example>
	172	+```
	173	+
	174	+### Type 4: Tool Usage Pattern
	175	+
	176	+Agent triggers based on prior tool usage:
	177	+
	178	+```markdown
	179	+<example>
	180	+Context: User made multiple edits to test files
	181	+user: "I've updated all the tests"
	182	+assistant: "Great! Let me verify test quality."
	183	+<commentary>
	184	+Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
	185	+to ensure tests follow best practices.
	186	+</commentary>
	187	+assistant: "I'll use the test-quality-analyzer agent to review the tests."
	188	+</example>
	189	+```
	190	+
	191	+## Multiple Examples Strategy
	192	+
	193	+### Cover Different Phrasings
	194	+
	195	+```markdown
	196	+<example>
	197	+user: "Review my code"
	198	+[...]
	199	+</example>
	200	+
	201	+<example>
	202	+user: "Can you check my implementation?"
	203	+[...]
	204	+</example>
	205	+
	206	+<example>
	207	+user: "Look over these changes"
	208	+[...]
	209	+</example>
	210	+```
	211	+
	212	+### Cover Proactive and Reactive
	213	+
	214	+```markdown
	215	+<example>
	216	+Context: User explicitly requests review
	217	+user: "Review my code for issues"
	218	+[...]
	219	+</example>
	220	+
	221	+<example>
	222	+Context: After user writes code
	223	+user: "I've implemented the feature"
	224	+assistant: "Great! Now let me review it."
	225	+<commentary>
	226	+Code written, proactively review.
	227	+</commentary>
	228	+[...]
	229	+</example>
	230	+```
	231	+
	232	+### Cover Edge Cases
	233	+
	234	+```markdown
	235	+<example>
	236	+Context: Typical usage
	237	+user: "Check my PR"
	238	+[...]
	239	+</example>
	240	+
	241	+<example>
	242	+Context: Large PR that needs thorough analysis
	243	+user: "This is a big PR, can you do a deep review?"
	244	+[...]
	245	+<commentary>
	246	+Large PR mentioned, use thorough analysis mode.
	247	+</commentary>
	248	+</example>
	249	+```
	250	+
	251	+## Common Mistakes
	252	+
	253	+### ❌ Missing Context
	254	+
	255	+```markdown
	256	+<example>
	257	+user: "Review my code"
	258	+assistant: "I'll use the code-reviewer agent."
	259	+</example>
	260	+```
	261	+
	262	+Why bad: No context about what led to this request.
	263	+
	264	+### ✅ With Context
	265	+
	266	+```markdown
	267	+<example>
	268	+Context: User just finished implementing authentication
	269	+user: "Review my code"
	270	+assistant: "I'll use the code-reviewer agent to analyze the auth implementation."
	271	+<commentary>
	272	+Auth code written, review for security and best practices.
	273	+</commentary>
	274	+</example>
	275	+```
	276	+
	277	+### ❌ No Commentary
	278	+
	279	+```markdown
	280	+<example>
	281	+Context: User requests review
	282	+user: "Check my changes"
	283	+assistant: "I'll use the reviewer agent."
	284	+</example>
	285	+```
	286	+
	287	+Why bad: Doesn't explain WHY agent triggers.
	288	+
	289	+### ✅ With Commentary
	290	+
	291	+```markdown
	292	+<example>
	293	+Context: User requests review after making changes
	294	+user: "Check my changes"
	295	+assistant: "I'll use the code-reviewer agent to analyze the modifications."
	296	+<commentary>
	297	+Code review request triggers agent to check quality, security, and adherence to standards.
	298	+</commentary>
	299	+</example>
	300	+```
	301	+
	302	+### ❌ Agent Responds Directly
	303	+
	304	+```markdown
	305	+<example>
	306	+user: "Review my code"
	307	+assistant: "I found the following issues: [lists issues]"
	308	+</example>
	309	+```
	310	+
	311	+Why bad: Shows agent's output, not triggering.
	312	+
	313	+### ✅ Shows Triggering
	314	+
	315	+```markdown
	316	+<example>
	317	+user: "Review my code"
	318	+assistant: "I'll use the code-reviewer agent to perform the review."
	319	+<commentary>
	320	+Review request triggers the agent.
	321	+</commentary>
	322	+</example>
	323	+```
	324	+
	325	+## How Many Examples?
	326	+
	327	+### Minimum: 2 Examples
	328	+
	329	+Cover at least:
	330	+1. Explicit request
	331	+2. One variation or proactive trigger
	332	+
	333	+### Recommended: 3-4 Examples
	334	+
	335	+Cover:
	336	+1. Explicit request (direct ask)
	337	+2. Implicit request (user implies need)
	338	+3. Proactive trigger (after relevant work)
	339	+4. Edge case or specific scenario
	340	+
	341	+### Maximum: 6 Examples
	342	+
	343	+More than 6 makes description too long. Focus on most important scenarios.
	344	+
	345	+## Template Library
	346	+
	347	+### Code Review Agent
	348	+
	349	+```markdown
	350	+<example>
	351	+Context: User just implemented a new feature
	352	+user: "I've added the user registration feature"
	353	+assistant: "Great! Let me review the code quality."
	354	+<commentary>
	355	+Code written, proactively trigger code-reviewer agent.
	356	+</commentary>
	357	+assistant: "I'll use the code-reviewer agent to analyze the implementation."
	358	+</example>
	359	+
	360	+<example>
	361	+Context: User explicitly requests review
	362	+user: "Can you review my changes for issues?"
	363	+assistant: "I'll use the code-reviewer agent to perform a thorough review."
	364	+<commentary>
	365	+Explicit review request triggers the agent.
	366	+</commentary>
	367	+</example>
	368	+```
	369	+
	370	+### Test Generation Agent
	371	+
	372	+```markdown
	373	+<example>
	374	+Context: User implemented functions without tests
	375	+user: "I've added the data processing functions"
	376	+assistant: "Great! Let me generate tests for these."
	377	+<commentary>
	378	+New code without tests, proactively trigger test-generator agent.
	379	+</commentary>
	380	+assistant: "I'll use the test-generator agent to create comprehensive tests."
	381	+</example>
	382	+
	383	+<example>
	384	+Context: User explicitly asks for tests
	385	+user: "Generate tests for my code"
	386	+assistant: "I'll use the test-generator agent to create a complete test suite."
	387	+<commentary>
	388	+Direct test generation request triggers the agent.
	389	+</commentary>
	390	+</example>
	391	+```
	392	+
	393	+### Documentation Agent
	394	+
	395	+```markdown
	396	+<example>
	397	+Context: User added new API endpoints
	398	+user: "I've implemented the REST API endpoints"
	399	+assistant: "I'll document these endpoints."
	400	+<commentary>
	401	+New API code, proactively generate documentation.
	402	+</commentary>
	403	+assistant: "I'll use the api-docs-writer agent to create comprehensive documentation."
	404	+</example>
	405	+
	406	+<example>
	407	+Context: User requests documentation
	408	+user: "Write docs for this API"
	409	+assistant: "I'll use the api-docs-writer agent to generate clear documentation."
	410	+<commentary>
	411	+Documentation request triggers the agent.
	412	+</commentary>
	413	+</example>
	414	+```
	415	+
	416	+### Validation Agent
	417	+
	418	+```markdown
	419	+<example>
	420	+Context: User ready to commit changes
	421	+user: "I'm ready to commit this code"
	422	+assistant: "Let me validate it first."
	423	+<commentary>
	424	+Before commit, proactively validate with validation-agent.
	425	+</commentary>
	426	+assistant: "I'll use the code-validator agent to check for issues."
	427	+</example>
	428	+
	429	+<example>
	430	+Context: User asks for validation
	431	+user: "Validate my implementation"
	432	+assistant: "I'll use the code-validator agent to verify correctness."
	433	+<commentary>
	434	+Explicit validation request triggers the agent.
	435	+</commentary>
	436	+</example>
	437	+```
	438	+
	439	+## Debugging Triggering Issues
	440	+
	441	+### Agent Not Triggering
	442	+
	443	+Check:
	444	+1. Examples include relevant keywords from user message
	445	+2. Context matches actual usage scenarios
	446	+3. Commentary explains triggering logic clearly
	447	+4. Assistant shows use of Agent tool in examples
	448	+
	449	+Fix:
	450	+Add more examples covering different phrasings.
	451	+
	452	+### Agent Triggers Too Often
	453	+
	454	+Check:
	455	+1. Examples are too broad or generic
	456	+2. Triggering conditions overlap with other agents
	457	+3. Commentary doesn't distinguish when NOT to use
	458	+
	459	+Fix:
	460	+Make examples more specific, add negative examples.
	461	+
	462	+### Agent Triggers in Wrong Scenarios
	463	+
	464	+Check:
	465	+1. Examples don't match actual intended use
	466	+2. Commentary suggests inappropriate triggering
	467	+
	468	+Fix:
	469	+Revise examples to show only correct triggering scenarios.
	470	+
	471	+## Best Practices Summary
	472	+
	473	+✅ DO:
	474	+- Include 2-4 concrete, specific examples
	475	+- Show both explicit and proactive triggering
	476	+- Provide clear context for each example
	477	+- Explain reasoning in commentary
	478	+- Vary user message phrasing
	479	+- Show Claude using Agent tool
	480	+
	481	+❌ DON'T:
	482	+- Use generic, vague examples
	483	+- Omit context or commentary
	484	+- Show only one type of triggering
	485	+- Skip the agent invocation step
	486	+- Make examples too similar
	487	+- Forget to explain why agent triggers
	488	+
	489	+## Conclusion
	490	+
	491	+Well-crafted examples are crucial for reliable agent triggering. Invest time in creating diverse, specific examples that clearly demonstrate when and why the agent should be used.

		@@ -1,0 +1,217 @@
	1	+#!/bin/bash
	2	+# Agent File Validator
	3	+# Validates agent markdown files for correct structure and content
	4	+
	5	+set -euo pipefail
	6	+
	7	+# Usage
	8	+if [ $# -eq 0 ]; then
	9	+ echo "Usage: $0 <path/to/agent.md>"
	10	+ echo ""
	11	+ echo "Validates agent file for:"
	12	+ echo " - YAML frontmatter structure"
	13	+ echo " - Required fields (name, description, model, color)"
	14	+ echo " - Field formats and constraints"
	15	+ echo " - System prompt presence and length"
	16	+ echo " - Example blocks in description"
	17	+ exit 1
	18	+fi
	19	+
	20	+AGENT_FILE="$1"
	21	+
	22	+echo "🔍 Validating agent file: $AGENT_FILE"
	23	+echo ""
	24	+
	25	+# Check 1: File exists
	26	+if [ ! -f "$AGENT_FILE" ]; then
	27	+ echo "❌ File not found: $AGENT_FILE"
	28	+ exit 1
	29	+fi
	30	+echo "✅ File exists"
	31	+
	32	+# Check 2: Starts with ---
	33	+FIRST_LINE=$(head -1 "$AGENT_FILE")
	34	+if [ "$FIRST_LINE" != "---" ]; then
	35	+ echo "❌ File must start with YAML frontmatter (---)"
	36	+ exit 1
	37	+fi
	38	+echo "✅ Starts with frontmatter"
	39	+
	40	+# Check 3: Has closing ---
	41	+if ! tail -n +2 "$AGENT_FILE" \| grep -q '^---$'; then
	42	+ echo "❌ Frontmatter not closed (missing second ---)"
	43	+ exit 1
	44	+fi
	45	+echo "✅ Frontmatter properly closed"
	46	+
	47	+# Extract frontmatter and system prompt
	48	+FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$AGENT_FILE")
	49	+SYSTEM_PROMPT=$(awk '/^---$/{i++; next} i>=2' "$AGENT_FILE")
	50	+
	51	+# Check 4: Required fields
	52	+echo ""
	53	+echo "Checking required fields..."
	54	+
	55	+error_count=0
	56	+warning_count=0
	57	+
	58	+# Check name field
	59	+NAME=$(echo "$FRONTMATTER" \| grep '^name:' \| sed 's/name: //' \| sed 's/^"\(.\)"$/\1/')
	60	+
	61	+if [ -z "$NAME" ]; then
	62	+ echo "❌ Missing required field: name"
	63	+ ((error_count++))
	64	+else
	65	+ echo "✅ name: $NAME"
	66	+
	67	+ # Validate name format
	68	+ if ! [[ "$NAME" =~ ^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$ ]]; then
	69	+ echo "❌ name must start/end with alphanumeric and contain only letters, numbers, hyphens"
	70	+ ((error_count++))
	71	+ fi
	72	+
	73	+ # Validate name length
	74	+ name_length=${#NAME}
	75	+ if [ $name_length -lt 3 ]; then
	76	+ echo "❌ name too short (minimum 3 characters)"
	77	+ ((error_count++))
	78	+ elif [ $name_length -gt 50 ]; then
	79	+ echo "❌ name too long (maximum 50 characters)"
	80	+ ((error_count++))
	81	+ fi
	82	+
	83	+ # Check for generic names
	84	+ if [[ "$NAME" =~ ^(helper\|assistant\|agent\|tool)$ ]]; then
	85	+ echo "⚠️ name is too generic: $NAME"
	86	+ ((warning_count++))
	87	+ fi
	88	+fi
	89	+
	90	+# Check description field
	91	+DESCRIPTION=$(echo "$FRONTMATTER" \| grep '^description:' \| sed 's/description: *//')
	92	+
	93	+if [ -z "$DESCRIPTION" ]; then
	94	+ echo "❌ Missing required field: description"
	95	+ ((error_count++))
	96	+else
	97	+ desc_length=${#DESCRIPTION}
	98	+ echo "✅ description: ${desc_length} characters"
	99	+
	100	+ if [ $desc_length -lt 10 ]; then
	101	+ echo "⚠️ description too short (minimum 10 characters recommended)"
	102	+ ((warning_count++))
	103	+ elif [ $desc_length -gt 5000 ]; then
	104	+ echo "⚠️ description very long (over 5000 characters)"
	105	+ ((warning_count++))
	106	+ fi
	107	+
	108	+ # Check for example blocks
	109	+ if ! echo "$DESCRIPTION" \| grep -q '<example>'; then
	110	+ echo "⚠️ description should include <example> blocks for triggering"
	111	+ ((warning_count++))
	112	+ fi
	113	+
	114	+ # Check for "Use this agent when" pattern
	115	+ if ! echo "$DESCRIPTION" \| grep -qi 'use this agent when'; then
	116	+ echo "⚠️ description should start with 'Use this agent when...'"
	117	+ ((warning_count++))
	118	+ fi
	119	+fi
	120	+
	121	+# Check model field
	122	+MODEL=$(echo "$FRONTMATTER" \| grep '^model:' \| sed 's/model: *//')
	123	+
	124	+if [ -z "$MODEL" ]; then
	125	+ echo "❌ Missing required field: model"
	126	+ ((error_count++))
	127	+else
	128	+ echo "✅ model: $MODEL"
	129	+
	130	+ case "$MODEL" in
	131	+ inherit\|sonnet\|opus\|haiku)
	132	+ # Valid model
	133	+ ;;
	134	+ *)
	135	+ echo "⚠️ Unknown model: $MODEL (valid: inherit, sonnet, opus, haiku)"
	136	+ ((warning_count++))
	137	+ ;;
	138	+ esac
	139	+fi
	140	+
	141	+# Check color field
	142	+COLOR=$(echo "$FRONTMATTER" \| grep '^color:' \| sed 's/color: *//')
	143	+
	144	+if [ -z "$COLOR" ]; then
	145	+ echo "❌ Missing required field: color"
	146	+ ((error_count++))
	147	+else
	148	+ echo "✅ color: $COLOR"
	149	+
	150	+ case "$COLOR" in
	151	+ blue\|cyan\|green\|yellow\|magenta\|red)
	152	+ # Valid color
	153	+ ;;
	154	+ *)
	155	+ echo "⚠️ Unknown color: $COLOR (valid: blue, cyan, green, yellow, magenta, red)"
	156	+ ((warning_count++))
	157	+ ;;
	158	+ esac
	159	+fi
	160	+
	161	+# Check tools field (optional)
	162	+TOOLS=$(echo "$FRONTMATTER" \| grep '^tools:' \| sed 's/tools: *//')
	163	+
	164	+if [ -n "$TOOLS" ]; then
	165	+ echo "✅ tools: $TOOLS"
	166	+else
	167	+ echo "💡 tools: not specified (agent has access to all tools)"
	168	+fi
	169	+
	170	+# Check 5: System prompt
	171	+echo ""
	172	+echo "Checking system prompt..."
	173	+
	174	+if [ -z "$SYSTEM_PROMPT" ]; then
	175	+ echo "❌ System prompt is empty"
	176	+ ((error_count++))
	177	+else
	178	+ prompt_length=${#SYSTEM_PROMPT}
	179	+ echo "✅ System prompt: $prompt_length characters"
	180	+
	181	+ if [ $prompt_length -lt 20 ]; then
	182	+ echo "❌ System prompt too short (minimum 20 characters)"
	183	+ ((error_count++))
	184	+ elif [ $prompt_length -gt 10000 ]; then
	185	+ echo "⚠️ System prompt very long (over 10,000 characters)"
	186	+ ((warning_count++))
	187	+ fi
	188	+
	189	+ # Check for second person
	190	+ if ! echo "$SYSTEM_PROMPT" \| grep -q "You are\\|You will\\|Your"; then
	191	+ echo "⚠️ System prompt should use second person (You are..., You will...)"
	192	+ ((warning_count++))
	193	+ fi
	194	+
	195	+ # Check for structure
	196	+ if ! echo "$SYSTEM_PROMPT" \| grep -qi "responsibilities\\|process\\|steps"; then
	197	+ echo "💡 Consider adding clear responsibilities or process steps"
	198	+ fi
	199	+
	200	+ if ! echo "$SYSTEM_PROMPT" \| grep -qi "output"; then
	201	+ echo "💡 Consider defining output format expectations"
	202	+ fi
	203	+fi
	204	+
	205	+echo ""
	206	+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
	207	+
	208	+if [ $error_count -eq 0 ] && [ $warning_count -eq 0 ]; then
	209	+ echo "✅ All checks passed!"
	210	+ exit 0
	211	+elif [ $error_count -eq 0 ]; then
	212	+ echo "⚠️ Validation passed with $warning_count warning(s)"
	213	+ exit 0
	214	+else
	215	+ echo "❌ Validation failed with $error_count error(s) and $warning_count warning(s)"
	216	+ exit 1
	217	+fi

		@@ -1,0 +1,272 @@
	1	+# Command Development Skill
	2	+
	3	+Comprehensive guidance on creating Claude Code slash commands, including file format, frontmatter options, dynamic arguments, and best practices.
	4	+
	5	+## Overview
	6	+
	7	+This skill provides knowledge about:
	8	+- Slash command file format and structure
	9	+- YAML frontmatter configuration fields
	10	+- Dynamic arguments ($ARGUMENTS, $1, $2, etc.)
	11	+- File references with @ syntax
	12	+- Bash execution with !` syntax
	13	+- Command organization and namespacing
	14	+- Best practices for command development
	15	+- Plugin-specific features (${CLAUDE_PLUGIN_ROOT}, plugin patterns)
	16	+- Integration with plugin components (agents, skills, hooks)
	17	+- Validation patterns and error handling
	18	+
	19	+## Skill Structure
	20	+
	21	+### SKILL.md (~2,470 words)
	22	+
	23	+Core skill content covering:
	24	+
	25	+Fundamentals:
	26	+- Command basics and locations
	27	+- File format (Markdown with optional frontmatter)
	28	+- YAML frontmatter fields overview
	29	+- Dynamic arguments ($ARGUMENTS and positional)
	30	+- File references (@ syntax)
	31	+- Bash execution (!` syntax)
	32	+- Command organization patterns
	33	+- Best practices and common patterns
	34	+- Troubleshooting
	35	+
	36	+Plugin-Specific:
	37	+- ${CLAUDE_PLUGIN_ROOT} environment variable
	38	+- Plugin command discovery and organization
	39	+- Plugin command patterns (configuration, template, multi-script)
	40	+- Integration with plugin components (agents, skills, hooks)
	41	+- Validation patterns (argument, file, resource, error handling)
	42	+
	43	+### References
	44	+
	45	+Detailed documentation:
	46	+
	47	+- frontmatter-reference.md: Complete YAML frontmatter field specifications
	48	+ - All field descriptions with types and defaults
	49	+ - When to use each field
	50	+ - Examples and best practices
	51	+ - Validation and common errors
	52	+
	53	+- plugin-features-reference.md: Plugin-specific command features
	54	+ - Plugin command discovery and organization
	55	+ - ${CLAUDE_PLUGIN_ROOT} environment variable usage
	56	+ - Plugin command patterns (configuration, template, multi-script)
	57	+ - Integration with plugin agents, skills, and hooks
	58	+ - Validation patterns and error handling
	59	+
	60	+### Examples
	61	+
	62	+Practical command examples:
	63	+
	64	+- simple-commands.md: 10 complete command examples
	65	+ - Code review commands
	66	+ - Testing commands
	67	+ - Deployment commands
	68	+ - Documentation generators
	69	+ - Git integration commands
	70	+ - Analysis and research commands
	71	+
	72	+- plugin-commands.md: 10 plugin-specific command examples
	73	+ - Simple plugin commands with scripts
	74	+ - Multi-script workflows
	75	+ - Template-based generation
	76	+ - Configuration-driven deployment
	77	+ - Agent and skill integration
	78	+ - Multi-component workflows
	79	+ - Validated input commands
	80	+ - Environment-aware commands
	81	+
	82	+## When This Skill Triggers
	83	+
	84	+Claude Code activates this skill when users:
	85	+- Ask to "create a slash command" or "add a command"
	86	+- Need to "write a custom command"
	87	+- Want to "define command arguments"
	88	+- Ask about "command frontmatter" or YAML configuration
	89	+- Need to "organize commands" or use namespacing
	90	+- Want to create commands with file references
	91	+- Ask about "bash execution in commands"
	92	+- Need command development best practices
	93	+
	94	+## Progressive Disclosure
	95	+
	96	+The skill uses progressive disclosure:
	97	+
	98	+1. SKILL.md (~2,470 words): Core concepts, common patterns, and plugin features overview
	99	+2. References (~13,500 words total): Detailed specifications
	100	+ - frontmatter-reference.md (~1,200 words)
	101	+ - plugin-features-reference.md (~1,800 words)
	102	+ - interactive-commands.md (~2,500 words)
	103	+ - advanced-workflows.md (~1,700 words)
	104	+ - testing-strategies.md (~2,200 words)
	105	+ - documentation-patterns.md (~2,000 words)
	106	+ - marketplace-considerations.md (~2,200 words)
	107	+3. Examples (~6,000 words total): Complete working command examples
	108	+ - simple-commands.md
	109	+ - plugin-commands.md
	110	+
	111	+Claude loads references and examples as needed based on task.
	112	+
	113	+## Command Basics Quick Reference
	114	+
	115	+### File Format
	116	+
	117	+```markdown
	118	+---
	119	+description: Brief description
	120	+argument-hint: [arg1] [arg2]
	121	+allowed-tools: Read, Bash(git:*)
	122	+---
	123	+
	124	+Command prompt content with:
	125	+- Arguments: $1, $2, or $ARGUMENTS
	126	+- Files: @path/to/file
	127	+- Bash: !`command here`
	128	+```
	129	+
	130	+### Locations
	131	+
	132	+- Project: `.claude/commands/` (shared with team)
	133	+- Personal: `~/.claude/commands/` (your commands)
	134	+- Plugin: `plugin-name/commands/` (plugin-specific)
	135	+
	136	+### Key Features
	137	+
	138	+Dynamic arguments:
	139	+- `$ARGUMENTS` - All arguments as single string
	140	+- `$1`, `$2`, `$3` - Positional arguments
	141	+
	142	+File references:
	143	+- `@path/to/file` - Include file contents
	144	+
	145	+Bash execution:
	146	+- `!`command`` - Execute and include output
	147	+
	148	+## Frontmatter Fields Quick Reference
	149	+
	150	+\| Field \| Purpose \| Example \|
	151	+\|-------\|---------\|---------\|
	152	+\| `description` \| Brief description for /help \| `"Review code for issues"` \|
	153	+\| `allowed-tools` \| Restrict tool access \| `Read, Bash(git:*)` \|
	154	+\| `model` \| Specify model \| `sonnet`, `opus`, `haiku` \|
	155	+\| `argument-hint` \| Document arguments \| `[pr-number] [priority]` \|
	156	+\| `disable-model-invocation` \| Manual-only command \| `true` \|
	157	+
	158	+## Common Patterns
	159	+
	160	+### Simple Review Command
	161	+
	162	+```markdown
	163	+---
	164	+description: Review code for issues
	165	+---
	166	+
	167	+Review this code for quality and potential bugs.
	168	+```
	169	+
	170	+### Command with Arguments
	171	+
	172	+```markdown
	173	+---
	174	+description: Deploy to environment
	175	+argument-hint: [environment] [version]
	176	+---
	177	+
	178	+Deploy to $1 environment using version $2
	179	+```
	180	+
	181	+### Command with File Reference
	182	+
	183	+```markdown
	184	+---
	185	+description: Document file
	186	+argument-hint: [file-path]
	187	+---
	188	+
	189	+Generate documentation for @$1
	190	+```
	191	+
	192	+### Command with Bash Execution
	193	+
	194	+```markdown
	195	+---
	196	+description: Show Git status
	197	+allowed-tools: Bash(git:*)
	198	+---
	199	+
	200	+Current status: !`git status`
	201	+Recent commits: !`git log --oneline -5`
	202	+```
	203	+
	204	+## Development Workflow
	205	+
	206	+1. Design command:
	207	+ - Define purpose and scope
	208	+ - Determine required arguments
	209	+ - Identify needed tools
	210	+
	211	+2. Create file:
	212	+ - Choose appropriate location
	213	+ - Create `.md` file with command name
	214	+ - Write basic prompt
	215	+
	216	+3. Add frontmatter:
	217	+ - Start minimal (just description)
	218	+ - Add fields as needed (allowed-tools, etc.)
	219	+ - Document arguments with argument-hint
	220	+
	221	+4. Test command:
	222	+ - Invoke with `/command-name`
	223	+ - Verify arguments work
	224	+ - Check bash execution
	225	+ - Test file references
	226	+
	227	+5. Refine:
	228	+ - Improve prompt clarity
	229	+ - Handle edge cases
	230	+ - Add examples in comments
	231	+ - Document requirements
	232	+
	233	+## Best Practices Summary
	234	+
	235	+1. Single responsibility: One command, one clear purpose
	236	+2. Clear descriptions: Make discoverable in `/help`
	237	+3. Document arguments: Always use argument-hint
	238	+4. Minimal tools: Use most restrictive allowed-tools
	239	+5. Test thoroughly: Verify all features work
	240	+6. Add comments: Explain complex logic
	241	+7. Handle errors: Consider missing arguments/files
	242	+
	243	+## Status
	244	+
	245	+Completed enhancements:
	246	+- ✓ Plugin command patterns (${CLAUDE_PLUGIN_ROOT}, discovery, organization)
	247	+- ✓ Integration patterns (agents, skills, hooks coordination)
	248	+- ✓ Validation patterns (input, file, resource validation, error handling)
	249	+
	250	+Remaining enhancements (in progress):
	251	+- Advanced workflows (multi-step command sequences)
	252	+- Testing strategies (how to test commands effectively)
	253	+- Documentation patterns (command documentation best practices)
	254	+- Marketplace considerations (publishing and distribution)
	255	+
	256	+## Maintenance
	257	+
	258	+To update this skill:
	259	+1. Keep SKILL.md focused on core fundamentals
	260	+2. Move detailed specifications to references/
	261	+3. Add new examples/ for different use cases
	262	+4. Update frontmatter when new fields added
	263	+5. Ensure imperative/infinitive form throughout
	264	+6. Test examples work with current Claude Code
	265	+
	266	+## Version History
	267	+
	268	+v0.1.0 (2025-01-15):
	269	+- Initial release with basic command fundamentals
	270	+- Frontmatter field reference
	271	+- 10 simple command examples
	272	+- Ready for plugin-specific pattern additions