gh-bradleyboehmke-brads-marketplace-marketplace-dev/skills/marketplace-command-patterns.md

title, description, tags

title	description	tags
Marketplace Command Patterns	Standard parameter patterns and output formatting for all marketplace commands	commands parameters output user-interface

Marketplace Command Patterns

Metadata

Purpose: Define standard command patterns for consistent user experience across marketplace Applies to: All user-facing commands in marketplace plugins Version: 1.0.0

---

Instructions

Standard Output Parameters

All user-facing commands in marketplace support:

Format Parameter:

• --format=console (default) - Display results in IDE/console
• --format=markdown - Generate markdown report file

Output Parameter:

• --output=<path> - Specify custom report file path
  • Only valid when --format=markdown
  • If not specified, uses default report path

Default Report Paths:

• Pattern: ./reports/{command-name}-report.md
• Example: ./reports/validate-docs-report.md

Parameter Documentation Template

Include this section in every command file:

## Command Parameters

This command supports the following optional parameters:

**Format Parameter:**
- `--format=console` (default) - Display results in IDE/console
- `--format=markdown` - Generate markdown report file

**Output Parameter:**
- `--output=<path>` - Specify custom report file path
  - Default: `./reports/{command-name}-report.md`
  - Only used with `--format=markdown`

**Usage Examples:**
\```bash
/{plugin-name}:{command-name}                                    # Console output
/{plugin-name}:{command-name} --format=markdown                  # Report in ./reports/
/{plugin-name}:{command-name} --format=markdown --output=./docs/report.md
\```

Output Mode Implementation

When --format=console (default):

1. Display results directly in console/IDE
2. Use clear formatting for readability
3. Include summary statistics if applicable
4. Provide actionable recommendations

When --format=markdown:

1. Check if user specified --output parameter
   • If yes, use that path
   • If no, use default: ./reports/{command-name}-report.md
2. Create report directory if it doesn't exist
3. Generate properly formatted markdown file with:
   • Metadata header (timestamp, project path, command used)
   • Executive summary
   • Detailed findings
   • Recommendations
   • Appendices (if applicable)
4. After saving:
   • Display confirmation with file path
   • Show brief summary in console

Report File Structure

All markdown reports should follow this structure:

# {Command Name} Report

**Generated**: {timestamp}
**Project**: {project-path}
**Command**: `/{plugin}:{command} {parameters}`

---

## Executive Summary

[High-level overview of findings, 2-3 sentences]

**Key Metrics**:
- Metric 1: Value
- Metric 2: Value

---

## Findings

### {Category 1}
[Detailed findings for category 1]

### {Category 2}
[Detailed findings for category 2]

---

## Recommendations

**High Priority**:
1. [Recommendation 1]
2. [Recommendation 2]

**Medium Priority**:
1. [Recommendation 3]

**Low Priority**:
1. [Recommendation 4]

---

## Appendices

### {Additional Details}
[Supporting information, raw data, etc.]

Parameter Parsing Pattern

When implementing parameter handling in commands:

## Parameter Detection

1. Check for `--format` parameter:
   - If `--format=markdown`, set output_mode to "markdown"
   - Otherwise, set output_mode to "console" (default)

2. Check for `--output` parameter (only if format=markdown):
   - If specified, use that path for report file
   - If not specified, use default: `./reports/{command-name}-report.md`
   - If format=console, ignore --output parameter

3. Validate parameters:
   - Warn if `--output` used without `--format=markdown`
   - Validate output path is writable

Console Output Best Practices

Structure:

• Clear section headings
• Use tables for metrics/scores
• Use lists for findings/recommendations
• Use visual separators (---, ===)

Tone:

• Actionable and specific
• Avoid jargon where possible
• Provide context for recommendations

Length:

• Concise but complete
• Long details can go in markdown report

Markdown Report Best Practices

File Management:

• Always create parent directories if missing
• Use consistent naming patterns
• Timestamp reports for versioning
• Overwrite existing report with same name (don't append)

Formatting:

• Use proper markdown hierarchy (# ## ###)
• Include code blocks with language specifiers
• Use tables for structured data
• Use blockquotes for important notes

Content:

• Self-contained (don't assume reader has console output)
• Include full context (project, command, timestamp)
• Provide actionable recommendations
• Link to relevant documentation/resources

---

Resources

Complete Command Implementation Example

---
description: Validate documentation standards compliance
---

# Validate Documentation Command

You are a documentation standards validator for Personal.

## Command Parameters

This command supports the following optional parameters:

**Format Parameter:**
- `--format=console` (default) - Display results in IDE/console
- `--format=markdown` - Generate markdown report file

**Output Parameter:**
- `--output=<path>` - Specify custom report file path
  - Default: `./reports/validate-docs-report.md`
  - Only used with `--format=markdown`

**Usage Examples:**
\```bash
/validator:validate-docs                                    # Console output
/validator:validate-docs --format=markdown                  # Report in ./reports/
/validator:validate-docs --format=markdown --output=./docs/validation.md
\```

## Output Mode Instructions

### Step 1: Detect Output Mode

Parse command parameters to determine output mode:
- Check for `--format` parameter
- Check for `--output` parameter (if format=markdown)
- Set output_mode variable accordingly

### Step 2: Perform Analysis

[Execute validation logic here]

### Step 3: Format Output

**If output_mode is "console":**
1. Display results directly in console
2. Show summary, findings, recommendations
3. Use clear formatting for readability

**If output_mode is "markdown":**
1. Determine output path:
   - Use `--output` value if provided
   - Otherwise use `./reports/validate-docs-report.md`
2. Create report directory: `mkdir -p reports`
3. Generate markdown report with proper structure
4. Save to file using Write tool
5. Confirm to user: "Report saved to {path}"
6. Show brief summary in console

## Validation Process

1. Activate skill: `documentation-standards`
2. Scan repository for documentation files
3. Assess against standards
4. Calculate scores
5. Generate recommendations
6. Format output based on output_mode

## Output Format

[Specific format for this command's findings]

Parameter Handling Code Pattern

When writing command instructions, include this pattern:

## Parameter Handling

**Step 1: Parse parameters from user command**

Extract parameters from the command invocation:
- `--format=console` or `--format=markdown`
- `--output=<path>` (optional, only with markdown format)

**Step 2: Set defaults**

If no parameters specified:
- `output_mode = "console"`
- `output_path = null`

If `--format=markdown` but no `--output`:
- `output_path = "./reports/{command-name}-report.md"`

**Step 3: Validate**

- If `--output` specified without `--format=markdown`, warn user and ignore
- Ensure output path is valid (if specified)

**Step 4: Execute command**

Proceed with command logic, keeping output_mode in mind

**Step 5: Generate output**

Format results according to output_mode (console or markdown)