surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / skills / plugin-structure / references / component-patterns.md

Daisy S. HollmanMerge pull request #11780 from anthropics/daisy/plugin-dev/public-marketplace c508e59 · on Nov 18, 2025 History

567 lines · 11.8 KBPreview CodeRaw

1	# Component Organization Patterns
2
3	Advanced patterns for organizing plugin components effectively.
4
5	## Component Lifecycle
6
7	### Discovery Phase
8
9	When Claude Code starts:
10
11	1. Scan enabled plugins: Read `.claude-plugin/plugin.json` for each
12	2. Discover components: Look in default and custom paths
13	3. Parse definitions: Read YAML frontmatter and configurations
14	4. Register components: Make available to Claude Code
15	5. Initialize: Start MCP servers, register hooks
16
17	Timing: Component registration happens during Claude Code initialization, not continuously.
18
19	### Activation Phase
20
21	When components are used:
22
23	Commands: User types slash command → Claude Code looks up → Executes
24	Agents: Task arrives → Claude Code evaluates capabilities → Selects agent
25	Skills: Task context matches description → Claude Code loads skill
26	Hooks: Event occurs → Claude Code calls matching hooks
27	MCP Servers: Tool call matches server capability → Forwards to server
28
29	## Command Organization Patterns
30
31	### Flat Structure
32
33	Single directory with all commands:
34
35	```
36	commands/
37	├── build.md
38	├── test.md
39	├── deploy.md
40	├── review.md
41	└── docs.md
42	```
43
44	When to use:
45	- 5-15 commands total
46	- All commands at same abstraction level
47	- No clear categorization
48
49	Advantages:
50	- Simple, easy to navigate
51	- No configuration needed
52	- Fast discovery
53
54	### Categorized Structure
55
56	Multiple directories for different command types:
57
58	```
59	commands/ # Core commands
60	├── build.md
61	└── test.md
62
63	admin-commands/ # Administrative
64	├── configure.md
65	└── manage.md
66
67	workflow-commands/ # Workflow automation
68	├── review.md
69	└── deploy.md
70	```
71
72	Manifest configuration:
73	```json
74	{
75	"commands": [
76	"./commands",
77	"./admin-commands",
78	"./workflow-commands"
79	]
80	}
81	```
82
83	When to use:
84	- 15+ commands
85	- Clear functional categories
86	- Different permission levels
87
88	Advantages:
89	- Organized by purpose
90	- Easier to maintain
91	- Can restrict access by directory
92
93	### Hierarchical Structure
94
95	Nested organization for complex plugins:
96
97	```
98	commands/
99	├── ci/
100	│ ├── build.md
101	│ ├── test.md
102	│ └── lint.md
103	├── deployment/
104	│ ├── staging.md
105	│ └── production.md
106	└── management/
107	├── config.md
108	└── status.md
109	```
110
111	Note: Claude Code doesn't support nested command discovery automatically. Use custom paths:
112
113	```json
114	{
115	"commands": [
116	"./commands/ci",
117	"./commands/deployment",
118	"./commands/management"
119	]
120	}
121	```
122
123	When to use:
124	- 20+ commands
125	- Multi-level categorization
126	- Complex workflows
127
128	Advantages:
129	- Maximum organization
130	- Clear boundaries
131	- Scalable structure
132
133	## Agent Organization Patterns
134
135	### Role-Based Organization
136
137	Organize agents by their primary role:
138
139	```
140	agents/
141	├── code-reviewer.md # Reviews code
142	├── test-generator.md # Generates tests
143	├── documentation-writer.md # Writes docs
144	└── refactorer.md # Refactors code
145	```
146
147	When to use:
148	- Agents have distinct, non-overlapping roles
149	- Users invoke agents manually
150	- Clear agent responsibilities
151
152	### Capability-Based Organization
153
154	Organize by specific capabilities:
155
156	```
157	agents/
158	├── python-expert.md # Python-specific
159	├── typescript-expert.md # TypeScript-specific
160	├── api-specialist.md # API design
161	└── database-specialist.md # Database work
162	```
163
164	When to use:
165	- Technology-specific agents
166	- Domain expertise focus
167	- Automatic agent selection
168
169	### Workflow-Based Organization
170
171	Organize by workflow stage:
172
173	```
174	agents/
175	├── planning-agent.md # Planning phase
176	├── implementation-agent.md # Coding phase
177	├── testing-agent.md # Testing phase
178	└── deployment-agent.md # Deployment phase
179	```
180
181	When to use:
182	- Sequential workflows
183	- Stage-specific expertise
184	- Pipeline automation
185
186	## Skill Organization Patterns
187
188	### Topic-Based Organization
189
190	Each skill covers a specific topic:
191
192	```
193	skills/
194	├── api-design/
195	│ └── SKILL.md
196	├── error-handling/
197	│ └── SKILL.md
198	├── testing-strategies/
199	│ └── SKILL.md
200	└── performance-optimization/
201	└── SKILL.md
202	```
203
204	When to use:
205	- Knowledge-based skills
206	- Educational or reference content
207	- Broad applicability
208
209	### Tool-Based Organization
210
211	Skills for specific tools or technologies:
212
213	```
214	skills/
215	├── docker/
216	│ ├── SKILL.md
217	│ └── references/
218	│ └── dockerfile-best-practices.md
219	├── kubernetes/
220	│ ├── SKILL.md
221	│ └── examples/
222	│ └── deployment.yaml
223	└── terraform/
224	├── SKILL.md
225	└── scripts/
226	└── validate-config.sh
227	```
228
229	When to use:
230	- Tool-specific expertise
231	- Complex tool configurations
232	- Tool best practices
233
234	### Workflow-Based Organization
235
236	Skills for complete workflows:
237
238	```
239	skills/
240	├── code-review-workflow/
241	│ ├── SKILL.md
242	│ └── references/
243	│ ├── checklist.md
244	│ └── standards.md
245	├── deployment-workflow/
246	│ ├── SKILL.md
247	│ └── scripts/
248	│ ├── pre-deploy.sh
249	│ └── post-deploy.sh
250	└── testing-workflow/
251	├── SKILL.md
252	└── examples/
253	└── test-structure.md
254	```
255
256	When to use:
257	- Multi-step processes
258	- Company-specific workflows
259	- Process automation
260
261	### Skill with Rich Resources
262
263	Comprehensive skill with all resource types:
264
265	```
266	skills/
267	└── api-testing/
268	├── SKILL.md # Core skill (1500 words)
269	├── references/
270	│ ├── rest-api-guide.md
271	│ ├── graphql-guide.md
272	│ └── authentication.md
273	├── examples/
274	│ ├── basic-test.js
275	│ ├── authenticated-test.js
276	│ └── integration-test.js
277	├── scripts/
278	│ ├── run-tests.sh
279	│ └── generate-report.py
280	└── assets/
281	└── test-template.json
282	```
283
284	Resource usage:
285	- SKILL.md: Overview and when to use resources
286	- references/: Detailed guides (loaded as needed)
287	- examples/: Copy-paste code samples
288	- scripts/: Executable test runners
289	- assets/: Templates and configurations
290
291	## Hook Organization Patterns
292
293	### Monolithic Configuration
294
295	Single hooks.json with all hooks:
296
297	```
298	hooks/
299	├── hooks.json # All hook definitions
300	└── scripts/
301	├── validate-write.sh
302	├── validate-bash.sh
303	└── load-context.sh
304	```
305
306	hooks.json:
307	```json
308	{
309	"PreToolUse": [...],
310	"PostToolUse": [...],
311	"Stop": [...],
312	"SessionStart": [...]
313	}
314	```
315
316	When to use:
317	- 5-10 hooks total
318	- Simple hook logic
319	- Centralized configuration
320
321	### Event-Based Organization
322
323	Separate files per event type:
324
325	```
326	hooks/
327	├── hooks.json # Combines all
328	├── pre-tool-use.json # PreToolUse hooks
329	├── post-tool-use.json # PostToolUse hooks
330	├── stop.json # Stop hooks
331	└── scripts/
332	├── validate/
333	│ ├── write.sh
334	│ └── bash.sh
335	└── context/
336	└── load.sh
337	```
338
339	hooks.json (combines):
340	```json
341	{
342	"PreToolUse": ${file:./pre-tool-use.json},
343	"PostToolUse": ${file:./post-tool-use.json},
344	"Stop": ${file:./stop.json}
345	}
346	```
347
348	Note: Use build script to combine files, Claude Code doesn't support file references.
349
350	When to use:
351	- 10+ hooks
352	- Different teams managing different events
353	- Complex hook configurations
354
355	### Purpose-Based Organization
356
357	Group by functional purpose:
358
359	```
360	hooks/
361	├── hooks.json
362	└── scripts/
363	├── security/
364	│ ├── validate-paths.sh
365	│ ├── check-credentials.sh
366	│ └── scan-malware.sh
367	├── quality/
368	│ ├── lint-code.sh
369	│ ├── check-tests.sh
370	│ └── verify-docs.sh
371	└── workflow/
372	├── notify-team.sh
373	└── update-status.sh
374	```
375
376	When to use:
377	- Many hook scripts
378	- Clear functional boundaries
379	- Team specialization
380
381	## Script Organization Patterns
382
383	### Flat Scripts
384
385	All scripts in single directory:
386
387	```
388	scripts/
389	├── build.sh
390	├── test.py
391	├── deploy.sh
392	├── validate.js
393	└── report.py
394	```
395
396	When to use:
397	- 5-10 scripts
398	- All scripts related
399	- Simple plugin
400
401	### Categorized Scripts
402
403	Group by purpose:
404
405	```
406	scripts/
407	├── build/
408	│ ├── compile.sh
409	│ └── package.sh
410	├── test/
411	│ ├── run-unit.sh
412	│ └── run-integration.sh
413	├── deploy/
414	│ ├── staging.sh
415	│ └── production.sh
416	└── utils/
417	├── log.sh
418	└── notify.sh
419	```
420
421	When to use:
422	- 10+ scripts
423	- Clear categories
424	- Reusable utilities
425
426	### Language-Based Organization
427
428	Group by programming language:
429
430	```
431	scripts/
432	├── bash/
433	│ ├── build.sh
434	│ └── deploy.sh
435	├── python/
436	│ ├── analyze.py
437	│ └── report.py
438	└── javascript/
439	├── bundle.js
440	└── optimize.js
441	```
442
443	When to use:
444	- Multi-language scripts
445	- Different runtime requirements
446	- Language-specific dependencies
447
448	## Cross-Component Patterns
449
450	### Shared Resources
451
452	Components sharing common resources:
453
454	```
455	plugin/
456	├── commands/
457	│ ├── test.md # Uses lib/test-utils.sh
458	│ └── deploy.md # Uses lib/deploy-utils.sh
459	├── agents/
460	│ └── tester.md # References lib/test-utils.sh
461	├── hooks/
462	│ └── scripts/
463	│ └── pre-test.sh # Sources lib/test-utils.sh
464	└── lib/
465	├── test-utils.sh
466	└── deploy-utils.sh
467	```
468
469	Usage in components:
470	```bash
471	#!/bin/bash
472	source "${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh"
473	run_tests
474	```
475
476	Benefits:
477	- Code reuse
478	- Consistent behavior
479	- Easier maintenance
480
481	### Layered Architecture
482
483	Separate concerns into layers:
484
485	```
486	plugin/
487	├── commands/ # User interface layer
488	├── agents/ # Orchestration layer
489	├── skills/ # Knowledge layer
490	└── lib/
491	├── core/ # Core business logic
492	├── integrations/ # External services
493	└── utils/ # Helper functions
494	```
495
496	When to use:
497	- Large plugins (100+ files)
498	- Multiple developers
499	- Clear separation of concerns
500
501	### Plugin Within Plugin
502
503	Nested plugin structure:
504
505	```
506	plugin/
507	├── .claude-plugin/
508	│ └── plugin.json
509	├── core/ # Core functionality
510	│ ├── commands/
511	│ └── agents/
512	└── extensions/ # Optional extensions
513	├── extension-a/
514	│ ├── commands/
515	│ └── agents/
516	└── extension-b/
517	├── commands/
518	└── agents/
519	```
520
521	Manifest:
522	```json
523	{
524	"commands": [
525	"./core/commands",
526	"./extensions/extension-a/commands",
527	"./extensions/extension-b/commands"
528	]
529	}
530	```
531
532	When to use:
533	- Modular functionality
534	- Optional features
535	- Plugin families
536
537	## Best Practices
538
539	### Naming
540
541	1. Consistent naming: Match file names to component purpose
542	2. Descriptive names: Indicate what component does
543	3. Avoid abbreviations: Use full words for clarity
544
545	### Organization
546
547	1. Start simple: Use flat structure, reorganize when needed
548	2. Group related items: Keep related components together
549	3. Separate concerns: Don't mix unrelated functionality
550
551	### Scalability
552
553	1. Plan for growth: Choose structure that scales
554	2. Refactor early: Reorganize before it becomes painful
555	3. Document structure: Explain organization in README
556
557	### Maintainability
558
559	1. Consistent patterns: Use same structure throughout
560	2. Minimize nesting: Keep directory depth manageable
561	3. Use conventions: Follow community standards
562
563	### Performance
564
565	1. Avoid deep nesting: Impacts discovery time
566	2. Minimize custom paths: Use defaults when possible
567	3. Keep configurations small: Large configs slow loading