Merge main into staging

plugins/example-plugin/README.md

@@ -7,41 +7,48 @@ A comprehensive example plugin demonstrating Claude Code extension options.
 ```
 example-plugin/
 ├── .claude-plugin/
-│   └── plugin.json        # Plugin metadata
-├── .mcp.json              # MCP server configuration
-├── commands/
-│   └── example-command.md # Slash command definition
-└── skills/
-    └── example-skill/
-        └── SKILL.md       # Skill definition
+│   └── 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)
 ```
 
 ## Extension Options
 
-### Commands (`commands/`)
+### Skills (`skills/`)
+
+Skills are the preferred format for both model-invoked capabilities and user-invoked slash commands. Create a `SKILL.md` in a subdirectory:
 
-Slash commands are user-invoked via `/command-name`. Define them as markdown files with frontmatter:
+**Model-invoked skill** (activated by task context):
 
 ```yaml
 ---
-description: Short description for /help
-argument-hint: <arg1> [optional-arg]
-allowed-tools: [Read, Glob, Grep]
+name: skill-name
+description: Trigger conditions for this skill
+version: 1.0.0
 ---
 ```
 
-### Skills (`skills/`)
-
-Skills are model-invoked capabilities. Create a `SKILL.md` in a subdirectory:
+**User-invoked skill** (slash command — `/skill-name`):
 
 ```yaml
 ---
 name: skill-name
-description: Trigger conditions for this skill
-version: 1.0.0
+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,10 +1,12 @@
 ---
-description: An example slash command that demonstrates command frontmatter options
+description: An example slash command that demonstrates command frontmatter options (legacy format)
 argument-hint: <required-arg> [optional-arg]
 allowed-tools: [Read, Glob, Grep, Bash]
 ---
 
-# Example Command
+# 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.
 
 This command demonstrates slash command structure and frontmatter options.
 

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

@@ -0,0 +1,39 @@
+---
+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,7 +1,18 @@
 ---
 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
@@ -26,6 +37,7 @@ 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
@@ -48,14 +60,17 @@ 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**: Does it need specialized knowledge? (hooks API, MCP patterns, etc.)
-   - **Commands**: User-initiated actions? (deploy, configure, analyze)
+   - **Skills**: Specialized knowledge OR user-initiated actions (deploy, configure, analyze). Skills are the preferred format for both — see note below.
    - **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
@@ -64,8 +79,7 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
    ```
    | Component Type | Count | Purpose |
    |----------------|-------|---------|
-   | Skills         | 2     | Hook patterns, MCP usage |
-   | Commands       | 3     | Deploy, configure, validate |
+   | Skills         | 5     | Hook patterns, MCP usage, deploy, configure, validate |
    | Agents         | 1     | Autonomous validation |
    | Hooks          | 0     | Not needed |
    | MCP            | 1     | Database integration |
@@ -83,9 +97,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?
-   - **Commands**: What arguments? What tools? Interactive or automated?
+   - **Skills**: What triggers them? What knowledge do they provide? How detailed? For user-invoked skills: 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?
@@ -98,12 +112,14 @@ 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?
@@ -118,6 +134,7 @@ 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?"
@@ -125,10 +142,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     # if needed
-   mkdir -p plugin-name/commands   # if needed
-   mkdir -p plugin-name/agents     # if needed
-   mkdir -p plugin-name/hooks      # if needed
+   mkdir -p plugin-name/skills/<skill-name>   # one dir per skill, each with a SKILL.md
+   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
@@ -143,7 +160,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
@@ -155,8 +172,9 @@ 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
-- Commands: Load command-development skill
+- Legacy `commands/` format (only if user explicitly requests): Load command-development skill
 - Agents: Load agent-development skill
 - Hooks: Load hook-development skill
 - MCP: Load mcp-integration skill
@@ -165,21 +183,26 @@ 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 structure
-   - Write SKILL.md with:
+   - Create skill directory: `skills/<skill-name>/`
+   - 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 Commands:
+### 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.
+
 1. Load command-development skill using Skill tool
 2. For each command:
    - Write command markdown with frontmatter
@@ -190,6 +213,7 @@ 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
@@ -199,6 +223,7 @@ 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
@@ -208,6 +233,7 @@ 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)
@@ -218,6 +244,7 @@ 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)
@@ -235,6 +262,7 @@ 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
@@ -275,6 +303,7 @@ 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
@@ -284,7 +313,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)
-   - [ ] Commands appear in `/help` and execute correctly
+   - [ ] User-invoked skills appear in `/help` and execute correctly
    - [ ] Agents trigger on appropriate scenarios
    - [ ] Hooks activate on events (if applicable)
    - [ ] MCP servers connect (if applicable)
