davila7--claude-code-templates
wehub-resource-sync
1 行
14 KiB
JSON
1 行
14 KiB
JSON
{"content": "---\nname: Plugin Structure\ndescription: 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.\nversion: 0.1.0\n---\n\n# 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.\n"} |