Add opsera-devsecops to marketplace

Moved to external-plugins-staging branch for separate review.

.github/scripts/check-marketplace-sorted.ts

@@ -1,42 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Checks that marketplace.json plugins are alphabetically sorted by name.
- *
- * Usage:
- *   bun check-marketplace-sorted.ts           # check, exit 1 if unsorted
- *   bun check-marketplace-sorted.ts --fix     # sort in place
- */
-
-import { readFileSync, writeFileSync } from "fs";
-import { join } from "path";
-
-const MARKETPLACE = join(import.meta.dir, "../../.claude-plugin/marketplace.json");
-
-type Plugin = { name: string; [k: string]: unknown };
-type Marketplace = { plugins: Plugin[]; [k: string]: unknown };
-
-const raw = readFileSync(MARKETPLACE, "utf8");
-const mp: Marketplace = JSON.parse(raw);
-
-const cmp = (a: Plugin, b: Plugin) =>
-  a.name.toLowerCase().localeCompare(b.name.toLowerCase());
-
-if (process.argv.includes("--fix")) {
-  mp.plugins.sort(cmp);
-  writeFileSync(MARKETPLACE, JSON.stringify(mp, null, 2) + "\n");
-  console.log(`sorted ${mp.plugins.length} plugins`);
-  process.exit(0);
-}
-
-for (let i = 1; i < mp.plugins.length; i++) {
-  if (cmp(mp.plugins[i - 1], mp.plugins[i]) > 0) {
-    console.error(
-      `marketplace.json plugins are not sorted: ` +
-        `'${mp.plugins[i - 1].name}' should come after '${mp.plugins[i].name}' (index ${i})`,
-    );
-    console.error(`  run: bun .github/scripts/check-marketplace-sorted.ts --fix`);
-    process.exit(1);
-  }
-}
-
-console.log(`ok: ${mp.plugins.length} plugins sorted`);

.github/scripts/validate-marketplace.ts

@@ -1,77 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Validates marketplace.json: well-formed JSON, plugins array present,
- * each entry has required fields, and no duplicate plugin names.
- *
- * Usage:
- *   bun validate-marketplace.ts <path-to-marketplace.json>
- */
-
-import { readFile } from "fs/promises";
-
-async function main() {
-  const filePath = process.argv[2];
-  if (!filePath) {
-    console.error("Usage: validate-marketplace.ts <path-to-marketplace.json>");
-    process.exit(2);
-  }
-
-  const content = await readFile(filePath, "utf-8");
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(content);
-  } catch (err) {
-    console.error(
-      `ERROR: ${filePath} is not valid JSON: ${err instanceof Error ? err.message : err}`
-    );
-    process.exit(1);
-  }
-
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    console.error(`ERROR: ${filePath} must be a JSON object`);
-    process.exit(1);
-  }
-
-  const marketplace = parsed as Record<string, unknown>;
-  if (!Array.isArray(marketplace.plugins)) {
-    console.error(`ERROR: ${filePath} missing "plugins" array`);
-    process.exit(1);
-  }
-
-  const errors: string[] = [];
-  const seen = new Set<string>();
-  const required = ["name", "description", "source"] as const;
-
-  marketplace.plugins.forEach((p, i) => {
-    if (!p || typeof p !== "object") {
-      errors.push(`plugins[${i}]: must be an object`);
-      return;
-    }
-    const entry = p as Record<string, unknown>;
-    for (const field of required) {
-      if (!entry[field]) {
-        errors.push(`plugins[${i}] (${entry.name ?? "?"}): missing required field "${field}"`);
-      }
-    }
-    if (typeof entry.name === "string") {
-      if (seen.has(entry.name)) {
-        errors.push(`plugins[${i}]: duplicate plugin name "${entry.name}"`);
-      }
-      seen.add(entry.name);
-    }
-  });
-
-  if (errors.length) {
-    console.error(`ERROR: ${filePath} has ${errors.length} validation error(s):`);
-    for (const e of errors) console.error(`  - ${e}`);
-    process.exit(1);
-  }
-
-  console.log(`OK: ${marketplace.plugins.length} plugins, no duplicates, all required fields present`);
-}
-
-main().catch((err) => {
-  console.error("Fatal error:", err);
-  process.exit(2);
-});

.github/workflows/validate-marketplace.yml

