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/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/<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?