--- name: marketplace-considerations description: marketplace-considerations skill metadata: short-description: marketplace-considerations skill category: utilities source: claude-code-templates --- # Marketplace Considerations # Marketplace Considerations for Commands Guidelines for creating commands designed for distribution and marketplace success. ## Overview Commands 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. ## Design for Distribution ### Universal Compatibility **Cross-platform considerations:** ```markdown --- description: Cross-platform command allowed-tools: Bash(*) --- # Platform-Aware Command Detecting platform... case "$(uname)" in Darwin*) PLATFORM="macOS" ;; Linux*) PLATFORM="Linux" ;; MINGW*|MSYS*|CYGWIN*) PLATFORM="Windows" ;; *) PLATFORM="Unknown" ;; esac Platform: $PLATFORM if [ "$PLATFORM" = "Windows" ]; then # Windows-specific handling PATH_SEP="\\" NULL_DEVICE="NUL" else # Unix-like handling PATH_SEP="\/" NULL_DEVICE="\/dev\/null" fi [Platform-appropriate implementation...] ``` **Avoid platform-specific commands:** ```markdown !`pbcopy < file.txt` if command -v pbcopy > \/dev\/null; then pbcopy < file.txt elif command -v xclip > \/dev\/null; then xclip -selection clipboard < file.txt elif command -v clip.exe > \/dev\/null; then cat file.txt | clip.exe else echo "Clipboard not available on this platform" fi ``` ### Minimal Dependencies **Check for required tools:** ```markdown --- description: Dependency-aware command allowed-tools: Bash(*) --- # Check Dependencies Required tools: - git - jq - node Checking availability... MISSING_DEPS="" for tool in git jq node; do if ! command -v $tool > \/dev\/null; then MISSING_DEPS="$MISSING_DEPS $tool" fi done if [ -n "$MISSING_DEPS" ]; then ❌ ERROR: Missing required dependencies:$MISSING_DEPS INSTALLATION: - git: https:\/\/git-scm.com\/downloads - jq: https:\/\/stedolan.github.io\/jq\/download\/ - node: https:\/\/nodejs.org\/ Install missing tools and try again. Exit. fi ✓ All dependencies available [Continue with command...] ``` **Document optional dependencies:** ```markdown ``` ### Graceful Degradation **Handle missing features:** ```markdown --- description: Feature-aware command --- # Feature Detection Detecting available features... FEATURES="" if command -v gh > \/dev\/null; then FEATURES="$FEATURES github" fi if command -v docker > \/dev\/null; then FEATURES="$FEATURES docker" fi Available features: $FEATURES if echo "$FEATURES" | grep -q "github"; then # Full functionality with GitHub integration echo "✓ GitHub integration available" else # Reduced functionality without GitHub echo "⚠ Limited functionality: GitHub CLI not installed" echo " Install 'gh' for full features" fi [Adapt behavior based on available features...] ``` ## User Experience for Unknown Users ### Clear Onboarding **First-run experience:** ```markdown --- description: Command with onboarding allowed-tools: Read, Write --- # First Run Check if [ ! -f ".claude\/command-initialized" ]; then **Welcome to Command Name!** This appears to be your first time using this command. WHAT THIS COMMAND DOES: [Brief explanation of purpose and benefits] QUICK START: 1. Basic usage: \/command [arg] 2. For help: \/command help 3. Examples: \/command examples SETUP: No additional setup required. You're ready to go! ✓ Initialization complete [Create initialization marker] Ready to proceed with your request... fi [Normal command execution...] ``` **Progressive feature discovery:** ```markdown --- description: Command with tips --- # Command Execution [Main functionality...] --- 💡 TIP: Did you know? You can speed up this command with the --fast flag: \/command --fast [args] For more tips: \/command tips ``` ### Comprehensive Error Handling **Anticipate user mistakes:** ```markdown --- description: Forgiving command --- # User Input Handling Argument: "$1" if [ "$1" = "hlep" ] || [ "$1" = "hepl" ]; then Did you mean: help? Showing help instead... [Display help] Exit. fi if [ "$1" != "valid-option1" ] && [ "$1" != "valid-option2" ]; then ❌ Unknown option: $1 Did you mean: - valid-option1 (most similar) - valid-option2 For all options: \/command help Exit. fi [Command continues...] ``` **Helpful diagnostics:** ```markdown --- description: Diagnostic command --- # Operation Failed The operation could not complete. **Diagnostic Information:** Environment: - Platform: $(uname) - Shell: $SHELL - Working directory: $(pwd) - Command: \/command $@ Checking common issues: - Git repository: $(git rev-parse --git-dir 2>&1) - Write permissions: $(test -w . && echo "OK" || echo "DENIED") - Required files: $(test -f config.yml && echo "Found" || echo "Missing") This information helps debug the issue. For support, include the above diagnostics. ``` ## Distribution Best Practices ### Namespace Awareness **Avoid name collisions:** ```markdown --- description: Namespaced command --- # Plugin Name Command [Implementation...] ``` **Document naming rationale:** ```markdown ``` ### Configurability **User preferences:** ```markdown --- description: Configurable command allowed-tools: Read --- # Load User Configuration Default configuration: - verbose: false - color: true - max_results: 10 Checking for user config: .claude\/plugin-name.local.md if [ -f ".claude\/plugin-name.local.md" ]; then # Parse YAML frontmatter for settings VERBOSE=$(grep "^verbose:" .claude\/plugin-name.local.md | cut -d: -f2 | tr -d ' ') COLOR=$(grep "^color:" .claude\/plugin-name.local.md | cut -d: -f2 | tr -d ' ') MAX_RESULTS=$(grep "^max_results:" .claude\/plugin-name.local.md | cut -d: -f2 | tr -d ' ') echo "✓ Using user configuration" else echo "Using default configuration" echo "Create .claude\/plugin-name.local.md to customize" fi [Use configuration in command...] ``` **Sensible defaults:** ```markdown --- description: Command with smart defaults --- # Smart Defaults Configuration: - Format: ${FORMAT:-json} # Defaults to json - Output: ${OUTPUT:-stdout} # Defaults to stdout - Verbose: ${VERBOSE:-false} # Defaults to false These defaults work for 80% of use cases. Override with arguments: \/command --format yaml --output file.txt --verbose Or set in .claude\/plugin-name.local.md: \`\`\`yaml --- format: yaml output: custom.txt verbose: true --- \`\`\` ``` ### Version Compatibility **Version checking:** ```markdown --- description: Version-aware command --- # Version Check Command version: 2.1.0 Plugin version: [detect from plugin.json] if [ "$PLUGIN_VERSION" < "2.0.0" ]; then ❌ ERROR: Incompatible plugin version This command requires plugin version >= 2.0.0 Current version: $PLUGIN_VERSION Update plugin: \/plugin update plugin-name Exit. fi ✓ Version compatible [Command continues...] ``` **Deprecation warnings:** ```markdown --- description: Command with deprecation warnings --- # Deprecation Check if [ "$1" = "--old-flag" ]; then ⚠️ DEPRECATION WARNING The --old-flag option is deprecated as of v2.0.0 It will be removed in v3.0.0 (est. June 2025) Use instead: --new-flag Example: Old: \/command --old-flag value New: \/command --new-flag value See migration guide: \/command migrate Continuing with deprecated behavior for now... fi [Handle both old and new flags during deprecation period...] ``` ## Marketplace Presentation ### Command Discovery **Descriptive naming:** ```markdown --- description: Review pull request with security and quality checks --- ``` ```markdown --- description: Do the thing --- ``` **Searchable keywords:** ```markdown ``` ### Showcase Examples **Compelling demonstrations:** ```markdown --- description: Advanced code analysis command --- # Code Analysis Command This command performs deep code analysis with actionable insights. ## Demo: Quick Security Audit Try it now: \`\`\` \/analyze-code src\/ --security \`\`\` **What you'll get:** - Security vulnerability detection - Code quality metrics - Performance bottleneck identification - Actionable recommendations **Sample output:** \`\`\` Security Analysis Results ========================= 🔴 Critical (2): - SQL injection risk in users.js:45 - XSS vulnerability in display.js:23 🟡 Warnings (5): - Unvalidated input in api.js:67 ... Recommendations: 1. Fix critical issues immediately 2. Review warnings before next release 3. Run \/analyze-code --fix for auto-fixes \`\`\` --- Ready to analyze your code... [Command implementation...] ``` ### User Reviews and Feedback **Feedback mechanism:** ```markdown --- description: Command with feedback --- # Command Complete [Command results...] --- **How was your experience?** This helps improve the command for everyone. Rate this command: - 👍 Helpful - 👎 Not helpful - 🐛 Found a bug - 💡 Have a suggestion Reply with an emoji or: - \/command feedback Your feedback matters! ``` **Usage analytics preparation:** ```markdown ``` ## Quality Standards ### Professional Polish **Consistent branding:** ```markdown --- description: Branded command --- # ✨ Command Name Part of the [Plugin Name] suite [Command functionality...] --- **Need Help?** - Documentation: https:\/\/docs.example.com - Support: support@example.com - Community: https:\/\/community.example.com Powered by Plugin Name v2.1.0 ``` **Attention to detail:** ```markdown ✓ Use proper emoji\/symbols consistently ✓ Align output columns neatly ✓ Format numbers with thousands separators ✓ Use color\/formatting appropriately ✓ Provide progress indicators ✓ Show estimated time remaining ✓ Confirm successful operations ``` ### Reliability **Idempotency:** ```markdown --- description: Idempotent command --- # Safe Repeated Execution Checking if operation already completed... if [ -f ".claude\/operation-completed.flag" ]; then ℹ️ Operation already completed Completed at: $(cat .claude\/operation-completed.flag) To re-run: 1. Remove flag: rm .claude\/operation-completed.flag 2. Run command again Otherwise, no action needed. Exit. fi Performing operation... [Safe, repeatable operation...] Marking complete... echo "$(date)" > .claude\/operation-completed.flag ``` **Atomic operations:** ```markdown --- description: Atomic command --- # Atomic Operation This operation is atomic - either fully succeeds or fully fails. Creating temporary workspace... TEMP_DIR=$(mktemp -d) Performing changes in isolated environment... [Make changes in $TEMP_DIR] if [ $? -eq 0 ]; then ✓ Changes validated Applying changes atomically... mv $TEMP_DIR\/* .\/target\/ ✓ Operation complete else ❌ Changes failed validation Rolling back... rm -rf $TEMP_DIR No changes applied. Safe to retry. fi ``` ## Testing for Distribution ### Pre-Release Checklist ```markdown ``` ### Beta Testing **Beta release approach:** ```markdown --- description: Beta command (v0.9.0) --- # 🧪 Beta Command **This is a beta release** Features may change based on feedback. BETA STATUS: - Version: 0.9.0 - Stability: Experimental - Support: Limited - Feedback: Encouraged Known limitations: - Performance not optimized - Some edge cases not handled - Documentation incomplete Help improve this command: - Report issues: \/command report-issue - Suggest features: \/command suggest - Join beta testers: \/command join-beta --- [Command implementation...] --- **Thank you for beta testing!** Your feedback helps make this command better. ``` ## Maintenance and Updates ### Update Strategy **Versioned commands:** ```markdown ``` **Update notifications:** ```markdown --- description: Update-aware command --- # Check for Updates Current version: 2.1.0 Latest version: [check if available] if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then 📢 UPDATE AVAILABLE New version: $LATEST_VERSION Current: $CURRENT_VERSION What's new: - Feature improvements - Bug fixes - Performance enhancements Update with: \/plugin update plugin-name Release notes: https:\/\/releases.example.com\/v$LATEST_VERSION fi [Command continues...] ``` ## Best Practices Summary ### Distribution Design 1. **Universal**: Works across platforms and environments 2. **Self-contained**: Minimal dependencies, clear requirements 3. **Graceful**: Degrades gracefully when features unavailable 4. **Forgiving**: Anticipates and handles user mistakes 5. **Helpful**: Clear errors, good defaults, excellent docs ### Marketplace Success 1. **Discoverable**: Clear name, good description, searchable keywords 2. **Professional**: Polished presentation, consistent branding 3. **Reliable**: Tested thoroughly, handles edge cases 4. **Maintainable**: Versioned, updated regularly, supported 5. **User-focused**: Great UX, responsive to feedback ### Quality Standards 1. **Complete**: Fully documented, all features working 2. **Tested**: Works in real environments, edge cases handled 3. **Secure**: No vulnerabilities, safe operations 4. **Performant**: Reasonable speed, resource-efficient 5. **Ethical**: Privacy-respecting, user consent With these considerations, commands become marketplace-ready and delight users across diverse environments and use cases. ## Usage Invoke this skill with: ``` $marketplace-considerations [arguments] ``` Or let Codex auto-select based on your prompt.