Command Development

AnthropicOfficialPublished by Anthropic

Skill
Tool integration
Agent tooling
Apache-2.0
No issues found

From the author

This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.

— the description by Anthropic

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Slash commands are Markdown-based instructions that allow Claude to execute specific, reusable tasks. This skill provides the framework for creating these commands, including how to use YAML frontmatter for configuration, dynamic arguments for flexibility, and bash execution for context-aware automation. It covers best practices for command structure, organization, and documentation to ensure commands are maintainable and easy to use.

What it does

Defines the structure of slash commands using Markdown and YAML frontmatter.
Explains how to implement dynamic arguments and file references for interactive tasks.
Guides the integration of bash commands to gather repository or environment context.
Provides patterns for organizing commands into project-specific or personal namespaces.
Offers best practices for command design, validation, and error handling.
Details how to document commands for better discoverability and maintainability.

When to use it

When you need to automate a recurring, multi-step task in Claude Code.
When you want to standardize workflows across a team or project.
When you need to create custom utilities that require specific tool access or model settings.
When you want to build complex, state-aware workflows using multiple commands.

Advantages

Increases efficiency by turning complex prompts into simple, reusable commands.
Ensures consistency in task execution across different users and projects.
Enables dynamic behavior through argument passing and inline bash execution.
Supports modular organization, making it easy to manage large sets of commands.

Usage examples

“Create a slash command to review a pull request.”: The agent will generate a Markdown file with appropriate frontmatter and instructions to analyze a PR, including steps for fetching details and checking code quality.
“How do I add an argument to my custom command?”: The agent will explain how to use $1, $2, or $ARGUMENTS syntax within your command file and how to document it using the argument-hint frontmatter field.
“Show me how to run a bash script inside a command.”: The agent will provide a template showing how to use backticks with bash commands and how to configure allowed-tools in the frontmatter for security.
“How should I organize my project commands?”: The agent will suggest a namespaced directory structure for your .claude/commands/ folder to keep related tasks grouped logically.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/anthropics/command-development/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip command-development.zip -d .agents/skills

Documentation by Anthropic

Command Development for Claude Code

Note: The .claude/commands/ directory is a legacy format. For new skills, use the .claude/skills/<name>/SKILL.md directory format. Both are loaded identically — the only difference is file layout. See the skill-development skill for the preferred format.

Overview

Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.

Key concepts:

Markdown file format for commands
YAML frontmatter for configuration
Dynamic arguments and file references
Bash execution for context
Command organization and namespacing

Command Basics

What is a Slash Command?

A slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:

Reusability: Define once, use repeatedly
Consistency: Standardize common workflows
Sharing: Distribute across team or projects
Efficiency: Quick access to complex prompts

Critical: Commands are Instructions FOR Claude

Commands are written for agent consumption, not human consumption.

When a user invokes /command-name, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.

Correct approach (instructions for Claude):

Review this code for security vulnerabilities including:

- SQL injection
- XSS attacks
- Authentication issues

Provide specific line numbers and severity ratings.

Incorrect approach (messages to user):

This command will review your code for security issues.
You'll receive a report with vulnerability details.

The first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.

Command Locations

Project commands (shared with team):

Location: .claude/commands/
Scope: Available in specific project
Label: Shown as "(project)" in /help
Use for: Team workflows, project-specific tasks

Personal commands (available everywhere):

Location: ~/.claude/commands/
Scope: Available in all projects
Label: Shown as "(user)" in /help
Use for: Personal workflows, cross-project utilities

Plugin commands (bundled with plugins):

Location: plugin-name/commands/
Scope: Available when plugin installed
Label: Shown as "(plugin-name)" in /help
Use for: Plugin-specific functionality

File Format

Basic Structure

Commands are Markdown files with .md extension:

.claude/commands/
├── review.md           # /review command
├── test.md             # /test command
└── deploy.md           # /deploy command

Simple command:

Review this code for security vulnerabilities including:

- SQL injection
- XSS attacks
- Authentication bypass
- Insecure data handling

No frontmatter needed for basic commands.

With YAML Frontmatter

Add configuration using YAML frontmatter:

---
description: Review code for security issues
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---

Review this code for security vulnerabilities...

YAML Frontmatter Fields

description

Purpose: Brief description shown in /help Type: String Default: First line of command prompt

---
description: Review pull request for code quality
---

Best practice: Clear, actionable description (under 60 characters)

allowed-tools

