plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md
Advanced patterns for organizing plugin components effectively.
When Claude Code starts:
.claude-plugin/plugin.json for eachTiming: Component registration happens during Claude Code initialization, not continuously.
When components are used:
Commands: User types slash command → Claude Code looks up → Executes Agents: Task arrives → Claude Code evaluates capabilities → Selects agent Skills: Task context matches description → Claude Code loads skill Hooks: Event occurs → Claude Code calls matching hooks MCP Servers: Tool call matches server capability → Forwards to server
Single directory with all commands:
commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md
When to use:
Advantages:
Multiple directories for different command types:
commands/ # Core commands
├── build.md
└── test.md
admin-commands/ # Administrative
├── configure.md
└── manage.md
workflow-commands/ # Workflow automation
├── review.md
└── deploy.md
Manifest configuration:
{
"commands": [
"./commands",
"./admin-commands",
"./workflow-commands"
]
}
When to use:
Advantages:
Nested organization for complex plugins:
commands/
├── ci/
│ ├── build.md
│ ├── test.md
│ └── lint.md
├── deployment/
│ ├── staging.md
│ └── production.md
└── management/
├── config.md
└── status.md
Note: Claude Code doesn't support nested command discovery automatically. Use custom paths:
{
"commands": [
"./commands/ci",
"./commands/deployment",
"./commands/management"
]
}
When to use:
Advantages:
Organize agents by their primary role:
agents/
├── code-reviewer.md # Reviews code
├── test-generator.md # Generates tests
├── documentation-writer.md # Writes docs
└── refactorer.md # Refactors code
When to use:
Organize by specific capabilities:
agents/
├── python-expert.md # Python-specific
├── typescript-expert.md # TypeScript-specific
├── api-specialist.md # API design
└── database-specialist.md # Database work
When to use:
Organize by workflow stage:
agents/
├── planning-agent.md # Planning phase
├── implementation-agent.md # Coding phase
├── testing-agent.md # Testing phase
└── deployment-agent.md # Deployment phase
When to use:
Each skill covers a specific topic:
skills/
├── api-design/
│ └── SKILL.md
├── error-handling/
│ └── SKILL.md
├── testing-strategies/
│ └── SKILL.md
└── performance-optimization/
└── SKILL.md
When to use:
Skills for specific tools or technologies:
skills/
├── docker/
│ ├── SKILL.md
│ └── references/
│ └── dockerfile-best-practices.md
├── kubernetes/
│ ├── SKILL.md
│ └── examples/
│ └── deployment.yaml
└── terraform/
├── SKILL.md
└── scripts/
└── validate-config.sh
When to use:
Skills for complete workflows:
skills/
├── code-review-workflow/
│ ├── SKILL.md
│ └── references/
│ ├── checklist.md
│ └── standards.md
├── deployment-workflow/
│ ├── SKILL.md
│ └── scripts/
│ ├── pre-deploy.sh
│ └── post-deploy.sh
└── testing-workflow/
├── SKILL.md
└── examples/
└── test-structure.md
When to use:
Comprehensive skill with all resource types:
skills/
└── api-testing/
├── SKILL.md # Core skill (1500 words)
├── references/
│ ├── rest-api-guide.md
│ ├── graphql-guide.md
│ └── authentication.md
├── examples/
│ ├── basic-test.js
│ ├── authenticated-test.js
│ └── integration-test.js
├── scripts/
│ ├── run-tests.sh
│ └── generate-report.py
└── assets/
└── test-template.json
Resource usage:
Single hooks.json with all hooks:
hooks/
├── hooks.json # All hook definitions
└── scripts/
├── validate-write.sh
├── validate-bash.sh
└── load-context.sh
hooks.json:
{
"PreToolUse": [...],
"PostToolUse": [...],
"Stop": [...],
"SessionStart": [...]
}
When to use:
Separate files per event type:
hooks/
├── hooks.json # Combines all
├── pre-tool-use.json # PreToolUse hooks
├── post-tool-use.json # PostToolUse hooks
├── stop.json # Stop hooks
└── scripts/
├── validate/
│ ├── write.sh
│ └── bash.sh
└── context/
└── load.sh
hooks.json (combines):
{
"PreToolUse": ${file:./pre-tool-use.json},
"PostToolUse": ${file:./post-tool-use.json},
"Stop": ${file:./stop.json}
}
Note: Use build script to combine files, Claude Code doesn't support file references.
When to use:
Group by functional purpose:
hooks/
├── hooks.json
└── scripts/
├── security/
│ ├── validate-paths.sh
│ ├── check-credentials.sh
│ └── scan-malware.sh
├── quality/
│ ├── lint-code.sh
│ ├── check-tests.sh
│ └── verify-docs.sh
└── workflow/
├── notify-team.sh
└── update-status.sh
When to use:
All scripts in single directory:
scripts/
├── build.sh
├── test.py
├── deploy.sh
├── validate.js
└── report.py
When to use:
Group by purpose:
scripts/
├── build/
│ ├── compile.sh
│ └── package.sh
├── test/
│ ├── run-unit.sh
│ └── run-integration.sh
├── deploy/
│ ├── staging.sh
│ └── production.sh
└── utils/
├── log.sh
└── notify.sh
When to use:
Group by programming language:
scripts/
├── bash/
│ ├── build.sh
│ └── deploy.sh
├── python/
│ ├── analyze.py
│ └── report.py
└── javascript/
├── bundle.js
└── optimize.js
When to use:
Components sharing common resources:
plugin/
├── commands/
│ ├── test.md # Uses lib/test-utils.sh
│ └── deploy.md # Uses lib/deploy-utils.sh
├── agents/
│ └── tester.md # References lib/test-utils.sh
├── hooks/
│ └── scripts/
│ └── pre-test.sh # Sources lib/test-utils.sh
└── lib/
├── test-utils.sh
└── deploy-utils.sh
Usage in components:
#!/bin/bash
source "${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh"
run_tests
Benefits:
Separate concerns into layers:
plugin/
├── commands/ # User interface layer
├── agents/ # Orchestration layer
├── skills/ # Knowledge layer
└── lib/
├── core/ # Core business logic
├── integrations/ # External services
└── utils/ # Helper functions
When to use:
Nested plugin structure:
plugin/
├── .claude-plugin/
│ └── plugin.json
├── core/ # Core functionality
│ ├── commands/
│ └── agents/
└── extensions/ # Optional extensions
├── extension-a/
│ ├── commands/
│ └── agents/
└── extension-b/
├── commands/
└── agents/
Manifest:
{
"commands": [
"./core/commands",
"./extensions/extension-a/commands",
"./extensions/extension-b/commands"
]
}
When to use: