1# Marketplace Considerations for Commands
2 
3Guidelines for creating commands designed for distribution and marketplace success.
4 
5## Overview
6 
7Commands distributed through marketplaces need additional consideration beyond personal use commands. They must work across environments, handle diverse use cases, and provide excellent user experience for unknown users.
8 
9## Design for Distribution
10 
11### Universal Compatibility
12 
13**Cross-platform considerations:**
14 
15```markdown
16---
17description: Cross-platform command
18allowed-tools: Bash(*)
19---
20 
21# Platform-Aware Command
22 
23Detecting platform...
24 
25case "$(uname)" in
26  Darwin*)  PLATFORM="macOS" ;;
27  Linux*)   PLATFORM="Linux" ;;
28  MINGW*|MSYS*|CYGWIN*) PLATFORM="Windows" ;;
29  *)        PLATFORM="Unknown" ;;
30esac
31 
32Platform: $PLATFORM
33 
34<!-- Adjust behavior based on platform -->
35if [ "$PLATFORM" = "Windows" ]; then
36  # Windows-specific handling
37  PATH_SEP="\\"
38  NULL_DEVICE="NUL"
39else
40  # Unix-like handling
41  PATH_SEP="/"
42  NULL_DEVICE="/dev/null"
43fi
44 
45[Platform-appropriate implementation...]
46```
47 
48**Avoid platform-specific commands:**
49 
50```markdown
51<!-- BAD: macOS-specific -->
52!`pbcopy < file.txt`
53 
54<!-- GOOD: Platform detection -->
55if command -v pbcopy > /dev/null; then
56  pbcopy < file.txt
57elif command -v xclip > /dev/null; then
58  xclip -selection clipboard < file.txt
59elif command -v clip.exe > /dev/null; then
60  cat file.txt | clip.exe
61else
62  echo "Clipboard not available on this platform"
63fi
64```
65 
66### Minimal Dependencies
67 
68**Check for required tools:**
69 
70```markdown
71---
72description: Dependency-aware command
73allowed-tools: Bash(*)
74---
75 
76# Check Dependencies
77 
78Required tools:
79- git
80- jq
81- node
82 
83Checking availability...
84 
85MISSING_DEPS=""
86 
87for tool in git jq node; do
88  if ! command -v $tool > /dev/null; then
89    MISSING_DEPS="$MISSING_DEPS $tool"
90  fi
91done
92 
93if [ -n "$MISSING_DEPS" ]; then
94  ❌ ERROR: Missing required dependencies:$MISSING_DEPS
95 
96  INSTALLATION:
97  - git: https://git-scm.com/downloads
98  - jq: https://stedolan.github.io/jq/download/
99  - node: https://nodejs.org/
100 
101  Install missing tools and try again.
102 
103  Exit.
104fi
105 
106✓ All dependencies available
107 
108[Continue with command...]
109```
110 
111**Document optional dependencies:**
112 
113```markdown
114<!--
115DEPENDENCIES:
116  Required:
117  - git 2.0+: Version control
118  - jq 1.6+: JSON processing
119 
120  Optional:
121  - gh: GitHub CLI (for PR operations)
122  - docker: Container operations (for containerized tests)
123 
124  Feature availability depends on installed tools.
125-->
126```
127 
128### Graceful Degradation
129 
130**Handle missing features:**
131 
132```markdown
133---
134description: Feature-aware command
135---
136 
137# Feature Detection
138 
139Detecting available features...
140 
141FEATURES=""
142 
143if command -v gh > /dev/null; then
144  FEATURES="$FEATURES github"
145fi
146 
147if command -v docker > /dev/null; then
148  FEATURES="$FEATURES docker"
149fi
150 
151Available features: $FEATURES
152 
153if echo "$FEATURES" | grep -q "github"; then
154  # Full functionality with GitHub integration
155  echo "✓ GitHub integration available"
156else
157  # Reduced functionality without GitHub
158  echo "⚠ Limited functionality: GitHub CLI not installed"
159  echo "  Install 'gh' for full features"
160fi
161 
162[Adapt behavior based on available features...]
163```
164 
165## User Experience for Unknown Users
166 
167### Clear Onboarding
168 
169**First-run experience:**
170 
171```markdown
172---
173description: Command with onboarding
174allowed-tools: Read, Write
175---
176 
177# First Run Check
178 
179if [ ! -f ".claude/command-initialized" ]; then
180  **Welcome to Command Name!**
181 
182  This appears to be your first time using this command.
183 
184  WHAT THIS COMMAND DOES:
185  [Brief explanation of purpose and benefits]
186 
187  QUICK START:
188  1. Basic usage: /command [arg]
189  2. For help: /command help
190  3. Examples: /command examples
191 
192  SETUP:
193  No additional setup required. You're ready to go!
194 
195  ✓ Initialization complete
196 
197  [Create initialization marker]
198 
199  Ready to proceed with your request...
200fi
201 
202[Normal command execution...]
203```
204 
205**Progressive feature discovery:**
206 
207```markdown
208---
209description: Command with tips
210---
211 
212# Command Execution
213 
214[Main functionality...]
215 
216---
217 
218💡 TIP: Did you know?
219 
220You can speed up this command with the --fast flag:
221  /command --fast [args]
222 
223For more tips: /command tips
224```
225 
226### Comprehensive Error Handling
227 
228**Anticipate user mistakes:**
229 
230```markdown
231---
232description: Forgiving command
233---
234 
235# User Input Handling
236 
237Argument: "$1"
238 
239<!-- Check for common typos -->
240if [ "$1" = "hlep" ] || [ "$1" = "hepl" ]; then
241  Did you mean: help?
242 
243  Showing help instead...
244  [Display help]
245 
246  Exit.
247fi
248 
249<!-- Suggest similar commands if not found -->
250if [ "$1" != "valid-option1" ] && [ "$1" != "valid-option2" ]; then
251  ❌ Unknown option: $1
252 
253  Did you mean:
254  - valid-option1 (most similar)
255  - valid-option2
256 
257  For all options: /command help
258 
259  Exit.
260fi
261 
262[Command continues...]
263```
264 
265**Helpful diagnostics:**
266 
267```markdown
268---
269description: Diagnostic command
270---
271 
272# Operation Failed
273 
274The operation could not complete.
275 
276**Diagnostic Information:**
277 
278Environment:
279- Platform: $(uname)
280- Shell: $SHELL
281- Working directory: $(pwd)
282- Command: /command $@
283 
284Checking common issues:
285- Git repository: $(git rev-parse --git-dir 2>&1)
286- Write permissions: $(test -w . && echo "OK" || echo "DENIED")
287- Required files: $(test -f config.yml && echo "Found" || echo "Missing")
288 
289This information helps debug the issue.
290 
291For support, include the above diagnostics.
292```
293 
294## Distribution Best Practices
295 
296### Namespace Awareness
297 
298**Avoid name collisions:**
299 
300```markdown
301---
302description: Namespaced command
303---
304 
305<!--
306COMMAND NAME: plugin-name-command
307 
308This command is namespaced with the plugin name to avoid
309conflicts with commands from other plugins.
310 
311Alternative naming approaches:
312- Use plugin prefix: /plugin-command
313- Use category: /category-command
314- Use verb-noun: /verb-noun
315 
316Chosen approach: plugin-name prefix
317Reasoning: Clearest ownership, least likely to conflict
318-->
319 
320# Plugin Name Command
321 
322[Implementation...]
323```
324 
325**Document naming rationale:**
326 
327```markdown
328<!--
329NAMING DECISION:
330 
331Command name: /deploy-app
332 
333Alternatives considered:
334- /deploy: Too generic, likely conflicts
335- /app-deploy: Less intuitive ordering
336- /my-plugin-deploy: Too verbose
337 
338Final choice balances:
339- Discoverability (clear purpose)
340- Brevity (easy to type)
341- Uniqueness (unlikely conflicts)
342-->
343```
344 
345### Configurability
346 
347**User preferences:**
348 
349```markdown
350---
351description: Configurable command
352allowed-tools: Read
353---
354 
355# Load User Configuration
356 
357Default configuration:
358- verbose: false
359- color: true
360- max_results: 10
361 
362Checking for user config: .claude/plugin-name.local.md
363 
364if [ -f ".claude/plugin-name.local.md" ]; then
365  # Parse YAML frontmatter for settings
366  VERBOSE=$(grep "^verbose:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
367  COLOR=$(grep "^color:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
368  MAX_RESULTS=$(grep "^max_results:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
369 
370  echo "✓ Using user configuration"
371else
372  echo "Using default configuration"
373  echo "Create .claude/plugin-name.local.md to customize"
374fi
375 
376[Use configuration in command...]
377```
378 
379**Sensible defaults:**
380 
381```markdown
382---
383description: Command with smart defaults
384---
385 
386# Smart Defaults
387 
388Configuration:
389- Format: ${FORMAT:-json}  # Defaults to json
390- Output: ${OUTPUT:-stdout}  # Defaults to stdout
391- Verbose: ${VERBOSE:-false}  # Defaults to false
392 
393These defaults work for 80% of use cases.
394 
395Override with arguments:
396  /command --format yaml --output file.txt --verbose
397 
398Or set in .claude/plugin-name.local.md:
399\`\`\`yaml
400---
401format: yaml
402output: custom.txt
403verbose: true
404---
405\`\`\`
406```
407 
408### Version Compatibility
409 
410**Version checking:**
411 
412```markdown
413---
414description: Version-aware command
415---
416 
417<!--
418COMMAND VERSION: 2.1.0
419 
420COMPATIBILITY:
421- Requires plugin version: >= 2.0.0
422- Breaking changes from v1.x documented in MIGRATION.md
423 
424VERSION HISTORY:
425- v2.1.0: Added --new-feature flag
426- v2.0.0: BREAKING: Changed argument order
427- v1.0.0: Initial release
428-->
429 
430# Version Check
431 
432Command version: 2.1.0
433Plugin version: [detect from plugin.json]
434 
435if [  "$PLUGIN_VERSION" < "2.0.0" ]; then
436  ❌ ERROR: Incompatible plugin version
437 
438  This command requires plugin version >= 2.0.0
439  Current version: $PLUGIN_VERSION
440 
441  Update plugin:
442    /plugin update plugin-name
443 
444  Exit.
445fi
446 
447✓ Version compatible
448 
449[Command continues...]
450```
451 
452**Deprecation warnings:**
453 
454```markdown
455---
456description: Command with deprecation warnings
457---
458 
459# Deprecation Check
460 
461if [ "$1" = "--old-flag" ]; then
462  ⚠️  DEPRECATION WARNING
463 
464  The --old-flag option is deprecated as of v2.0.0
465  It will be removed in v3.0.0 (est. June 2025)
466 
467  Use instead: --new-flag
468 
469  Example:
470    Old: /command --old-flag value
471    New: /command --new-flag value
472 
473  See migration guide: /command migrate
474 
475  Continuing with deprecated behavior for now...
476fi
477 
478[Handle both old and new flags during deprecation period...]
479```
480 
481## Marketplace Presentation
482 
483### Command Discovery
484 
485**Descriptive naming:**
486 
487```markdown
488---
489description: Review pull request with security and quality checks
490---
491 
492<!-- GOOD: Descriptive name and description -->
493```
494 
495```markdown
496---
497description: Do the thing
498---
499 
500<!-- BAD: Vague description -->
501```
502 
503**Searchable keywords:**
504 
505```markdown
506<!--
507KEYWORDS: security, code-review, quality, validation, audit
508 
509These keywords help users discover this command when searching
510for related functionality in the marketplace.
511-->
512```
513 
514### Showcase Examples
515 
516**Compelling demonstrations:**
517 
518```markdown
519---
520description: Advanced code analysis command
521---
522 
523# Code Analysis Command
524 
525This command performs deep code analysis with actionable insights.
526 
527## Demo: Quick Security Audit
528 
529Try it now:
530\`\`\`
531/analyze-code src/ --security
532\`\`\`
533 
534**What you'll get:**
535- Security vulnerability detection
536- Code quality metrics
537- Performance bottleneck identification
538- Actionable recommendations
539 
540**Sample output:**
541\`\`\`
542Security Analysis Results
543=========================
544 
545🔴 Critical (2):
546  - SQL injection risk in users.js:45
547  - XSS vulnerability in display.js:23
548 
549🟡 Warnings (5):
550  - Unvalidated input in api.js:67
551  ...
552 
553Recommendations:
5541. Fix critical issues immediately
5552. Review warnings before next release
5563. Run /analyze-code --fix for auto-fixes
557\`\`\`
558 
559---
560 
561Ready to analyze your code...
562 
563[Command implementation...]
564```
565 
566### User Reviews and Feedback
567 
568**Feedback mechanism:**
569 
570```markdown
571---
572description: Command with feedback
573---
574 
575# Command Complete
576 
577[Command results...]
578 
579---
580 
581**How was your experience?**
582 
583This helps improve the command for everyone.
584 
585Rate this command:
586- 👍 Helpful
587- 👎 Not helpful
588- 🐛 Found a bug
589- 💡 Have a suggestion
590 
591Reply with an emoji or:
592- /command feedback
593 
594Your feedback matters!
595```
596 
597**Usage analytics preparation:**
598 
599```markdown
600<!--
601ANALYTICS NOTES:
602 
603Track for improvement:
604- Most common arguments
605- Failure rates
606- Average execution time
607- User satisfaction scores
608 
609Privacy-preserving:
610- No personally identifiable information
611- Aggregate statistics only
612- User opt-out respected
613-->
614```
615 
616## Quality Standards
617 
618### Professional Polish
619 
620**Consistent branding:**
621 
622```markdown
623---
624description: Branded command
625---
626 
627# ✨ Command Name
628 
629Part of the [Plugin Name] suite
630 
631[Command functionality...]
632 
633---
634 
635**Need Help?**
636- Documentation: https://docs.example.com
637- Support: [email protected]
638- Community: https://community.example.com
639 
640Powered by Plugin Name v2.1.0
641```
642 
643**Attention to detail:**
644 
645```markdown
646<!-- Details that matter -->
647 
648✓ Use proper emoji/symbols consistently
649✓ Align output columns neatly
650✓ Format numbers with thousands separators
651✓ Use color/formatting appropriately
652✓ Provide progress indicators
653✓ Show estimated time remaining
654✓ Confirm successful operations
655```
656 
657### Reliability
658 
659**Idempotency:**
660 
661```markdown
662---
663description: Idempotent command
664---
665 
666# Safe Repeated Execution
667 
668Checking if operation already completed...
669 
670if [ -f ".claude/operation-completed.flag" ]; then
671  ℹ️  Operation already completed
672 
673  Completed at: $(cat .claude/operation-completed.flag)
674 
675  To re-run:
676  1. Remove flag: rm .claude/operation-completed.flag
677  2. Run command again
678 
679  Otherwise, no action needed.
680 
681  Exit.
682fi
683 
684Performing operation...
685 
686[Safe, repeatable operation...]
687 
688Marking complete...
689echo "$(date)" > .claude/operation-completed.flag
690```
691 
692**Atomic operations:**
693 
694```markdown
695---
696description: Atomic command
697---
698 
699# Atomic Operation
700 
701This operation is atomic - either fully succeeds or fully fails.
702 
703Creating temporary workspace...
704TEMP_DIR=$(mktemp -d)
705 
706Performing changes in isolated environment...
707[Make changes in $TEMP_DIR]
708 
709if [ $? -eq 0 ]; then
710  ✓ Changes validated
711 
712  Applying changes atomically...
713  mv $TEMP_DIR/* ./target/
714 
715  ✓ Operation complete
716else
717  ❌ Changes failed validation
718 
719  Rolling back...
720  rm -rf $TEMP_DIR
721 
722  No changes applied. Safe to retry.
723fi
724```
725 
726## Testing for Distribution
727 
728### Pre-Release Checklist
729 
730```markdown
731<!--
732PRE-RELEASE CHECKLIST:
733 
734Functionality:
735- [ ] Works on macOS
736- [ ] Works on Linux
737- [ ] Works on Windows (WSL)
738- [ ] All arguments tested
739- [ ] Error cases handled
740- [ ] Edge cases covered
741 
742User Experience:
743- [ ] Clear description
744- [ ] Helpful error messages
745- [ ] Examples provided
746- [ ] First-run experience good
747- [ ] Documentation complete
748 
749Distribution:
750- [ ] No hardcoded paths
751- [ ] Dependencies documented
752- [ ] Configuration options clear
753- [ ] Version number set
754- [ ] Changelog updated
755 
756Quality:
757- [ ] No TODO comments
758- [ ] No debug code
759- [ ] Performance acceptable
760- [ ] Security reviewed
761- [ ] Privacy considered
762 
763Support:
764- [ ] README complete
765- [ ] Troubleshooting guide
766- [ ] Support contact provided
767- [ ] Feedback mechanism
768- [ ] License specified
769-->
770```
771 
772### Beta Testing
773 
774**Beta release approach:**
775 
776```markdown
777---
778description: Beta command (v0.9.0)
779---
780 
781# 🧪 Beta Command
782 
783**This is a beta release**
784 
785Features may change based on feedback.
786 
787BETA STATUS:
788- Version: 0.9.0
789- Stability: Experimental
790- Support: Limited
791- Feedback: Encouraged
792 
793Known limitations:
794- Performance not optimized
795- Some edge cases not handled
796- Documentation incomplete
797 
798Help improve this command:
799- Report issues: /command report-issue
800- Suggest features: /command suggest
801- Join beta testers: /command join-beta
802 
803---
804 
805[Command implementation...]
806 
807---
808 
809**Thank you for beta testing!**
810 
811Your feedback helps make this command better.
812```
813 
814## Maintenance and Updates
815 
816### Update Strategy
817 
818**Versioned commands:**
819 
820```markdown
821<!--
822VERSION STRATEGY:
823 
824Major (X.0.0): Breaking changes
825- Document all breaking changes
826- Provide migration guide
827- Support old version briefly
828 
829Minor (x.Y.0): New features
830- Backward compatible
831- Announce new features
832- Update examples
833 
834Patch (x.y.Z): Bug fixes
835- No user-facing changes
836- Update changelog
837- Security fixes prioritized
838 
839Release schedule:
840- Patches: As needed
841- Minors: Monthly
842- Majors: Annually or as needed
843-->
844```
845 
846**Update notifications:**
847 
848```markdown
849---
850description: Update-aware command
851---
852 
853# Check for Updates
854 
855Current version: 2.1.0
856Latest version: [check if available]
857 
858if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then
859  📢 UPDATE AVAILABLE
860 
861  New version: $LATEST_VERSION
862  Current: $CURRENT_VERSION
863 
864  What's new:
865  - Feature improvements
866  - Bug fixes
867  - Performance enhancements
868 
869  Update with:
870    /plugin update plugin-name
871 
872  Release notes: https://releases.example.com/v$LATEST_VERSION
873fi
874 
875[Command continues...]
876```
877 
878## Best Practices Summary
879 
880### Distribution Design
881 
8821. **Universal**: Works across platforms and environments
8832. **Self-contained**: Minimal dependencies, clear requirements
8843. **Graceful**: Degrades gracefully when features unavailable
8854. **Forgiving**: Anticipates and handles user mistakes
8865. **Helpful**: Clear errors, good defaults, excellent docs
887 
888### Marketplace Success
889 
8901. **Discoverable**: Clear name, good description, searchable keywords
8912. **Professional**: Polished presentation, consistent branding
8923. **Reliable**: Tested thoroughly, handles edge cases
8934. **Maintainable**: Versioned, updated regularly, supported
8945. **User-focused**: Great UX, responsive to feedback
895 
896### Quality Standards
897 
8981. **Complete**: Fully documented, all features working
8992. **Tested**: Works in real environments, edge cases handled
9003. **Secure**: No vulnerabilities, safe operations
9014. **Performant**: Reasonable speed, resource-efficient
9025. **Ethical**: Privacy-respecting, user consent
903 
904With these considerations, commands become marketplace-ready and delight users across diverse environments and use cases.
905