Purpose: Specify which tools command can use Type: String or Array Default: Inherits from conversation

---
allowed-tools: Read, Write, Edit, Bash(git:*)
---

Patterns:

Read, Write, Edit - Specific tools
Bash(git:*) - Bash with git commands only
* - All tools (rarely needed)

Use when: Command requires specific tool access

model

Purpose: Specify model for command execution Type: String (sonnet, opus, haiku) Default: Inherits from conversation

---
model: haiku
---

Use cases:

haiku - Fast, simple commands
sonnet - Standard workflows
opus - Complex analysis

argument-hint

Purpose: Document expected arguments for autocomplete Type: String Default: None

---
argument-hint: [pr-number] [priority] [assignee]
---

Benefits:

Helps users understand command arguments
Improves command discovery
Documents command interface

disable-model-invocation

Purpose: Prevent SlashCommand tool from programmatically calling command Type: Boolean Default: false

---
disable-model-invocation: true
---

Use when: Command should only be manually invoked

Dynamic Arguments

Using $ARGUMENTS

Capture all arguments as single string:

---
description: Fix issue by number
argument-hint: [issue-number]
---

Fix issue #$ARGUMENTS following our coding standards and best practices.

Usage:

> /fix-issue 123
> /fix-issue 456

Expands to:

Fix issue #123 following our coding standards...
Fix issue #456 following our coding standards...

Using Positional Arguments

Capture individual arguments with $1, $2, $3, etc.:

---
description: Review PR with priority and assignee
argument-hint: [pr-number] [priority] [assignee]
---

Review pull request #$1 with priority level $2.
After review, assign to $3 for follow-up.

Usage:

> /review-pr 123 high alice

Expands to:

Review pull request #123 with priority level high.
After review, assign to alice for follow-up.

Combining Arguments

Mix positional and remaining arguments:

Deploy $1 to $2 environment with options: $3

Usage:

> /deploy api staging --force --skip-tests

Expands to:

Deploy api to staging environment with options: --force --skip-tests

File References

Using @ Syntax

Include file contents in command:

---
description: Review specific file
argument-hint: [file-path]
---

Review @$1 for:

- Code quality
- Best practices
- Potential bugs

Usage:

> /review-file src/api/users.ts

Effect: Claude reads src/api/users.ts before processing command

Multiple File References

Reference multiple files:

Compare @src/old-version.js with @src/new-version.js

Identify:

- Breaking changes
- New features
- Bug fixes

Static File References

Reference known files without arguments:

Review @package.json and @tsconfig.json for consistency

Ensure:

- TypeScript version matches
- Dependencies are aligned
- Build configuration is correct

Bash Execution in Commands

Commands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.

When to use:

Include dynamic context (git status, environment vars, etc.)
Gather project/repository state
Build context-aware workflows

Implementation details: For complete syntax, examples, and best practices, see references/plugin-features-reference.md section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues

Command Organization

Flat Structure

Simple organization for small command sets:

.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md

Use when: 5-15 commands, no clear categories

Namespaced Structure

Organize commands in subdirectories:

.claude/commands/
├── ci/
│   ├── build.md        # /build (project:ci)
│   ├── test.md         # /test (project:ci)
│   └── lint.md         # /lint (project:ci)
├── git/
│   ├── commit.md       # /commit (project:git)
│   └── pr.md           # /pr (project:git)
└── docs/
    ├── generate.md     # /generate (project:docs)
    └── publish.md      # /publish (project:docs)

Benefits:

Logical grouping by category
Namespace shown in /help
Easier to find related commands

Use when: 15+ commands, clear categories

Best Practices

Command Design

Single responsibility: One command, one task
Clear descriptions: Self-explanatory in /help
Explicit dependencies: Use allowed-tools when needed
Document arguments: Always provide argument-hint
Consistent naming: Use verb-noun pattern (review-pr, fix-issue)

Argument Handling

Validate arguments: Check for required arguments in prompt
Provide defaults: Suggest defaults when arguments missing
Document format: Explain expected argument format
Handle edge cases: Consider missing or invalid arguments

---
argument-hint: [pr-number]
---

$IF($1,
Review PR #$1,
Please provide a PR number. Usage: /review-pr [number]
)

File References

Explicit paths: Use clear file paths
Check existence: Handle missing files gracefully
Relative paths: Use project-relative paths
Glob support: Consider using Glob tool for patterns

Bash Commands

