From 78497c524da3762865d47377357c30af5b50d522 Mon Sep 17 00:00:00 2001 From: Tobin South Date: Tue, 17 Mar 2026 02:00:28 +0000 Subject: [PATCH 1/2] updates(staging): merge staging additions into main (#677) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix readme typo * fix(plugin-dev): add missing .claude-plugin/plugin.json The plugin-dev plugin was missing its required plugin.json manifest file, causing the plugin to fail loading. This adds the missing configuration file following the same format as other official plugins. πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 * Add README and setup documentation for Greptile plugin - Add README.md with setup instructions for getting API key - Document the GREPTILE_API_KEY environment variable requirement - Add homepage, author URL, and keywords to plugin.json - Update description to reflect Greptile as AI code review agent πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude * feat: add c7 agent * Update Context7 plugin for v2 API - Update skill/agent/command to use new query-docs tool (replaces get-library-docs) - Add query parameter usage for intelligent reranking - Add version pinning support (e.g., /vercel/next.js/v15.1.8) - Add tools and model metadata to agent - Simplify docs to focus on workflow, not parameter details - Add README.md with usage examples * Switch Context7 MCP to remote HTTP server * feat: update tools with better skill/agent format prompt * fmt * fix: installation guide * Change Notion name to lowercase in marketplace.json According to the SKILLS spec (see https://agentskills.io/specification#:~:text=Max%2064%20characters.%20Lowercase%20letters%2C%20numbers%2C%20and%20hyphens%20only.%20Must%20not%20start%20or%20end%20with%20a%20hyphen.) names should not contain uppercase letters. This prevents loading the marketplace in spec-compliant agents. Update the name to be in lowercase. * Fix empty array crash on bash 3.2 in setup-ralph-loop.sh * Update Vercel plugin to point to vercel-labs/vercel-plugin Replace the marketplace pointer for the Vercel plugin from vercel/vercel-deploy-claude-code-plugin to vercel-labs/vercel-plugin. * vercel-labs to vercel * docs(ralph-loop): add Windows compatibility section Retargeted from PR #124 (originally against plugins/ralph-wiggum/, since renamed). Documents the Git Bash workaround for Windows users hitting WSL bash resolution issues in the stop hook. Original author: @stefanzvonar * add(plugin): terraform β€” HashiCorp infrastructure-as-code Adapted from PR #14 by @gautambaghel (HashiCorp). Original: https://github.com/anthropics/claude-plugins-official/pull/14 * add(plugin): autofix-bot β€” DeepSource automated code review Adapted from PR #23 by @jai-deepsource (DeepSource). Original: https://github.com/anthropics/claude-plugins-official/pull/23 * add(plugin): stagehand β€” Browserbase browser automation Adapted from PR #43 by @Kylejeong2 (Browserbase). PR's marketplace.json had a syntax error (missing '},' before adjacent entry); entry reconstructed from the diff. Original: https://github.com/anthropics/claude-plugins-official/pull/43 * add(plugin): atomic-agents β€” BrainBlend-AI framework Adapted from PR #46 by @KennyVaneetvelde (BrainBlend-AI). Original: https://github.com/anthropics/claude-plugins-official/pull/46 * add(plugin): microsoft-docs β€” official Microsoft documentation MCP Adapted from PR #55 by @TianqiZhang (Microsoft). Original: https://github.com/anthropics/claude-plugins-official/pull/55 * add(plugin): bonfire β€” session-context workflow tooling Adapted from PR #108 by @vieko (Vercel). Original: https://github.com/anthropics/claude-plugins-official/pull/108 * Add intercom to marketplace * Add neon to marketplace * Remove qodo SHA * Merge staging into add-plugin/intercom to resolve conflict * Merge latest staging to resolve conflict * Remove external_plugins changes from staging Moved to external-plugins-staging branch for separate review. --------- Co-authored-by: Han T. Co-authored-by: Julien Tavernier Co-authored-by: Claude Opus 4.5 Co-authored-by: Daksh Gupta Co-authored-by: Fahreddin Γ–zcan Co-authored-by: Matt Kotsenas Co-authored-by: LuciferDono --- .claude-plugin/marketplace.json | 102 +++++++++++++++++- README.md | 2 +- plugins/plugin-dev/.claude-plugin/plugin.json | 8 ++ plugins/ralph-loop/README.md | 18 ++++ .../ralph-loop/scripts/setup-ralph-loop.sh | 2 +- 5 files changed, 125 insertions(+), 7 deletions(-) create mode 100644 plugins/plugin-dev/.claude-plugin/plugin.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 58ed66b..2ed6589 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -552,7 +552,7 @@ "homepage": "https://github.com/anthropics/claude-plugins-public/tree/main/external_plugins/linear" }, { - "name": "Notion", + "name": "notion", "description": "Notion workspace integration. Search pages, create and update documents, manage databases, and access your team's knowledge base directly from Claude Code for seamless documentation workflows.", "category": "productivity", "source": { @@ -594,9 +594,9 @@ "category": "deployment", "source": { "source": "url", - "url": "https://github.com/vercel/vercel-deploy-claude-code-plugin.git" + "url": "https://github.com/vercel/vercel-plugin.git" }, - "homepage": "https://github.com/vercel/vercel-deploy-claude-code-plugin" + "homepage": "https://github.com/vercel/vercel-plugin" }, { "name": "stripe", @@ -709,8 +709,7 @@ "category": "development", "source": { "source": "url", - "url": "https://github.com/qodo-ai/qodo-skills.git", - "sha": "623eb4ed4364d8111f9a9132a791d7497d814b6a" + "url": "https://github.com/qodo-ai/qodo-skills.git" }, "homepage": "https://github.com/qodo-ai/qodo-skills.git" }, @@ -946,6 +945,99 @@ "sha": "b93007e9a726c6ee93c57a949e732744ef5acbfd" }, "homepage": "https://github.com/zapier/zapier-mcp/tree/main/plugins/zapier" + }, + { + "name": "terraform", + "description": "The Terraform MCP Server provides seamless integration with Terraform ecosystem, enabling advanced automation and interaction capabilities for Infrastructure as Code (IaC) development.", + "author": { + "name": "HashiCorp", + "email": "support@hashicorp.com" + }, + "category": "development", + "source": "./external_plugins/terraform", + "homepage": "https://github.com/anthropics/claude-plugins-public/tree/main/external_plugins/terraform" + }, + { + "name": "autofix-bot", + "description": "Code review agent that detects security vulnerabilities, code quality issues, and hardcoded secrets. Combines 5,000+ static analyzers to scan your code and dependencies for CVEs.", + "author": { + "name": "DeepSource Corp" + }, + "category": "security", + "source": "./external_plugins/autofix-bot", + "homepage": "https://github.com/anthropics/claude-plugins-public/tree/main/external_plugins/autofix-bot" + }, + { + "name": "stagehand", + "description": "Browser automation skill for Claude Code using Stagehand. Automate web interactions, extract data, and navigate websites using natural language.", + "version": "0.1.0", + "author": { + "name": "Browserbase" + }, + "source": { + "source": "github", + "repo": "browserbase/agent-browse" + }, + "category": "automation", + "keywords": [ + "browser", + "automation", + "stagehand", + "web-scraping" + ], + "homepage": "https://github.com/browserbase/agent-browse", + "strict": false, + "skills": [ + "./.claude/skills/browser-automation" + ] + }, + { + "name": "atomic-agents", + "description": "Comprehensive development workflow for building AI agents with the Atomic Agents framework. Includes specialized agents for schema design, architecture planning, code review, and tool development. Features guided workflows, progressive-disclosure skills, and best practice validation.", + "category": "development", + "source": { + "source": "url", + "url": "https://github.com/BrainBlend-AI/atomic-agents.git", + "path": "claude-plugin/atomic-agents" + }, + "homepage": "https://github.com/BrainBlend-AI/atomic-agents", + "tags": [ + "community-managed" + ] + }, + { + "name": "microsoft-docs", + "description": "Access official Microsoft documentation, API references, and code samples for Azure, .NET, Windows, and more.", + "category": "development", + "source": { + "source": "url", + "url": "https://github.com/MicrosoftDocs/mcp.git" + }, + "homepage": "https://github.com/microsoftdocs/mcp" + }, + { + "name": "neon", + "description": "Manage your Neon projects and databases with the neon-postgres agent skill and the Neon MCP Server.", + "category": "database", + "source": { + "source": "git-subdir", + "url": "neondatabase/agent-skills", + "path": "plugins/neon-postgres", + "ref": "main", + "sha": "54d7a9db2ddd476f84d5d1fd7bac323907858a8b" + }, + "homepage": "https://github.com/neondatabase/agent-skills/tree/main/plugins/neon-postgres" + }, + { + "name": "intercom", + "description": "Intercom integration for Claude Code. Search conversations, analyze customer support patterns, look up contacts and companies, and install the Intercom Messenger. Connect your Intercom workspace to get real-time insights from customer data.", + "category": "productivity", + "source": { + "source": "url", + "url": "https://github.com/intercom/claude-plugin-external.git", + "sha": "eeef353eead2e3dc5f33f64dbaae54e1309e0d45" + }, + "homepage": "https://github.com/intercom/claude-plugin-external" } ] } diff --git a/README.md b/README.md index 624f6d7..1d9caa0 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ A curated directory of high-quality plugins for Claude Code. Plugins can be installed directly from this marketplace via Claude Code's plugin system. -To install, run `/plugin install {plugin-name}@claude-plugin-directory` +To install, run `/plugin install {plugin-name}@claude-plugins-official` or browse for the plugin in `/plugin > Discover` diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json new file mode 100644 index 0000000..19cd871 --- /dev/null +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "plugin-dev", + "description": "Plugin development toolkit with skills for creating agents, commands, hooks, MCP integrations, and comprehensive plugin structure guidance", + "author": { + "name": "Anthropic", + "email": "support@anthropic.com" + } +} diff --git a/plugins/ralph-loop/README.md b/plugins/ralph-loop/README.md index 531c31e..1e1c9f9 100644 --- a/plugins/ralph-loop/README.md +++ b/plugins/ralph-loop/README.md @@ -169,6 +169,24 @@ Keep trying until success. The loop handles retry logic automatically. - One $50k contract completed for $297 in API costs - Created entire programming language ("cursed") over 3 months using this approach +## Windows Compatibility + +The stop hook uses a bash script that requires Git for Windows to run properly. + +**Issue**: On Windows, the `bash` command may resolve to WSL bash (often misconfigured) instead of Git Bash, causing the hook to fail with errors like: +- `wsl: Unknown key 'automount.crossDistro'` +- `execvpe(/bin/bash) failed: No such file or directory` + +**Workaround**: Edit the cached plugin's `hooks/hooks.json` to use Git Bash explicitly: + +```json +"command": "\"C:/Program Files/Git/bin/bash.exe\" ${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh" +``` + +**Location**: `~/.claude/plugins/cache/claude-plugins-official/ralph-wiggum//hooks/hooks.json` + +**Note**: Use `Git/bin/bash.exe` (the wrapper with proper PATH), not `Git/usr/bin/bash.exe` (raw MinGW bash without utilities in PATH). + ## Learn More - Original technique: https://ghuntley.com/ralph/ diff --git a/plugins/ralph-loop/scripts/setup-ralph-loop.sh b/plugins/ralph-loop/scripts/setup-ralph-loop.sh index c0897d4..d4f6e0f 100755 --- a/plugins/ralph-loop/scripts/setup-ralph-loop.sh +++ b/plugins/ralph-loop/scripts/setup-ralph-loop.sh @@ -110,7 +110,7 @@ HELP_EOF done # Join all prompt parts with spaces -PROMPT="${PROMPT_PARTS[*]}" +PROMPT="${PROMPT_PARTS[*]:-}" # Validate prompt is non-empty if [[ -z "$PROMPT" ]]; then From 6b70f99f769f58b9b642dc8a271936b17862cf8c Mon Sep 17 00:00:00 2001 From: Tobin South Date: Tue, 17 Mar 2026 22:45:25 +0000 Subject: [PATCH 2/2] docs(plugin-dev): deprecate commands/ in favor of skills//SKILL.md (#717) 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 Co-authored-by: Henry Shi --- 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