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 / examples / advanced-plugin.md

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

765 lines · 18.3 KBPreview CodeRaw

1	# Advanced Plugin Example
2
3	A complex, enterprise-grade plugin with MCP integration and advanced organization.
4
5	## Directory Structure
6
7	```
8	enterprise-devops/
9	├── .claude-plugin/
10	│ └── plugin.json
11	├── commands/
12	│ ├── ci/
13	│ │ ├── build.md
14	│ │ ├── test.md
15	│ │ └── deploy.md
16	│ ├── monitoring/
17	│ │ ├── status.md
18	│ │ └── logs.md
19	│ └── admin/
20	│ ├── configure.md
21	│ └── manage.md
22	├── agents/
23	│ ├── orchestration/
24	│ │ ├── deployment-orchestrator.md
25	│ │ └── rollback-manager.md
26	│ └── specialized/
27	│ ├── kubernetes-expert.md
28	│ ├── terraform-expert.md
29	│ └── security-auditor.md
30	├── skills/
31	│ ├── kubernetes-ops/
32	│ │ ├── SKILL.md
33	│ │ ├── references/
34	│ │ │ ├── deployment-patterns.md
35	│ │ │ ├── troubleshooting.md
36	│ │ │ └── security.md
37	│ │ ├── examples/
38	│ │ │ ├── basic-deployment.yaml
39	│ │ │ ├── stateful-set.yaml
40	│ │ │ └── ingress-config.yaml
41	│ │ └── scripts/
42	│ │ ├── validate-manifest.sh
43	│ │ └── health-check.sh
44	│ ├── terraform-iac/
45	│ │ ├── SKILL.md
46	│ │ ├── references/
47	│ │ │ └── best-practices.md
48	│ │ └── examples/
49	│ │ └── module-template/
50	│ └── ci-cd-pipelines/
51	│ ├── SKILL.md
52	│ └── references/
53	│ └── pipeline-patterns.md
54	├── hooks/
55	│ ├── hooks.json
56	│ └── scripts/
57	│ ├── security/
58	│ │ ├── scan-secrets.sh
59	│ │ ├── validate-permissions.sh
60	│ │ └── audit-changes.sh
61	│ ├── quality/
62	│ │ ├── check-config.sh
63	│ │ └── verify-tests.sh
64	│ └── workflow/
65	│ ├── notify-team.sh
66	│ └── update-status.sh
67	├── .mcp.json
68	├── servers/
69	│ ├── kubernetes-mcp/
70	│ │ ├── index.js
71	│ │ ├── package.json
72	│ │ └── lib/
73	│ ├── terraform-mcp/
74	│ │ ├── main.py
75	│ │ └── requirements.txt
76	│ └── github-actions-mcp/
77	│ ├── server.js
78	│ └── package.json
79	├── lib/
80	│ ├── core/
81	│ │ ├── logger.js
82	│ │ ├── config.js
83	│ │ └── auth.js
84	│ ├── integrations/
85	│ │ ├── slack.js
86	│ │ ├── pagerduty.js
87	│ │ └── datadog.js
88	│ └── utils/
89	│ ├── retry.js
90	│ └── validation.js
91	└── config/
92	├── environments/
93	│ ├── production.json
94	│ ├── staging.json
95	│ └── development.json
96	└── templates/
97	├── deployment.yaml
98	└── service.yaml
99	```
100
101	## File Contents
102
103	### .claude-plugin/plugin.json
104
105	```json
106	{
107	"name": "enterprise-devops",
108	"version": "2.3.1",
109	"description": "Comprehensive DevOps automation for enterprise CI/CD pipelines, infrastructure management, and monitoring",
110	"author": {
111	"name": "DevOps Platform Team",
112	"email": "devops-platform@company.com",
113	"url": "https://company.com/teams/devops"
114	},
115	"homepage": "https://docs.company.com/plugins/devops",
116	"repository": {
117	"type": "git",
118	"url": "https://github.com/company/devops-plugin.git"
119	},
120	"license": "Apache-2.0",
121	"keywords": [
122	"devops",
123	"ci-cd",
124	"kubernetes",
125	"terraform",
126	"automation",
127	"infrastructure",
128	"deployment",
129	"monitoring"
130	],
131	"commands": [
132	"./commands/ci",
133	"./commands/monitoring",
134	"./commands/admin"
135	],
136	"agents": [
137	"./agents/orchestration",
138	"./agents/specialized"
139	],
140	"hooks": "./hooks/hooks.json",
141	"mcpServers": "./.mcp.json"
142	}
143	```
144
145	### .mcp.json
146
147	```json
148	{
149	"mcpServers": {
150	"kubernetes": {
151	"command": "node",
152	"args": ["${CLAUDE_PLUGIN_ROOT}/servers/kubernetes-mcp/index.js"],
153	"env": {
154	"KUBECONFIG": "${KUBECONFIG}",
155	"K8S_NAMESPACE": "${K8S_NAMESPACE:-default}"
156	}
157	},
158	"terraform": {
159	"command": "python",
160	"args": ["${CLAUDE_PLUGIN_ROOT}/servers/terraform-mcp/main.py"],
161	"env": {
162	"TF_STATE_BUCKET": "${TF_STATE_BUCKET}",
163	"AWS_REGION": "${AWS_REGION}"
164	}
165	},
166	"github-actions": {
167	"command": "node",
168	"args": ["${CLAUDE_PLUGIN_ROOT}/servers/github-actions-mcp/server.js"],
169	"env": {
170	"GITHUB_TOKEN": "${GITHUB_TOKEN}",
171	"GITHUB_ORG": "${GITHUB_ORG}"
172	}
173	}
174	}
175	}
176	```
177
178	### commands/ci/build.md
179
180	```markdown
181	---
182	name: build
183	description: Trigger and monitor CI build pipeline
184	---
185
186	# Build Command
187
188	Trigger CI/CD build pipeline and monitor progress in real-time.
189
190	## Process
191
192	1. Validation: Check prerequisites
193	- Verify branch status
194	- Check for uncommitted changes
195	- Validate configuration files
196
197	2. Trigger: Start build via MCP server
198	\`\`\`javascript
199	// Uses github-actions MCP server
200	const build = await tools.github_actions_trigger_workflow({
201	workflow: 'build.yml',
202	ref: currentBranch
203	})
204	\`\`\`
205
206	3. Monitor: Track build progress
207	- Display real-time logs
208	- Show test results as they complete
209	- Alert on failures
210
211	4. Report: Summarize results
212	- Build status
213	- Test coverage
214	- Performance metrics
215	- Deploy readiness
216
217	## Integration
218
219	After successful build:
220	- Offer to deploy to staging
221	- Suggest performance optimizations
222	- Generate deployment checklist
223	```
224
225	### agents/orchestration/deployment-orchestrator.md
226
227	```markdown
228	---
229	description: Orchestrates complex multi-environment deployments with rollback capabilities and health monitoring
230	capabilities:
231	- Plan and execute multi-stage deployments
232	- Coordinate service dependencies
233	- Monitor deployment health
234	- Execute automated rollbacks
235	- Manage deployment approvals
236	---
237
238	# Deployment Orchestrator Agent
239
240	Specialized agent for orchestrating complex deployments across multiple environments.
241
242	## Expertise
243
244	- Deployment strategies: Blue-green, canary, rolling updates
245	- Dependency management: Service startup ordering, dependency injection
246	- Health monitoring: Service health checks, metric validation
247	- Rollback automation: Automatic rollback on failure detection
248	- Approval workflows: Multi-stage approval processes
249
250	## Orchestration Process
251
252	1. Planning Phase
253	- Analyze deployment requirements
254	- Identify service dependencies
255	- Generate deployment plan
256	- Calculate rollback strategy
257
258	2. Validation Phase
259	- Verify environment readiness
260	- Check resource availability
261	- Validate configurations
262	- Run pre-deployment tests
263
264	3. Execution Phase
265	- Deploy services in dependency order
266	- Monitor health after each stage
267	- Validate metrics and logs
268	- Proceed to next stage on success
269
270	4. Verification Phase
271	- Run smoke tests
272	- Validate service integration
273	- Check performance metrics
274	- Confirm deployment success
275
276	5. Rollback Phase (if needed)
277	- Detect failure conditions
278	- Execute rollback plan
279	- Restore previous state
280	- Notify stakeholders
281
282	## MCP Integration
283
284	Uses multiple MCP servers:
285	- `kubernetes`: Deploy and manage containers
286	- `terraform`: Provision infrastructure
287	- `github-actions`: Trigger deployment pipelines
288
289	## Monitoring Integration
290
291	Integrates with monitoring tools via lib:
292	\`\`\`javascript
293	const { DatadogClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/datadog')
294	const metrics = await DatadogClient.getMetrics(service, timeRange)
295	\`\`\`
296
297	## Notification Integration
298
299	Sends updates via Slack and PagerDuty:
300	\`\`\`javascript
301	const { SlackClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/slack')
302	await SlackClient.notify({
303	channel: '#deployments',
304	message: 'Deployment started',
305	metadata: deploymentPlan
306	})
307	\`\`\`
308	```
309
310	### skills/kubernetes-ops/SKILL.md
311
312	```markdown
313	---
314	name: Kubernetes Operations
315	description: This skill should be used when deploying to Kubernetes, managing K8s resources, troubleshooting cluster issues, configuring ingress/services, scaling deployments, or working with Kubernetes manifests. Provides comprehensive Kubernetes operational knowledge and best practices.
316	version: 2.0.0
317	---
318
319	# Kubernetes Operations
320
321	Comprehensive operational knowledge for managing Kubernetes clusters and workloads.
322
323	## Overview
324
325	Manage Kubernetes infrastructure effectively through:
326	- Deployment strategies and patterns
327	- Resource configuration and optimization
328	- Troubleshooting and debugging
329	- Security best practices
330	- Performance tuning
331
332	## Core Concepts
333
334	### Resource Management
335
336	Deployments: Use for stateless applications
337	- Rolling updates for zero-downtime deployments
338	- Rollback capabilities for failed deployments
339	- Replica management for scaling
340
341	StatefulSets: Use for stateful applications
342	- Stable network identities
343	- Persistent storage
344	- Ordered deployment and scaling
345
346	DaemonSets: Use for node-level services
347	- Log collectors
348	- Monitoring agents
349	- Network plugins
350
351	### Configuration
352
353	ConfigMaps: Store non-sensitive configuration
354	- Environment-specific settings
355	- Application configuration files
356	- Feature flags
357
358	Secrets: Store sensitive data
359	- API keys and tokens
360	- Database credentials
361	- TLS certificates
362
363	Use external secret management (Vault, AWS Secrets Manager) for production.
364
365	### Networking
366
367	Services: Expose applications internally
368	- ClusterIP for internal communication
369	- NodePort for external access (non-production)
370	- LoadBalancer for external access (production)
371
372	Ingress: HTTP/HTTPS routing
373	- Path-based routing
374	- Host-based routing
375	- TLS termination
376	- Load balancing
377
378	## Deployment Strategies
379
380	### Rolling Update
381
382	Default strategy, gradual replacement:
383	\`\`\`yaml
384	strategy:
385	type: RollingUpdate
386	rollingUpdate:
387	maxSurge: 1
388	maxUnavailable: 0
389	\`\`\`
390
391	When to use: Standard deployments, minor updates
392
393	### Recreate
394
395	Stop all pods, then create new ones:
396	\`\`\`yaml
397	strategy:
398	type: Recreate
399	\`\`\`
400
401	When to use: Stateful apps that can't run multiple versions
402
403	### Blue-Green
404
405	Run two complete environments, switch traffic:
406	1. Deploy new version (green)
407	2. Test green environment
408	3. Switch traffic to green
409	4. Keep blue for quick rollback
410
411	When to use: Critical services, need instant rollback
412
413	### Canary
414
415	Gradually roll out to subset of users:
416	1. Deploy canary version (10% traffic)
417	2. Monitor metrics and errors
418	3. Increase traffic gradually
419	4. Complete rollout or rollback
420
421	When to use: High-risk changes, want gradual validation
422
423	## Resource Configuration
424
425	### Resource Requests and Limits
426
427	Always set for production workloads:
428	\`\`\`yaml
429	resources:
430	requests:
431	memory: "256Mi"
432	cpu: "250m"
433	limits:
434	memory: "512Mi"
435	cpu: "500m"
436	\`\`\`
437
438	Requests: Guaranteed resources
439	Limits: Maximum allowed resources
440
441	### Health Checks
442
443	Essential for reliability:
444	\`\`\`yaml
445	livenessProbe:
446	httpGet:
447	path: /health
448	port: 8080
449	initialDelaySeconds: 30
450	periodSeconds: 10
451
452	readinessProbe:
453	httpGet:
454	path: /ready
455	port: 8080
456	initialDelaySeconds: 5
457	periodSeconds: 5
458	\`\`\`
459
460	Liveness: Restart unhealthy pods
461	Readiness: Remove unready pods from service
462
463	## Troubleshooting
464
465	### Common Issues
466
467	1. Pods not starting
468	- Check: `kubectl describe pod <name>`
469	- Look for: Image pull errors, resource constraints
470	- Fix: Verify image name, increase resources
471
472	2. Service not reachable
473	- Check: `kubectl get svc`, `kubectl get endpoints`
474	- Look for: No endpoints, wrong selector
475	- Fix: Verify pod labels match service selector
476
477	3. High memory usage
478	- Check: `kubectl top pods`
479	- Look for: Pods near memory limit
480	- Fix: Increase limits, optimize application
481
482	4. Frequent restarts
483	- Check: `kubectl get pods`, `kubectl logs <name>`
484	- Look for: Liveness probe failures, OOMKilled
485	- Fix: Adjust health checks, increase memory
486
487	### Debugging Commands
488
489	Get pod details:
490	\`\`\`bash
491	kubectl describe pod <name>
492	kubectl logs <name>
493	kubectl logs <name> --previous # logs from crashed container
494	\`\`\`
495
496	Execute commands in pod:
497	\`\`\`bash
498	kubectl exec -it <name> -- /bin/sh
499	kubectl exec <name> -- env
500	\`\`\`
501
502	Check resource usage:
503	\`\`\`bash
504	kubectl top nodes
505	kubectl top pods
506	\`\`\`
507
508	## Security Best Practices
509
510	### Pod Security
511
512	- Run as non-root user
513	- Use read-only root filesystem
514	- Drop unnecessary capabilities
515	- Use security contexts
516
517	Example:
518	\`\`\`yaml
519	securityContext:
520	runAsNonRoot: true
521	runAsUser: 1000
522	readOnlyRootFilesystem: true
523	capabilities:
524	drop:
525	- ALL
526	\`\`\`
527
528	### Network Policies
529
530	Restrict pod communication:
531	\`\`\`yaml
532	apiVersion: networking.k8s.io/v1
533	kind: NetworkPolicy
534	metadata:
535	name: api-allow
536	spec:
537	podSelector:
538	matchLabels:
539	app: api
540	ingress:
541	- from:
542	- podSelector:
543	matchLabels:
544	app: frontend
545	\`\`\`
546
547	### Secrets Management
548
549	- Never commit secrets to git
550	- Use external secret managers
551	- Rotate secrets regularly
552	- Limit secret access with RBAC
553
554	## Performance Optimization
555
556	### Resource Tuning
557
558	1. Start conservative: Set low limits initially
559	2. Monitor usage: Track actual resource consumption
560	3. Adjust gradually: Increase based on metrics
561	4. Set appropriate requests: Match typical usage
562	5. Set safe limits: 2x requests for headroom
563
564	### Horizontal Pod Autoscaling
565
566	Automatically scale based on metrics:
567	\`\`\`yaml
568	apiVersion: autoscaling/v2
569	kind: HorizontalPodAutoscaler
570	metadata:
571	name: api-hpa
572	spec:
573	scaleTargetRef:
574	apiVersion: apps/v1
575	kind: Deployment
576	name: api
577	minReplicas: 2
578	maxReplicas: 10
579	metrics:
580	- type: Resource
581	resource:
582	name: cpu
583	target:
584	type: Utilization
585	averageUtilization: 70
586	\`\`\`
587
588	## MCP Server Integration
589
590	This skill works with the kubernetes MCP server for operations:
591
592	List pods:
593	\`\`\`javascript
594	const pods = await tools.k8s_list_pods({ namespace: 'default' })
595	\`\`\`
596
597	Get pod logs:
598	\`\`\`javascript
599	const logs = await tools.k8s_get_logs({ pod: 'api-xyz', container: 'app' })
600	\`\`\`
601
602	Apply manifests:
603	\`\`\`javascript
604	const result = await tools.k8s_apply_manifest({ file: 'deployment.yaml' })
605	\`\`\`
606
607	## Detailed References
608
609	For in-depth information:
610	- Deployment patterns: `references/deployment-patterns.md`
611	- Troubleshooting guide: `references/troubleshooting.md`
612	- Security hardening: `references/security.md`
613
614	## Example Manifests
615
616	For copy-paste examples:
617	- Basic deployment: `examples/basic-deployment.yaml`
618	- StatefulSet: `examples/stateful-set.yaml`
619	- Ingress config: `examples/ingress-config.yaml`
620
621	## Validation Scripts
622
623	For manifest validation:
624	\`\`\`bash
625	bash ${CLAUDE_PLUGIN_ROOT}/skills/kubernetes-ops/scripts/validate-manifest.sh deployment.yaml
626	\`\`\`
627	```
628
629	### hooks/hooks.json
630
631	```json
632	{
633	"PreToolUse": [
634	{
635	"matcher": "Write\|Edit",
636	"hooks": [
637	{
638	"type": "command",
639	"command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/scan-secrets.sh",
640	"timeout": 30
641	}
642	]
643	},
644	{
645	"matcher": "Bash",
646	"hooks": [
647	{
648	"type": "prompt",
649	"prompt": "Evaluate if this bash command is safe for production environment. Check for destructive operations, missing safeguards, and potential security issues. Commands should be idempotent and reversible.",
650	"timeout": 20
651	}
652	]
653	}
654	],
655	"PostToolUse": [
656	{
657	"matcher": "Bash",
658	"hooks": [
659	{
660	"type": "command",
661	"command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/update-status.sh",
662	"timeout": 15
663	}
664	]
665	}
666	],
667	"Stop": [
668	{
669	"matcher": ".*",
670	"hooks": [
671	{
672	"type": "command",
673	"command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/quality/check-config.sh",
674	"timeout": 45
675	},
676	{
677	"type": "command",
678	"command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/notify-team.sh",
679	"timeout": 30
680	}
681	]
682	}
683	],
684	"SessionStart": [
685	{
686	"matcher": ".*",
687	"hooks": [
688	{
689	"type": "command",
690	"command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/validate-permissions.sh",
691	"timeout": 20
692	}
693	]
694	}
695	]
696	}
697	```
698
699	## Key Features
700
701	### Multi-Level Organization
702
703	Commands: Organized by function (CI, monitoring, admin)
704	Agents: Separated by role (orchestration vs. specialized)
705	Skills: Rich resources (references, examples, scripts)
706
707	### MCP Integration
708
709	Three custom MCP servers:
710	- Kubernetes: Cluster operations
711	- Terraform: Infrastructure provisioning
712	- GitHub Actions: CI/CD automation
713
714	### Shared Libraries
715
716	Reusable code in `lib/`:
717	- Core: Common utilities (logging, config, auth)
718	- Integrations: External services (Slack, Datadog)
719	- Utils: Helper functions (retry, validation)
720
721	### Configuration Management
722
723	Environment-specific configs in `config/`:
724	- Environments: Per-environment settings
725	- Templates: Reusable deployment templates
726
727	### Security Automation
728
729	Multiple security hooks:
730	- Secret scanning before writes
731	- Permission validation on session start
732	- Configuration auditing on completion
733
734	### Monitoring Integration
735
736	Built-in monitoring via lib integrations:
737	- Datadog for metrics
738	- PagerDuty for alerts
739	- Slack for notifications
740
741	## Use Cases
742
743	1. Multi-environment deployments: Orchestrated rollouts across dev/staging/prod
744	2. Infrastructure as code: Terraform automation with state management
745	3. CI/CD automation: Build, test, deploy pipelines
746	4. Monitoring and observability: Integrated metrics and alerting
747	5. Security enforcement: Automated security scanning and validation
748	6. Team collaboration: Slack notifications and status updates
749
750	## When to Use This Pattern
751
752	- Large-scale enterprise deployments
753	- Multiple environment management
754	- Complex CI/CD workflows
755	- Integrated monitoring requirements
756	- Security-critical infrastructure
757	- Team collaboration needs
758
759	## Scaling Considerations
760
761	- Performance: Separate MCP servers for parallel operations
762	- Organization: Multi-level directories for scalability
763	- Maintainability: Shared libraries reduce duplication
764	- Flexibility: Environment configs enable customization
765	- Security: Layered security hooks and validation