Limit scope: Use Bash(git:*) not Bash(*)
Safe commands: Avoid destructive operations
Handle errors: Consider command failures
Keep fast: Long-running commands slow invocation

Documentation

Add comments: Explain complex logic
Provide examples: Show usage in comments
List requirements: Document dependencies
Version commands: Note breaking changes

---
description: Deploy application to environment
argument-hint: [environment] [version]
---

<!--
Usage: /deploy [staging|production] [version]
Requires: AWS credentials configured
Example: /deploy staging v1.2.3
-->

Deploy application to $1 environment using version $2...

Common Patterns

Review Pattern

---
description: Review code changes
allowed-tools: Read, Bash(git:*)
---

Files changed: !`git diff --name-only`

Review each file for:

1. Code quality and style
2. Potential bugs or issues
3. Test coverage
4. Documentation needs

Provide specific feedback for each file.

Testing Pattern

---
description: Run tests for specific file
argument-hint: [test-file]
allowed-tools: Bash(npm:*)
---

Run tests: !`npm test $1`

Analyze results and suggest fixes for failures.

Documentation Pattern

---
description: Generate documentation for file
argument-hint: [source-file]
---

Generate comprehensive documentation for @$1 including:

- Function/class descriptions
- Parameter documentation
- Return value descriptions
- Usage examples
- Edge cases and errors

Workflow Pattern

---
description: Complete PR workflow
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---

PR #$1 Workflow:

1. Fetch PR: !`gh pr view $1`
2. Review changes
3. Run checks
4. Approve or request changes

Troubleshooting

Command not appearing:

Check file is in correct directory
Verify .md extension present
Ensure valid Markdown format
Restart Claude Code

Arguments not working:

Verify $1, $2 syntax correct
Check argument-hint matches usage
Ensure no extra spaces

Bash execution failing:

Check allowed-tools includes Bash
Verify command syntax in backticks
Test command in terminal first
Check for required permissions

File references not working:

Verify @ syntax correct
Check file path is valid
Ensure Read tool allowed
Use absolute or project-relative paths

Plugin-Specific Features

CLAUDE_PLUGIN_ROOT Variable

Plugin commands have access to ${CLAUDE_PLUGIN_ROOT}, an environment variable that resolves to the plugin's absolute path.

Purpose:

Reference plugin files portably
Execute plugin scripts
Load plugin configuration
Access plugin templates

Basic usage:

---
description: Analyze using plugin script
allowed-tools: Bash(node:*)
---

Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`

Review results and report findings.

Common patterns:

# Execute plugin script

!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`

# Load plugin configuration

@${CLAUDE_PLUGIN_ROOT}/config/settings.json

# Use plugin template

@${CLAUDE_PLUGIN_ROOT}/templates/report.md

# Access plugin resources

@${CLAUDE_PLUGIN_ROOT}/docs/reference.md

Why use it:

Works across all installations
Portable between systems
No hardcoded paths needed
Essential for multi-file plugins

Plugin Command Organization

Plugin commands discovered automatically from commands/ directory:

plugin-name/
├── commands/
│   ├── foo.md              # /foo (plugin:plugin-name)
│   ├── bar.md              # /bar (plugin:plugin-name)
│   └── utils/
│       └── helper.md       # /helper (plugin:plugin-name:utils)
└── plugin.json

Namespace benefits:

Logical command grouping
Shown in /help output
Avoid name conflicts
Organize related commands

Naming conventions:

Use descriptive action names
Avoid generic names (test, run)
Consider plugin-specific prefix
Use hyphens for multi-word names

Plugin Command Patterns

Configuration-based pattern:

---
description: Deploy using plugin configuration
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---

Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json

Deploy to $1 using configuration settings.
Monitor deployment and report status.

Template-based pattern:

---
description: Generate docs from template
argument-hint: [component]
---

Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md

Generate documentation for $1 following template structure.

Multi-script pattern:

