Initial commit

skills/plugin-builder/SKILL.md

@@ -0,0 +1,453 @@
+---
+name: Creating and Editing Claude Plugins
+description: Use before creating or editing plugin.json manifests, organizing .claude-plugin directories, or when user asks about plugin structure, versioning, or distribution. Provides expert guidance on manifest configuration, component organization, semantic versioning, and shareable plugin best practices. Invoke when working with any plugin files or discussing plugin architecture to ensure correct structure and discoverability.
+---
+
+# Building Claude Code Plugins
+
+This skill provides comprehensive guidance for creating Claude Code plugins that extend Claude with shareable, discoverable functionality.
+
+## What Are Claude Code Plugins?
+
+Plugins are packages of functionality that can be shared across projects and teams. They can contain:
+- **Custom slash commands**: User-invoked commands
+- **Custom agents**: Specialized agent behaviors
+- **Agent skills**: Reusable capabilities agents can invoke
+- **Event hooks**: Handlers that trigger on specific events
+- **MCP servers**: External tool integrations
+
+Plugins are discoverable through plugin marketplaces and easy to install with `/plugin install`.
+
+## Core Requirements
+
+Every plugin requires exactly one file: `.claude-plugin/plugin.json`
+
+**Minimum valid plugin:**
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0"
+}
+```
+
+All other components (commands, agents, skills, hooks, MCP servers) are optional.
+
+## Quick Start
+
+1. **Create plugin directory**: `mkdir my-plugin`
+2. **Create manifest**: `mkdir my-plugin/.claude-plugin`
+3. **Create plugin.json** with name and version
+4. **Add components** (skills, commands, etc.) as needed
+5. **Test locally**: `/plugin install /path/to/my-plugin`
+
+For complete templates, see `templates/plugin.json` and `templates/README.md`.
+
+## Plugin Manifest
+
+The `plugin.json` file defines your plugin's metadata and component locations.
+
+### Required Fields
+- `name`: Unique identifier in kebab-case
+- `version`: Semantic versioning (MAJOR.MINOR.PATCH)
+
+### Optional Metadata
+- `description`: Brief plugin purpose
+- `author`: Object with `name` (required) and `email` (optional)
+- `homepage`: Documentation URL
+- `repository`: Source code link
+- `license`: Open source license identifier
+- `keywords`: Array of discovery tags
+
+### Component Paths
+Specify where Claude should find each component type:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "commands": ["./commands"],
+  "agents": ["./agents"],
+  "skills": ["./skills"],
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+**Path rules:**
+- Must be relative to plugin root
+- Should start with `./`
+- Can be arrays for multiple directories
+- Use `${CLAUDE_PLUGIN_ROOT}` variable for flexible resolution
+
+See `reference/plugin-structure.md` for detailed structure information.
+
+## Component Types
+
+### Commands
+Custom slash commands users invoke directly.
+- Location: Specified in `commands` field
+- Format: Markdown files with frontmatter
+- Example: `/my-command`
+
+### Agents
+Specialized agent behaviors with custom capabilities.
+- Location: Specified in `agents` field
+- Format: Markdown files describing agent
+
+### Skills
+Reusable capabilities agents can invoke autonomously.
+- Location: Specified in `skills` field
+- Format: Directories containing `SKILL.md`
+- Most common component type
+
+### Hooks
+Event handlers triggered by specific events.
+- Location: Specified in `hooks` field (points to hooks.json)
+- Events: PreToolUse, PostToolUse, UserPromptSubmit
+- Format: JSON configuration file
+
+### MCP Servers
+External tool integrations via Model Context Protocol.
+- Location: Specified in `mcpServers` field (points to .mcp.json)
+- Purpose: Connect external data sources and tools
+
+## Ensuring Consistency Between Commands and Skills
+
+**CRITICAL**: When a plugin contains both slash commands and skills that work together, they must provide consistent instructions. Inconsistencies cause Claude to follow the wrong workflow.
+
+### The Problem
+
+Slash commands execute first and provide initial instructions. If the command has different instructions than a skill it invokes, Claude will follow the command's approach instead of the skill's approach.
+
+**Example issue:**
+- Slash command says: "Clone the repository with `gh repo clone`"
+- Skill says: "Create a git worktree with `git worktree add`"
+- Result: Claude clones instead of using worktrees (following the command's instructions)
+
+### The Solution
+
+1. **Align workflows**: Ensure slash commands and skills describe the same approach
+2. **Avoid duplication**: Have the command reference the skill rather than duplicating instructions
+3. **Provide complete context**: When handing off to another Claude session, include all necessary details (what, where, what to skip)
+
+### Example: Correct Pattern
+
+**Slash command approach:**
+```markdown
+## 1. Setup
+Create git worktree following the standard workflow:
+[Include essential setup instructions]
+
+## 2. Launch New Session
+Provide user with complete context to continue:
+- What PR/task they're working on
+- Where the code is located
+- Which skill to invoke
+- What steps to skip (already completed)
+```
+
+**Skill approach:**
+```markdown
+## 1. Setup (if needed)
+[Same setup instructions as command]
+
+## 2. Continue workflow
+[Rest of the process]
+```
+
+### Portability Considerations
+
+**DON'T hardcode machine-specific paths:**
+```markdown
+# Bad: Assumes all users organize code the same way
+cd ~/src/<repo_name>
+```
+
+**DO use adaptable instructions:**
+```markdown
+# Good: Adapts to any user's setup
+First, check if the repository exists locally.
+Ask the user where they keep repositories if not found.
+```
+
+This keeps plugins portable across different users and environments.
+
+### Validation Checklist
+
+When creating or reviewing plugins with both commands and skills:
+- [ ] Commands and skills describe the same workflow approach
+- [ ] No hardcoded machine-specific paths
+- [ ] Handoffs between sessions include complete context
+- [ ] Instructions clearly state what steps to skip when already completed
+- [ ] Examples use generic paths, not specific to one developer
+
+## Creating Your Plugin
+
+### Choose Your Pattern
+
+**Single-purpose plugin** (one component type):
+```
+my-command-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── commands/
+    └── my-command.md
+```
+
+**Skills-focused plugin** (most common):
+```
+my-skills-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── skills/
+    ├── skill-one/
+    │   └── SKILL.md
+    └── skill-two/
+        └── SKILL.md
+```
+
+**Full-featured plugin**:
+```
+enterprise-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+├── agents/
+├── skills/
+├── hooks/
+│   └── hooks.json
+└── .mcp.json
+```
+
+See `reference/plugin-structure.md` for more patterns and examples.
+
+### Writing plugin.json
+
+Start minimal, add metadata as needed:
+
+```json
+{
+  "name": "data-processor",
+  "version": "1.0.0",
+  "description": "Tools for processing and analyzing data files",
+  "author": {
+    "name": "Your Name"
+  },
+  "keywords": ["data", "analysis", "processing"],
+  "skills": ["./skills"]
+}
+```
+
+**Key points:**
+- Name must be unique and descriptive
+- Version must follow semantic versioning
+- Description helps with discoverability
+- Only specify component paths you're using
+
+## Best Practices
+
+For comprehensive best practices, see `reference/best-practices.md`. Key highlights:
+
+### Organization
+- Keep related functionality together
+- Use clear, descriptive naming
+- One plugin = one cohesive purpose
+- Don't create mega-plugins that do everything
+
+### Versioning
+- Follow semantic versioning strictly
+- MAJOR: Breaking changes
+- MINOR: New features (backward compatible)
+- PATCH: Bug fixes
+
+### Documentation
+- Write clear descriptions for discoverability
+- Document each component's purpose
+- Include usage examples
+- Specify any requirements or dependencies
+
+### Testing
+- Test plugin installation: `/plugin install /path/to/plugin`
+- Verify components load: Use `claude --debug`
+- Test in clean environment before sharing
+- Validate all paths are relative and correct
+
+### Path Management
+- Always use relative paths starting with `./`
+- Verify paths are correct relative to plugin root
+- Test that components are found after installation
+
+## Reviewing Plugins
+
+When reviewing plugins (your own or others') before sharing or adding to marketplaces, use this systematic approach to ensure quality and adherence to best practices.
+
+### Review Process
+
+Follow these five steps for thorough plugin review:
+
+**Step 1: Initial Inspection**
+1. Check plugin.json exists at `.claude-plugin/plugin.json`
+2. Validate JSON syntax
+3. Verify required fields (name, version)
+4. Review overall directory structure
+
+**Step 2: Component Verification**
+1. Test each component path references valid location
+2. Check component files exist and are properly formatted
+3. Verify component-specific requirements (SKILL.md, frontmatter, etc.)
+
+**Step 3: Local Testing**
+1. Install plugin locally: `/plugin install /path/to/plugin`
+2. Verify installation: `/plugin` shows plugin
+3. Check for errors: `claude --debug`
+4. Test each component works as documented
+5. Uninstall and reinstall to verify clean installation
+
+**Step 4: Quality Assessment**
+1. Evaluate documentation completeness
+2. Check if plugin has single, clear purpose
+3. Assess naming quality and discoverability
+4. Review for best practices adherence
+
+**Step 5: Final Validation**
+1. Confirm no security issues
+2. Verify version is appropriate
+3. Check all documentation is accurate
+4. Ensure plugin is ready for intended audience
+
+### Review Checklist
+
+For a comprehensive checklist covering all aspects of plugin review, see `reference/review-checklist.md`. Key areas to review:
+
+1. **Manifest Validation**: plugin.json structure, required fields, JSON syntax
+2. **Path Validation**: Relative paths, correct references, no external dependencies
+3. **Structure and Organization**: Clear patterns, cohesive purpose
+4. **Component Quality**: Skills, commands, agents, hooks, MCP servers
+5. **Documentation**: README, installation, usage examples
+6. **Naming Conventions**: Descriptive, non-generic names
+7. **Versioning**: Semantic versioning, appropriate version number
+8. **Security and Safety**: No credentials, safe operations, no malicious code
+
+The detailed checklist in `reference/review-checklist.md` provides specific items to verify for each category, common issues to flag (critical, important, minor), and decision criteria for determining if a plugin is ready to share.
+
+### Quick Review Tips
+
+1. **Test in clean environment**: Install plugin fresh to catch missing dependencies
+2. **Read documentation first**: Verify docs match actual functionality
+3. **Check debug output**: `claude --debug` reveals loading issues
+4. **Try all components**: Don't assume untested components work
+5. **Think like a user**: Is it easy to understand and use?
+6. **Verify paths manually**: Walk through directory structure to confirm paths
+7. **Check version history**: If updating, ensure version change is appropriate
+
+## Testing and Debugging
+
+### Local Testing
+```bash
+# Install locally
+/plugin install /path/to/my-plugin
+
+# Check installation
+/plugin
+
+# Verify components loaded
+/help                    # Check for new commands
+claude --debug          # See plugin loading details
+
+# Update plugin after making changes
+/plugin                 # Select plugin to update (easiest)
+# OR manually uninstall/reinstall:
+/plugin uninstall my-plugin@local
+/plugin install /path/to/my-plugin
+```
+
+**Validation steps:**
+- Plugin appears in `/plugin` list
+- No errors in `claude --debug` output
+- Commands appear in `/help` (if plugin has commands)
+- Skills are discoverable in conversation
+- All component paths resolve correctly
+
+### Common Issues
+- **Plugin not found**: Check plugin.json exists at `.claude-plugin/plugin.json`
+- **Components not loaded**: Verify paths in plugin.json are relative and correct
+- **Version conflicts**: Ensure version follows semantic versioning format
+- **Invalid JSON**: Validate plugin.json syntax
+
+Use `claude --debug` to see detailed plugin loading information.
+
+## Sharing Your Plugin
+
+### Via Marketplace
+1. Create or add to a marketplace (see marketplace-builder skill)
+2. Add plugin entry to marketplace.json
+3. Share marketplace URL or path
+4. Users add marketplace: `/plugin marketplace add <url>`
+5. Users install: `/plugin install my-plugin@marketplace-name`
+
+### Direct Installation
+Users can install directly without a marketplace:
+```bash
+/plugin install /path/to/plugin
+# or
+/plugin install https://github.com/user/repo
+```
+
+## Key Principles
+
+### 1. Single Responsibility
+Each plugin should have one clear purpose. Don't create catch-all plugins.
+
+### 2. Clear Naming
+Use descriptive kebab-case names that indicate purpose:
+- Good: `git-workflow`, `data-analyzer`, `react-toolkit`
+- Avoid: `helpers`, `utils`, `misc`
+
+### 3. Minimal Manifest
+Only include what you need. Start with name and version, add components as needed.
+
+### 4. Relative Paths
+All paths must be relative to plugin root and start with `./`
+
+### 5. Semantic Versioning
+Version strictly: breaking changes = MAJOR, features = MINOR, fixes = PATCH
+
+## Progressive Development
+
+### Start Simple
+1. Create minimal plugin.json
+2. Add one component type
+3. Test locally
+4. Iterate and refine
+
+### Add Complexity Gradually
+1. Start with core functionality
+2. Test thoroughly
+3. Add additional components
+4. Document as you go
+5. Share when stable
+
+### Iterate Based on Usage
+1. Release early version
+2. Gather feedback
+3. Add features based on real needs
+4. Maintain backward compatibility when possible
+
+## References
+
+- `reference/plugin-structure.md`: Complete structure details and patterns
+- `reference/best-practices.md`: Comprehensive development guide
+- `templates/plugin.json`: Starting template for plugin manifest
+- `templates/README.md`: Starting template for plugin documentation
+
+## Quick Decision Guide
+
+Creating a plugin? Ask:
+1. **What's the core purpose?** One clear goal per plugin
+2. **What components do I need?** Start minimal, add as needed
+3. **Is the name descriptive?** Clear, kebab-case, indicates purpose
+4. **Are paths relative?** All paths start with `./` from plugin root
+5. **Is it versioned correctly?** Semantic versioning (x.y.z)
+6. **Have I tested locally?** Install and verify before sharing
+
+Remember: Plugins package related functionality for easy sharing. Start simple, test thoroughly, and iterate based on real usage.

skills/plugin-builder/reference/best-practices.md

@@ -0,0 +1,793 @@
+# Plugin Development Best Practices
+
+Comprehensive guide to creating high-quality, maintainable Claude Code plugins.
+
+## Development Workflow
+
+### Starting a New Plugin
+
+**Step 1: Plan Your Plugin**
+- Define clear purpose and scope
+- Decide what components you need
+- Choose appropriate plugin pattern
+- Identify target users and use cases
+
+**Step 2: Create Basic Structure**
+```bash
+mkdir my-plugin
+mkdir my-plugin/.claude-plugin
+```
+
+**Step 3: Create Minimal Manifest**
+Start with only required fields:
+```json
+{
+  "name": "my-plugin",
+  "version": "0.1.0"
+}
+```
+
+**Step 4: Add First Component**
+Start with one component type, test it, then add more.
+
+**Step 5: Test Locally**
+```bash
+/plugin install /path/to/my-plugin
+```
+
+**Step 6: Iterate**
+- Test each component
+- Refine based on usage
+- Add documentation
+- Increment version
+
+### Local Development Setup
+
+**Option 1: Standalone Plugin Directory**
+```bash
+mkdir ~/my-plugins
+cd ~/my-plugins
+mkdir my-plugin
+# Develop plugin
+/plugin install ~/my-plugins/my-plugin
+```
+
+**Option 2: Personal Marketplace**
+```bash
+mkdir ~/my-marketplace
+cd ~/my-marketplace
+mkdir .claude-plugin
+# Create marketplace.json
+mkdir my-plugin
+# Develop plugin
+/plugin marketplace add ~/my-marketplace
+/plugin install my-plugin@my-marketplace
+```
+
+**Recommended:** Use personal marketplace for managing multiple plugins.
+
+### Iterative Development
+
+1. **Make changes** to plugin files
+2. **Update** the plugin using one of these methods:
+   - **Easiest**: Run `/plugin` and select the plugin to update (Claude Code will reload it)
+   - **Manual**: `/plugin uninstall my-plugin@marketplace-name` then `/plugin install my-plugin@marketplace-name`
+3. **Restart Claude Code** if prompted to apply changes
+4. **Test** the changes
+5. **Repeat** until satisfied
+
+**Tips:**
+- The `/plugin` menu command is the easiest way to update during development
+- Restart Claude Code to reload all plugins without manual uninstall/reinstall
+- For marketplaces, changes are picked up when reinstalling from the marketplace
+
+## Versioning
+
+### Semantic Versioning
+
+Follow semantic versioning strictly: `MAJOR.MINOR.PATCH`
+
+**MAJOR version** (e.g., 1.0.0 → 2.0.0)
+- Breaking changes to existing functionality
+- Removing components
+- Changing component behavior in incompatible ways
+- Renaming plugin
+
+**MINOR version** (e.g., 1.0.0 → 1.1.0)
+- New features added
+- New components added
+- Backward-compatible enhancements
+- New optional parameters
+
+**PATCH version** (e.g., 1.0.0 → 1.0.1)
+- Bug fixes
+- Documentation updates
+- Performance improvements
+- No functionality changes
+
+### Version Examples
+
+**Breaking change (MAJOR):**
+```json
+// Version 1.0.0
+{
+  "name": "data-processor",
+  "version": "1.0.0",
+  "skills": ["./skills"]
+}
+
+// Version 2.0.0 - Removed commands, renamed skills directory
+{
+  "name": "data-processor",
+  "version": "2.0.0",
+  "skills": ["./processors"]
+}
+```
+
+**New feature (MINOR):**
+```json
+// Version 1.0.0
+{
+  "name": "toolkit",
+  "version": "1.0.0",
+  "skills": ["./skills"]
+}
+
+// Version 1.1.0 - Added commands
+{
+  "name": "toolkit",
+  "version": "1.1.0",
+  "skills": ["./skills"],
+  "commands": ["./commands"]
+}
+```
+
+**Bug fix (PATCH):**
+```json
+// Version 1.0.0 - Has a bug in skill logic
+{
+  "name": "analyzer",
+  "version": "1.0.0",
+  "skills": ["./skills"]
+}
+
+// Version 1.0.1 - Fixed skill logic, no API changes
+{
+  "name": "analyzer",
+  "version": "1.0.1",
+  "skills": ["./skills"]
+}
+```
+
+### Pre-release Versions
+
+For development and testing:
+```json
+{
+  "version": "0.1.0"  // Initial development
+}
+{
+  "version": "0.9.0"  // Feature complete, testing
+}
+{
+  "version": "1.0.0"  // Stable release
+}
+```
+
+**Convention:**
+- `0.x.x` = Under development, breaking changes allowed
+- `1.0.0` = First stable release
+- `1.x.x+` = Maintain backward compatibility
+
+## Naming Conventions
+
+### Plugin Names
+
+**Format:** kebab-case
+
+**Good names:**
+- `git-workflow` - Descriptive, clear purpose
+- `data-analyzer` - Indicates functionality
+- `react-toolkit` - Shows what it helps with
+- `security-scanner` - Obvious use case
+
+**Bad names:**
+- `helpers` - Too vague
+- `utils` - Doesn't indicate purpose
+- `my_plugin` - Wrong case (use kebab-case)
+- `MyPlugin` - Wrong case (use kebab-case)
+- `stuff` - Not descriptive
+
+**Guidelines:**
+- Use 2-3 words typically
+- Be specific about functionality
+- Avoid generic terms (utils, helpers, tools)
+- Make it discoverable by name alone
+
+### Component Names
+
+**Commands:** Action verbs
+- `deploy-app.md`
+- `run-tests.md`
+- `generate-report.md`
+
+**Skills:** Gerund form (verb + -ing)
+- `processing-data/`
+- `analyzing-code/`
+- `generating-reports/`
+
+**Agents:** Role-based
+- `code-reviewer.md`
+- `security-auditor.md`
+- `test-generator.md`
+
+## Documentation
+
+### Plugin Description
+
+Write descriptions that:
+- Clearly state purpose
+- Include key terms for discoverability
+- Are concise (1-2 sentences)
+- Help users understand when to use it
+
+**Good examples:**
+```json
+{
+  "description": "Tools for processing and analyzing CSV and JSON data files with validation and transformation capabilities"
+}
+```
+
+```json
+{
+  "description": "Git workflow automation including branch management, PR creation, and commit formatting"
+}
+```
+
+**Bad examples:**
+```json
+{
+  "description": "Helpful stuff"  // Too vague
+}
+```
+
+```json
+{
+  "description": "This plugin provides various utilities and tools that can help you with different tasks in your workflow and make things easier when working with data and files"  // Too verbose
+}
+```
+
+### Keywords
+
+Choose keywords that:
+- Describe functionality
+- Match user search terms
+- Are specific and relevant
+- Help with discovery
+
+**Example:**
+```json
+{
+  "name": "react-toolkit",
+  "keywords": ["react", "components", "typescript", "testing", "hooks"]
+}
+```
+
+**Guidelines:**
+- Include 3-7 keywords
+- Use specific terms, not generic ones
+- Think about how users would search
+- Include technology names when relevant
+
+### README Files
+
+Include README.md for complex plugins:
+
+**Essential sections:**
+1. **Overview**: What does the plugin do?
+2. **Installation**: How to install it
+3. **Components**: What's included
+4. **Usage**: How to use each component
+5. **Examples**: Real-world usage examples
+6. **Requirements**: Any dependencies or prerequisites
+7. **License**: Licensing information
+
+**CRITICAL: Keep README synchronized with plugin contents**
+
+When adding or removing components (especially skills), ALWAYS update the README to reflect the changes:
+
+- **Adding a skill**: Add it to the Components section with a brief description
+- **Removing a skill**: Remove it from the Components section
+- **Updating a skill**: Update its description if purpose changed
+- **Adding commands/agents**: Document them in the appropriate sections
+
+This is easy to forget but critical for discoverability. Users read the README to understand what the plugin offers.
+
+**Example README structure:**
+```markdown
+# My Plugin
+
+Brief description of what the plugin does.
+
+## Installation
+
+```bash
+/plugin marketplace add <marketplace-url>
+/plugin install my-plugin@marketplace-name
+```
+
+## Components
+
+### Skills
+- **Processing Data**: Handles CSV and JSON files
+- **Validating Input**: Validates data against schemas
+
+### Commands
+- `/process-data`: Process data files
+- `/validate-schema`: Validate data schema
+
+## Usage Examples
+
+### Processing CSV Files
+...
+
+## Requirements
+
+- Node.js 18+
+- Python 3.9+ (for validation scripts)
+
+## License
+
+MIT
+```
+
+## Testing
+
+### Local Testing Workflow
+
+**1. Installation Test**
+```bash
+# Install plugin
+/plugin install /path/to/my-plugin
+
+# Verify installation
+/plugin
+
+# Check for errors
+claude --debug
+```
+
+**2. Component Testing**
+```bash
+# Verify commands appear
+/help
+
+# Test slash command
+/my-command
+
+# Test skill (use it in conversation)
+# Skills are auto-discovered and invoked
+
+# Verify agents registered
+# Agents appear in specialized workflows
+```
+
+**3. Path Testing**
+- Verify all component paths are relative
+- Check paths start with `./`
+- Ensure directories/files exist
+- Test that components load correctly
+
+**4. Manifest Validation**
+```bash
+# Validate JSON syntax
+cat .claude-plugin/plugin.json | python -m json.tool
+
+# Check required fields
+# - name (present and kebab-case)
+# - version (semantic versioning format)
+```
+
+**5. Clean Environment Testing**
+Before sharing:
+- Uninstall plugin
+- Restart Claude Code
+- Reinstall and test fresh
+
+### Testing Checklist
+
+Before releasing:
+- [ ] Plugin installs without errors
+- [ ] All components load correctly
+- [ ] Commands appear in `/help`
+- [ ] Skills are discoverable
+- [ ] Agents work as expected
+- [ ] Hooks trigger correctly
+- [ ] No errors in `claude --debug`
+- [ ] Documentation is accurate
+- [ ] Version number is correct
+- [ ] Tested in clean environment
+
+## Code Quality
+
+### Manifest Quality
+
+**Required fields present:**
+```json
+{
+  "name": "my-plugin",      // ✓ Required
+  "version": "1.0.0"        // ✓ Required
+}
+```
+
+**Metadata complete:**
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "...",     // ✓ Recommended
+  "author": {
+    "name": "..."          // ✓ Recommended
+  },
+  "keywords": [...]         // ✓ Recommended
+}
+```
+
+**Paths correct:**
+```json
+{
+  "skills": ["./skills"],            // ✓ Relative path
+  "commands": ["./commands"],        // ✓ Starts with ./
+  "hooks": "./hooks/hooks.json"      // ✓ File reference
+}
+```
+
+### Component Quality
+
+**Skills:**
+- Have clear SKILL.md with frontmatter
+- Include name and description in frontmatter
+- Keep SKILL.md under 500 lines
+- Use reference files for details
+
+**Commands:**
+- Have frontmatter with name and description
+- Clear, concise command prompts
+- Include usage examples
+- Document parameters
+
+**Agents:**
+- Clear agent descriptions
+- Specific capabilities listed
+- Tool restrictions if needed
+
+**Hooks:**
+- Valid hooks.json format
+- Scripts exist at specified paths
+- Proper permissions on scripts
+- Error handling in scripts
+
+### Error Handling
+
+**In scripts:**
+```bash
+#!/bin/bash
+set -e  # Exit on error
+
+# Validate inputs
+if [ -z "$1" ]; then
+  echo "Error: Missing required parameter"
+  exit 1
+fi
+
+# Main logic here
+```
+
+**In MCP servers:**
+```javascript
+try {
+  // Server logic
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}
+```
+
+## Organization
+
+### Single Responsibility
+
+Each plugin should have ONE clear purpose.
+
+**Good: Focused plugins**
+- `git-workflow` - Git operations only
+- `data-analyzer` - Data analysis only
+- `react-toolkit` - React development only
+
+**Bad: Catch-all plugins**
+- `my-utils` - Vague, does everything
+- `helpers` - No clear purpose
+- `tools` - Too generic
+
+### Component Organization
+
+**By functionality:**
+```
+my-plugin/
+├── skills/
+│   ├── core-processing/     # Core functionality
+│   ├── validation/          # Validation features
+│   └── reporting/           # Reporting features
+```
+
+**By category:**
+```
+data-plugin/
+├── skills/
+│   ├── csv/                 # CSV-specific
+│   ├── json/                # JSON-specific
+│   └── xml/                 # XML-specific
+```
+
+**Flat structure (simple plugins):**
+```
+simple-plugin/
+├── skills/
+│   ├── skill-one/
+│   └── skill-two/
+```
+
+### File Organization
+
+**Supporting files:**
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── skills/
+│   └── my-skill/
+│       ├── SKILL.md
+│       ├── reference/       # Detailed docs
+│       ├── templates/       # Templates
+│       └── scripts/         # Helper scripts
+├── scripts/                 # Plugin-level scripts
+├── docs/                    # Additional documentation
+├── tests/                   # Test files (if applicable)
+├── README.md
+└── LICENSE
+```
+
+## Distribution
+
+### Via Marketplace
+
+**Best for:**
+- Sharing with teams
+- Publishing to community
+- Managing multiple plugins
+- Versioning and updates
+
+**Steps:**
+1. Create/add to marketplace
+2. Add entry to marketplace.json
+3. Share marketplace URL
+4. Users add marketplace once
+5. Users install/update plugins easily
+
+**Example marketplace.json entry:**
+```json
+{
+  "plugins": [
+    {
+      "name": "my-plugin",
+      "source": "./my-plugin",
+      "description": "Plugin description"
+    }
+  ]
+}
+```
+
+### Direct Installation
+
+**Best for:**
+- Quick testing
+- Private plugins
+- One-off sharing
+
+**Methods:**
+```bash
+# Local path
+/plugin install /path/to/plugin
+
+# Git repository
+/plugin install https://github.com/user/plugin
+
+# GitHub shorthand
+/plugin install github:user/plugin
+```
+
+## Common Pitfalls
+
+### Absolute Paths
+**Problem:**
+```json
+{
+  "skills": "/Users/me/plugins/my-plugin/skills"  // ✗ Absolute
+}
+```
+
+**Solution:**
+```json
+{
+  "skills": ["./skills"]  // ✓ Relative
+}
+```
+
+### Missing Plugin Directory
+**Problem:**
+```
+my-plugin/
+└── plugin.json  // ✗ Wrong location
+```
+
+**Solution:**
+```
+my-plugin/
+└── .claude-plugin/
+    └── plugin.json  // ✓ Correct location
+```
+
+### Invalid Version Format
+**Problem:**
+```json
+{
+  "version": "1"       // ✗ Invalid
+}
+{
+  "version": "v1.0.0"  // ✗ Don't include 'v'
+}
+```
+
+**Solution:**
+```json
+{
+  "version": "1.0.0"   // ✓ Semantic versioning
+}
+```
+
+### Overly Generic Names
+**Problem:**
+```json
+{
+  "name": "utils"      // ✗ Too vague
+}
+```
+
+**Solution:**
+```json
+{
+  "name": "data-utils" // ✓ More specific
+}
+```
+
+### Missing Component Files
+**Problem:**
+```json
+{
+  "skills": ["./skills"]
+}
+// But no skills/ directory exists
+```
+
+**Solution:**
+- Create directory before referencing
+- Or remove reference from plugin.json
+
+### Wrong Component Format
+**Problem:**
+```markdown
+# My Skill
+
+Content without frontmatter
+```
+
+**Solution:**
+```markdown
+---
+name: My Skill
+description: Skill description
+---
+
+# My Skill
+
+Content
+```
+
+## Maintenance
+
+### Keeping Plugins Updated
+
+**Regular maintenance:**
+- Fix bugs promptly
+- Update documentation
+- Respond to user feedback
+- Test with new Claude Code versions
+
+**Version updates:**
+- Follow semantic versioning
+- Document changes in CHANGELOG.md
+- Test before releasing
+- Update marketplace.json
+
+### Deprecation Strategy
+
+When removing features:
+
+**1. Announce deprecation** (MINOR version)
+```json
+{
+  "version": "1.5.0",
+  "description": "Note: feature X deprecated, will be removed in 2.0.0"
+}
+```
+
+**2. Remove feature** (MAJOR version)
+```json
+{
+  "version": "2.0.0",
+  "description": "Breaking: feature X removed"
+}
+```
+
+**3. Document migration** in README
+
+### Backward Compatibility
+
+**Maintain in MINOR versions:**
+- Keep existing component paths
+- Don't remove components
+- Don't break existing functionality
+- Add, don't replace
+
+**Break only in MAJOR versions:**
+- Remove components
+- Change component behavior
+- Rename paths
+- Require new dependencies
+
+## Security Considerations
+
+### Script Safety
+- Validate all inputs
+- Use proper permissions
+- Avoid executing untrusted code
+- Document security requirements
+
+### Sensitive Data
+- Don't hardcode credentials
+- Use environment variables
+- Document required secrets
+- Provide examples, not real values
+
+### MCP Server Security
+- Validate external inputs
+- Use HTTPS for remote connections
+- Handle errors gracefully
+- Log security-relevant events
+
+## Summary
+
+**Key Best Practices:**
+
+1. **Plan before building** - Clear purpose, right components
+2. **Start minimal** - plugin.json only, add as needed
+3. **Use relative paths** - Always start with `./`
+4. **Follow semantic versioning** - MAJOR.MINOR.PATCH strictly
+5. **Test thoroughly** - Install, test, debug before sharing
+6. **Document well** - Clear descriptions, examples, README
+7. **Organize logically** - Single responsibility, clear structure
+8. **Maintain actively** - Fix bugs, respond to feedback
+9. **Version carefully** - Don't break backward compatibility
+10. **Secure by default** - Validate inputs, protect secrets
+
+Follow these practices to create high-quality, maintainable plugins that users will trust and enjoy using.

skills/plugin-builder/reference/plugin-structure.md

@@ -0,0 +1,606 @@
+# Plugin Directory Structure
+
+Complete reference for organizing Claude Code plugin directories and files.
+
+## Complete Structure Example
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json          # REQUIRED: Plugin manifest
+├── commands/                 # Optional: Custom slash commands
+│   ├── command-one.md
+│   └── command-two.md
+├── agents/                   # Optional: Custom agents
+│   ├── agent-one.md
+│   └── agent-two.md
+├── skills/                   # Optional: Agent skills
+│   ├── skill-one/
+│   │   ├── SKILL.md
+│   │   ├── reference/
+│   │   │   └── details.md
+│   │   └── templates/
+│   │       └── template.md
+│   └── skill-two/
+│       └── SKILL.md
+├── hooks/                    # Optional: Event handlers
+│   └── hooks.json
+├── .mcp.json                 # Optional: MCP server config
+├── scripts/                  # Optional: Helper scripts
+│   └── setup.sh
+└── README.md                 # Optional: Documentation
+```
+
+## Required Files
+
+### Plugin Manifest (.claude-plugin/plugin.json)
+
+This is the ONLY required file. Every plugin must have this.
+
+**Minimal example:**
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0"
+}
+```
+
+**Complete example:**
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "Brief description of plugin purpose",
+  "author": {
+    "name": "Your Name",
+    "email": "email@example.com"
+  },
+  "homepage": "https://docs.example.com",
+  "repository": "https://github.com/username/repo",
+  "license": "MIT",
+  "keywords": ["tag1", "tag2", "tag3"],
+  "commands": ["./commands"],
+  "agents": ["./agents"],
+  "skills": ["./skills"],
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+### Field Definitions
+
+**Required fields:**
+- `name` (string): Unique plugin identifier in kebab-case
+- `version` (string): Semantic version (MAJOR.MINOR.PATCH)
+
+**Optional metadata:**
+- `description` (string): Brief plugin purpose for discoverability
+- `author` (object): Author information
+  - `name` (string, required): Author's name
+  - `email` (string, optional): Author's email
+- `homepage` (string): URL to documentation
+- `repository` (string): URL to source code
+- `license` (string): Open source license identifier (e.g., "MIT", "Apache-2.0")
+- `keywords` (array of strings): Tags for marketplace discovery
+
+**Component paths:**
+- `commands` (string or array): Path(s) to command directories
+- `agents` (string or array): Path(s) to agent directories
+- `skills` (string or array): Path(s) to skill directories
+- `hooks` (string): Path to hooks.json file
+- `mcpServers` (string): Path to .mcp.json file
+
+## Path Resolution
+
+### Path Rules
+
+1. **Must be relative** to plugin root
+2. **Should start with** `./`
+3. **Can use variable** `${CLAUDE_PLUGIN_ROOT}` for flexibility
+4. **Can be arrays** for multiple component directories
+
+### Path Examples
+
+**Single directory:**
+```json
+{
+  "skills": "./skills"
+}
+```
+
+**Multiple directories:**
+```json
+{
+  "skills": ["./skills", "./shared-skills"]
+}
+```
+
+**With variable (advanced):**
+```json
+{
+  "skills": "${CLAUDE_PLUGIN_ROOT}/skills"
+}
+```
+
+**File reference:**
+```json
+{
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+## Component Directories
+
+### Commands Directory
+
+Contains custom slash command definitions.
+
+**Structure:**
+```
+commands/
+├── my-command.md
+├── another-command.md
+└── nested/
+    └── sub-command.md
+```
+
+**File format:**
+Each command is a Markdown file with frontmatter:
+
+```markdown
+---
+name: my-command
+description: Command description
+---
+
+Command prompt content here.
+```
+
+**Usage:** Users invoke with `/my-command`
+
+### Agents Directory
+
+Contains custom agent definitions.
+
+**Structure:**
+```
+agents/
+├── my-agent.md
+└── specialized-agent.md
+```
+
+**File format:**
+Markdown files describing agent capabilities and behavior.
+
+### Skills Directory
+
+Contains agent skills (most common component type).
+
+**Structure:**
+```
+skills/
+├── skill-one/
+│   ├── SKILL.md           # Required
+│   ├── reference/         # Optional: detailed docs
+│   │   └── details.md
+│   └── templates/         # Optional: templates
+│       └── output.json
+└── skill-two/
+    └── SKILL.md           # Minimal skill
+```
+
+**Requirements:**
+- Each skill is a directory
+- Must contain `SKILL.md` with YAML frontmatter
+- Can include supporting files (reference docs, templates, scripts)
+
+### Hooks Directory
+
+Contains event handler configuration.
+
+**Structure:**
+```
+hooks/
+└── hooks.json
+```
+
+**hooks.json format:**
+```json
+{
+  "hooks": [
+    {
+      "event": "PreToolUse",
+      "command": "./scripts/pre-tool.sh"
+    },
+    {
+      "event": "PostToolUse",
+      "command": "./scripts/post-tool.sh"
+    },
+    {
+      "event": "UserPromptSubmit",
+      "command": "./scripts/on-submit.sh"
+    }
+  ]
+}
+```
+
+**Supported events:**
+- `PreToolUse`: Before tool execution
+- `PostToolUse`: After tool execution
+- `UserPromptSubmit`: When user submits prompt
+
+### MCP Servers Configuration
+
+Model Context Protocol server integration.
+
+**File location:** `.mcp.json` in plugin root
+
+**Format:**
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "node",
+      "args": ["./path/to/server.js"],
+      "env": {
+        "API_KEY": "value"
+      }
+    }
+  }
+}
+```
+
+## Common Plugin Patterns
+
+### Pattern 1: Skills-Only Plugin (Most Common)
+
+Simplest and most common plugin pattern.
+
+```
+my-skills-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── skills/
+    ├── skill-one/
+    │   └── SKILL.md
+    └── skill-two/
+        └── SKILL.md
+```
+
+**plugin.json:**
+```json
+{
+  "name": "my-skills-plugin",
+  "version": "1.0.0",
+  "description": "Collection of helpful skills",
+  "skills": ["./skills"]
+}
+```
+
+**Use when:** You want to share reusable capabilities that agents can invoke.
+
+### Pattern 2: Commands-Only Plugin
+
+For user-invoked custom commands.
+
+```
+my-commands-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── commands/
+    ├── deploy.md
+    └── test.md
+```
+
+**plugin.json:**
+```json
+{
+  "name": "my-commands-plugin",
+  "version": "1.0.0",
+  "description": "Custom deployment and testing commands",
+  "commands": ["./commands"]
+}
+```
+
+**Use when:** You want custom slash commands for specific workflows.
+
+### Pattern 3: Agent-Focused Plugin
+
+For specialized agent behaviors.
+
+```
+my-agent-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── agents/
+    └── code-reviewer.md
+```
+
+**plugin.json:**
+```json
+{
+  "name": "my-agent-plugin",
+  "version": "1.0.0",
+  "description": "Specialized code review agent",
+  "agents": ["./agents"]
+}
+```
+
+**Use when:** You need specialized agent behaviors.
+
+### Pattern 4: MCP Integration Plugin
+
+For external tool integrations.
+
+```
+mcp-integration-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── .mcp.json
+└── servers/
+    └── custom-server.js
+```
+
+**plugin.json:**
+```json
+{
+  "name": "mcp-integration",
+  "version": "1.0.0",
+  "description": "Custom MCP server integration",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+**Use when:** Integrating external data sources or tools.
+
+### Pattern 5: Workflow Plugin (Multi-Component)
+
+Combines multiple component types for complete workflow.
+
+```
+workflow-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   └── start-workflow.md
+├── skills/
+│   ├── process-data/
+│   │   └── SKILL.md
+│   └── generate-report/
+│       └── SKILL.md
+└── hooks/
+    └── hooks.json
+```
+
+**plugin.json:**
+```json
+{
+  "name": "workflow-plugin",
+  "version": "1.0.0",
+  "description": "Complete data processing workflow",
+  "commands": ["./commands"],
+  "skills": ["./skills"],
+  "hooks": "./hooks/hooks.json"
+}
+```
+
+**Use when:** Building complete workflows with commands, skills, and hooks.
+
+### Pattern 6: Enterprise Plugin (Full-Featured)
+
+Comprehensive plugin with all component types.
+
+```
+enterprise-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   ├── deploy.md
+│   └── rollback.md
+├── agents/
+│   └── security-scanner.md
+├── skills/
+│   ├── compliance-check/
+│   │   └── SKILL.md
+│   └── audit-log/
+│       └── SKILL.md
+├── hooks/
+│   └── hooks.json
+├── .mcp.json
+├── scripts/
+│   ├── pre-deploy.sh
+│   └── post-deploy.sh
+└── README.md
+```
+
+**plugin.json:**
+```json
+{
+  "name": "enterprise-plugin",
+  "version": "2.1.0",
+  "description": "Enterprise deployment and compliance toolkit",
+  "author": {
+    "name": "Enterprise Team",
+    "email": "team@enterprise.com"
+  },
+  "homepage": "https://docs.enterprise.com/plugin",
+  "repository": "https://github.com/enterprise/plugin",
+  "license": "MIT",
+  "keywords": ["enterprise", "deployment", "compliance", "security"],
+  "commands": ["./commands"],
+  "agents": ["./agents"],
+  "skills": ["./skills"],
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+**Use when:** Building comprehensive tooling for enterprise workflows.
+
+## Multi-Directory Support
+
+You can specify multiple directories for component types.
+
+**Example:**
+```json
+{
+  "name": "multi-source-plugin",
+  "version": "1.0.0",
+  "skills": ["./skills", "./shared-skills", "./experimental-skills"],
+  "commands": ["./commands", "./admin-commands"]
+}
+```
+
+**Directory structure:**
+```
+multi-source-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── skills/
+│   └── core-skill/
+│       └── SKILL.md
+├── shared-skills/
+│   └── shared-skill/
+│       └── SKILL.md
+├── experimental-skills/
+│   └── experimental-skill/
+│       └── SKILL.md
+├── commands/
+│   └── user-command.md
+└── admin-commands/
+    └── admin-command.md
+```
+
+**Use when:**
+- Organizing components by category
+- Separating stable from experimental features
+- Sharing components across multiple plugins
+
+## Supporting Files
+
+### Scripts Directory
+
+Optional directory for helper scripts.
+
+```
+scripts/
+├── setup.sh
+├── validate.py
+└── hooks/
+    ├── pre-tool.sh
+    └── post-tool.sh
+```
+
+**Use for:**
+- Installation scripts
+- Validation scripts
+- Hook implementations
+- Utility scripts
+
+### Documentation Files
+
+Optional documentation in plugin root.
+
+```
+my-plugin/
+├── .claude-plugin/
+├── README.md          # Main documentation
+├── CHANGELOG.md       # Version history
+└── LICENSE            # License file
+```
+
+**Recommended:**
+- README.md: Installation, usage, examples
+- CHANGELOG.md: Version history and changes
+- LICENSE: License text for open source plugins
+
+## Best Practices
+
+### Organization
+- Group related components together
+- Use clear, descriptive directory names
+- Keep supporting files in logical locations
+- Don't mix component types in same directory
+
+### File Naming
+- Use kebab-case for file names
+- Be descriptive: `generate-report.md` not `gen.md`
+- Match component names to file names when possible
+
+### Component Placement
+- Commands: User-facing, workflow-oriented
+- Skills: Agent-invoked, reusable capabilities
+- Agents: Specialized behaviors
+- Hooks: Event-driven actions
+- MCP: External integrations
+
+### Path Management
+- Always use relative paths
+- Start paths with `./`
+- Test all paths after creating manifest
+- Verify paths work after installation
+
+### Documentation
+- Include README.md for complex plugins
+- Document each component's purpose
+- Provide usage examples
+- List any requirements or dependencies
+
+## Troubleshooting
+
+### Plugin Not Found
+**Symptom:** Plugin doesn't appear after installation
+**Check:**
+- `.claude-plugin/plugin.json` exists
+- JSON is valid (use linter)
+- Plugin directory is in correct location
+
+### Components Not Loaded
+**Symptom:** Commands/skills don't appear after install
+**Check:**
+- Paths in plugin.json are relative and correct
+- Paths start with `./`
+- Component files have correct format (frontmatter, etc.)
+- Use `claude --debug` to see loading details
+
+### Invalid Manifest
+**Symptom:** Error when installing plugin
+**Check:**
+- Required fields present (name, version)
+- Version follows semantic versioning (x.y.z)
+- JSON syntax is valid
+- Paths exist and are relative
+
+### Path Resolution Issues
+**Symptom:** Components not found
+**Check:**
+- Paths are relative, not absolute
+- Paths start with `./`
+- Directories/files exist at specified paths
+- No typos in path strings
+
+## Validation Checklist
+
+Before sharing your plugin:
+
+- [ ] `.claude-plugin/plugin.json` exists and is valid JSON
+- [ ] Required fields present: `name`, `version`
+- [ ] Version follows semantic versioning (x.y.z)
+- [ ] All paths are relative and start with `./`
+- [ ] All referenced paths exist
+- [ ] Component files have correct format
+- [ ] Plugin installs without errors
+- [ ] Components appear and work correctly
+- [ ] Tested with `claude --debug`
+- [ ] Documentation is clear and complete
+
+## Summary
+
+**Key Takeaways:**
+1. Only `.claude-plugin/plugin.json` is required
+2. All other components are optional
+3. Use relative paths starting with `./`
+4. Choose patterns that match your needs
+5. Start simple, add complexity as needed
+6. Test thoroughly before sharing

skills/plugin-builder/reference/review-checklist.md

@@ -0,0 +1,137 @@
+# Plugin Review Checklist
+
+This comprehensive checklist helps ensure plugins follow best practices before being shared or added to marketplaces.
+
+## Detailed Review Checklist
+
+### 1. Manifest Validation
+- [ ] `plugin.json` exists at `.claude-plugin/plugin.json` (not at root)
+- [ ] `name` field is present and uses kebab-case
+- [ ] `version` field follows semantic versioning (MAJOR.MINOR.PATCH)
+- [ ] `description` is clear and concise (if present)
+- [ ] `author.name` is specified (if author field exists)
+- [ ] `keywords` are relevant for discoverability (if present)
+- [ ] JSON syntax is valid (no trailing commas, proper quotes)
+
+### 2. Path Validation
+- [ ] All component paths are relative (start with `./`)
+- [ ] No absolute paths in plugin.json
+- [ ] Component paths reference directories/files that actually exist
+- [ ] No use of `../` to reference files outside plugin directory
+- [ ] Paths use forward slashes (not backslashes)
+- [ ] `${CLAUDE_PLUGIN_ROOT}` variable is used correctly if present
+
+### 3. Structure and Organization
+- [ ] Plugin follows a clear structural pattern (single-purpose, skills-focused, or full-featured)
+- [ ] Related functionality is grouped together
+- [ ] Directory names are descriptive and consistent
+- [ ] No unnecessary files or directories
+- [ ] Plugin has single, cohesive purpose (not a catch-all)
+
+### 4. Component Quality
+
+**For Skills:**
+- [ ] Each skill has `SKILL.md` in its directory
+- [ ] Skill frontmatter includes `name` and `description`
+- [ ] Skill descriptions clearly indicate when to use the skill
+- [ ] Skills provide actionable guidance, not just information dumps
+- [ ] Skills use progressive disclosure (start simple, reveal detail as needed)
+
+**For Commands:**
+- [ ] Command files use `.md` extension
+- [ ] Command names are descriptive and follow naming conventions
+- [ ] Commands include usage examples
+- [ ] Commands document required vs optional parameters
+
+**For Agents:**
+- [ ] Agent files clearly describe agent purpose and capabilities
+- [ ] Agent tools and behaviors are well-defined
+- [ ] Agent use cases are documented
+
+**For Hooks:**
+- [ ] `hooks.json` has valid structure
+- [ ] Hook events are valid (PreToolUse, PostToolUse, UserPromptSubmit)
+- [ ] Hook scripts/commands are tested
+
+**For MCP Servers:**
+- [ ] `.mcp.json` configuration is valid
+- [ ] Server dependencies are documented
+- [ ] Installation instructions are provided
+
+### 5. Documentation
+- [ ] README.md exists and explains plugin purpose
+- [ ] Installation instructions are clear
+- [ ] Usage examples are provided
+- [ ] Requirements and dependencies are documented
+- [ ] License is specified (in plugin.json or LICENSE file)
+- [ ] Each component has adequate documentation
+
+### 6. Naming Conventions
+- [ ] Plugin name is descriptive and indicates purpose
+- [ ] Plugin name doesn't conflict with common/existing plugins
+- [ ] Avoid generic names like `utils`, `helpers`, `misc`
+- [ ] Skill names clearly indicate their purpose
+- [ ] Command names are intuitive and follow slash-command conventions
+
+### 7. Versioning
+- [ ] Version number is appropriate for current state
+- [ ] Breaking changes increment MAJOR version
+- [ ] New features increment MINOR version
+- [ ] Bug fixes increment PATCH version
+- [ ] Version matches expected maturity (1.0.0+ for production-ready)
+
+### 8. Security and Safety
+- [ ] No hardcoded credentials or API keys
+- [ ] No references to private/internal systems in public plugins
+- [ ] Hook commands don't execute unsafe operations
+- [ ] MCP servers use secure connection methods
+- [ ] No malicious or obfuscated code
+
+## Common Issues to Flag
+
+### Critical Issues (must fix before sharing)
+- Missing or malformed plugin.json
+- Invalid JSON syntax
+- Absolute paths instead of relative paths
+- Missing required component files
+- Security vulnerabilities (hardcoded secrets, unsafe code)
+- Invalid semantic versioning
+
+### Important Issues (should fix)
+- Missing or inadequate description
+- Poor or generic naming
+- Missing documentation
+- Untested components
+- Paths that don't start with `./`
+- No version or author information
+
+### Minor Issues (nice to fix)
+- Missing keywords for discoverability
+- No homepage or repository link
+- Could benefit from more examples
+- Documentation could be clearer
+- Directory structure could be more intuitive
+
+## Review Decision Criteria
+
+### Ready to Share
+Plugin is ready to share if:
+- All critical issues resolved
+- Plugin installs and works correctly
+- Documentation is adequate
+- Follows best practices
+- Has clear, single purpose
+
+### Needs Revision
+Plugin needs revision if:
+- Any critical issues present
+- Important issues significantly impact usability
+- Testing reveals functionality problems
+- Documentation is insufficient
+
+### Reject
+Plugin should be rejected if:
+- Security vulnerabilities present
+- Malicious or deceptive functionality
+- Violates plugin system requirements
+- Cannot be fixed to meet minimum standards

skills/plugin-builder/templates/README.md

@@ -0,0 +1,149 @@
+# Plugin Name
+
+Brief description of what this plugin does and why it's useful.
+
+## Installation
+
+### Via Marketplace
+
+```bash
+/plugin marketplace add <marketplace-url>
+/plugin install my-plugin@marketplace-name
+```
+
+### Direct Installation
+
+```bash
+/plugin install /path/to/my-plugin
+```
+
+Or from GitHub:
+
+```bash
+/plugin install https://github.com/username/my-plugin
+```
+
+## Components
+
+### Skills
+
+- **Skill Name**: Brief description of what the skill does
+- **Another Skill**: Brief description
+
+### Commands
+
+- `/my-command`: Description of what this command does
+- `/another-command`: Description of another command
+
+### Agents
+
+- **Agent Name**: Description of specialized agent behavior
+
+## Usage
+
+### Using Skills
+
+Skills are automatically discovered by Claude. Just mention tasks related to:
+- Key capability 1
+- Key capability 2
+- Key capability 3
+
+### Using Commands
+
+```bash
+# Example command usage
+/my-command param1 param2
+
+# Another example
+/another-command
+```
+
+### Example Workflows
+
+**Workflow 1: Common Task**
+1. Step 1
+2. Step 2
+3. Step 3
+
+**Workflow 2: Another Common Task**
+1. Step 1
+2. Step 2
+
+## Requirements
+
+- List any dependencies
+- Required environment variables
+- Minimum Claude Code version
+- System requirements
+
+## Configuration
+
+If your plugin needs configuration:
+
+```bash
+# Set environment variable
+export MY_PLUGIN_CONFIG=value
+```
+
+Or create a config file:
+
+```json
+{
+  "setting1": "value1",
+  "setting2": "value2"
+}
+```
+
+## Examples
+
+### Example 1: Basic Usage
+
+Detailed example showing basic functionality.
+
+```
+Step-by-step example
+```
+
+### Example 2: Advanced Usage
+
+More complex example showing advanced features.
+
+```
+Step-by-step example
+```
+
+## Troubleshooting
+
+**Problem: Common issue**
+- Solution: How to fix it
+
+**Problem: Another common issue**
+- Solution: How to fix it
+
+## Development
+
+To contribute or modify this plugin:
+
+```bash
+# Clone repository
+git clone https://github.com/username/my-plugin
+
+# Install locally
+/plugin install /path/to/my-plugin
+
+# Make changes
+# Test changes
+# Submit PR
+```
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Author
+
+Your Name (your.email@example.com)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.

skills/plugin-builder/templates/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": [
+    {
+      "event": "PreToolUse",
+      "command": "./scripts/pre-tool.sh"
+    },
+    {
+      "event": "PostToolUse",
+      "command": "./scripts/post-tool.sh"
+    },
+    {
+      "event": "UserPromptSubmit",
+      "command": "./scripts/on-submit.sh"
+    }
+  ]
+}

skills/plugin-builder/templates/plugin-minimal.json

@@ -0,0 +1,4 @@
+{
+  "name": "my-plugin",
+  "version": "1.0.0"
+}

skills/plugin-builder/templates/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "Brief description of what this plugin does",
+  "author": {
+    "name": "Your Name",
+    "email": "your.email@example.com"
+  },
+  "homepage": "https://github.com/username/plugin",
+  "repository": "https://github.com/username/plugin",
+  "license": "MIT",
+  "keywords": ["keyword1", "keyword2", "keyword3"],
+  "commands": ["./commands"],
+  "agents": ["./agents"],
+  "skills": ["./skills"],
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}