From 58ad5cbb02028102d0abf6a58f7a89ba4d83b05f Mon Sep 17 00:00:00 2001 From: Henry Shi Date: Sun, 8 Mar 2026 15:56:20 -0700 Subject: [PATCH] docs(plugin-dev): deprecate commands/ in favor of skills//SKILL.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P0 follow-up for EA-471. Updates plugin-dev teaching materials to stop recommending the commands/ directory layout for new plugins: - command-development/SKILL.md: add legacy banner at top pointing to skills/ format - create-plugin.md: update scaffolding to create skills//SKILL.md instead of commands/; mark commands/ as acceptable legacy alternative; update all examples, tables, and testing instructions - example-plugin: migrate example-command to skills/example-command/SKILL.md; keep commands/example-command.md with a legacy-format note; update README to reflect new preferred structure Both formats remain loaded identically — this is a documentation change only. Refs: anthropics/apps#26827 --- plugins/example-plugin/README.md | 47 ++++++----- .../commands/example-command.md | 6 +- .../skills/example-command/SKILL.md | 39 +++++++++ plugins/plugin-dev/commands/create-plugin.md | 80 +++++++++++++------ .../skills/command-development/SKILL.md | 76 +++++++++++++++--- 5 files changed, 190 insertions(+), 58 deletions(-) create mode 100644 plugins/example-plugin/skills/example-command/SKILL.md diff --git a/plugins/example-plugin/README.md b/plugins/example-plugin/README.md index 34d9c2a..6f9f16b 100644 --- a/plugins/example-plugin/README.md +++ b/plugins/example-plugin/README.md @@ -7,32 +7,24 @@ 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/`) - -Slash commands are user-invoked via `/command-name`. Define them as markdown files with frontmatter: - -```yaml ---- -description: Short description for /help -argument-hint: [optional-arg] -allowed-tools: [Read, Glob, Grep] ---- -``` - ### Skills (`skills/`) -Skills are model-invoked capabilities. Create a `SKILL.md` in a subdirectory: +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): ```yaml --- @@ -42,6 +34,21 @@ version: 1.0.0 --- ``` +**User-invoked skill** (slash command — `/skill-name`): + +```yaml +--- +name: skill-name +description: Short description for /help +argument-hint: [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//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: diff --git a/plugins/example-plugin/commands/example-command.md b/plugins/example-plugin/commands/example-command.md index 103b7ee..5cf32af 100644 --- a/plugins/example-plugin/commands/example-command.md +++ b/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: [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//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. diff --git a/plugins/example-plugin/skills/example-command/SKILL.md b/plugins/example-plugin/skills/example-command/SKILL.md new file mode 100644 index 0000000..a179337 --- /dev/null +++ b/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//SKILL.md layout +argument-hint: [optional-arg] +allowed-tools: [Read, Glob, Grep, Bash] +--- + +# Example Command (Skill Format) + +This demonstrates the `skills//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 +``` diff --git a/plugins/plugin-dev/commands/create-plugin.md b/plugins/plugin-dev/commands/create-plugin.md index 8839281..56f2a91 100644 --- a/plugins/plugin-dev/commands/create-plugin.md +++ b/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//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/ # 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//` + - 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//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? diff --git a/plugins/plugin-dev/skills/command-development/SKILL.md b/plugins/plugin-dev/skills/command-development/SKILL.md index 5780211..4c82f7e 100644 --- a/plugins/plugin-dev/skills/command-development/SKILL.md +++ b/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//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