---
description: Complete build workflow
allowed-tools: Bash(*)
---

Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`

Review outputs and report workflow status.

See references/plugin-features-reference.md for detailed patterns.

Integration with Plugin Components

Commands can integrate with other plugin components for powerful workflows.

Agent Integration

Launch plugin agents for complex tasks:

---
description: Deep code review
argument-hint: [file-path]
---

Initiate comprehensive review of @$1 using the code-reviewer agent.

The agent will analyze:

- Code structure
- Security issues
- Performance
- Best practices

Agent uses plugin resources:

- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md

Key points:

Agent must exist in plugin/agents/ directory
Claude uses Task tool to launch agent
Document agent capabilities
Reference plugin resources agent uses

Skill Integration

Leverage plugin skills for specialized knowledge:

---
description: Document API with standards
argument-hint: [api-file]
---

Document API in @$1 following plugin standards.

Use the api-docs-standards skill to ensure:

- Complete endpoint documentation
- Consistent formatting
- Example quality
- Error documentation

Generate production-ready API docs.

Key points:

Skill must exist in plugin/skills/ directory
Mention skill name to trigger invocation
Document skill purpose
Explain what skill provides

Hook Coordination

Design commands that work with plugin hooks:

Commands can prepare state for hooks to process
Hooks execute automatically on tool events
Commands should document expected hook behavior
Guide Claude on interpreting hook output

See references/plugin-features-reference.md for examples of commands that coordinate with hooks

Multi-Component Workflows

Combine agents, skills, and scripts:

---
description: Comprehensive review workflow
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

Target: @$1

Phase 1 - Static Analysis:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Phase 2 - Deep Review:
Launch code-reviewer agent for detailed analysis.

Phase 3 - Standards Check:
Use coding-standards skill for validation.

Phase 4 - Report:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md

Compile findings into report following template.

When to use:

Complex multi-step workflows
Leverage multiple plugin capabilities
Require specialized analysis
Need structured outputs

Validation Patterns

Commands should validate inputs and resources before processing.

Argument Validation

---
description: Deploy with validation
argument-hint: [environment]
---

Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`

If $1 is valid environment:
Deploy to $1
Otherwise:
Explain valid environments: dev, staging, prod
Show usage: /deploy [environment]

File Existence Checks

---
description: Process configuration
argument-hint: [config-file]
---

Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`

If file exists:
Process configuration: @$1
Otherwise:
Explain where to place config file
Show expected format
Provide example configuration

Plugin Resource Validation

---
description: Run plugin analyzer
allowed-tools: Bash(test:*)
---

Validate plugin setup:

- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`

If all checks pass, run analysis.
Otherwise, report missing components.

Error Handling

---
description: Build with error handling
allowed-tools: Bash(*)
---

Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"`

If build succeeded:
Report success and output location
If build failed:
Analyze error output
Suggest likely causes
Provide troubleshooting steps

Best practices:

Validate early in command
Provide helpful error messages
Suggest corrective actions
Handle edge cases gracefully

For detailed frontmatter field specifications, see references/frontmatter-reference.md. For plugin-specific features and patterns, see references/plugin-features-reference.md. For command pattern examples, see examples/ directory.

Files

ATTRIBUTION.mdAdded by AutoGineer976 B
LICENSELicence file added by AutoGineer11.1 KiB
README.md7.5 KiB
SKILL.md18.8 KiB
examples/plugin-commands.md13.7 KiB
examples/simple-commands.md8.5 KiB
references/advanced-workflows.md13.3 KiB
references/documentation-patterns.md14.6 KiB
references/frontmatter-reference.md8.9 KiB
references/interactive-commands.md20.5 KiB
references/marketplace-considerations.md16.1 KiB
references/plugin-features-reference.md14.3 KiB
references/testing-strategies.md14.5 KiB

references/marketplace-considerations.md

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:

---
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

<!-- Adjust behavior based on 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:

<!-- BAD: macOS-specific -->
!`pbcopy < file.txt`

<!-- GOOD: Platform detection -->
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:

---
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:

<!--
DEPENDENCIES:
  Required:
  - git 2.0+: Version control
  - jq 1.6+: JSON processing

  Optional:
  - gh: GitHub CLI (for PR operations)
  - docker: Container operations (for containerized tests)

  Feature availability depends on installed tools.
-->

Graceful Degradation

Handle missing features:

---
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:

---
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:

---
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:

---
description: Forgiving command
---

# User Input Handling

Argument: "$1"

<!-- Check for common typos -->
if [ "$1" = "hlep" ] || [ "$1" = "hepl" ]; then
  Did you mean: help?

  Showing help instead...
  [Display help]

  Exit.
fi

<!-- Suggest similar commands if not found -->
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:

---
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:

---
description: Namespaced command
---

<!--
COMMAND NAME: plugin-name-command

This command is namespaced with the plugin name to avoid
conflicts with commands from other plugins.

Alternative naming approaches:
- Use plugin prefix: /plugin-command
- Use category: /category-command
- Use verb-noun: /verb-noun