@@ -1,20 +0,0 @@
-name: Validate Marketplace JSON
-
-on:
-  pull_request:
-    paths:
-      - '.claude-plugin/marketplace.json'
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: oven-sh/setup-bun@v2
-
-      - name: Validate marketplace.json
-        run: bun .github/scripts/validate-marketplace.ts .claude-plugin/marketplace.json
-
-      - name: Check plugins sorted
-        run: bun .github/scripts/check-marketplace-sorted.ts

plugins/example-plugin/README.md

@@ -9,22 +9,30 @@ example-plugin/
 ├── .claude-plugin/
 │   └── plugin.json        # Plugin metadata
 ├── .mcp.json              # MCP server configuration
-├── skills/
-│   ├── example-skill/
-│   │   └── SKILL.md           # Model-invoked skill (contextual guidance)
-│   └── example-command/
-│       └── SKILL.md           # User-invoked skill (slash command)
-└── commands/
-    └── example-command.md     # Legacy slash command format (see note below)
+├── commands/
+│   └── example-command.md # Slash command definition
+└── skills/
+    └── example-skill/
+        └── SKILL.md       # Skill definition
 ```
 
 ## Extension Options
 
+### Commands (`commands/`)
+
+Slash commands are user-invoked via `/command-name`. Define them as markdown files with frontmatter:
+
+```yaml
+---
+description: Short description for /help
+argument-hint: <arg1> [optional-arg]
+allowed-tools: [Read, Glob, Grep]
+---
+```
+
 ### Skills (`skills/`)
 
-Skills are the preferred format for both model-invoked capabilities and user-invoked slash commands. Create a `SKILL.md` in a subdirectory:
-
-**Model-invoked skill** (activated by task context):
+Skills are model-invoked capabilities. Create a `SKILL.md` in a subdirectory:
 
 ```yaml
 ---
