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 / command-development / references / documentation-patterns.md

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

739 lines · 14.6 KBPreview CodeRaw

1	# Command Documentation Patterns
2
3	Strategies for creating self-documenting, maintainable commands with excellent user experience.
4
5	## Overview
6
7	Well-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers.
8
9	## Self-Documenting Command Structure
10
11	### Complete Command Template
12
13	```markdown
14	---
15	description: Clear, actionable description under 60 chars
16	argument-hint: [arg1] [arg2] [optional-arg]
17	allowed-tools: Read, Bash(git:*)
18	model: sonnet
19	---
20
21	<!--
22	COMMAND: command-name
23	VERSION: 1.0.0
24	AUTHOR: Team Name
25	LAST UPDATED: 2025-01-15
26
27	PURPOSE:
28	Detailed explanation of what this command does and why it exists.
29
30	USAGE:
31	/command-name arg1 arg2
32
33	ARGUMENTS:
34	arg1: Description of first argument (required)
35	arg2: Description of second argument (optional, defaults to X)
36
37	EXAMPLES:
38	/command-name feature-branch main
39	→ Compares feature-branch with main
40
41	/command-name my-branch
42	→ Compares my-branch with current branch
43
44	REQUIREMENTS:
45	- Git repository
46	- Branch must exist
47	- Permissions to read repository
48
49	RELATED COMMANDS:
50	/other-command - Related functionality
51	/another-command - Alternative approach
52
53	TROUBLESHOOTING:
54	- If branch not found: Check branch name spelling
55	- If permission denied: Check repository access
56
57	CHANGELOG:
58	v1.0.0 (2025-01-15): Initial release
59	v0.9.0 (2025-01-10): Beta version
60	-->
61
62	# Command Implementation
63
64	[Command prompt content here...]
65
66	[Explain what will happen...]
67
68	[Guide user through steps...]
69
70	[Provide clear output...]
71	```
72
73	### Documentation Comment Sections
74
75	PURPOSE: Why the command exists
76	- Problem it solves
77	- Use cases
78	- When to use vs when not to use
79
80	USAGE: Basic syntax
81	- Command invocation pattern
82	- Required vs optional arguments
83	- Default values
84
85	ARGUMENTS: Detailed argument documentation
86	- Each argument described
87	- Type information
88	- Valid values/ranges
89	- Defaults
90
91	EXAMPLES: Concrete usage examples
92	- Common use cases
93	- Edge cases
94	- Expected outputs
95
96	REQUIREMENTS: Prerequisites
97	- Dependencies
98	- Permissions
99	- Environmental setup
100
101	RELATED COMMANDS: Connections
102	- Similar commands
103	- Complementary commands
104	- Alternative approaches
105
106	TROUBLESHOOTING: Common issues
107	- Known problems
108	- Solutions
109	- Workarounds
110
111	CHANGELOG: Version history
112	- What changed when
113	- Breaking changes highlighted
114	- Migration guidance
115
116	## In-Line Documentation Patterns
117
118	### Commented Sections
119
120	```markdown
121	---
122	description: Complex multi-step command
123	---
124
125	<!-- SECTION 1: VALIDATION -->
126	<!-- This section checks prerequisites before proceeding -->
127
128	Checking prerequisites...
129	- Git repository: !`git rev-parse --git-dir 2>/dev/null`
130	- Branch exists: [validation logic]
131
132	<!-- SECTION 2: ANALYSIS -->
133	<!-- Analyzes the differences between branches -->
134
135	Analyzing differences between $1 and $2...
136	[Analysis logic...]
137
138	<!-- SECTION 3: RECOMMENDATIONS -->
139	<!-- Provides actionable recommendations -->
140
141	Based on analysis, recommend:
142	[Recommendations...]
143
144	<!-- END: Next steps for user -->
145	```
146
147	### Inline Explanations
148
149	```markdown
150	---
151	description: Deployment command with inline docs
152	---
153
154	# Deploy to $1
155
156	## Pre-flight Checks
157
158	<!-- We check branch status to prevent deploying from wrong branch -->
159	Current branch: !`git branch --show-current`
160
161	<!-- Production deploys must come from main/master -->
162	if [ "$1" = "production" ] && [ "$(git branch --show-current)" != "main" ]; then
163	⚠️ WARNING: Not on main branch for production deploy
164	This is unusual. Confirm this is intentional.
165	fi
166
167	<!-- Test status ensures we don't deploy broken code -->
168	Running tests: !`npm test`
169
170	✓ All checks passed
171
172	## Deployment
173
174	<!-- Actual deployment happens here -->
175	<!-- Uses blue-green strategy for zero-downtime -->
176	Deploying to $1 environment...
177	[Deployment steps...]
178
179	<!-- Post-deployment verification -->
180	Verifying deployment health...
181	[Health checks...]
182
183	Deployment complete!
184
185	## Next Steps
186
187	<!-- Guide user on what to do after deployment -->
188	1. Monitor logs: /logs $1
189	2. Run smoke tests: /smoke-test $1
190	3. Notify team: /notify-deployment $1
191	```
192
193	### Decision Point Documentation
194
195	```markdown
196	---
197	description: Interactive deployment command
198	---
199
200	# Interactive Deployment
201
202	## Configuration Review
203
204	Target: $1
205	Current version: !`cat version.txt`
206	New version: $2
207
208	<!-- DECISION POINT: User confirms configuration -->
209	<!-- This pause allows user to verify everything is correct -->
210	<!-- We can't automatically proceed because deployment is risky -->
211
212	Review the above configuration.
213
214	Continue with deployment?
215	- Reply "yes" to proceed
216	- Reply "no" to cancel
217	- Reply "edit" to modify configuration
218
219	[Await user input before continuing...]
220
221	<!-- After user confirms, we proceed with deployment -->
222	<!-- All subsequent steps are automated -->
223
224	Proceeding with deployment...
225	```
226
227	## Help Text Patterns
228
229	### Built-in Help Command
230
231	Create a help subcommand for complex commands:
232
233	```markdown
234	---
235	description: Main command with help
236	argument-hint: [subcommand] [args]
237	---
238
239	# Command Processor
240
241	if [ "$1" = "help" ] \|\| [ "$1" = "--help" ] \|\| [ "$1" = "-h" ]; then
242	Command Help
243
244	USAGE:
245	/command [subcommand] [args]
246
247	SUBCOMMANDS:
248	init [name] Initialize new configuration
249	deploy [env] Deploy to environment
250	status Show current status
251	rollback Rollback last deployment
252	help Show this help
253
254	EXAMPLES:
255	/command init my-project
256	/command deploy staging
257	/command status
258	/command rollback
259
260	For detailed help on a subcommand:
261	/command [subcommand] --help
262
263	Exit.
264	fi
265
266	[Regular command processing...]
267	```
268
269	### Contextual Help
270
271	Provide help based on context:
272
273	```markdown
274	---
275	description: Context-aware command
276	argument-hint: [operation] [target]
277	---
278
279	# Context-Aware Operation
280
281	if [ -z "$1" ]; then
282	No operation specified
283
284	Available operations:
285	- analyze: Analyze target for issues
286	- fix: Apply automatic fixes
287	- report: Generate detailed report
288
289	Usage: /command [operation] [target]
290
291	Examples:
292	/command analyze src/
293	/command fix src/app.js
294	/command report
295
296	Run /command help for more details.
297
298	Exit.
299	fi
300
301	[Command continues if operation provided...]
302	```
303
304	## Error Message Documentation
305
306	### Helpful Error Messages
307
308	```markdown
309	---
310	description: Command with good error messages
311	---
312
313	# Validation Command
314
315	if [ -z "$1" ]; then
316	❌ ERROR: Missing required argument
317
318	The 'file-path' argument is required.
319
320	USAGE:
321	/validate [file-path]
322
323	EXAMPLE:
324	/validate src/app.js
325
326	Try again with a file path.
327
328	Exit.
329	fi
330
331	if [ ! -f "$1" ]; then
332	❌ ERROR: File not found: $1
333
334	The specified file does not exist or is not accessible.
335
336	COMMON CAUSES:
337	1. Typo in file path
338	2. File was deleted or moved
339	3. Insufficient permissions
340
341	SUGGESTIONS:
342	- Check spelling: $1
343	- Verify file exists: ls -la $(dirname "$1")
344	- Check permissions: ls -l "$1"
345
346	Exit.
347	fi
348
349	[Command continues if validation passes...]
350	```
351
352	### Error Recovery Guidance
353
354	```markdown
355	---
356	description: Command with recovery guidance
357	---
358
359	# Operation Command
360
361	Running operation...
362
363	!`risky-operation.sh`
364
365	if [ $? -ne 0 ]; then
366	❌ OPERATION FAILED
367
368	The operation encountered an error and could not complete.
369
370	WHAT HAPPENED:
371	The risky-operation.sh script returned a non-zero exit code.
372
373	WHAT THIS MEANS:
374	- Changes may be partially applied
375	- System may be in inconsistent state
376	- Manual intervention may be needed
377
378	RECOVERY STEPS:
379	1. Check operation logs: cat /tmp/operation.log
380	2. Verify system state: /check-state
381	3. If needed, rollback: /rollback-operation
382	4. Fix underlying issue
383	5. Retry operation: /retry-operation
384
385	NEED HELP?
386	- Check troubleshooting guide: /help troubleshooting
387	- Contact support with error code: ERR_OP_FAILED_001
388
389	Exit.
390	fi
391	```
392
393	## Usage Example Documentation
394
395	### Embedded Examples
396
397	```markdown
398	---
399	description: Command with embedded examples
400	---
401
402	# Feature Command
403
404	This command performs feature analysis with multiple options.
405
406	## Basic Usage
407
408	\`\`\`
409	/feature analyze src/
410	\`\`\`
411
412	Analyzes all files in src/ directory for feature usage.
413
414	## Advanced Usage
415
416	\`\`\`
417	/feature analyze src/ --detailed
418	\`\`\`
419
420	Provides detailed analysis including:
421	- Feature breakdown by file
422	- Usage patterns
423	- Optimization suggestions
424
425	## Use Cases
426
427	Use Case 1: Quick overview
428	\`\`\`
429	/feature analyze .
430	\`\`\`
431	Get high-level feature summary of entire project.
432
433	Use Case 2: Specific directory
434	\`\`\`
435	/feature analyze src/components
436	\`\`\`
437	Focus analysis on components directory only.
438
439	Use Case 3: Comparison
440	\`\`\`
441	/feature analyze src/ --compare baseline.json
442	\`\`\`
443	Compare current features against baseline.
444
445	---
446
447	Now processing your request...
448
449	[Command implementation...]
450	```
451
452	### Example-Driven Documentation
453
454	```markdown
455	---
456	description: Example-heavy command
457	---
458
459	# Transformation Command
460
461	## What This Does
462
463	Transforms data from one format to another.
464
465	## Examples First
466
467	### Example 1: JSON to YAML
468	Input: `data.json`
469	\`\`\`json
470	{"name": "test", "value": 42}
471	\`\`\`
472
473	Command: `/transform data.json yaml`
474
475	Output: `data.yaml`
476	\`\`\`yaml
477	name: test
478	value: 42
479	\`\`\`
480
481	### Example 2: CSV to JSON
482	Input: `data.csv`
483	\`\`\`csv
484	name,value
485	test,42
486	\`\`\`
487
488	Command: `/transform data.csv json`
489
490	Output: `data.json`
491	\`\`\`json
492	[{"name": "test", "value": "42"}]
493	\`\`\`
494
495	### Example 3: With Options
496	Command: `/transform data.json yaml --pretty --sort-keys`
497
498	Result: Formatted YAML with sorted keys
499
500	---
501
502	## Your Transformation
503
504	File: $1
505	Format: $2
506
507	[Perform transformation...]
508	```
509
510	## Maintenance Documentation
511
512	### Version and Changelog
513
514	```markdown
515	<!--
516	VERSION: 2.1.0
517	LAST UPDATED: 2025-01-15
518	AUTHOR: DevOps Team
519
520	CHANGELOG:
521	v2.1.0 (2025-01-15):
522	- Added support for YAML configuration
523	- Improved error messages
524	- Fixed bug with special characters in arguments
525
526	v2.0.0 (2025-01-01):
527	- BREAKING: Changed argument order
528	- BREAKING: Removed deprecated --old-flag
529	- Added new validation checks
530	- Migration guide: /migration-v2
531
532	v1.5.0 (2024-12-15):
533	- Added --verbose flag
534	- Improved performance by 50%
535
536	v1.0.0 (2024-12-01):
537	- Initial stable release
538
539	MIGRATION NOTES:
540	From v1.x to v2.0:
541	Old: /command arg1 arg2 --old-flag
542	New: /command arg2 arg1
543
544	The --old-flag is removed. Use --new-flag instead.
545
546	DEPRECATION WARNINGS:
547	- The --legacy-mode flag is deprecated as of v2.1.0
548	- Will be removed in v3.0.0 (estimated 2025-06-01)
549	- Use --modern-mode instead
550
551	KNOWN ISSUES:
552	- #123: Slow performance with large files (workaround: use --stream flag)
553	- #456: Special characters in Windows (fix planned for v2.2.0)
554	-->
555	```
556
557	### Maintenance Notes
558
559	```markdown
560	<!--
561	MAINTENANCE NOTES:
562
563	CODE STRUCTURE:
564	- Lines 1-50: Argument parsing and validation
565	- Lines 51-100: Main processing logic
566	- Lines 101-150: Output formatting
567	- Lines 151-200: Error handling
568
569	DEPENDENCIES:
570	- Requires git 2.x or later
571	- Uses jq for JSON processing
572	- Needs bash 4.0+ for associative arrays
573
574	PERFORMANCE:
575	- Fast path for small inputs (< 1MB)
576	- Streams large files to avoid memory issues
577	- Caches results in /tmp for 1 hour
578
579	SECURITY CONSIDERATIONS:
580	- Validates all inputs to prevent injection
581	- Uses allowed-tools to limit Bash access
582	- No credentials in command file
583
584	TESTING:
585	- Unit tests: tests/command-test.sh
586	- Integration tests: tests/integration/
587	- Manual test checklist: tests/manual-checklist.md
588
589	FUTURE IMPROVEMENTS:
590	- TODO: Add support for TOML format
591	- TODO: Implement parallel processing
592	- TODO: Add progress bar for large files
593
594	RELATED FILES:
595	- lib/parser.sh: Shared parsing logic
596	- lib/formatter.sh: Output formatting
597	- config/defaults.yml: Default configuration
598	-->
599	```
600
601	## README Documentation
602
603	Commands should have companion README files:
604
605	```markdown
606	# Command Name
607
608	Brief description of what the command does.
609
610	## Installation
611
612	This command is part of the [plugin-name] plugin.
613
614	Install with:
615	\`\`\`
616	/plugin install plugin-name
617	\`\`\`
618
619	## Usage
620
621	Basic usage:
622	\`\`\`
623	/command-name [arg1] [arg2]
624	\`\`\`
625
626	## Arguments
627
628	- `arg1`: Description (required)
629	- `arg2`: Description (optional, defaults to X)
630
631	## Examples
632
633	### Example 1: Basic Usage
634	\`\`\`
635	/command-name value1 value2
636	\`\`\`
637
638	Description of what happens.
639
640	### Example 2: Advanced Usage
641	\`\`\`
642	/command-name value1 --option
643	\`\`\`
644
645	Description of advanced feature.
646
647	## Configuration
648
649	Optional configuration file: `.claude/command-name.local.md`
650
651	\`\`\`markdown
652	---
653	default_arg: value
654	enable_feature: true
655	---
656	\`\`\`
657
658	## Requirements
659
660	- Git 2.x or later
661	- jq (for JSON processing)
662	- Node.js 14+ (optional, for advanced features)
663
664	## Troubleshooting
665
666	### Issue: Command not found
667
668	Solution: Ensure plugin is installed and enabled.
669
670	### Issue: Permission denied
671
672	Solution: Check file permissions and allowed-tools setting.
673
674	## Contributing
675
676	Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
677
678	## License
679
680	MIT License - See [LICENSE](LICENSE).
681
682	## Support
683
684	- Issues: https://github.com/user/plugin/issues
685	- Docs: https://docs.example.com
686	- Email: support@example.com
687	```
688
689	## Best Practices
690
691	### Documentation Principles
692
693	1. Write for your future self: Assume you'll forget details
694	2. Examples before explanations: Show, then tell
695	3. Progressive disclosure: Basic info first, details available
696	4. Keep it current: Update docs when code changes
697	5. Test your docs: Verify examples actually work
698
699	### Documentation Locations
700
701	1. In command file: Core usage, examples, inline explanations
702	2. README: Installation, configuration, troubleshooting
703	3. Separate docs: Detailed guides, tutorials, API reference
704	4. Comments: Implementation details for maintainers
705
706	### Documentation Style
707
708	1. Clear and concise: No unnecessary words
709	2. Active voice: "Run the command" not "The command can be run"
710	3. Consistent terminology: Use same terms throughout
711	4. Formatted well: Use headings, lists, code blocks
712	5. Accessible: Assume reader is beginner
713
714	### Documentation Maintenance
715
716	1. Version everything: Track what changed when
717	2. Deprecate gracefully: Warn before removing features
718	3. Migration guides: Help users upgrade
719	4. Archive old docs: Keep old versions accessible
720	5. Review regularly: Ensure docs match reality
721
722	## Documentation Checklist
723
724	Before releasing a command:
725
726	- [ ] Description in frontmatter is clear
727	- [ ] argument-hint documents all arguments
728	- [ ] Usage examples in comments
729	- [ ] Common use cases shown
730	- [ ] Error messages are helpful
731	- [ ] Requirements documented
732	- [ ] Related commands listed
733	- [ ] Changelog maintained
734	- [ ] Version number updated
735	- [ ] README created/updated
736	- [ ] Examples actually work
737	- [ ] Troubleshooting section complete
738
739	With good documentation, commands become self-service, reducing support burden and improving user experience.