Loading source
Pulling the file list, source metadata, and syntax-aware rendering for this listing.
Source from repo
Directory structure and conventions for building Claude Code plugins (from the official Anthropic claude-code repo).
Files
Skill
Size
Entrypoint
Format
Open file
Syntax-highlighted preview of this file as included in the skill package.
references/component-patterns.md
1# Component Organization Patterns2Advanced patterns for organizing plugin components effectively.4## Component Lifecycle6### Discovery Phase8When Claude Code starts:101. **Scan enabled plugins**: Read `.claude-plugin/plugin.json` for each122. **Discover components**: Look in default and custom paths133. **Parse definitions**: Read YAML frontmatter and configurations144. **Register components**: Make available to Claude Code155. **Initialize**: Start MCP servers, register hooks16**Timing**: Component registration happens during Claude Code initialization, not continuously.18### Activation Phase20When components are used:22**Commands**: User types slash command → Claude Code looks up → Executes24**Agents**: Task arrives → Claude Code evaluates capabilities → Selects agent25**Skills**: Task context matches description → Claude Code loads skill26**Hooks**: Event occurs → Claude Code calls matching hooks27**MCP Servers**: Tool call matches server capability → Forwards to server28## Command Organization Patterns30### Flat Structure32Single directory with all commands:34```36commands/37├── build.md38├── test.md39├── deploy.md40├── review.md41└── docs.md42```43**When to use**:45- 5-15 commands total46- All commands at same abstraction level47- No clear categorization48**Advantages**:50- Simple, easy to navigate51- No configuration needed52- Fast discovery53### Categorized Structure55Multiple directories for different command types:57```59commands/ # Core commands60├── build.md61└── test.md62admin-commands/ # Administrative64├── configure.md65└── manage.md66workflow-commands/ # Workflow automation68├── review.md69└── deploy.md70```71**Manifest configuration**:73```json74{75"commands": [76"./commands",77"./admin-commands",78"./workflow-commands"79]80}81```82**When to use**:84- 15+ commands85- Clear functional categories86- Different permission levels87**Advantages**:89- Organized by purpose90- Easier to maintain91- Can restrict access by directory92### Hierarchical Structure94Nested organization for complex plugins:96```98commands/99├── ci/100│ ├── build.md101│ ├── test.md102│ └── lint.md103├── deployment/104│ ├── staging.md105│ └── production.md106└── management/107├── config.md108└── status.md109```110**Note**: Claude Code doesn't support nested command discovery automatically. Use custom paths:112```json114{115"commands": [116"./commands/ci",117"./commands/deployment",118"./commands/management"119]120}121```122**When to use**:124- 20+ commands125- Multi-level categorization126- Complex workflows127**Advantages**:129- Maximum organization130- Clear boundaries131- Scalable structure132## Agent Organization Patterns134### Role-Based Organization136Organize agents by their primary role:138```140agents/141├── code-reviewer.md # Reviews code142├── test-generator.md # Generates tests143├── documentation-writer.md # Writes docs144└── refactorer.md # Refactors code145```146**When to use**:148- Agents have distinct, non-overlapping roles149- Users invoke agents manually150- Clear agent responsibilities151### Capability-Based Organization153Organize by specific capabilities:155```157agents/158├── python-expert.md # Python-specific159├── typescript-expert.md # TypeScript-specific160├── api-specialist.md # API design161└── database-specialist.md # Database work162```163**When to use**:165- Technology-specific agents166- Domain expertise focus167- Automatic agent selection168### Workflow-Based Organization170Organize by workflow stage:172```174agents/175├── planning-agent.md # Planning phase176├── implementation-agent.md # Coding phase177├── testing-agent.md # Testing phase178└── deployment-agent.md # Deployment phase179```180**When to use**:182- Sequential workflows183- Stage-specific expertise184- Pipeline automation185## Skill Organization Patterns187### Topic-Based Organization189Each skill covers a specific topic:191```193skills/194├── api-design/195│ └── SKILL.md196├── error-handling/197│ └── SKILL.md198├── testing-strategies/199│ └── SKILL.md200└── performance-optimization/201└── SKILL.md202```203**When to use**:205- Knowledge-based skills206- Educational or reference content207- Broad applicability208### Tool-Based Organization210Skills for specific tools or technologies:212```214skills/215├── docker/216│ ├── SKILL.md217│ └── references/218│ └── dockerfile-best-practices.md219├── kubernetes/220│ ├── SKILL.md221│ └── examples/222│ └── deployment.yaml223└── terraform/224├── SKILL.md225└── scripts/226└── validate-config.sh227```228**When to use**:230- Tool-specific expertise231- Complex tool configurations232- Tool best practices233### Workflow-Based Organization235Skills for complete workflows:237```239skills/240├── code-review-workflow/241│ ├── SKILL.md242│ └── references/243│ ├── checklist.md244│ └── standards.md245├── deployment-workflow/246│ ├── SKILL.md247│ └── scripts/248│ ├── pre-deploy.sh249│ └── post-deploy.sh250└── testing-workflow/251├── SKILL.md252└── examples/253└── test-structure.md254```255**When to use**:257- Multi-step processes258- Company-specific workflows259- Process automation260### Skill with Rich Resources262Comprehensive skill with all resource types:264```266skills/267└── api-testing/268├── SKILL.md # Core skill (1500 words)269├── references/270│ ├── rest-api-guide.md271│ ├── graphql-guide.md272│ └── authentication.md273├── examples/274│ ├── basic-test.js275│ ├── authenticated-test.js276│ └── integration-test.js277├── scripts/278│ ├── run-tests.sh279│ └── generate-report.py280└── assets/281└── test-template.json282```283**Resource usage**:285- **SKILL.md**: Overview and when to use resources286- **references/**: Detailed guides (loaded as needed)287- **examples/**: Copy-paste code samples288- **scripts/**: Executable test runners289- **assets/**: Templates and configurations290## Hook Organization Patterns292### Monolithic Configuration294Single hooks.json with all hooks:296```298hooks/299├── hooks.json # All hook definitions300└── scripts/301├── validate-write.sh302├── validate-bash.sh303└── load-context.sh304```305**hooks.json**:307```json308{309"PreToolUse": [...],310"PostToolUse": [...],311"Stop": [...],312"SessionStart": [...]313}314```315**When to use**:317- 5-10 hooks total318- Simple hook logic319- Centralized configuration320### Event-Based Organization322Separate files per event type:324```326hooks/327├── hooks.json # Combines all328├── pre-tool-use.json # PreToolUse hooks329├── post-tool-use.json # PostToolUse hooks330├── stop.json # Stop hooks331└── scripts/332├── validate/333│ ├── write.sh334│ └── bash.sh335└── context/336└── load.sh337```338**hooks.json** (combines):340```json341{342"PreToolUse": ${file:./pre-tool-use.json},343"PostToolUse": ${file:./post-tool-use.json},344"Stop": ${file:./stop.json}345}346```347**Note**: Use build script to combine files, Claude Code doesn't support file references.349**When to use**:351- 10+ hooks352- Different teams managing different events353- Complex hook configurations354### Purpose-Based Organization356Group by functional purpose:358```360hooks/361├── hooks.json362└── scripts/363├── security/364│ ├── validate-paths.sh365│ ├── check-credentials.sh366│ └── scan-malware.sh367├── quality/368│ ├── lint-code.sh369│ ├── check-tests.sh370│ └── verify-docs.sh371└── workflow/372├── notify-team.sh373└── update-status.sh374```375**When to use**:377- Many hook scripts378- Clear functional boundaries379- Team specialization380## Script Organization Patterns382### Flat Scripts384All scripts in single directory:386```388scripts/389├── build.sh390├── test.py391├── deploy.sh392├── validate.js393└── report.py394```395**When to use**:397- 5-10 scripts398- All scripts related399- Simple plugin400### Categorized Scripts402Group by purpose:404```406scripts/407├── build/408│ ├── compile.sh409│ └── package.sh410├── test/411│ ├── run-unit.sh412│ └── run-integration.sh413├── deploy/414│ ├── staging.sh415│ └── production.sh416└── utils/417├── log.sh418└── notify.sh419```420**When to use**:422- 10+ scripts423- Clear categories424- Reusable utilities425### Language-Based Organization427Group by programming language:429```431scripts/432├── bash/433│ ├── build.sh434│ └── deploy.sh435├── python/436│ ├── analyze.py437│ └── report.py438└── javascript/439├── bundle.js440└── optimize.js441```442**When to use**:444- Multi-language scripts445- Different runtime requirements446- Language-specific dependencies447## Cross-Component Patterns449### Shared Resources451Components sharing common resources:453```455plugin/456├── commands/457│ ├── test.md # Uses lib/test-utils.sh458│ └── deploy.md # Uses lib/deploy-utils.sh459├── agents/460│ └── tester.md # References lib/test-utils.sh461├── hooks/462│ └── scripts/463│ └── pre-test.sh # Sources lib/test-utils.sh464└── lib/465├── test-utils.sh466└── deploy-utils.sh467```468**Usage in components**:470```bash471#!/bin/bash472source "${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh"473run_tests474```475**Benefits**:477- Code reuse478- Consistent behavior479- Easier maintenance480### Layered Architecture482Separate concerns into layers:484```486plugin/487├── commands/ # User interface layer488├── agents/ # Orchestration layer489├── skills/ # Knowledge layer490└── lib/491├── core/ # Core business logic492├── integrations/ # External services493└── utils/ # Helper functions494```495**When to use**:497- Large plugins (100+ files)498- Multiple developers499- Clear separation of concerns500### Plugin Within Plugin502Nested plugin structure:504```506plugin/507├── .claude-plugin/508│ └── plugin.json509├── core/ # Core functionality510│ ├── commands/511│ └── agents/512└── extensions/ # Optional extensions513├── extension-a/514│ ├── commands/515│ └── agents/516└── extension-b/517├── commands/518└── agents/519```520**Manifest**:522```json523{524"commands": [525"./core/commands",526"./extensions/extension-a/commands",527"./extensions/extension-b/commands"528]529}530```531**When to use**:533- Modular functionality534- Optional features535- Plugin families536## Best Practices538### Naming5401. **Consistent naming**: Match file names to component purpose5422. **Descriptive names**: Indicate what component does5433. **Avoid abbreviations**: Use full words for clarity544### Organization5461. **Start simple**: Use flat structure, reorganize when needed5482. **Group related items**: Keep related components together5493. **Separate concerns**: Don't mix unrelated functionality550### Scalability5521. **Plan for growth**: Choose structure that scales5542. **Refactor early**: Reorganize before it becomes painful5553. **Document structure**: Explain organization in README556### Maintainability5581. **Consistent patterns**: Use same structure throughout5602. **Minimize nesting**: Keep directory depth manageable5613. **Use conventions**: Follow community standards562### Performance5641. **Avoid deep nesting**: Impacts discovery time5662. **Minimize custom paths**: Use defaults when possible5673. **Keep configurations small**: Large configs slow loading568