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
| 1 | # Marketplace Considerations for Commands |
| 2 | |
| 3 | Guidelines for creating commands designed for distribution and marketplace success. |
| 4 | |
| 5 | ## Overview |
| 6 | |
| 7 | 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. |
| 8 | |
| 9 | ## Design for Distribution |
| 10 | |
| 11 | ### Universal Compatibility |
| 12 | |
| 13 | **Cross-platform considerations:** |
| 14 | |
| 15 | ```markdown |
| 16 | --- |
| 17 | description: Cross-platform command |
| 18 | allowed-tools: Bash(*) |
| 19 | --- |
| 20 | |
| 21 | # Platform-Aware Command |
| 22 | |
| 23 | Detecting platform... |
| 24 | |
| 25 | case "$(uname)" in |
| 26 | Darwin*) PLATFORM="macOS" ;; |
| 27 | Linux*) PLATFORM="Linux" ;; |
| 28 | MINGW*|MSYS*|CYGWIN*) PLATFORM="Windows" ;; |
| 29 | *) PLATFORM="Unknown" ;; |
| 30 | esac |
| 31 | |
| 32 | Platform: $PLATFORM |
| 33 | |
| 34 | <!-- Adjust behavior based on platform --> |
| 35 | if [ "$PLATFORM" = "Windows" ]; then |
| 36 | # Windows-specific handling |
| 37 | PATH_SEP="\\" |
| 38 | NULL_DEVICE="NUL" |
| 39 | else |
| 40 | # Unix-like handling |
| 41 | PATH_SEP="/" |
| 42 | NULL_DEVICE="/dev/null" |
| 43 | fi |
| 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 --> |
| 55 | if command -v pbcopy > /dev/null; then |
| 56 | pbcopy < file.txt |
| 57 | elif command -v xclip > /dev/null; then |
| 58 | xclip -selection clipboard < file.txt |
| 59 | elif command -v clip.exe > /dev/null; then |
| 60 | cat file.txt | clip.exe |
| 61 | else |
| 62 | echo "Clipboard not available on this platform" |
| 63 | fi |
| 64 | ``` |
| 65 | |
| 66 | ### Minimal Dependencies |
| 67 | |
| 68 | **Check for required tools:** |
| 69 | |
| 70 | ```markdown |
| 71 | --- |
| 72 | description: Dependency-aware command |
| 73 | allowed-tools: Bash(*) |
| 74 | --- |
| 75 | |
| 76 | # Check Dependencies |
| 77 | |
| 78 | Required tools: |
| 79 | - git |
| 80 | - jq |
| 81 | - node |
| 82 | |
| 83 | Checking availability... |
| 84 | |
| 85 | MISSING_DEPS="" |
| 86 | |
| 87 | for tool in git jq node; do |
| 88 | if ! command -v $tool > /dev/null; then |
| 89 | MISSING_DEPS="$MISSING_DEPS $tool" |
| 90 | fi |
| 91 | done |
| 92 | |
| 93 | if [ -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. |
| 104 | fi |
| 105 | |
| 106 | ✓ All dependencies available |
| 107 | |
| 108 | [Continue with command...] |
| 109 | ``` |
| 110 | |
| 111 | **Document optional dependencies:** |
| 112 | |
| 113 | ```markdown |
| 114 | <!-- |
| 115 | DEPENDENCIES: |
| 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 | --- |
| 134 | description: Feature-aware command |
| 135 | --- |
| 136 | |
| 137 | # Feature Detection |
| 138 | |
| 139 | Detecting available features... |
| 140 | |
| 141 | FEATURES="" |
| 142 | |
| 143 | if command -v gh > /dev/null; then |
| 144 | FEATURES="$FEATURES github" |
| 145 | fi |
| 146 | |
| 147 | if command -v docker > /dev/null; then |
| 148 | FEATURES="$FEATURES docker" |
| 149 | fi |
| 150 | |
| 151 | Available features: $FEATURES |
| 152 | |
| 153 | if echo "$FEATURES" | grep -q "github"; then |
| 154 | # Full functionality with GitHub integration |
| 155 | echo "✓ GitHub integration available" |
| 156 | else |
| 157 | # Reduced functionality without GitHub |
| 158 | echo "⚠ Limited functionality: GitHub CLI not installed" |
| 159 | echo " Install 'gh' for full features" |
| 160 | fi |
| 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 | --- |
| 173 | description: Command with onboarding |
| 174 | allowed-tools: Read, Write |
| 175 | --- |
| 176 | |
| 177 | # First Run Check |
| 178 | |
| 179 | if [ ! -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... |
| 200 | fi |
| 201 | |
| 202 | [Normal command execution...] |
| 203 | ``` |
| 204 | |
| 205 | **Progressive feature discovery:** |
| 206 | |
| 207 | ```markdown |
| 208 | --- |
| 209 | description: Command with tips |
| 210 | --- |
| 211 | |
| 212 | # Command Execution |
| 213 | |
| 214 | [Main functionality...] |
| 215 | |
| 216 | --- |
| 217 | |
| 218 | 💡 TIP: Did you know? |
| 219 | |
| 220 | You can speed up this command with the --fast flag: |
| 221 | /command --fast [args] |
| 222 | |
| 223 | For more tips: /command tips |
| 224 | ``` |
| 225 | |
| 226 | ### Comprehensive Error Handling |
| 227 | |
| 228 | **Anticipate user mistakes:** |
| 229 | |
| 230 | ```markdown |
| 231 | --- |
| 232 | description: Forgiving command |
| 233 | --- |
| 234 | |
| 235 | # User Input Handling |
| 236 | |
| 237 | Argument: "$1" |
| 238 | |
| 239 | <!-- Check for common typos --> |
| 240 | if [ "$1" = "hlep" ] || [ "$1" = "hepl" ]; then |
| 241 | Did you mean: help? |
| 242 | |
| 243 | Showing help instead... |
| 244 | [Display help] |
| 245 | |
| 246 | Exit. |
| 247 | fi |
| 248 | |
| 249 | <!-- Suggest similar commands if not found --> |
| 250 | if [ "$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. |
| 260 | fi |
| 261 | |
| 262 | [Command continues...] |
| 263 | ``` |
| 264 | |
| 265 | **Helpful diagnostics:** |
| 266 | |
| 267 | ```markdown |
| 268 | --- |
| 269 | description: Diagnostic command |
| 270 | --- |
| 271 | |
| 272 | # Operation Failed |
| 273 | |
| 274 | The operation could not complete. |
| 275 | |
| 276 | **Diagnostic Information:** |
| 277 | |
| 278 | Environment: |
| 279 | - Platform: $(uname) |
| 280 | - Shell: $SHELL |
| 281 | - Working directory: $(pwd) |
| 282 | - Command: /command $@ |
| 283 | |
| 284 | Checking 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 | |
| 289 | This information helps debug the issue. |
| 290 | |
| 291 | For support, include the above diagnostics. |
| 292 | ``` |
| 293 | |
| 294 | ## Distribution Best Practices |
| 295 | |
| 296 | ### Namespace Awareness |
| 297 | |
| 298 | **Avoid name collisions:** |
| 299 | |
| 300 | ```markdown |
| 301 | --- |
| 302 | description: Namespaced command |
| 303 | --- |
| 304 | |
| 305 | <!-- |
| 306 | COMMAND NAME: plugin-name-command |
| 307 | |
| 308 | This command is namespaced with the plugin name to avoid |
| 309 | conflicts with commands from other plugins. |
| 310 | |
| 311 | Alternative naming approaches: |
| 312 | - Use plugin prefix: /plugin-command |
| 313 | - Use category: /category-command |
| 314 | - Use verb-noun: /verb-noun |
| 315 | |
| 316 | Chosen approach: plugin-name prefix |
| 317 | Reasoning: 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 | <!-- |
| 329 | NAMING DECISION: |
| 330 | |
| 331 | Command name: /deploy-app |
| 332 | |
| 333 | Alternatives considered: |
| 334 | - /deploy: Too generic, likely conflicts |
| 335 | - /app-deploy: Less intuitive ordering |
| 336 | - /my-plugin-deploy: Too verbose |
| 337 | |
| 338 | Final 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 | --- |
| 351 | description: Configurable command |
| 352 | allowed-tools: Read |
| 353 | --- |
| 354 | |
| 355 | # Load User Configuration |
| 356 | |
| 357 | Default configuration: |
| 358 | - verbose: false |
| 359 | - color: true |
| 360 | - max_results: 10 |
| 361 | |
| 362 | Checking for user config: .claude/plugin-name.local.md |
| 363 | |
| 364 | if [ -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" |
| 371 | else |
| 372 | echo "Using default configuration" |
| 373 | echo "Create .claude/plugin-name.local.md to customize" |
| 374 | fi |
| 375 | |
| 376 | [Use configuration in command...] |
| 377 | ``` |
| 378 | |
| 379 | **Sensible defaults:** |
| 380 | |
| 381 | ```markdown |
| 382 | --- |
| 383 | description: Command with smart defaults |
| 384 | --- |
| 385 | |
| 386 | # Smart Defaults |
| 387 | |
| 388 | Configuration: |
| 389 | - Format: ${FORMAT:-json} # Defaults to json |
| 390 | - Output: ${OUTPUT:-stdout} # Defaults to stdout |
| 391 | - Verbose: ${VERBOSE:-false} # Defaults to false |
| 392 | |
| 393 | These defaults work for 80% of use cases. |
| 394 | |
| 395 | Override with arguments: |
| 396 | /command --format yaml --output file.txt --verbose |
| 397 | |
| 398 | Or set in .claude/plugin-name.local.md: |
| 399 | \`\`\`yaml |
| 400 | --- |
| 401 | format: yaml |
| 402 | output: custom.txt |
| 403 | verbose: true |
| 404 | --- |
| 405 | \`\`\` |
| 406 | ``` |
| 407 | |
| 408 | ### Version Compatibility |
| 409 | |
| 410 | **Version checking:** |
| 411 | |
| 412 | ```markdown |
| 413 | --- |
| 414 | description: Version-aware command |
| 415 | --- |
| 416 | |
| 417 | <!-- |
| 418 | COMMAND VERSION: 2.1.0 |
| 419 | |
| 420 | COMPATIBILITY: |
| 421 | - Requires plugin version: >= 2.0.0 |
| 422 | - Breaking changes from v1.x documented in MIGRATION.md |
| 423 | |
| 424 | VERSION 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 | |
| 432 | Command version: 2.1.0 |
| 433 | Plugin version: [detect from plugin.json] |
| 434 | |
| 435 | if [ "$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. |
| 445 | fi |
| 446 | |
| 447 | ✓ Version compatible |
| 448 | |
| 449 | [Command continues...] |
| 450 | ``` |
| 451 | |
| 452 | **Deprecation warnings:** |
| 453 | |
| 454 | ```markdown |
| 455 | --- |
| 456 | description: Command with deprecation warnings |
| 457 | --- |
| 458 | |
| 459 | # Deprecation Check |
| 460 | |
| 461 | if [ "$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... |
| 476 | fi |
| 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 | --- |
| 489 | description: Review pull request with security and quality checks |
| 490 | --- |
| 491 | |
| 492 | <!-- GOOD: Descriptive name and description --> |
| 493 | ``` |
| 494 | |
| 495 | ```markdown |
| 496 | --- |
| 497 | description: Do the thing |
| 498 | --- |
| 499 | |
| 500 | <!-- BAD: Vague description --> |
| 501 | ``` |
| 502 | |
| 503 | **Searchable keywords:** |
| 504 | |
| 505 | ```markdown |
| 506 | <!-- |
| 507 | KEYWORDS: security, code-review, quality, validation, audit |
| 508 | |
| 509 | These keywords help users discover this command when searching |
| 510 | for related functionality in the marketplace. |
| 511 | --> |
| 512 | ``` |
| 513 | |
| 514 | ### Showcase Examples |
| 515 | |
| 516 | **Compelling demonstrations:** |
| 517 | |
| 518 | ```markdown |
| 519 | --- |
| 520 | description: Advanced code analysis command |
| 521 | --- |
| 522 | |
| 523 | # Code Analysis Command |
| 524 | |
| 525 | This command performs deep code analysis with actionable insights. |
| 526 | |
| 527 | ## Demo: Quick Security Audit |
| 528 | |
| 529 | Try 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 | \`\`\` |
| 542 | Security 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 | |
| 553 | Recommendations: |
| 554 | 1. Fix critical issues immediately |
| 555 | 2. Review warnings before next release |
| 556 | 3. Run /analyze-code --fix for auto-fixes |
| 557 | \`\`\` |
| 558 | |
| 559 | --- |
| 560 | |
| 561 | Ready to analyze your code... |
| 562 | |
| 563 | [Command implementation...] |
| 564 | ``` |
| 565 | |
| 566 | ### User Reviews and Feedback |
| 567 | |
| 568 | **Feedback mechanism:** |
| 569 | |
| 570 | ```markdown |
| 571 | --- |
| 572 | description: Command with feedback |
| 573 | --- |
| 574 | |
| 575 | # Command Complete |
| 576 | |
| 577 | [Command results...] |
| 578 | |
| 579 | --- |
| 580 | |
| 581 | **How was your experience?** |
| 582 | |
| 583 | This helps improve the command for everyone. |
| 584 | |
| 585 | Rate this command: |
| 586 | - 👍 Helpful |
| 587 | - 👎 Not helpful |
| 588 | - 🐛 Found a bug |
| 589 | - 💡 Have a suggestion |
| 590 | |
| 591 | Reply with an emoji or: |
| 592 | - /command feedback |
| 593 | |
| 594 | Your feedback matters! |
| 595 | ``` |
| 596 | |
| 597 | **Usage analytics preparation:** |
| 598 | |
| 599 | ```markdown |
| 600 | <!-- |
| 601 | ANALYTICS NOTES: |
| 602 | |
| 603 | Track for improvement: |
| 604 | - Most common arguments |
| 605 | - Failure rates |
| 606 | - Average execution time |
| 607 | - User satisfaction scores |
| 608 | |
| 609 | Privacy-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 | --- |
| 624 | description: Branded command |
| 625 | --- |
| 626 | |
| 627 | # ✨ Command Name |
| 628 | |
| 629 | Part of the [Plugin Name] suite |
| 630 | |
| 631 | [Command functionality...] |
| 632 | |
| 633 | --- |
| 634 | |
| 635 | **Need Help?** |
| 636 | - Documentation: https://docs.example.com |
| 637 | - Support: support@example.com |
| 638 | - Community: https://community.example.com |
| 639 | |
| 640 | Powered 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 | --- |
| 663 | description: Idempotent command |
| 664 | --- |
| 665 | |
| 666 | # Safe Repeated Execution |
| 667 | |
| 668 | Checking if operation already completed... |
| 669 | |
| 670 | if [ -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. |
| 682 | fi |
| 683 | |
| 684 | Performing operation... |
| 685 | |
| 686 | [Safe, repeatable operation...] |
| 687 | |
| 688 | Marking complete... |
| 689 | echo "$(date)" > .claude/operation-completed.flag |
| 690 | ``` |
| 691 | |
| 692 | **Atomic operations:** |
| 693 | |
| 694 | ```markdown |
| 695 | --- |
| 696 | description: Atomic command |
| 697 | --- |
| 698 | |
| 699 | # Atomic Operation |
| 700 | |
| 701 | This operation is atomic - either fully succeeds or fully fails. |
| 702 | |
| 703 | Creating temporary workspace... |
| 704 | TEMP_DIR=$(mktemp -d) |
| 705 | |
| 706 | Performing changes in isolated environment... |
| 707 | [Make changes in $TEMP_DIR] |
| 708 | |
| 709 | if [ $? -eq 0 ]; then |
| 710 | ✓ Changes validated |
| 711 | |
| 712 | Applying changes atomically... |
| 713 | mv $TEMP_DIR/* ./target/ |
| 714 | |
| 715 | ✓ Operation complete |
| 716 | else |
| 717 | ❌ Changes failed validation |
| 718 | |
| 719 | Rolling back... |
| 720 | rm -rf $TEMP_DIR |
| 721 | |
| 722 | No changes applied. Safe to retry. |
| 723 | fi |
| 724 | ``` |
| 725 | |
| 726 | ## Testing for Distribution |
| 727 | |
| 728 | ### Pre-Release Checklist |
| 729 | |
| 730 | ```markdown |
| 731 | <!-- |
| 732 | PRE-RELEASE CHECKLIST: |
| 733 | |
| 734 | Functionality: |
| 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 | |
| 742 | User Experience: |
| 743 | - [ ] Clear description |
| 744 | - [ ] Helpful error messages |
| 745 | - [ ] Examples provided |
| 746 | - [ ] First-run experience good |
| 747 | - [ ] Documentation complete |
| 748 | |
| 749 | Distribution: |
| 750 | - [ ] No hardcoded paths |
| 751 | - [ ] Dependencies documented |
| 752 | - [ ] Configuration options clear |
| 753 | - [ ] Version number set |
| 754 | - [ ] Changelog updated |
| 755 | |
| 756 | Quality: |
| 757 | - [ ] No TODO comments |
| 758 | - [ ] No debug code |
| 759 | - [ ] Performance acceptable |
| 760 | - [ ] Security reviewed |
| 761 | - [ ] Privacy considered |
| 762 | |
| 763 | Support: |
| 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 | --- |
| 778 | description: Beta command (v0.9.0) |
| 779 | --- |
| 780 | |
| 781 | # 🧪 Beta Command |
| 782 | |
| 783 | **This is a beta release** |
| 784 | |
| 785 | Features may change based on feedback. |
| 786 | |
| 787 | BETA STATUS: |
| 788 | - Version: 0.9.0 |
| 789 | - Stability: Experimental |
| 790 | - Support: Limited |
| 791 | - Feedback: Encouraged |
| 792 | |
| 793 | Known limitations: |
| 794 | - Performance not optimized |
| 795 | - Some edge cases not handled |
| 796 | - Documentation incomplete |
| 797 | |
| 798 | Help 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 | |
| 811 | Your feedback helps make this command better. |
| 812 | ``` |
| 813 | |
| 814 | ## Maintenance and Updates |
| 815 | |
| 816 | ### Update Strategy |
| 817 | |
| 818 | **Versioned commands:** |
| 819 | |
| 820 | ```markdown |
| 821 | <!-- |
| 822 | VERSION STRATEGY: |
| 823 | |
| 824 | Major (X.0.0): Breaking changes |
| 825 | - Document all breaking changes |
| 826 | - Provide migration guide |
| 827 | - Support old version briefly |
| 828 | |
| 829 | Minor (x.Y.0): New features |
| 830 | - Backward compatible |
| 831 | - Announce new features |
| 832 | - Update examples |
| 833 | |
| 834 | Patch (x.y.Z): Bug fixes |
| 835 | - No user-facing changes |
| 836 | - Update changelog |
| 837 | - Security fixes prioritized |
| 838 | |
| 839 | Release schedule: |
| 840 | - Patches: As needed |
| 841 | - Minors: Monthly |
| 842 | - Majors: Annually or as needed |
| 843 | --> |
| 844 | ``` |
| 845 | |
| 846 | **Update notifications:** |
| 847 | |
| 848 | ```markdown |
| 849 | --- |
| 850 | description: Update-aware command |
| 851 | --- |
| 852 | |
| 853 | # Check for Updates |
| 854 | |
| 855 | Current version: 2.1.0 |
| 856 | Latest version: [check if available] |
| 857 | |
| 858 | if [ "$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 |
| 873 | fi |
| 874 | |
| 875 | [Command continues...] |
| 876 | ``` |
| 877 | |
| 878 | ## Best Practices Summary |
| 879 | |
| 880 | ### Distribution Design |
| 881 | |
| 882 | 1. **Universal**: Works across platforms and environments |
| 883 | 2. **Self-contained**: Minimal dependencies, clear requirements |
| 884 | 3. **Graceful**: Degrades gracefully when features unavailable |
| 885 | 4. **Forgiving**: Anticipates and handles user mistakes |
| 886 | 5. **Helpful**: Clear errors, good defaults, excellent docs |
| 887 | |
| 888 | ### Marketplace Success |
| 889 | |
| 890 | 1. **Discoverable**: Clear name, good description, searchable keywords |
| 891 | 2. **Professional**: Polished presentation, consistent branding |
| 892 | 3. **Reliable**: Tested thoroughly, handles edge cases |
| 893 | 4. **Maintainable**: Versioned, updated regularly, supported |
| 894 | 5. **User-focused**: Great UX, responsive to feedback |
| 895 | |
| 896 | ### Quality Standards |
| 897 | |
| 898 | 1. **Complete**: Fully documented, all features working |
| 899 | 2. **Tested**: Works in real environments, edge cases handled |
| 900 | 3. **Secure**: No vulnerabilities, safe operations |
| 901 | 4. **Performant**: Reasonable speed, resource-efficient |
| 902 | 5. **Ethical**: Privacy-respecting, user consent |
| 903 | |
| 904 | With these considerations, commands become marketplace-ready and delight users across diverse environments and use cases. |