plugin-sdk-patterns

# Plugin SDK Patterns ## Overview This skill documents unified patterns and templates for creating consistent, professional Claude Code plugins. Following these patterns ensures your plugins integrate seamlessly with Claude Code's ecosystem and provide a predictable developer experience. ### Why Standardized Plugin Patterns Matter **Consistency**: Users expect the same structure across all plugins, making them easier to learn and use. **Maintainability**: Standard patterns make it easier to update and extend plugins over time. **Discoverability**: Consistent naming and structure helps users find what they need quickly. **Quality**: Templates enforce best practices and reduce common errors. **Collaboration**: Teams can work together more effectively with shared conventions. ### The Builder Pattern Approach Claude Code plugins follow a **builder pattern** where components (skills, commands, agents, hooks) are modular and composable: - Each component is self-contained in its own directory - Components declare their metadata via frontmatter - The plugin.json manifest ties everything together - Hooks provide lifecycle integration points ### Plugin Anatomy ``` my-plugin/ ├── plugin.json # Plugin manifest (required) ├── README.md # User-facing documentation ├── DEPENDENCIES.md # External dependencies (if any) ├── skills/ # Reusable knowledge modules │ ├── skill-one/ │ │ └── SKILL.md │ └── skill-two/ │ └── SKILL.md ├── commands/ # Interactive commands │ ├── command-one.md │ └── command-two.md ├── agents/ # Autonomous agents │ ├── agent-one.md │ └── agent-two.md ├── hooks/ # Lifecycle hooks (optional) │ └── hooks.json ├── mcp-servers/ # MCP server configurations (optional) │ └── servers.json └── examples/ # Example workflows (optional) └── example-workflow.md ``` ## Plugin Manifest (plugin.json) Template ### Complete Template ```json { "name": "my-plugin", "version": "1.0.0", "description": "Brief description of what the plugin does", "author": "Your Name <email@example.com>", "license": "MIT", "homepage": "https://github.com/yourusername/your-repo", "repository": { "type": "git", "url": "https://github.com/yourusername/your-repo.git" }, "tags": ["category1", "category2", "category3"], "keywords": ["keyword1", "keyword2", "keyword3"], "skills": [ { "name": "skill-one", "path": "skills/skill-one/SKILL.md", "description": "Brief description of skill one" }, { "name": "skill-two", "path": "skills/skill-two/SKILL.md", "description": "Brief description of skill two" } ], "skillBundles": [ { "name": "core-bundle", "description": "Core skills for basic functionality", "skills": ["skill-one", "skill-two"] } ], "commands": [ { "name": "/command-one", "path": "commands/command-one.md", "description": "Brief description of command one" } ], "agents": [ { "name": "agent-one", "path": "agents/agent-one.md", "description": "Brief description of agent one" } ], "hooks": { "enabled": true, "configPath": "hooks/hooks.json" }, "mcpServers": { "enabled": true, "configPath": "mcp-servers/servers.json" }, "dependencies": { "system": ["node>=18.0.0", "git"], "npm": ["package-name@^1.0.0"], "plugins": ["other-plugin@marketplace-name"] }, "compatibility": { "claudeCode": ">=1.0.0" } } ``` ### Field Descriptions **Core Metadata:** - `name` (required): Lowercase, hyphen-separated plugin identifier - `version` (required): Semantic version (MAJOR.MINOR.PATCH) - `description` (required): One-sentence summary (under 150 characters) - `author`: Name and email in standard format - `license`: SPDX license identifier (typically MIT) - `homepage`: Primary documentation URL - `repository`: Git repository information **Discovery:** - `tags`: Broad categories (e.g., "frontend", "backend", "testing") - `keywords`: Specific search terms (e.g., "react", "typescript", "api") **Components:** - `skills`: Array of skill definitions - `skillBundles`: Logical groupings of skills for auto-load - `commands`: Array of command definitions - `agents`: Array of agent definitions **Integration:** - `hooks`: Lifecycle hook configuration - `mcpServers`: MCP server configuration - `dependencies`: External requirements - `compatibility`: Claude Code version requirements ## Skill File Template ### Standard SKILL.md Structure ```markdown --- name: skill-name description: Clear, concise description of what this skill teaches. Include trigger keywords and use cases. Trigger keywords - "keyword1", "keyword2", "keyword3". version: 1.0.0 tags: [category1, category2, category3] keywords: [keyword1, keyword2, keyword3, keyword4] plugin: plugin-name updated: 2026-01-28 --- # Skill Name ## Overview Brief introduction to the skill and its purpose. Explain when to use this skill and what problems it solves. ### Key Concepts - **Concept 1**: Brief explanation - **Concept 2**: Brief explanation - **Concept 3**: Brief explanation ### When to Use This Skill - Scenario 1 - Scenario 2 - Scenario 3 ## Core Patterns ### Pattern 1: Pattern Name **Purpose**: Why this pattern exists **Structure**: ``` Example code or structure ``` **Usage**: - Step 1 - Step 2 - Step 3 **Best Practices**: - Do this - Don't do that ### Pattern 2: Pattern Name (Same structure as Pattern 1) ## Integration ### With Other Skills How this skill works alongside other skills in your plugin or ecosystem. ### With Tools Which Claude Code tools are most relevant: - Read/Write/Edit for file operations - Bash for system commands - Grep/Glob for searching - Task for delegation ### With External Systems Any external dependencies or integrations. ## Best Practices ### Do - ✅ Best practice 1 - ✅ Best practice 2 - ✅ Best practice 3 ### Don't - ❌ Anti-pattern 1 - ❌ Anti-pattern 2 - ❌ Anti-pattern 3 ## Examples ### Example 1: Basic Usage **Scenario**: Clear description of the use case **Implementation**: ``` Code or step-by-step example ``` **Result**: Expected outcome ### Example 2: Advanced Usage (Same structure as Example 1) ## Troubleshooting ### Common Issues **Issue 1**: Problem description - **Cause**: Why it happens - **Solution**: How to fix it **Issue 2**: Problem description - **Cause**: Why it happens - **Solution**: How to fix it ## Summary ### Key Takeaways - Takeaway 1 - Takeaway 2 - Takeaway 3 ### Quick Reference | Scenario | Pattern to Use | Key Points | |----------|---------------|------------| | Scenario 1 | Pattern 1 | Point 1, Point 2 | | Scenario 2 | Pattern 2 | Point 1, Point 2 | --- *Inspired by [Source/Project Name]* ``` ### Frontmatter Fields **Required:** - `name`: Lowercase, hyphen-separated identifier - `description`: Include trigger keywords and use cases - `version`: Semantic version - `plugin`: Parent plugin name - `updated`: ISO date (YYYY-MM-DD) **Recommended:** - `tags`: 3-5 broad categories - `keywords`: 5-10 specific terms for search ### Section Guidelines **Overview** (50-100 lines): - Introduction and purpose - Key concepts - When to use **Core Patterns** (100-200 lines): - 2-5 main patterns - Each with purpose, structure, usage, best practices **Integration** (30-50 lines): - How it works with other components - Tool usage recommendations **Best Practices** (30-50 lines): - Do/Don't lists - Common pitfalls **Examples** (50-100 lines): - 2-3 concrete examples - Scenario, implementation, result **Troubleshooting** (30-50 lines): - Common issues and solutions **Summary** (20-30 lines): - Key takeaways - Quick reference table ## Command File Template ### Standard Command Structure ```markdown --- name: /command-name description: Brief description of what this command does version: 1.0.0 plugin: plugin-name updated: 2026-01-28 --- <role> <identity>Clear Role Name</identity> <expertise> - Expertise area 1 - Expertise area 2 - Expertise area 3 </expertise> <mission> Single-sentence mission statement describing the command's purpose. </mission> </role> <instructions> <critical_constraints> <constraint name="Constraint 1"> Description of the constraint and why it matters. </constraint> <constraint name="Constraint 2"> Description of the constraint and why it matters. </constraint> </critical_constraints> <workflow> <phase number="1" name="Phase Name"> <objective>What this phase accomplishes</objective> <steps> <step>Specific action 1</step> <step>Specific action 2</step> <step>Specific action 3</step> </steps> <output>What gets produced</output> </phase> <phase number="2" name="Phase Name"> (Same structure as Phase 1) </phase> </workflow> <validation> <check>Validation check 1</check> <check>Validation check 2</check> <error_handling>How to handle failures</error_handling> </validation> </instructions> <examples> <example name="Example 1"> <scenario>Description of the scenario</scenario> <execution> ``` Example input/output ``` </execution> <result>Expected outcome</result> </example> </examples> <formatting> <communication_style> - Guideline 1 - Guideline 2 </communication_style> <completion_message> ## Command Complete **Summary**: Brief summary of what was done **Output**: Description of the output **Next Steps**: Recommended actions </completion_message> </formatting> ``` ### Command Design Principles **Single Responsibility**: Each command should do one thing well. **Clear Phases**: Break work into distinct, sequential phases. **Validation**: Always validate inputs and outputs. **Error Handling**: Provide clear error messages and recovery steps. **Examples**: Include 2-3 concrete usage examples. ## Agent File Template ### Standard Agent Structure ```markdown --- name: agent-name description: Brief description of the agent's purpose and capabilities version: 1.0.0 tools: [Read, Write, Edit, Bash, Grep, Glob, Task] plugin: plugin-name updated: 2026-01-28 --- <role> <identity>Clear Agent Identity</identity> <expertise> - Domain area 1 - Domain area 2 - Domain area 3 </expertise> <mission> Single-sentence mission statement describing what the agent does. </mission> </role> <instructions> <critical_constraints> <constraint name="Tool Usage"> - Prefer X tool for Y operations - Never use Z for W operations - Always validate before executing </constraint> <constraint name="Quality Standards"> - Standard 1 - Standard 2 - Standard 3 </constraint> </critical_constraints> <workflow> <phase number="1" name="Analysis"> <objective>Understand the task and codebase</objective> <actions> <action>Use Grep to find relevant files</action> <action>Use Read to understand existing patterns</action> <action>Identify what needs to be done</action> </actions> </phase> <phase number="2" name="Planning"> <objective>Create implementation plan</objective> <actions> <action>Break down task into steps</action> <action>Identify dependencies</action> <action>Choose appropriate patterns</action> </actions> </phase> <phase number="3" name="Implementation">