Chosen approach: plugin-name prefix
Reasoning: Clearest ownership, least likely to conflict
-->

# Plugin Name Command

[Implementation...]

Document naming rationale:

<!--
NAMING DECISION:

Command name: /deploy-app

Alternatives considered:
- /deploy: Too generic, likely conflicts
- /app-deploy: Less intuitive ordering
- /my-plugin-deploy: Too verbose

Final choice balances:
- Discoverability (clear purpose)
- Brevity (easy to type)
- Uniqueness (unlikely conflicts)
-->

Configurability

User preferences:

---
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:

---
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:

---
description: Version-aware command
---

<!--
COMMAND VERSION: 2.1.0

COMPATIBILITY:
- Requires plugin version: >= 2.0.0
- Breaking changes from v1.x documented in MIGRATION.md

VERSION HISTORY:
- v2.1.0: Added --new-feature flag
- v2.0.0: BREAKING: Changed argument order
- v1.0.0: Initial release
-->

# 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:

---
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:

---
description: Review pull request with security and quality checks
---

<!-- GOOD: Descriptive name and description -->

---
description: Do the thing
---

<!-- BAD: Vague description -->

Searchable keywords:

<!--
KEYWORDS: security, code-review, quality, validation, audit

These keywords help users discover this command when searching
for related functionality in the marketplace.
-->

Showcase Examples

Compelling demonstrations:

---
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:

---
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:

<!--
ANALYTICS NOTES:

Track for improvement:
- Most common arguments
- Failure rates
- Average execution time
- User satisfaction scores

Privacy-preserving:
- No personally identifiable information
- Aggregate statistics only
- User opt-out respected
-->

Quality Standards

Professional Polish

Consistent branding:

---
description: Branded command
---

# ✨ Command Name

Part of the [Plugin Name] suite

[Command functionality...]

---

**Need Help?**
- Documentation: https://docs.example.com
- Support: [email protected]
- Community: https://community.example.com

Powered by Plugin Name v2.1.0

Attention to detail:

<!-- Details that matter -->

✓ 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:

---
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:

---
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

<!--
PRE-RELEASE CHECKLIST:

Functionality:
- [ ] Works on macOS
- [ ] Works on Linux
- [ ] Works on Windows (WSL)
- [ ] All arguments tested
- [ ] Error cases handled
- [ ] Edge cases covered

User Experience:
- [ ] Clear description
- [ ] Helpful error messages
- [ ] Examples provided
- [ ] First-run experience good
- [ ] Documentation complete

Distribution:
- [ ] No hardcoded paths
- [ ] Dependencies documented
- [ ] Configuration options clear
- [ ] Version number set
- [ ] Changelog updated

Quality:
- [ ] No TODO comments
- [ ] No debug code
- [ ] Performance acceptable
- [ ] Security reviewed
- [ ] Privacy considered

Support:
- [ ] README complete
- [ ] Troubleshooting guide
- [ ] Support contact provided
- [ ] Feedback mechanism
- [ ] License specified
-->

Beta Testing

Beta release approach:

---
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:

<!--
VERSION STRATEGY:

Major (X.0.0): Breaking changes
- Document all breaking changes
- Provide migration guide
- Support old version briefly

Minor (x.Y.0): New features
- Backward compatible
- Announce new features
- Update examples

Patch (x.y.Z): Bug fixes
- No user-facing changes
- Update changelog
- Security fixes prioritized

Release schedule:
- Patches: As needed
- Minors: Monthly
- Majors: Annually or as needed
-->

Update notifications:

---
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

Universal: Works across platforms and environments
Self-contained: Minimal dependencies, clear requirements
Graceful: Degrades gracefully when features unavailable
Forgiving: Anticipates and handles user mistakes
Helpful: Clear errors, good defaults, excellent docs

Marketplace Success

Discoverable: Clear name, good description, searchable keywords
Professional: Polished presentation, consistent branding
Reliable: Tested thoroughly, handles edge cases
Maintainable: Versioned, updated regularly, supported
User-focused: Great UX, responsive to feedback

Quality Standards

Complete: Fully documented, all features working
Tested: Works in real environments, edge cases handled
Secure: No vulnerabilities, safe operations
Performant: Reasonable speed, resource-efficient
Ethical: Privacy-respecting, user consent

With these considerations, commands become marketplace-ready and delight users across diverse environments and use cases.

Requirements and compatibility

Written for: Claude Code, Claude apps

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Names Claude Code tools, Needs Node.js