{"id":"plugin-structure","name":"Plugin Structure","summary":"このスキルは、ユーザーが「プラグインを作成する」「プラグインのスキャフォールド」「プラグイン構造を理解する」「プラグインコンポーネントの整理」「plugin.jsonの設定」「${CLAUDE_PLUGIN_ROOT}を使う」「コマンド/エージェント/スキル/フックを追加」「自動発見の設定」、プラグインの指示について…","body":"# Plugin Structure for Claude Code\n\n## Overview\n\nClaude 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.\n\n**Key concepts:**\n- Conventional directory layout for automatic discovery\n- Manifest-driven configuration in `.claude-plugin/plugin.json`\n- Component-based organization (commands, agents, skills, hooks)\n- Portable path references using `${CLAUDE_PLUGIN_ROOT}`\n- Explicit vs. auto-discovered component loading\n\n## Directory Structure\n\nEvery Claude Code plugin follows this organizational pattern:\n\n```\nplugin-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\n```\n\n**Critical rules:**\n\n1. **Manifest location**: The `plugin.json` manifest MUST be in `.claude-plugin/` directory\n2. **Component locations**: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside `.claude-plugin/`\n3. **Optional components**: Only create directories for components the plugin actually uses\n4. **Naming convention**: Use kebab-case for all directory and file names\n\n## Plugin Manifest (plugin.json)\n\nThe manifest defines plugin metadata and configuration. Located at `.claude-plugin/plugin.json`:\n\n### Required Fields\n\n```json\n{\n  \"name\": \"plugin-name\"\n}\n```\n\n**Name requirements:**\n- Use kebab-case format (lowercase with hyphens)\n- Must be unique across installed plugins\n- No spaces or special characters\n- Example: `code-review-assistant`, `test-runner`, `api-docs`\n\n### Recommended Metadata\n\n```json\n{\n  \"name\": \"plugin-name\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Brief explanation of plugin purpose\",\n  \"author\": {\n    \"name\": \"Author Name\",\n    \"email\": \"author@example.com\",\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}\n```\n\n**Version format**: Follow semantic versioning (MAJOR.MINOR.PATCH)\n**Keywords**: Use for plugin discovery and categorization\n\n### Component Path Configuration\n\nSpecify custom paths for components (supplements default directories):\n\n```json\n{\n  \"name\": \"plugin-name\",\n  \"commands\": \"./custom-commands\",\n  \"agents\": [\"./agents\", \"./specialized-agents\"],\n  \"hooks\": \"./config/hooks.json\",\n  \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n**Important**: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.\n\n**Path rules:**\n- Must be relative to plugin root\n- Must start with `./`\n- Cannot use absolute paths\n- Support arrays for multiple locations\n\n## Component Organization\n\n### Commands\n\n**Location**: `commands/` directory\n**Format**: Markdown files with YAML frontmatter\n**Auto-discovery**: All `.md` files in `commands/` load automatically\n\n**Example structure**:\n```\ncommands/\n├── review.md        # /review command\n├── test.md          # /test command\n└── deploy.md        # /deploy command\n```\n\n**File format**:\n```markdown\n---\nname: command-name\ndescription: Command description\n---\n\nCommand implementation instructions...\n```\n\n**Usage**: Commands integrate as native slash commands in Claude Code\n\n### Agents\n\n**Location**: `agents/` directory\n**Format**: Markdown files with YAML frontmatter\n**Auto-discovery**: All `.md` files in `agents/` load automatically\n\n**Example structure**:\n```\nagents/\n├── code-reviewer.md\n├── test-generator.md\n└── refactorer.md\n```\n\n**File format**:\n```markdown\n---\ndescription: Agent role and expertise\ncapabilities:\n  - Specific task 1\n  - Specific task 2\n---\n\nDetailed agent instructions and knowledge...\n```\n\n**Usage**: Users can invoke agents manually, or Claude Code selects them automatically based on task context\n\n### Skills\n\n**Location**: `skills/` directory with subdirectories per skill\n**Format**: Each skill in its own directory with `SKILL.md` file\n**Auto-discovery**: All `SKILL.md` files in skill subdirectories load automatically\n\n**Example structure**:\n```\nskills/\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\n```\n\n**SKILL.md format**:\n```markdown\n---\nname: Skill Name\ndescription: When to use this skill\nversion: 1.0.0\n---\n\nSkill instructions and guidance...\n```\n\n**Supporting files**: Skills can include scripts, references, examples, or assets in subdirectories\n\n**Usage**: Claude Code autonomously activates skills based on task context matching the description\n\n### Hooks\n\n**Location**: `hooks/hooks.json` or inline in `plugin.json`\n**Format**: JSON configuration defining event handlers\n**Registration**: Hooks register automatically when plugin enables\n\n**Example structure**:\n```\nhooks/\n├── hooks.json           # Hook configuration\n└── scripts/\n    ├── validate.sh      # Hook script\n    └── check-style.sh   # Hook script\n```\n\n**Configuration format**:\n```json\n{\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}\n```\n\n**Available events**: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification\n\n**Usage**: Hooks execute automatically in response to Claude Code events\n\n### MCP Servers\n\n**Location**: `.mcp.json` at plugin root or inline in `plugin.json`\n**Format**: JSON configuration for MCP server definitions\n**Auto-start**: Servers start automatically when plugin enables\n\n**Example format**:\n```json\n{\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}\n```\n\n**Usage**: MCP servers integrate seamlessly with Claude Code's tool system\n\n## Portable Path References\n\n### ${CLAUDE_PLUGIN_ROOT}\n\nUse `${CLAUDE_PLUGIN_ROOT}` environment variable for all intra-plugin path references:\n\n```json\n{\n  \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh\"\n}\n```\n\n**Why it matters**: Plugins install in different locations depending on:\n- User installation method (marketplace, local, npm)\n- Operating system conventions\n- User preferences\n\n**Where to use it**:\n- Hook command paths\n- MCP server command arguments\n- Script execution references\n- Resource file paths\n\n**Never use**:\n- Hardcoded absolute paths (`/Users/name/plugins/...`)\n- Relative paths from working directory (`./scripts/...` in commands)\n- Home directory shortcuts (`~/plugins/...`)\n\n### Path Resolution Rules\n\n**In manifest JSON fields** (hooks, MCP servers):\n```json\n\"command\": \"${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh\"\n```\n\n**In component files** (commands, agents, skills):\n```markdown\nReference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py\n```\n\n**In executed scripts**:\n```bash\n#!/bin/bash\n# ${CLAUDE_PLUGIN_ROOT} available as environment variable\nsource \"${CLAUDE_PLUGIN_ROOT}/lib/common.sh\"\n```\n\n## File Naming Conventions\n\n### Component Files\n\n**Commands**: Use kebab-case `.md` files\n- `code-review.md` → `/code-review`\n- `run-tests.md` → `/run-tests`\n- `api-docs.md` → `/api-docs`\n\n**Agents**: Use kebab-case `.md` files describing role\n- `test-generator.md`\n- `code-reviewer.md`\n- `performance-analyzer.md`\n\n**Skills**: Use kebab-case directory names\n- `api-testing/`\n- `database-migrations/`\n- `error-handling/`\n\n### Supporting Files\n\n**Scripts**: Use descriptive kebab-case names with appropriate extensions\n- `validate-input.sh`\n- `generate-report.py`\n- `process-data.js`\n\n**Documentation**: Use kebab-case markdown files\n- `api-reference.md`\n- `migration-guide.md`\n- `best-practices.md`\n\n**Configuration**: Use standard names\n- `hooks.json`\n- `.mcp.json`\n- `plugin.json`\n\n## Auto-Discovery Mechanism\n\nClaude Code automatically discovers and loads components:\n\n1. **Plugin manifest**: Reads `.claude-plugin/plugin.json` when plugin enables\n2. **Commands**: Scans `commands/` directory for `.md` files\n3. **Agents**: Scans `agents/` directory for `.md` files\n4. **Skills**: Scans `skills/` for subdirectories containing `SKILL.md`\n5. **Hooks**: Loads configuration from `hooks/hooks.json` or manifest\n6. **MCP servers**: Loads configuration from `.mcp.json` or manifest\n\n**Discovery timing**:\n- Plugin installation: Components register with Claude Code\n- Plugin enable: Components become available for use\n- No restart required: Changes take effect on next Claude Code session\n\n**Override behavior**: Custom paths in `plugin.json` supplement (not replace) default directories\n\n## Best Practices\n\n### Organization\n\n1. **Logical grouping**: Group related components together\n   - Put test-related commands, agents, and skills together\n   - Create subdirectories in `scripts/` for different purposes\n\n2. **Minimal manifest**: Keep `plugin.json` lean\n   - Only specify custom paths when necessary\n   - Rely on auto-discovery for standard layouts\n   - Use inline configuration only for simple cases\n\n3. **Documentation**: Include README files\n   - Plugin root: Overall purpose and usage\n   - Component directories: Specific guidance\n   - Script directories: Usage and requirements\n\n### Naming\n\n1. **Consistency**: Use consistent naming across components\n   - If command is `test-runner`, name related agent `test-runner-agent`\n   - Match skill directory names to their purpose\n\n2. **Clarity**: Use descriptive names that indicate purpose\n   - Good: `api-integration-testing/`, `code-quality-checker.md`\n   - Avoid: `utils/`, `misc.md`, `temp.sh`\n\n3. **Length**: Balance brevity with clarity\n   - Commands: 2-3 words (`review-pr`, `run-ci`)\n   - Agents: Describe role clearly (`code-reviewer`, `test-generator`)\n   - Skills: Topic-focused (`error-handling`, `api-design`)\n\n### Portability\n\n1. **Always use ${CLAUDE_PLUGIN_ROOT}**: Never hardcode paths\n2. **Test on multiple systems**: Verify on macOS, Linux, Windows\n3. **Document dependencies**: List required tools and versions\n4. **Avoid system-specific features**: Use portable bash/Python constructs\n\n### Maintenance\n\n1. **Version consistently**: Update version in plugin.json for releases\n2. **Deprecate gracefully**: Mark old components clearly before removal\n3. **Document breaking changes**: Note changes affecting existing users\n4. **Test thoroughly**: Verify all components work after changes\n\n## Common Patterns\n\n### Minimal Plugin\n\nSingle command with no dependencies:\n```\nmy-plugin/\n├── .claude-plugin/\n│   └── plugin.json    # Just name field\n└── commands/\n    └── hello.md       # Single command\n```\n\n### Full-Featured Plugin\n\nComplete plugin with all component types:\n```\nmy-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\n```\n\n### Skill-Focused Plugin\n\nPlugin providing only skills:\n```\nmy-plugin/\n├── .claude-plugin/\n│   └── plugin.json\n└── skills/\n    ├── skill-one/\n    │   └── SKILL.md\n    └── skill-two/\n        └── SKILL.md\n```\n\n## Troubleshooting\n\n**Component not loading**:\n- Verify file is in correct directory with correct extension\n- Check YAML frontmatter syntax (commands, agents, skills)\n- Ensure skill has `SKILL.md` (not `README.md` or other name)\n- Confirm plugin is enabled in Claude Code settings\n\n**Path resolution errors**:\n- Replace all hardcoded paths with `${CLAUDE_PLUGIN_ROOT}`\n- Verify paths are relative and start with `./` in manifest\n- Check that referenced files exist at specified paths\n- Test with `echo $CLAUDE_PLUGIN_ROOT` in hook scripts\n\n**Auto-discovery not working**:\n- Confirm directories are at plugin root (not in `.claude-plugin/`)\n- Check file naming follows conventions (kebab-case, correct extensions)\n- Verify custom paths in manifest are correct\n- Restart Claude Code to reload plugin configuration\n\n**Conflicts between plugins**:\n- Use unique, descriptive component names\n- Namespace commands with plugin name if needed\n- Document potential conflicts in plugin README\n- Consider command prefixes for related functionality\n\n---\n\nFor detailed examples and advanced patterns, see files in `references/` and `examples/` directories.","author":"@tzachbon","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/tzachbon/smart-ralph/tree/main/.agents/skills/Plugin Structure","license":"MIT","category":null,"lang":"en","tokens":3111,"stars":0,"calls30d":0,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"examples/advanced-plugin.md","size":18746,"sha256":"3d24f5856048a94cb99fe2b8207d99f2f5d69325771b361d63ec73024290759c"},{"path":"examples/minimal-plugin.md","size":1731,"sha256":"c4f14fe56b153be3c532b7947bb10b453fc92e280dca5a7da752d2b1b5d17448"},{"path":"examples/standard-plugin.md","size":13310,"sha256":"b8cfba84bd4dbdc83365cebcde5dcc6391252372300df0c1ea7890441582d784"},{"path":"references/component-patterns.md","size":12086,"sha256":"38681792a6aba4f06d3c391b20b04060263f1fbaacc5880cc0cafe0543d37f91"},{"path":"references/manifest-reference.md","size":12061,"sha256":"d0ff8ffece4754df92c543266b8d0b689fb85473f51fbb57e215f2d235ee9782"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["company.com","docs.company.com","docs.example.com","janedeveloper.com"]}}