Plugin Structure for Claude Code Overview Claude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code. Key concepts: - Conventional directory layout for automatic discovery - Manifest-driven configuration in - Component-based organization (commands, agents, skills, hooks) - Portable path references using - Explicit vs. auto-discovered component loading Directory Structure Every Claude Code plugin follows this organizational pattern…

|| true)\n\nif [[ -z \"$CHANGED_FILES\" ]]; then\n echo '{\"systemMessage\": \"No code files changed. Validation passed.\"}'\n exit 0\nfi\n\n# Run appropriate linters\nISSUES=0\n\nfor file in $CHANGED_FILES; do\n case \"$file\" in\n *.js|*.ts)\n if ! npx eslint \"$file\" --quiet; then\n ISSUES=$((ISSUES + 1))\n fi\n ;;\n *.py)\n if ! python -m pylint \"$file\" --errors-only; then\n ISSUES=$((ISSUES + 1))\n fi\n ;;\n esac\ndone\n\nif [[ $ISSUES -gt 0 ]]; then\n echo \"{\\\"systemMessage\\\": \\\"Found $ISSUES code quality issues. Please fix before completing.\\\"}\"\n exit 1\nfi\n\necho '{\"systemMessage\": \"Code quality checks passed. Ready to commit.\"}'\nexit 0\n```\n\n## Usage Examples\n\n### Running Commands\n\n```\n$ claude\n> /lint\nRunning linter checks...\n\nCritical Issues (2):\n src/api/users.js:45 - SQL injection vulnerability\n src/utils/helpers.js:12 - Unhandled promise rejection\n\nWarnings (5):\n src/components/Button.tsx:23 - Missing PropTypes\n ...\n\nStyle Suggestions (8):\n src/index.js:1 - Use const instead of let\n ...\n\n> /test\nRunning test suite...\n\nTest Results:\n ✓ 245 passed\n ✗ 3 failed\n ○ 2 skipped\n\nCoverage: 87.3%\n\nUntested Files:\n src/utils/cache.js - 0% coverage\n src/api/webhooks.js - 23% coverage\n\nFailed Tests:\n 1. User API › GET /users › should handle pagination\n Expected 200, received 500\n ...\n```\n\n### Using Agents\n\n```\n> Review the changes in src/api/users.js\n\n[code-reviewer agent selected automatically]\n\nCode Review: src/api/users.js\n\nCritical Issues:\n 1. Line 45: SQL injection vulnerability\n - Using string concatenation for SQL query\n - Replace with parameterized query\n - Priority: CRITICAL\n\n 2. Line 67: Missing error handling\n - Database query without try/catch\n - Could crash server on DB error\n - Priority: HIGH\n\nSuggestions:\n 1. Line 23: Consider caching user data\n - Frequent DB queries for same users\n - Add Redis caching layer\n - Priority: MEDIUM\n```\n\n## Key Points\n\n1. **Complete manifest**: All recommended metadata fields\n2. **Multiple components**: Commands, agents, skills, hooks\n3. **Rich skills**: References and examples for detailed information\n4. **Automation**: Hooks enforce standards automatically\n5. **Integration**: Components work together cohesively\n\n## When to Use This Pattern\n\n- Production plugins for distribution\n- Team collaboration tools\n- Plugins requiring consistency enforcement\n- Complex workflows with multiple entry points\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":13310,"content_sha256":"b8cfba84bd4dbdc83365cebcde5dcc6391252372300df0c1ea7890441582d784"},{"filename":"README.md","content":"# Plugin Structure Skill\n\nComprehensive guidance on Claude Code plugin architecture, directory layout, and best practices.\n\n## Overview\n\nThis skill provides detailed knowledge about:\n- Plugin directory structure and organization\n- `plugin.json` manifest configuration\n- Component organization (commands, agents, skills, hooks)\n- Auto-discovery mechanisms\n- Portable path references with `${CLAUDE_PLUGIN_ROOT}`\n- File naming conventions\n\n## Skill Structure\n\n### SKILL.md (1,619 words)\n\nCore skill content covering:\n- Directory structure overview\n- Plugin manifest (plugin.json) fields\n- Component organization patterns\n- ${CLAUDE_PLUGIN_ROOT} usage\n- File naming conventions\n- Auto-discovery mechanism\n- Best practices\n- Common patterns\n- Troubleshooting\n\n### References\n\nDetailed documentation for deep dives:\n\n- **manifest-reference.md**: Complete `plugin.json` field reference\n - All field descriptions and examples\n - Path resolution rules\n - Validation guidelines\n - Minimal vs. complete manifest examples\n\n- **component-patterns.md**: Advanced organization patterns\n - Component lifecycle (discovery, activation)\n - Command organization patterns\n - Agent organization patterns\n - Skill organization patterns\n - Hook organization patterns\n - Script organization patterns\n - Cross-component patterns\n - Best practices for scalability\n\n### Examples\n\nThree complete plugin examples:\n\n- **minimal-plugin.md**: Simplest possible plugin\n - Single command\n - Minimal manifest\n - When to use this pattern\n\n- **standard-plugin.md**: Well-structured production plugin\n - Multiple components (commands, agents, skills, hooks)\n - Complete manifest with metadata\n - Rich skill structure\n - Integration between components\n\n- **advanced-plugin.md**: Enterprise-grade plugin\n - Multi-level organization\n - MCP server integration\n - Shared libraries\n - Configuration management\n - Security automation\n - Monitoring integration\n\n## When This Skill Triggers\n\nClaude Code activates this skill when users:\n- Ask to \"create a plugin\" or \"scaffold a plugin\"\n- Need to \"understand plugin structure\"\n- Want to \"organize plugin components\"\n- Need to \"set up plugin.json\"\n- Ask about \"${CLAUDE_PLUGIN_ROOT}\" usage\n- Want to \"add commands/agents/skills/hooks\"\n- Need \"configure auto-discovery\" help\n- Ask about plugin architecture or best practices\n\n## Progressive Disclosure\n\nThe skill uses progressive disclosure to manage context:\n\n1. **SKILL.md** (~1600 words): Core concepts and workflows\n2. **References** (~6000 words): Detailed field references and patterns\n3. **Examples** (~8000 words): Complete working examples\n\nClaude loads references and examples only as needed based on the task.\n\n## Related Skills\n\nThis skill works well with:\n- **hook-development**: For creating plugin hooks\n- **mcp-integration**: For integrating MCP servers (when available)\n- **marketplace-publishing**: For publishing plugins (when available)\n\n## Maintenance\n\nTo update this skill:\n1. Keep SKILL.md lean and focused on core concepts\n2. Move detailed information to references/\n3. Add new examples/ for common patterns\n4. Update version in SKILL.md frontmatter\n5. Ensure all documentation uses imperative/infinitive form\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3210,"content_sha256":"c7cb4931d6d71198cba6b552e4733b41940be56a65552a2ff7c5656750b95184"},{"filename":"references/component-patterns.md","content":"# Component Organization Patterns\n\nAdvanced patterns for organizing plugin components effectively.\n\n## Component Lifecycle\n\n### Discovery Phase\n\nWhen Claude Code starts:\n\n1. **Scan enabled plugins**: Read `.claude-plugin/plugin.json` for each\n2. **Discover components**: Look in default and custom paths\n3. **Parse definitions**: Read YAML frontmatter and configurations\n4. **Register components**: Make available to Claude Code\n5. **Initialize**: Start MCP servers, register hooks\n\n**Timing**: Component registration happens during Claude Code initialization, not continuously.\n\n### Activation Phase\n\nWhen components are used:\n\n**Commands**: User types slash command → Claude Code looks up → Executes\n**Agents**: Task arrives → Claude Code evaluates capabilities → Selects agent\n**Skills**: Task context matches description → Claude Code loads skill\n**Hooks**: Event occurs → Claude Code calls matching hooks\n**MCP Servers**: Tool call matches server capability → Forwards to server\n\n## Command Organization Patterns\n\n### Flat Structure\n\nSingle directory with all commands:\n\n```\ncommands/\n├── build.md\n├── test.md\n├── deploy.md\n├── review.md\n└── docs.md\n```\n\n**When to use**:\n- 5-15 commands total\n- All commands at same abstraction level\n- No clear categorization\n\n**Advantages**:\n- Simple, easy to navigate\n- No configuration needed\n- Fast discovery\n\n### Categorized Structure\n\nMultiple directories for different command types:\n\n```\ncommands/ # Core commands\n├── build.md\n└── test.md\n\nadmin-commands/ # Administrative\n├── configure.md\n└── manage.md\n\nworkflow-commands/ # Workflow automation\n├── review.md\n└── deploy.md\n```\n\n**Manifest configuration**:\n```json\n{\n \"commands\": [\n \"./commands\",\n \"./admin-commands\",\n \"./workflow-commands\"\n ]\n}\n```\n\n**When to use**:\n- 15+ commands\n- Clear functional categories\n- Different permission levels\n\n**Advantages**:\n- Organized by purpose\n- Easier to maintain\n- Can restrict access by directory\n\n### Hierarchical Structure\n\nNested organization for complex plugins:\n\n```\ncommands/\n├── ci/\n│ ├── build.md\n│ ├── test.md\n│ └── lint.md\n├── deployment/\n│ ├── staging.md\n│ └── production.md\n└── management/\n ├── config.md\n └── status.md\n```\n\n**Note**: Claude Code doesn't support nested command discovery automatically. Use custom paths:\n\n```json\n{\n \"commands\": [\n \"./commands/ci\",\n \"./commands/deployment\",\n \"./commands/management\"\n ]\n}\n```\n\n**When to use**:\n- 20+ commands\n- Multi-level categorization\n- Complex workflows\n\n**Advantages**:\n- Maximum organization\n- Clear boundaries\n- Scalable structure\n\n## Agent Organization Patterns\n\n### Role-Based Organization\n\nOrganize agents by their primary role:\n\n```\nagents/\n├── code-reviewer.md # Reviews code\n├── test-generator.md # Generates tests\n├── documentation-writer.md # Writes docs\n└── refactorer.md # Refactors code\n```\n\n**When to use**:\n- Agents have distinct, non-overlapping roles\n- Users invoke agents manually\n- Clear agent responsibilities\n\n### Capability-Based Organization\n\nOrganize by specific capabilities:\n\n```\nagents/\n├── python-expert.md # Python-specific\n├── typescript-expert.md # TypeScript-specific\n├── api-specialist.md # API design\n└── database-specialist.md # Database work\n```\n\n**When to use**:\n- Technology-specific agents\n- Domain expertise focus\n- Automatic agent selection\n\n### Workflow-Based Organization\n\nOrganize by workflow stage:\n\n```\nagents/\n├── planning-agent.md # Planning phase\n├── implementation-agent.md # Coding phase\n├── testing-agent.md # Testing phase\n└── deployment-agent.md # Deployment phase\n```\n\n**When to use**:\n- Sequential workflows\n- Stage-specific expertise\n- Pipeline automation\n\n## Skill Organization Patterns\n\n### Topic-Based Organization\n\nEach skill covers a specific topic:\n\n```\nskills/\n├── api-design/\n│ └── SKILL.md\n├── error-handling/\n│ └── SKILL.md\n├── testing-strategies/\n│ └── SKILL.md\n└── performance-optimization/\n └── SKILL.md\n```\n\n**When to use**:\n- Knowledge-based skills\n- Educational or reference content\n- Broad applicability\n\n### Tool-Based Organization\n\nSkills for specific tools or technologies:\n\n```\nskills/\n├── docker/\n│ ├── SKILL.md\n│ └── references/\n│ └── dockerfile-best-practices.md\n├── kubernetes/\n│ ├── SKILL.md\n│ └── examples/\n│ └── deployment.yaml\n└── terraform/\n ├── SKILL.md\n └── scripts/\n └── validate-config.sh\n```\n\n**When to use**:\n- Tool-specific expertise\n- Complex tool configurations\n- Tool best practices\n\n### Workflow-Based Organization\n\nSkills for complete workflows:\n\n```\nskills/\n├── code-review-workflow/\n│ ├── SKILL.md\n│ └── references/\n│ ├── checklist.md\n│ └── standards.md\n├── deployment-workflow/\n│ ├── SKILL.md\n│ └── scripts/\n│ ├── pre-deploy.sh\n│ └── post-deploy.sh\n└── testing-workflow/\n ├── SKILL.md\n └── examples/\n └── test-structure.md\n```\n\n**When to use**:\n- Multi-step processes\n- Company-specific workflows\n- Process automation\n\n### Skill with Rich Resources\n\nComprehensive skill with all resource types:\n\n```\nskills/\n└── api-testing/\n ├── SKILL.md # Core skill (1500 words)\n ├── references/\n │ ├── rest-api-guide.md\n │ ├── graphql-guide.md\n │ └── authentication.md\n ├── examples/\n │ ├── basic-test.js\n │ ├── authenticated-test.js\n │ └── integration-test.js\n ├── scripts/\n │ ├── run-tests.sh\n │ └── generate-report.py\n └── assets/\n └── test-template.json\n```\n\n**Resource usage**:\n- **SKILL.md**: Overview and when to use resources\n- **references/**: Detailed guides (loaded as needed)\n- **examples/**: Copy-paste code samples\n- **scripts/**: Executable test runners\n- **assets/**: Templates and configurations\n\n## Hook Organization Patterns\n\n### Monolithic Configuration\n\nSingle hooks.json with all hooks:\n\n```\nhooks/\n├── hooks.json # All hook definitions\n└── scripts/\n ├── validate-write.sh\n ├── validate-bash.sh\n └── load-context.sh\n```\n\n**hooks.json**:\n```json\n{\n \"PreToolUse\": [...],\n \"PostToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n}\n```\n\n**When to use**:\n- 5-10 hooks total\n- Simple hook logic\n- Centralized configuration\n\n### Event-Based Organization\n\nSeparate files per event type:\n\n```\nhooks/\n├── hooks.json # Combines all\n├── pre-tool-use.json # PreToolUse hooks\n├── post-tool-use.json # PostToolUse hooks\n├── stop.json # Stop hooks\n└── scripts/\n ├── validate/\n │ ├── write.sh\n │ └── bash.sh\n └── context/\n └── load.sh\n```\n\n**hooks.json** (combines):\n```json\n{\n \"PreToolUse\": ${file:./pre-tool-use.json},\n \"PostToolUse\": ${file:./post-tool-use.json},\n \"Stop\": ${file:./stop.json}\n}\n```\n\n**Note**: Use build script to combine files, Claude Code doesn't support file references.\n\n**When to use**:\n- 10+ hooks\n- Different teams managing different events\n- Complex hook configurations\n\n### Purpose-Based Organization\n\nGroup by functional purpose:\n\n```\nhooks/\n├── hooks.json\n└── scripts/\n ├── security/\n │ ├── validate-paths.sh\n │ ├── check-credentials.sh\n │ └── scan-malware.sh\n ├── quality/\n │ ├── lint-code.sh\n │ ├── check-tests.sh\n │ └── verify-docs.sh\n └── workflow/\n ├── notify-team.sh\n └── update-status.sh\n```\n\n**When to use**:\n- Many hook scripts\n- Clear functional boundaries\n- Team specialization\n\n## Script Organization Patterns\n\n### Flat Scripts\n\nAll scripts in single directory:\n\n```\nscripts/\n├── build.sh\n├── test.py\n├── deploy.sh\n├── validate.js\n└── report.py\n```\n\n**When to use**:\n- 5-10 scripts\n- All scripts related\n- Simple plugin\n\n### Categorized Scripts\n\nGroup by purpose:\n\n```\nscripts/\n├── build/\n│ ├── compile.sh\n│ └── package.sh\n├── test/\n│ ├── run-unit.sh\n│ └── run-integration.sh\n├── deploy/\n│ ├── staging.sh\n│ └── production.sh\n└── utils/\n ├── log.sh\n └── notify.sh\n```\n\n**When to use**:\n- 10+ scripts\n- Clear categories\n- Reusable utilities\n\n### Language-Based Organization\n\nGroup by programming language:\n\n```\nscripts/\n├── bash/\n│ ├── build.sh\n│ └── deploy.sh\n├── python/\n│ ├── analyze.py\n│ └── report.py\n└── javascript/\n ├── bundle.js\n └── optimize.js\n```\n\n**When to use**:\n- Multi-language scripts\n- Different runtime requirements\n- Language-specific dependencies\n\n## Cross-Component Patterns\n\n### Shared Resources\n\nComponents sharing common resources:\n\n```\nplugin/\n├── commands/\n│ ├── test.md # Uses lib/test-utils.sh\n│ └── deploy.md # Uses lib/deploy-utils.sh\n├── agents/\n│ └── tester.md # References lib/test-utils.sh\n├── hooks/\n│ └── scripts/\n│ └── pre-test.sh # Sources lib/test-utils.sh\n└── lib/\n ├── test-utils.sh\n └── deploy-utils.sh\n```\n\n**Usage in components**:\n```bash\n#!/bin/bash\nsource \"${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh\"\nrun_tests\n```\n\n**Benefits**:\n- Code reuse\n- Consistent behavior\n- Easier maintenance\n\n### Layered Architecture\n\nSeparate concerns into layers:\n\n```\nplugin/\n├── commands/ # User interface layer\n├── agents/ # Orchestration layer\n├── skills/ # Knowledge layer\n└── lib/\n ├── core/ # Core business logic\n ├── integrations/ # External services\n └── utils/ # Helper functions\n```\n\n**When to use**:\n- Large plugins (100+ files)\n- Multiple developers\n- Clear separation of concerns\n\n### Plugin Within Plugin\n\nNested plugin structure:\n\n```\nplugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── core/ # Core functionality\n│ ├── commands/\n│ └── agents/\n└── extensions/ # Optional extensions\n ├── extension-a/\n │ ├── commands/\n │ └── agents/\n └── extension-b/\n ├── commands/\n └── agents/\n```\n\n**Manifest**:\n```json\n{\n \"commands\": [\n \"./core/commands\",\n \"./extensions/extension-a/commands\",\n \"./extensions/extension-b/commands\"\n ]\n}\n```\n\n**When to use**:\n- Modular functionality\n- Optional features\n- Plugin families\n\n## Best Practices\n\n### Naming\n\n1. **Consistent naming**: Match file names to component purpose\n2. **Descriptive names**: Indicate what component does\n3. **Avoid abbreviations**: Use full words for clarity\n\n### Organization\n\n1. **Start simple**: Use flat structure, reorganize when needed\n2. **Group related items**: Keep related components together\n3. **Separate concerns**: Don't mix unrelated functionality\n\n### Scalability\n\n1. **Plan for growth**: Choose structure that scales\n2. **Refactor early**: Reorganize before it becomes painful\n3. **Document structure**: Explain organization in README\n\n### Maintainability\n\n1. **Consistent patterns**: Use same structure throughout\n2. **Minimize nesting**: Keep directory depth manageable\n3. **Use conventions**: Follow community standards\n\n### Performance\n\n1. **Avoid deep nesting**: Impacts discovery time\n2. **Minimize custom paths**: Use defaults when possible\n3. **Keep configurations small**: Large configs slow loading\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12086,"content_sha256":"38681792a6aba4f06d3c391b20b04060263f1fbaacc5880cc0cafe0543d37f91"},{"filename":"references/manifest-reference.md","content":"# Plugin Manifest Reference\n\nComplete reference for `plugin.json` configuration.\n\n## File Location\n\n**Required path**: `.claude-plugin/plugin.json`\n\nThe manifest MUST be in the `.claude-plugin/` directory at the plugin root. Claude Code will not recognize plugins without this file in the correct location.\n\n## Complete Field Reference\n\n### Core Fields\n\n#### name (required)\n\n**Type**: String\n**Format**: kebab-case\n**Example**: `\"test-automation-suite\"`\n\nThe unique identifier for the plugin. Used for:\n- Plugin identification in Claude Code\n- Conflict detection with other plugins\n- Command namespacing (optional)\n\n**Requirements**:\n- Must be unique across all installed plugins\n- Use only lowercase letters, numbers, and hyphens\n- No spaces or special characters\n- Start with a letter\n- End with a letter or number\n\n**Validation**:\n```javascript\n/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/\n```\n\n**Examples**:\n- ✅ Good: `api-tester`, `code-review`, `git-workflow-automation`\n- ❌ Bad: `API Tester`, `code_review`, `-git-workflow`, `test-`\n\n#### version\n\n**Type**: String\n**Format**: Semantic versioning (MAJOR.MINOR.PATCH)\n**Example**: `\"2.1.0\"`\n**Default**: `\"0.1.0\"` if not specified\n\nSemantic versioning guidelines:\n- **MAJOR**: Incompatible API changes, breaking changes\n- **MINOR**: New functionality, backward-compatible\n- **PATCH**: Bug fixes, backward-compatible\n\n**Pre-release versions**:\n- `\"1.0.0-alpha.1\"` - Alpha release\n- `\"1.0.0-beta.2\"` - Beta release\n- `\"1.0.0-rc.1\"` - Release candidate\n\n**Examples**:\n- `\"0.1.0\"` - Initial development\n- `\"1.0.0\"` - First stable release\n- `\"1.2.3\"` - Patch update to 1.2\n- `\"2.0.0\"` - Major version with breaking changes\n\n#### description\n\n**Type**: String\n**Length**: 50-200 characters recommended\n**Example**: `\"Automates code review workflows with style checks and automated feedback\"`\n\nBrief explanation of plugin purpose and functionality.\n\n**Best practices**:\n- Focus on what the plugin does, not how\n- Use active voice\n- Mention key features or benefits\n- Keep under 200 characters for marketplace display\n\n**Examples**:\n- ✅ \"Generates comprehensive test suites from code analysis and coverage reports\"\n- ✅ \"Integrates with Jira for automatic issue tracking and sprint management\"\n- ❌ \"A plugin that helps you do testing stuff\"\n- ❌ \"This is a very long description that goes on and on about every single feature...\"\n\n### Metadata Fields\n\n#### author\n\n**Type**: Object\n**Fields**: name (required), email (optional), url (optional)\n\n```json\n{\n \"author\": {\n \"name\": \"Jane Developer\",\n \"email\": \"[email protected]\",\n \"url\": \"https://janedeveloper.com\"\n }\n}\n```\n\n**Alternative format** (string only):\n```json\n{\n \"author\": \"Jane Developer \[email protected]> (https://janedeveloper.com)\"\n}\n```\n\n**Use cases**:\n- Credit and attribution\n- Contact for support or questions\n- Marketplace display\n- Community recognition\n\n#### homepage\n\n**Type**: String (URL)\n**Example**: `\"https://docs.example.com/plugins/my-plugin\"`\n\nLink to plugin documentation or landing page.\n\n**Should point to**:\n- Plugin documentation site\n- Project homepage\n- Detailed usage guide\n- Installation instructions\n\n**Not for**:\n- Source code (use `repository` field)\n- Issue tracker (include in documentation)\n- Personal websites (use `author.url`)\n\n#### repository\n\n**Type**: String (URL) or Object\n**Example**: `\"https://github.com/user/plugin-name\"`\n\nSource code repository location.\n\n**String format**:\n```json\n{\n \"repository\": \"https://github.com/user/plugin-name\"\n}\n```\n\n**Object format** (detailed):\n```json\n{\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/user/plugin-name.git\",\n \"directory\": \"packages/plugin-name\"\n }\n}\n```\n\n**Use cases**:\n- Source code access\n- Issue reporting\n- Community contributions\n- Transparency and trust\n\n#### license\n\n**Type**: String\n**Format**: SPDX identifier\n**Example**: `\"MIT\"`\n\nSoftware license identifier.\n\n**Common licenses**:\n- `\"MIT\"` - Permissive, popular choice\n- `\"Apache-2.0\"` - Permissive with patent grant\n- `\"GPL-3.0\"` - Copyleft\n- `\"BSD-3-Clause\"` - Permissive\n- `\"ISC\"` - Permissive, similar to MIT\n- `\"UNLICENSED\"` - Proprietary, not open source\n\n**Full list**: https://spdx.org/licenses/\n\n**Multiple licenses**:\n```json\n{\n \"license\": \"(MIT OR Apache-2.0)\"\n}\n```\n\n#### keywords\n\n**Type**: Array of strings\n**Example**: `[\"testing\", \"automation\", \"ci-cd\", \"quality-assurance\"]`\n\nTags for plugin discovery and categorization.\n\n**Best practices**:\n- Use 5-10 keywords\n- Include functionality categories\n- Add technology names\n- Use common search terms\n- Avoid duplicating plugin name\n\n**Categories to consider**:\n- Functionality: `testing`, `debugging`, `documentation`, `deployment`\n- Technologies: `typescript`, `python`, `docker`, `aws`\n- Workflows: `ci-cd`, `code-review`, `git-workflow`\n- Domains: `web-development`, `data-science`, `devops`\n\n### Component Path Fields\n\n#### commands\n\n**Type**: String or Array of strings\n**Default**: `[\"./commands\"]`\n**Example**: `\"./cli-commands\"`\n\nAdditional directories or files containing command definitions.\n\n**Single path**:\n```json\n{\n \"commands\": \"./custom-commands\"\n}\n```\n\n**Multiple paths**:\n```json\n{\n \"commands\": [\n \"./commands\",\n \"./admin-commands\",\n \"./experimental-commands\"\n ]\n}\n```\n\n**Behavior**: Supplements default `commands/` directory (does not replace)\n\n**Use cases**:\n- Organizing commands by category\n- Separating stable from experimental commands\n- Loading commands from shared locations\n\n#### agents\n\n**Type**: String or Array of strings\n**Default**: `[\"./agents\"]`\n**Example**: `\"./specialized-agents\"`\n\nAdditional directories or files containing agent definitions.\n\n**Format**: Same as `commands` field\n\n**Use cases**:\n- Grouping agents by specialization\n- Separating general-purpose from task-specific agents\n- Loading agents from plugin dependencies\n\n#### hooks\n\n**Type**: String (path to JSON file) or Object (inline configuration)\n**Default**: `\"./hooks/hooks.json\"`\n\nHook configuration location or inline definition.\n\n**File path**:\n```json\n{\n \"hooks\": \"./config/hooks.json\"\n}\n```\n\n**Inline configuration**:\n```json\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\",\n \"timeout\": 30\n }\n ]\n }\n ]\n }\n}\n```\n\n**Use cases**:\n- Simple plugins: Inline configuration (\u003c 50 lines)\n- Complex plugins: External JSON file\n- Multiple hook sets: Separate files for different contexts\n\n#### mcpServers\n\n**Type**: String (path to JSON file) or Object (inline configuration)\n**Default**: `./.mcp.json`\n\nMCP server configuration location or inline definition.\n\n**File path**:\n```json\n{\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n**Inline configuration**:\n```json\n{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/github-mcp.js\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\"\n }\n }\n }\n}\n```\n\n**Use cases**:\n- Simple plugins: Single inline server (\u003c 20 lines)\n- Complex plugins: External `.mcp.json` file\n- Multiple servers: Always use external file\n\n## Path Resolution\n\n### Relative Path Rules\n\nAll paths in component fields must follow these rules:\n\n1. **Must be relative**: No absolute paths\n2. **Must start with `./`**: Indicates relative to plugin root\n3. **Cannot use `../`**: No parent directory navigation\n4. **Forward slashes only**: Even on Windows\n\n**Examples**:\n- ✅ `\"./commands\"`\n- ✅ `\"./src/commands\"`\n- ✅ `\"./configs/hooks.json\"`\n- ❌ `\"/Users/name/plugin/commands\"`\n- ❌ `\"commands\"` (missing `./`)\n- ❌ `\"../shared/commands\"`\n- ❌ `\".\\\\commands\"` (backslash)\n\n### Resolution Order\n\nWhen Claude Code loads components:\n\n1. **Default directories**: Scans standard locations first\n - `./commands/`\n - `./agents/`\n - `./skills/`\n - `./hooks/hooks.json`\n - `./.mcp.json`\n\n2. **Custom paths**: Scans paths specified in manifest\n - Paths from `commands` field\n - Paths from `agents` field\n - Files from `hooks` and `mcpServers` fields\n\n3. **Merge behavior**: Components from all locations load\n - No overwriting\n - All discovered components register\n - Name conflicts cause errors\n\n## Validation\n\n### Manifest Validation\n\nClaude Code validates the manifest on plugin load:\n\n**Syntax validation**:\n- Valid JSON format\n- No syntax errors\n- Correct field types\n\n**Field validation**:\n- `name` field present and valid format\n- `version` follows semantic versioning (if present)\n- Paths are relative with `./` prefix\n- URLs are valid (if present)\n\n**Component validation**:\n- Referenced paths exist\n- Hook and MCP configurations are valid\n- No circular dependencies\n\n### Common Validation Errors\n\n**Invalid name format**:\n```json\n{\n \"name\": \"My Plugin\" // ❌ Contains spaces\n}\n```\nFix: Use kebab-case\n```json\n{\n \"name\": \"my-plugin\" // ✅\n}\n```\n\n**Absolute path**:\n```json\n{\n \"commands\": \"/Users/name/commands\" // ❌ Absolute path\n}\n```\nFix: Use relative path\n```json\n{\n \"commands\": \"./commands\" // ✅\n}\n```\n\n**Missing ./ prefix**:\n```json\n{\n \"hooks\": \"hooks/hooks.json\" // ❌ No ./\n}\n```\nFix: Add ./ prefix\n```json\n{\n \"hooks\": \"./hooks/hooks.json\" // ✅\n}\n```\n\n**Invalid version**:\n```json\n{\n \"version\": \"1.0\" // ❌ Not semantic versioning\n}\n```\nFix: Use MAJOR.MINOR.PATCH\n```json\n{\n \"version\": \"1.0.0\" // ✅\n}\n```\n\n## Minimal vs. Complete Examples\n\n### Minimal Plugin\n\nBare minimum for a working plugin:\n\n```json\n{\n \"name\": \"hello-world\"\n}\n```\n\nRelies entirely on default directory discovery.\n\n### Recommended Plugin\n\nGood metadata for distribution:\n\n```json\n{\n \"name\": \"code-review-assistant\",\n \"version\": \"1.0.0\",\n \"description\": \"Automates code review with style checks and suggestions\",\n \"author\": {\n \"name\": \"Jane Developer\",\n \"email\": \"[email protected]\"\n },\n \"homepage\": \"https://docs.example.com/code-review\",\n \"repository\": \"https://github.com/janedev/code-review-assistant\",\n \"license\": \"MIT\",\n \"keywords\": [\"code-review\", \"automation\", \"quality\", \"ci-cd\"]\n}\n```\n\n### Complete Plugin\n\nFull configuration with all features:\n\n```json\n{\n \"name\": \"enterprise-devops\",\n \"version\": \"2.3.1\",\n \"description\": \"Comprehensive DevOps automation for enterprise CI/CD pipelines\",\n \"author\": {\n \"name\": \"DevOps Team\",\n \"email\": \"[email protected]\",\n \"url\": \"https://company.com/devops\"\n },\n \"homepage\": \"https://docs.company.com/plugins/devops\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/company/devops-plugin.git\"\n },\n \"license\": \"Apache-2.0\",\n \"keywords\": [\n \"devops\",\n \"ci-cd\",\n \"automation\",\n \"kubernetes\",\n \"docker\",\n \"deployment\"\n ],\n \"commands\": [\n \"./commands\",\n \"./admin-commands\"\n ],\n \"agents\": \"./specialized-agents\",\n \"hooks\": \"./config/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n## Best Practices\n\n### Metadata\n\n1. **Always include version**: Track changes and updates\n2. **Write clear descriptions**: Help users understand plugin purpose\n3. **Provide contact information**: Enable user support\n4. **Link to documentation**: Reduce support burden\n5. **Choose appropriate license**: Match project goals\n\n### Paths\n\n1. **Use defaults when possible**: Minimize configuration\n2. **Organize logically**: Group related components\n3. **Document custom paths**: Explain why non-standard layout used\n4. **Test path resolution**: Verify on multiple systems\n\n### Maintenance\n\n1. **Bump version on changes**: Follow semantic versioning\n2. **Update keywords**: Reflect new functionality\n3. **Keep description current**: Match actual capabilities\n4. **Maintain changelog**: Track version history\n5. **Update repository links**: Keep URLs current\n\n### Distribution\n\n1. **Complete metadata before publishing**: All fields filled\n2. **Test on clean install**: Verify plugin works without dev environment\n3. **Validate manifest**: Use validation tools\n4. **Include README**: Document installation and usage\n5. **Specify license file**: Include LICENSE file in plugin root\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12061,"content_sha256":"d0ff8ffece4754df92c543266b8d0b689fb85473f51fbb57e215f2d235ee9782"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Plugin Structure for Claude Code","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"Claude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code.","type":"text"}]},{"type":"paragraph","content":[{"text":"Key concepts:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Conventional directory layout for automatic discovery","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Manifest-driven configuration in ","type":"text"},{"text":".claude-plugin/plugin.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component-based organization (commands, agents, skills, hooks)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Portable path references using ","type":"text"},{"text":"${CLAUDE_PLUGIN_ROOT}","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Explicit vs. auto-discovered component loading","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Directory Structure","type":"text"}]},{"type":"paragraph","content":[{"text":"Every Claude Code plugin follows this organizational pattern:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"plugin-name/\n├── .claude-plugin/\n│ └── plugin.json # Required: Plugin manifest\n├── commands/ # Slash commands (.md files)\n├── agents/ # Subagent definitions (.md files)\n├── skills/ # Agent skills (subdirectories)\n│ └── skill-name/\n│ └── SKILL.md # Required for each skill\n├── hooks/\n│ └── hooks.json # Event handler configuration\n├── .mcp.json # MCP server definitions\n└── scripts/ # Helper scripts and utilities","type":"text"}]},{"type":"paragraph","content":[{"text":"Critical rules:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Manifest location","type":"text","marks":[{"type":"strong"}]},{"text":": The ","type":"text"},{"text":"plugin.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" manifest MUST be in ","type":"text"},{"text":".claude-plugin/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component locations","type":"text","marks":[{"type":"strong"}]},{"text":": All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside ","type":"text"},{"text":".claude-plugin/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optional components","type":"text","marks":[{"type":"strong"}]},{"text":": Only create directories for components the plugin actually uses","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Naming convention","type":"text","marks":[{"type":"strong"}]},{"text":": Use kebab-case for all directory and file names","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Plugin Manifest (plugin.json)","type":"text"}]},{"type":"paragraph","content":[{"text":"The manifest defines plugin metadata and configuration. Located at ","type":"text"},{"text":".claude-plugin/plugin.json","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Required Fields","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"name\": \"plugin-name\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Name requirements:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use kebab-case format (lowercase with hyphens)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Must be unique across installed plugins","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No spaces or special characters","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"code-review-assistant","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"test-runner","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"api-docs","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Recommended Metadata","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"name\": \"plugin-name\",\n \"version\": \"1.0.0\",\n \"description\": \"Brief explanation of plugin purpose\",\n \"author\": {\n \"name\": \"Author Name\",\n \"email\": \"[email protected]\",\n \"url\": \"https://example.com\"\n },\n \"homepage\": \"https://docs.example.com\",\n \"repository\": \"https://github.com/user/plugin-name\",\n \"license\": \"MIT\",\n \"keywords\": [\"testing\", \"automation\", \"ci-cd\"]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Version format","type":"text","marks":[{"type":"strong"}]},{"text":": Follow semantic versioning (MAJOR.MINOR.PATCH) ","type":"text"},{"text":"Keywords","type":"text","marks":[{"type":"strong"}]},{"text":": Use for plugin discovery and categorization","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Component Path Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"Specify custom paths for components (supplements default directories):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"name\": \"plugin-name\",\n \"commands\": \"./custom-commands\",\n \"agents\": [\"./agents\", \"./specialized-agents\"],\n \"hooks\": \"./config/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Important","type":"text","marks":[{"type":"strong"}]},{"text":": Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.","type":"text"}]},{"type":"paragraph","content":[{"text":"Path rules:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Must be relative to plugin root","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Must start with ","type":"text"},{"text":"./","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cannot use absolute paths","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Support arrays for multiple locations","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Component Organization","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Commands","type":"text"}]},{"type":"paragraph","content":[{"text":"Location","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"commands/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory ","type":"text"},{"text":"Format","type":"text","marks":[{"type":"strong"}]},{"text":": Markdown files with YAML frontmatter ","type":"text"},{"text":"Auto-discovery","type":"text","marks":[{"type":"strong"}]},{"text":": All ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files in ","type":"text"},{"text":"commands/","type":"text","marks":[{"type":"code_inline"}]},{"text":" load automatically","type":"text"}]},{"type":"paragraph","content":[{"text":"Example structure","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"commands/\n├── review.md # /review command\n├── test.md # /test command\n└── deploy.md # /deploy command","type":"text"}]},{"type":"paragraph","content":[{"text":"File format","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"---\nname: command-name\ndescription: Command description\n---\n\nCommand implementation instructions...","type":"text"}]},{"type":"paragraph","content":[{"text":"Usage","type":"text","marks":[{"type":"strong"}]},{"text":": Commands integrate as native slash commands in Claude Code","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Agents","type":"text"}]},{"type":"paragraph","content":[{"text":"Location","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"agents/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory ","type":"text"},{"text":"Format","type":"text","marks":[{"type":"strong"}]},{"text":": Markdown files with YAML frontmatter ","type":"text"},{"text":"Auto-discovery","type":"text","marks":[{"type":"strong"}]},{"text":": All ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files in ","type":"text"},{"text":"agents/","type":"text","marks":[{"type":"code_inline"}]},{"text":" load automatically","type":"text"}]},{"type":"paragraph","content":[{"text":"Example structure","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"agents/\n├── code-reviewer.md\n├── test-generator.md\n└── refactorer.md","type":"text"}]},{"type":"paragraph","content":[{"text":"File format","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"---\ndescription: Agent role and expertise\ncapabilities:\n - Specific task 1\n - Specific task 2\n---\n\nDetailed agent instructions and knowledge...","type":"text"}]},{"type":"paragraph","content":[{"text":"Usage","type":"text","marks":[{"type":"strong"}]},{"text":": Users can invoke agents manually, or Claude Code selects them automatically based on task context","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Skills","type":"text"}]},{"type":"paragraph","content":[{"text":"Location","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"skills/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory with subdirectories per skill ","type":"text"},{"text":"Format","type":"text","marks":[{"type":"strong"}]},{"text":": Each skill in its own directory with ","type":"text"},{"text":"SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" file ","type":"text"},{"text":"Auto-discovery","type":"text","marks":[{"type":"strong"}]},{"text":": All ","type":"text"},{"text":"SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files in skill subdirectories load automatically","type":"text"}]},{"type":"paragraph","content":[{"text":"Example structure","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"skills/\n├── api-testing/\n│ ├── SKILL.md\n│ ├── scripts/\n│ │ └── test-runner.py\n│ └── references/\n│ └── api-spec.md\n└── database-migrations/\n ├── SKILL.md\n └── examples/\n └── migration-template.sql","type":"text"}]},{"type":"paragraph","content":[{"text":"SKILL.md format","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"---\nname: Skill Name\ndescription: When to use this skill\nversion: 1.0.0\n---\n\nSkill instructions and guidance...","type":"text"}]},{"type":"paragraph","content":[{"text":"Supporting files","type":"text","marks":[{"type":"strong"}]},{"text":": Skills can include scripts, references, examples, or assets in subdirectories","type":"text"}]},{"type":"paragraph","content":[{"text":"Usage","type":"text","marks":[{"type":"strong"}]},{"text":": Claude Code autonomously activates skills based on task context matching the description","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Hooks","type":"text"}]},{"type":"paragraph","content":[{"text":"Location","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"hooks/hooks.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" or inline in ","type":"text"},{"text":"plugin.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"Format","type":"text","marks":[{"type":"strong"}]},{"text":": JSON configuration defining event handlers ","type":"text"},{"text":"Registration","type":"text","marks":[{"type":"strong"}]},{"text":": Hooks register automatically when plugin enables","type":"text"}]},{"type":"paragraph","content":[{"text":"Example structure","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"hooks/\n├── hooks.json # Hook configuration\n└── scripts/\n ├── validate.sh # Hook script\n └── check-style.sh # Hook script","type":"text"}]},{"type":"paragraph","content":[{"text":"Configuration format","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"PreToolUse\": [{\n \"matcher\": \"Write|Edit\",\n \"hooks\": [{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh\",\n \"timeout\": 30\n }]\n }]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Available events","type":"text","marks":[{"type":"strong"}]},{"text":": PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification","type":"text"}]},{"type":"paragraph","content":[{"text":"Usage","type":"text","marks":[{"type":"strong"}]},{"text":": Hooks execute automatically in response to Claude Code events","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"MCP Servers","type":"text"}]},{"type":"paragraph","content":[{"text":"Location","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":".mcp.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" at plugin root or inline in ","type":"text"},{"text":"plugin.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"Format","type":"text","marks":[{"type":"strong"}]},{"text":": JSON configuration for MCP server definitions ","type":"text"},{"text":"Auto-start","type":"text","marks":[{"type":"strong"}]},{"text":": Servers start automatically when plugin enables","type":"text"}]},{"type":"paragraph","content":[{"text":"Example format","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"mcpServers\": {\n \"server-name\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/server.js\"],\n \"env\": {\n \"API_KEY\": \"${API_KEY}\"\n }\n }\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Usage","type":"text","marks":[{"type":"strong"}]},{"text":": MCP servers integrate seamlessly with Claude Code's tool system","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Portable Path References","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"${CLAUDE_PLUGIN_ROOT}","type":"text"}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"${CLAUDE_PLUGIN_ROOT}","type":"text","marks":[{"type":"code_inline"}]},{"text":" environment variable for all intra-plugin path references:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Why it matters","type":"text","marks":[{"type":"strong"}]},{"text":": Plugins install in different locations depending on:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User installation method (marketplace, local, npm)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Operating system conventions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User preferences","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Where to use it","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hook command paths","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP server command arguments","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Script execution references","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resource file paths","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Never use","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hardcoded absolute paths (","type":"text"},{"text":"/Users/name/plugins/...","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Relative paths from working directory (","type":"text"},{"text":"./scripts/...","type":"text","marks":[{"type":"code_inline"}]},{"text":" in commands)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Home directory shortcuts (","type":"text"},{"text":"~/plugins/...","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Path Resolution Rules","type":"text"}]},{"type":"paragraph","content":[{"text":"In manifest JSON fields","type":"text","marks":[{"type":"strong"}]},{"text":" (hooks, MCP servers):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"\"command\": \"${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh\"","type":"text"}]},{"type":"paragraph","content":[{"text":"In component files","type":"text","marks":[{"type":"strong"}]},{"text":" (commands, agents, skills):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"Reference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py","type":"text"}]},{"type":"paragraph","content":[{"text":"In executed scripts","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# ${CLAUDE_PLUGIN_ROOT} available as environment variable\nsource \"${CLAUDE_PLUGIN_ROOT}/lib/common.sh\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"File Naming Conventions","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Component Files","type":"text"}]},{"type":"paragraph","content":[{"text":"Commands","type":"text","marks":[{"type":"strong"}]},{"text":": Use kebab-case ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"code-review.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" → ","type":"text"},{"text":"/code-review","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"run-tests.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" → ","type":"text"},{"text":"/run-tests","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"api-docs.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" → ","type":"text"},{"text":"/api-docs","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Agents","type":"text","marks":[{"type":"strong"}]},{"text":": Use kebab-case ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files describing role","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"test-generator.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"code-reviewer.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"performance-analyzer.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Skills","type":"text","marks":[{"type":"strong"}]},{"text":": Use kebab-case directory names","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"api-testing/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"database-migrations/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"error-handling/","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Supporting Files","type":"text"}]},{"type":"paragraph","content":[{"text":"Scripts","type":"text","marks":[{"type":"strong"}]},{"text":": Use descriptive kebab-case names with appropriate extensions","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"validate-input.sh","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"generate-report.py","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"process-data.js","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Documentation","type":"text","marks":[{"type":"strong"}]},{"text":": Use kebab-case markdown files","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"api-reference.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"migration-guide.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"best-practices.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Configuration","type":"text","marks":[{"type":"strong"}]},{"text":": Use standard names","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"hooks.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":".mcp.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"plugin.json","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Auto-Discovery Mechanism","type":"text"}]},{"type":"paragraph","content":[{"text":"Claude Code automatically discovers and loads components:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Plugin manifest","type":"text","marks":[{"type":"strong"}]},{"text":": Reads ","type":"text"},{"text":".claude-plugin/plugin.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" when plugin enables","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commands","type":"text","marks":[{"type":"strong"}]},{"text":": Scans ","type":"text"},{"text":"commands/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory for ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Agents","type":"text","marks":[{"type":"strong"}]},{"text":": Scans ","type":"text"},{"text":"agents/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory for ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skills","type":"text","marks":[{"type":"strong"}]},{"text":": Scans ","type":"text"},{"text":"skills/","type":"text","marks":[{"type":"code_inline"}]},{"text":" for subdirectories containing ","type":"text"},{"text":"SKILL.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hooks","type":"text","marks":[{"type":"strong"}]},{"text":": Loads configuration from ","type":"text"},{"text":"hooks/hooks.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" or manifest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP servers","type":"text","marks":[{"type":"strong"}]},{"text":": Loads configuration from ","type":"text"},{"text":".mcp.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" or manifest","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Discovery timing","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Plugin installation: Components register with Claude Code","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Plugin enable: Components become available for use","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No restart required: Changes take effect on next Claude Code session","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Override behavior","type":"text","marks":[{"type":"strong"}]},{"text":": Custom paths in ","type":"text"},{"text":"plugin.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" supplement (not replace) default directories","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Best Practices","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Organization","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Logical grouping","type":"text","marks":[{"type":"strong"}]},{"text":": Group related components together","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Put test-related commands, agents, and skills together","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create subdirectories in ","type":"text"},{"text":"scripts/","type":"text","marks":[{"type":"code_inline"}]},{"text":" for different purposes","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Minimal manifest","type":"text","marks":[{"type":"strong"}]},{"text":": Keep ","type":"text"},{"text":"plugin.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" lean","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Only specify custom paths when necessary","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rely on auto-discovery for standard layouts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use inline configuration only for simple cases","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Documentation","type":"text","marks":[{"type":"strong"}]},{"text":": Include README files","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Plugin root: Overall purpose and usage","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component directories: Specific guidance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Script directories: Usage and requirements","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Naming","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Consistency","type":"text","marks":[{"type":"strong"}]},{"text":": Use consistent naming across components","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If command is ","type":"text"},{"text":"test-runner","type":"text","marks":[{"type":"code_inline"}]},{"text":", name related agent ","type":"text"},{"text":"test-runner-agent","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Match skill directory names to their purpose","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Clarity","type":"text","marks":[{"type":"strong"}]},{"text":": Use descriptive names that indicate purpose","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Good: ","type":"text"},{"text":"api-integration-testing/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"code-quality-checker.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Avoid: ","type":"text"},{"text":"utils/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"misc.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"temp.sh","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Length","type":"text","marks":[{"type":"strong"}]},{"text":": Balance brevity with clarity","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commands: 2-3 words (","type":"text"},{"text":"review-pr","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"run-ci","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Agents: Describe role clearly (","type":"text"},{"text":"code-reviewer","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"test-generator","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skills: Topic-focused (","type":"text"},{"text":"error-handling","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"api-design","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Portability","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Always use ${CLAUDE_PLUGIN_ROOT}","type":"text","marks":[{"type":"strong"}]},{"text":": Never hardcode paths","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test on multiple systems","type":"text","marks":[{"type":"strong"}]},{"text":": Verify on macOS, Linux, Windows","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document dependencies","type":"text","marks":[{"type":"strong"}]},{"text":": List required tools and versions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Avoid system-specific features","type":"text","marks":[{"type":"strong"}]},{"text":": Use portable bash/Python constructs","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Maintenance","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Version consistently","type":"text","marks":[{"type":"strong"}]},{"text":": Update version in plugin.json for releases","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Deprecate gracefully","type":"text","marks":[{"type":"strong"}]},{"text":": Mark old components clearly before removal","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document breaking changes","type":"text","marks":[{"type":"strong"}]},{"text":": Note changes affecting existing users","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test thoroughly","type":"text","marks":[{"type":"strong"}]},{"text":": Verify all components work after changes","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Common Patterns","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Minimal Plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"Single command with no dependencies:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"my-plugin/\n├── .claude-plugin/\n│ └── plugin.json # Just name field\n└── commands/\n └── hello.md # Single command","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Full-Featured Plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"Complete plugin with all component types:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"my-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/ # User-facing commands\n├── agents/ # Specialized subagents\n├── skills/ # Auto-activating skills\n├── hooks/ # Event handlers\n│ ├── hooks.json\n│ └── scripts/\n├── .mcp.json # External integrations\n└── scripts/ # Shared utilities","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Skill-Focused Plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"Plugin providing only skills:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"my-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n└── skills/\n ├── skill-one/\n │ └── SKILL.md\n └── skill-two/\n └── SKILL.md","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"paragraph","content":[{"text":"Component not loading","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify file is in correct directory with correct extension","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check YAML frontmatter syntax (commands, agents, skills)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ensure skill has ","type":"text"},{"text":"SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (not ","type":"text"},{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" or other name)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Confirm plugin is enabled in Claude Code settings","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Path resolution errors","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Replace all hardcoded paths with ","type":"text"},{"text":"${CLAUDE_PLUGIN_ROOT}","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify paths are relative and start with ","type":"text"},{"text":"./","type":"text","marks":[{"type":"code_inline"}]},{"text":" in manifest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check that referenced files exist at specified paths","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test with ","type":"text"},{"text":"echo $CLAUDE_PLUGIN_ROOT","type":"text","marks":[{"type":"code_inline"}]},{"text":" in hook scripts","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Auto-discovery not working","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Confirm directories are at plugin root (not in ","type":"text"},{"text":".claude-plugin/","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check file naming follows conventions (kebab-case, correct extensions)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify custom paths in manifest are correct","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Restart Claude Code to reload plugin configuration","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Conflicts between plugins","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use unique, descriptive component names","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Namespace commands with plugin name if needed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document potential conflicts in plugin README","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Consider command prefixes for related functionality","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"For detailed examples and advanced patterns, see files in ","type":"text"},{"text":"references/","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"examples/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directories.","type":"text"}]}]},"metadata":{"date":"2026-06-05","name":"Plugin Structure","author":"@skillopedia","source":{"stars":129313,"repo_name":"claude-code","origin_url":"https://github.com/anthropics/claude-code/blob/HEAD/plugins/plugin-dev/skills/plugin-structure/SKILL.md","repo_owner":"anthropics","body_sha256":"ed2468c18f843e7c1cfa9ac1b216b72ffb091b87d1aa999eb2c3e3fe848e395a","cluster_key":"319aae91be4df6c83d45e84d78ab8e67e3c6d468dfe14b4fdd430c4f49654ec6","clean_bundle":{"format":"clean-skill-bundle-v1","source":"anthropics/claude-code/plugins/plugin-dev/skills/plugin-structure/SKILL.md","attachments":[{"id":"c41447fa-0aa4-5e0b-80be-acad52bab543","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c41447fa-0aa4-5e0b-80be-acad52bab543/attachment.md","path":"README.md","size":3210,"sha256":"c7cb4931d6d71198cba6b552e4733b41940be56a65552a2ff7c5656750b95184","contentType":"text/markdown; charset=utf-8"},{"id":"5fb8b5e6-1881-5162-b0dd-71793ed6e821","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5fb8b5e6-1881-5162-b0dd-71793ed6e821/attachment.md","path":"examples/advanced-plugin.md","size":18746,"sha256":"3d24f5856048a94cb99fe2b8207d99f2f5d69325771b361d63ec73024290759c","contentType":"text/markdown; charset=utf-8"},{"id":"2f76daba-322e-528c-828c-1ff10ec5bbc1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2f76daba-322e-528c-828c-1ff10ec5bbc1/attachment.md","path":"examples/minimal-plugin.md","size":1731,"sha256":"c4f14fe56b153be3c532b7947bb10b453fc92e280dca5a7da752d2b1b5d17448","contentType":"text/markdown; charset=utf-8"},{"id":"c454b0bb-c7ae-582d-b9e7-44008616f7a1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c454b0bb-c7ae-582d-b9e7-44008616f7a1/attachment.md","path":"examples/standard-plugin.md","size":13310,"sha256":"b8cfba84bd4dbdc83365cebcde5dcc6391252372300df0c1ea7890441582d784","contentType":"text/markdown; charset=utf-8"},{"id":"bb0530be-6bbe-5b25-90b3-2cf86816cb3c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bb0530be-6bbe-5b25-90b3-2cf86816cb3c/attachment.md","path":"references/component-patterns.md","size":12086,"sha256":"38681792a6aba4f06d3c391b20b04060263f1fbaacc5880cc0cafe0543d37f91","contentType":"text/markdown; charset=utf-8"},{"id":"f2c3cb7d-321f-5d76-8ca2-e6e8ed67214d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f2c3cb7d-321f-5d76-8ca2-e6e8ed67214d/attachment.md","path":"references/manifest-reference.md","size":12061,"sha256":"d0ff8ffece4754df92c543266b8d0b689fb85473f51fbb57e215f2d235ee9782","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"b5aba5203f815efe585120c3f4a5a49907abfb1e6b28edcb7bf3d8664f02dffd","attachment_count":6,"text_attachments":6,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":27,"skill_md_path":"plugins/plugin-dev/skills/plugin-structure/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"web-development","category_label":"Web"},"exact_dupes_collapsed_into_this":26},"version":"v1","category":"web-development","import_tag":"clean-skills-v1","description":"This skill should be used when the user asks to \"create a plugin\", \"scaffold a plugin\", \"understand plugin structure\", \"organize plugin components\", \"set up plugin.json\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"add commands/agents/skills/hooks\", \"configure auto-discovery\", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices."}},"renderedAt":1782979218024}

Plugin Structure for Claude Code Overview Claude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code. Key concepts: - Conventional directory layout for automatic discovery - Manifest-driven configuration in - Component-based organization (commands, agents, skills, hooks) - Portable path references using - Explicit vs. auto-discovered component loading Directory Structure Every Claude Code plugin follows this organizational pattern…