@@ -292,7 +321,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 commands: Run `/plugin-name:command-name` with various arguments
+   - For user-invoked skills: Run `/plugin-name:skill-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
@@ -310,6 +339,7 @@ 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
@@ -325,7 +355,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 commands, Z agents, etc.)
+     - Components created (X skills, Y agents, etc.)
      - Key files and their purposes
      - Total file count and structure
    - Next steps:
@@ -354,7 +384,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
-  - Commands written FOR Claude
+  - Skill instructions written FOR Claude (not TO user)
   - Strong trigger phrases
   - ${CLAUDE_PLUGIN_ROOT} for portability
   - Progressive disclosure
@@ -371,12 +401,13 @@ 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, command-development, agent-development, hook-development, mcp-integration, plugin-settings (as needed)
+- **Phase 5**: skill-development, agent-development, hook-development, mcp-integration, plugin-settings (as needed); command-development only for legacy `commands/` layout
 - **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)
@@ -390,19 +421,22 @@ 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: 1 (migration best practices)
-- Commands: 3 (create-migration, run-migrations, rollback)
+
+- Skills: 4 (migration best practices, 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,11 +6,14 @@ 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
@@ -22,6 +25,7 @@ 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
@@ -34,8 +38,10 @@ 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
@@ -44,6 +50,7 @@ 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.
@@ -54,18 +61,21 @@ 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`
@@ -85,8 +95,10 @@ Commands are Markdown files with `.md` extension:
 ```
 
 **Simple command:**
+
 ```markdown
 Review this code for security vulnerabilities including:
+
 - SQL injection
 - XSS attacks
 - Authentication bypass
@@ -138,6 +150,7 @@ allowed-tools: Read, Write, Edit, Bash(git:*)
 ```
 
 **Patterns:**
+
 - `Read, Write, Edit` - Specific tools
 - `Bash(git:*)` - Bash with git commands only
 - `*` - All tools (rarely needed)
@@ -157,6 +170,7 @@ model: haiku
 ```
 
 **Use cases:**
+
 - `haiku` - Fast, simple commands
 - `sonnet` - Standard workflows
 - `opus` - Complex analysis
@@ -174,6 +188,7 @@ argument-hint: [pr-number] [priority] [assignee]
 ```
 
 **Benefits:**
+
 - Helps users understand command arguments
 - Improves command discovery
 - Documents command interface
@@ -208,12 +223,14 @@ 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...
@@ -234,11 +251,13 @@ 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.
@@ -253,11 +272,13 @@ 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
 ```
@@ -275,12 +296,14 @@ argument-hint: [file-path]
 ---
 
 Review @$1 for:
+
 - Code quality
 - Best practices
 - Potential bugs
 ```
 
 **Usage:**
+
 ```
 > /review-file src/api/users.ts
 ```
@@ -295,6 +318,7 @@ Reference multiple files:
 Compare @src/old-version.js with @src/new-version.js
 
 Identify:
+
 - Breaking changes
 - New features
 - Bug fixes
@@ -308,6 +332,7 @@ Reference known files without arguments:
 Review @package.json and @tsconfig.json for consistency
 
 Ensure:
+
 - TypeScript version matches
 - Dependencies are aligned
 - Build configuration is correct
@@ -318,6 +343,7 @@ 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
@@ -361,6 +387,7 @@ Organize commands in subdirectories:
 ```
 
 **Benefits:**
+
 - Logical grouping by category
 - Namespace shown in `/help`
 - Easier to find related commands
@@ -390,8 +417,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]
 )
 ```
 
@@ -444,6 +471,7 @@ 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
@@ -475,6 +503,7 @@ argument-hint: [source-file]
 ---
 
 Generate comprehensive documentation for @$1 including:
+
 - Function/class descriptions
 - Parameter documentation
 - Return value descriptions
@@ -502,23 +531,27 @@ 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
@@ -531,6 +564,7 @@ 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
@@ -553,19 +587,24 @@ 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
@@ -586,12 +625,14 @@ 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
@@ -661,17 +702,20 @@ 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
@@ -690,6 +734,7 @@ 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
@@ -699,6 +744,7 @@ Generate production-ready API docs.
 ```
 
 **Key points:**
+
 - Skill must exist in `plugin/skills/` directory
 - Mention skill name to trigger invocation
 - Document skill purpose
@@ -707,6 +753,7 @@ 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
@@ -743,6 +790,7 @@ Compile findings into report following template.
 ```
 
 **When to use:**
+
 - Complex multi-step workflows
 - Leverage multiple plugin capabilities
 - Require specialized analysis
@@ -763,10 +811,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
@@ -780,11 +828,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
@@ -796,6 +844,7 @@ 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 "✗"`
 
@@ -814,14 +863,15 @@ 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