docs(plugin-dev): deprecate commands/ in favor of skills/<name>/SKILL.md (#717)

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/<name>/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 Co-authored-by: Henry Shi <henrys@anthropic.com>
2026-03-18 10:53:09 +00:00 · 2026-03-17 22:45:25 +00:00
parent 78497c524d
commit 6b70f99f76
5 changed files with 190 additions and 58 deletions
--- 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/<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