@@ -34,21 +42,6 @@ version: 1.0.0
 ---
 ```
 
-**User-invoked skill** (slash command — `/skill-name`):
-
-```yaml
----
-name: skill-name
-description: Short description for /help
-argument-hint: <arg1> [optional-arg]
-allowed-tools: [Read, Glob, Grep]
----
-```
-
-### Commands (`commands/`) — legacy
-
-> **Note:** The `commands/*.md` layout is a legacy format. It is loaded identically to `skills/<name>/SKILL.md` — the only difference is file layout. For new plugins, prefer the `skills/` directory format. This plugin keeps `commands/example-command.md` as a reference for the legacy layout.
-
 ### MCP Servers (`.mcp.json`)
 
 Configure external tool integration via Model Context Protocol:

plugins/example-plugin/commands/example-command.md

@@ -1,12 +1,10 @@
 ---
-description: An example slash command that demonstrates command frontmatter options (legacy format)
+description: An example slash command that demonstrates command frontmatter options
 argument-hint: <required-arg> [optional-arg]
 allowed-tools: [Read, Glob, Grep, Bash]
 ---
 
-# Example Command (Legacy `commands/` Format)
-
-> **Note:** This demonstrates the legacy `commands/*.md` layout. For new plugins, prefer the `skills/<name>/SKILL.md` directory format (see `skills/example-command/SKILL.md` in this plugin). Both are loaded identically — the only difference is file layout.
+# Example Command
 
 This command demonstrates slash command structure and frontmatter options.
 

plugins/example-plugin/skills/example-command/SKILL.md

@@ -1,39 +0,0 @@
----
-name: example-command
-description: An example user-invoked skill that demonstrates frontmatter options and the skills/<name>/SKILL.md layout
-argument-hint: <required-arg> [optional-arg]
-allowed-tools: [Read, Glob, Grep, Bash]
----
-
-# Example Command (Skill Format)
-
-This demonstrates the `skills/<name>/SKILL.md` layout for user-invoked slash commands. It is functionally identical to the legacy `commands/example-command.md` format — both are loaded the same way; only the file layout differs.
-
-## Arguments
-
-The user invoked this with: $ARGUMENTS
-
-## Instructions
-
-When this skill is invoked:
-
-1. Parse the arguments provided by the user
-2. Perform the requested action using allowed tools
-3. Report results back to the user
-
-## Frontmatter Options Reference
-
-Skills in this layout support these frontmatter fields:
-
-- **name**: Skill identifier (matches directory name)
-- **description**: Short description shown in /help
-- **argument-hint**: Hints for command arguments shown to user
-- **allowed-tools**: Pre-approved tools for this skill (reduces permission prompts)
-- **model**: Override the model (e.g., "haiku", "sonnet", "opus")
-
-## Example Usage
-
-```
-/example-command my-argument
-/example-command arg1 arg2
-```

plugins/plugin-dev/commands/create-plugin.md

@@ -1,18 +1,7 @@
 ---
 description: Guided end-to-end plugin creation workflow with component design, implementation, and validation
 argument-hint: Optional plugin description
-allowed-tools:
-  [
-    "Read",
-    "Write",
-    "Grep",
-    "Glob",
-    "Bash",
-    "TodoWrite",
-    "AskUserQuestion",
-    "Skill",
-    "Task",
-  ]
+allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash", "TodoWrite", "AskUserQuestion", "Skill", "Task"]
 ---
 
 # Plugin Creation Workflow
@@ -37,7 +26,6 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **Goal**: Understand what plugin needs to be built and what problem it solves
 
 **Actions**:
-
 1. Create todo list with all 7 phases
 2. If plugin purpose is clear from arguments:
    - Summarize understanding
@@ -60,17 +48,14 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **MUST load plugin-structure skill** using Skill tool before this phase.
 
 **Actions**:
-
 1. Load plugin-structure skill to understand component types
 2. Analyze plugin requirements and determine needed components:
-   - **Skills**: Specialized knowledge OR user-initiated actions (deploy, configure, analyze). Skills are the preferred format for both — see note below.
+   - **Skills**: Does it need specialized knowledge? (hooks API, MCP patterns, etc.)
+   - **Commands**: User-initiated actions? (deploy, configure, analyze)
    - **Agents**: Autonomous tasks? (validation, generation, analysis)
    - **Hooks**: Event-driven automation? (validation, notifications)
    - **MCP**: External service integration? (databases, APIs)
    - **Settings**: User configuration? (.local.md files)
-
-   > **Note:** The `commands/` directory is a legacy format. For new plugins, user-invoked slash commands should be created as skills in `skills/<name>/SKILL.md`. Both are loaded identically — the only difference is file layout. `commands/` remains an acceptable legacy alternative.
-
 3. For each component type needed, identify:
    - How many of each type
    - What each one does
@@ -79,7 +64,8 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
    ```
    | Component Type | Count | Purpose |
    |----------------|-------|---------|
-   | Skills         | 5     | Hook patterns, MCP usage, deploy, configure, validate |
+   | Skills         | 2     | Hook patterns, MCP usage |
+   | Commands       | 3     | Deploy, configure, validate |
    | Agents         | 1     | Autonomous validation |
    | Hooks          | 0     | Not needed |
    | MCP            | 1     | Database integration |
@@ -97,9 +83,9 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **CRITICAL**: This is one of the most important phases. DO NOT SKIP.
 
 **Actions**:
-
 1. For each component in the plan, identify underspecified aspects:
-   - **Skills**: What triggers them? What knowledge do they provide? How detailed? For user-invoked skills: what arguments, what tools, interactive or automated?
+   - **Skills**: What triggers them? What knowledge do they provide? How detailed?
+   - **Commands**: What arguments? What tools? Interactive or automated?
    - **Agents**: When to trigger (proactive/reactive)? What tools? Output format?
    - **Hooks**: Which events? Prompt or command based? Validation criteria?
    - **MCP**: What server type? Authentication? Which tools?
@@ -112,14 +98,12 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 4. If user says "whatever you think is best", provide specific recommendations and get explicit confirmation
 
 **Example questions for a skill**:
-
 - What specific user queries should trigger this skill?
 - Should it include utility scripts? What functionality?
 - How detailed should the core SKILL.md be vs references/?
 - Any real-world examples to include?
 
 **Example questions for an agent**:
-
 - Should this agent trigger proactively after certain actions, or only when explicitly requested?
 - What tools does it need (Read, Write, Bash, etc.)?
 - What should the output format be?
@@ -134,7 +118,6 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **Goal**: Create plugin directory structure and manifest
 
 **Actions**:
-
 1. Determine plugin name (kebab-case, descriptive)
 2. Choose plugin location:
    - Ask user: "Where should I create the plugin?"
@@ -142,10 +125,10 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 3. Create directory structure using bash:
    ```bash
    mkdir -p plugin-name/.claude-plugin
-   mkdir -p plugin-name/skills/<skill-name>   # one dir per skill, each with a SKILL.md
+   mkdir -p plugin-name/skills     # if needed
+   mkdir -p plugin-name/commands   # if needed
    mkdir -p plugin-name/agents     # if needed
    mkdir -p plugin-name/hooks      # if needed
-   # Note: plugin-name/commands/ is a legacy alternative to skills/ — prefer skills/
    ```
 4. Create plugin.json manifest using Write tool:
    ```json
@@ -160,7 +143,7 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
    }
    ```
 5. Create README.md template
-6. Create .gitignore if needed (for .claude/\*.local.md, etc.)
+6. Create .gitignore if needed (for .claude/*.local.md, etc.)
 7. Initialize git repo if creating new directory
 
 **Output**: Plugin directory structure created and ready for components
@@ -172,9 +155,8 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **Goal**: Create each component following best practices
 
 **LOAD RELEVANT SKILLS** before implementing each component type:
-
 - Skills: Load skill-development skill
-- Legacy `commands/` format (only if user explicitly requests): Load command-development skill
+- Commands: Load command-development skill
 - Agents: Load agent-development skill
 - Hooks: Load hook-development skill
 - MCP: Load mcp-integration skill
@@ -183,26 +165,21 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **Actions for each component**:
 
 ### For Skills:
-
 1. Load skill-development skill using Skill tool
 2. For each skill:
    - Ask user for concrete usage examples (or use from Phase 3)
    - Plan resources (scripts/, references/, examples/)
-   - Create skill directory: `skills/<skill-name>/`
-   - Write `SKILL.md` with:
+   - Create skill directory structure
+   - Write SKILL.md with:
      - Third-person description with specific trigger phrases
      - Lean body (1,500-2,000 words) in imperative form
      - References to supporting files
-   - For user-invoked skills (slash commands): include `description`, `argument-hint`, and `allowed-tools` frontmatter; write instructions FOR Claude (not TO user)
    - Create reference files for detailed content
    - Create example files for working code
    - Create utility scripts if needed
 3. Use skill-reviewer agent to validate each skill
 
-### For legacy `commands/` format (only if user explicitly requests):
-
-> Prefer `skills/<name>/SKILL.md` for new plugins. Use `commands/` only when maintaining an existing plugin that already uses this layout.
-
+### For Commands:
 1. Load command-development skill using Skill tool
 2. For each command:
    - Write command markdown with frontmatter
@@ -213,7 +190,6 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
    - Reference relevant skills if applicable
 
 ### For Agents:
-
 1. Load agent-development skill using Skill tool
 2. For each agent, use agent-creator agent:
    - Provide description of what agent should do
@@ -223,7 +199,6 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
    - Validate with validate-agent.sh script
 
 ### For Hooks:
-
 1. Load hook-development skill using Skill tool
 2. For each hook:
    - Create hooks/hooks.json with hook configuration
@@ -233,7 +208,6 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
    - Test with validate-hook-schema.sh and test-hook.sh utilities
 
 ### For MCP:
-
 1. Load mcp-integration skill using Skill tool
 2. Create .mcp.json configuration with:
    - Server type (stdio for local, SSE for hosted)
@@ -244,7 +218,6 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 4. Provide setup instructions
 
 ### For Settings:
-
 1. Load plugin-settings skill using Skill tool
 2. Create settings template in README
 3. Create example .claude/plugin-name.local.md file (as documentation)
@@ -262,7 +235,6 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **Goal**: Ensure plugin meets quality standards and works correctly
 
 **Actions**:
-
 1. **Run plugin-validator agent**:
    - Use plugin-validator agent to comprehensively validate plugin
    - Check: manifest, structure, naming, components, security
@@ -303,7 +275,6 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **Goal**: Test that plugin works correctly in Claude Code
 
 **Actions**:
-
 1. **Installation instructions**:
    - Show user how to test locally:
      ```bash
@@ -313,7 +284,7 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 
 2. **Verification checklist** for user to perform:
    - [ ] Skills load when triggered (ask questions with trigger phrases)
-   - [ ] User-invoked skills appear in `/help` and execute correctly
+   - [ ] Commands appear in `/help` and execute correctly
    - [ ] Agents trigger on appropriate scenarios
    - [ ] Hooks activate on events (if applicable)
    - [ ] MCP servers connect (if applicable)
@@ -321,7 +292,7 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 
 3. **Testing recommendations**:
    - For skills: Ask questions using trigger phrases from descriptions
-   - For user-invoked skills: Run `/plugin-name:skill-name` with various arguments
+   - For commands: Run `/plugin-name:command-name` with various arguments
    - For agents: Create scenarios matching agent examples
    - For hooks: Use `claude --debug` to see hook execution
    - For MCP: Use `/mcp` to verify servers and tools
@@ -339,7 +310,6 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **Goal**: Ensure plugin is well-documented and ready for distribution
 
 **Actions**:
-
 1. **Verify README completeness**:
    - Check README has: overview, features, installation, prerequisites, usage
    - For MCP plugins: Document required environment variables
@@ -355,7 +325,7 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
    - Mark all todos complete
    - List what was created:
      - Plugin name and purpose
-     - Components created (X skills, Y agents, etc.)
+     - Components created (X skills, Y commands, Z agents, etc.)
      - Key files and their purposes
      - Total file count and structure
    - Next steps:
@@ -384,7 +354,7 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 - **Apply best practices**:
   - Third-person descriptions for skills
   - Imperative form in skill bodies
-  - Skill instructions written FOR Claude (not TO user)
+  - Commands written FOR Claude
   - Strong trigger phrases
   - ${CLAUDE_PLUGIN_ROOT} for portability
   - Progressive disclosure
@@ -401,13 +371,12 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 ### Skills to Load by Phase
 
 - **Phase 2**: plugin-structure
-- **Phase 5**: skill-development, agent-development, hook-development, mcp-integration, plugin-settings (as needed); command-development only for legacy `commands/` layout
+- **Phase 5**: skill-development, command-development, agent-development, hook-development, mcp-integration, plugin-settings (as needed)
 - **Phase 6**: (agents will use skills automatically)
 
 ### Quality Standards
 
 Every component must meet these standards:
-
 - ✅ Follows plugin-dev's proven patterns
 - ✅ Uses correct naming conventions
 - ✅ Has strong trigger conditions (skills/agents)
@@ -421,22 +390,19 @@ Every component must meet these standards:
 ## Example Workflow
 
 ### User Request
-
 "Create a plugin for managing database migrations"
 
 ### Phase 1: Discovery
-
 - Understand: Migration management, database schema versioning
 - Confirm: User wants to create, run, rollback migrations
 
 ### Phase 2: Component Planning
-
-- Skills: 4 (migration best practices, create-migration, run-migrations, rollback)
+- Skills: 1 (migration best practices)
+- Commands: 3 (create-migration, run-migrations, rollback)
 - Agents: 1 (migration-validator)
 - MCP: 1 (database connection)
 
 ### Phase 3: Clarifying Questions
-
 - Which databases? (PostgreSQL, MySQL, etc.)
 - Migration file format? (SQL, code-based?)
 - Should agent validate before applying?

plugins/plugin-dev/skills/command-development/SKILL.md

@@ -6,14 +6,11 @@ version: 0.2.0
 
 # 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
@@ -25,7 +22,6 @@ Slash commands are frequently-used prompts defined as Markdown files that Claude
 ### 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
@@ -38,10 +34,8 @@ A slash command is a Markdown file containing a prompt that Claude executes when
 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):**
-
 ```markdown
 Review this code for security vulnerabilities including:
-
 - SQL injection
 - XSS attacks
 - Authentication issues
@@ -50,7 +44,6 @@ Provide specific line numbers and severity ratings.
 ```
 
 **Incorrect approach (messages to user):**
-
 ```markdown
 This command will review your code for security issues.
 You'll receive a report with vulnerability details.
@@ -61,21 +54,18 @@ The first example tells Claude what to do. The second tells the user what will h
 ### 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`
@@ -95,10 +85,8 @@ Commands are Markdown files with `.md` extension:
 ```
 
 **Simple command:**
-
 ```markdown
 Review this code for security vulnerabilities including:
-
 - SQL injection
 - XSS attacks
 - Authentication bypass
@@ -150,7 +138,6 @@ allowed-tools: Read, Write, Edit, Bash(git:*)
 ```
 
 **Patterns:**
-
 - `Read, Write, Edit` - Specific tools
 - `Bash(git:*)` - Bash with git commands only
 - `*` - All tools (rarely needed)
@@ -170,7 +157,6 @@ model: haiku
 ```
 
 **Use cases:**
-
 - `haiku` - Fast, simple commands
 - `sonnet` - Standard workflows
 - `opus` - Complex analysis
@@ -188,7 +174,6 @@ argument-hint: [pr-number] [priority] [assignee]
 ```
 
 **Benefits:**
-
 - Helps users understand command arguments
 - Improves command discovery
 - Documents command interface
@@ -223,14 +208,12 @@ 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...
@@ -251,13 +234,11 @@ 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.
@@ -272,13 +253,11 @@ 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
 ```
@@ -296,14 +275,12 @@ argument-hint: [file-path]
 ---
 
 Review @$1 for:
-
 - Code quality
 - Best practices
 - Potential bugs
 ```
 
 **Usage:**
-
 ```
 > /review-file src/api/users.ts
 ```
@@ -318,7 +295,6 @@ Reference multiple files:
 Compare @src/old-version.js with @src/new-version.js
 
 Identify:
-
 - Breaking changes
 - New features
 - Bug fixes
@@ -332,7 +308,6 @@ Reference known files without arguments:
 Review @package.json and @tsconfig.json for consistency
 
 Ensure:
-
 - TypeScript version matches
 - Dependencies are aligned
 - Build configuration is correct
@@ -343,7 +318,6 @@ Ensure:
 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
@@ -387,7 +361,6 @@ Organize commands in subdirectories:
 ```
 
 **Benefits:**
-
 - Logical grouping by category
 - Namespace shown in `/help`
 - Easier to find related commands
@@ -417,8 +390,8 @@ argument-hint: [pr-number]
 ---
 
 $IF($1,
-Review PR #$1,
-Please provide a PR number. Usage: /review-pr [number]
+  Review PR #$1,
+  Please provide a PR number. Usage: /review-pr [number]
 )
 ```
 
@@ -471,7 +444,6 @@ 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
@@ -503,7 +475,6 @@ argument-hint: [source-file]
 ---
 
 Generate comprehensive documentation for @$1 including:
-
 - Function/class descriptions
 - Parameter documentation
 - Return value descriptions
@@ -531,27 +502,23 @@ PR #$1 Workflow:
 ## 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
@@ -564,7 +531,6 @@ PR #$1 Workflow:
 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
@@ -587,24 +553,19 @@ Review results and report findings.
 
 ```markdown
 # 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
@@ -625,14 +586,12 @@ plugin-name/
 ```
 
 **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
@@ -702,20 +661,17 @@ 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
@@ -734,7 +690,6 @@ 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
@@ -744,7 +699,6 @@ Generate production-ready API docs.
 ```
 
 **Key points:**
-
 - Skill must exist in `plugin/skills/` directory
 - Mention skill name to trigger invocation
 - Document skill purpose
@@ -753,7 +707,6 @@ Generate production-ready API docs.
 ### 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
@@ -790,7 +743,6 @@ Compile findings into report following template.
 ```
 
 **When to use:**
-
 - Complex multi-step workflows
 - Leverage multiple plugin capabilities
 - Require specialized analysis
@@ -811,10 +763,10 @@ argument-hint: [environment]
 Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`
 
 If $1 is valid environment:
-Deploy to $1
+  Deploy to $1
 Otherwise:
-Explain valid environments: dev, staging, prod
-Show usage: /deploy [environment]
+  Explain valid environments: dev, staging, prod
+  Show usage: /deploy [environment]
 ```
 
 ### File Existence Checks
@@ -828,11 +780,11 @@ argument-hint: [config-file]
 Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`
 
 If file exists:
-Process configuration: @$1
+  Process configuration: @$1
 Otherwise:
-Explain where to place config file
-Show expected format
-Provide example configuration
+  Explain where to place config file
+  Show expected format
+  Provide example configuration
 ```
 
 ### Plugin Resource Validation
@@ -844,7 +796,6 @@ 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 "✗"`
 
@@ -863,15 +814,14 @@ 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
+  Report success and output location
 If build failed:
-Analyze error output
-Suggest likely causes
-Provide troubleshooting steps
+  Analyze error output
+  Suggest likely causes
+  Provide troubleshooting steps
 ```
 
 **Best practices:**
-
 - Validate early in command
 - Provide helpful error messages
 - Suggest corrective actions