ros/claude-plugins-official
1
0
Fork 0
mirror of https://github.com/anthropics/claude-plugins-official.git synced 2026-03-18 10:53:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Henry Shi
2026-03-08 15:56:20 -07:00
parent 205b6e0b30
commit 58ad5cbb02
5 changed files with 190 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
plugins/plugin-dev/commands/create-plugin.md
View File

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