docs: sync plugin-development documentation with official Anthropic docs

plugins/plugin-development/agents/plugin-reviewer.md

@@ -1,8 +1,16 @@
 ---
-description: Reviews a plugin for correct structure, safe hooks, clear commands and skills, and marketplace readiness
-capabilities: ["structure-audit", "hook-safety-checks", "component-validation", "marketplace-readiness"]
+name: plugin-reviewer
+description: Reviews a plugin for correct structure, safe hooks, clear commands and skills, and marketplace readiness. Use PROACTIVELY before releasing or distributing plugins.
+tools: Read, Grep, Glob
+model: inherit
+permissionMode: default
 ---
 
+<!--
+NOTE: The 'capabilities' field has been removed as it is NOT in official Anthropic docs.
+Agent capabilities are now documented in the body content below.
+-->
+
 # Plugin Reviewer Agent
 
 Comprehensive audit of Claude Code plugins for structure, safety, and best practices.

plugins/plugin-development/commands/add-agent.md

@@ -109,8 +109,11 @@ Create a new sub-agent file with proper frontmatter and structure.
 
 ```markdown
 ---
+name: $1
 description: $2
-capabilities: ["capability-1", "capability-2", "capability-3"]
+tools: Read, Grep, Glob, Bash
+model: inherit
+permissionMode: default
 ---
 
 # $1 Agent
@@ -222,8 +225,12 @@ Description: $2
 Next steps:
 1. Edit <plugin-name>/agents/$1.md with specific instructions
 2. Key frontmatter fields:
-   - description: What the agent does (shows in /agents list)
-   - capabilities: List of capabilities (JSON array)
+   - name: Unique agent identifier (lowercase with hyphens)
+   - description: What the agent does and when to invoke (shows in /agents list)
+   - tools: CSV list of tools (optional, inherits all if omitted)
+   - model: sonnet, opus, haiku, or inherit (optional)
+   - permissionMode: default, acceptEdits, bypassPermissions, or plan (optional)
+   - skills: CSV list of skills to auto-load (optional)
 3. Define clear workflow steps
 4. Specify what the agent returns
 5. Test with /plugin-development:test-local
@@ -312,22 +319,61 @@ Or via Task tool in main conversation.
 
 ```yaml
 ---
-description: Third-person description of what this agent does
+name: agent-name
+description: Third-person description of what this agent does and when to invoke it
 ---
 ```
 
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | String | **Required.** Unique identifier using lowercase letters and hyphens (e.g., `code-reviewer`, `test-runner`) |
+| `description` | String | **Required.** Natural language description of when the agent should be invoked. Include "PROACTIVELY" for auto-delegation |
+
 ### Optional Fields
 
 ```yaml
 ---
-description: Agent description
-capabilities: ["capability-1", "capability-2"]    # List of what it can do
+name: agent-name
+description: Agent description. Use PROACTIVELY for auto-delegation.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+permissionMode: default
+skills: skill1, skill2
 ---
 ```
 
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `tools` | CSV String | Inherits all | Comma-separated list of tools (e.g., `Read, Grep, Glob, Bash`). If omitted, inherits all tools from main thread including MCP tools |
+| `model` | String | `sonnet` | Which AI model to use. Valid values: `sonnet`, `opus`, `haiku`, `inherit`. Use `inherit` to match main conversation's model |
+| `permissionMode` | String | `default` | How the agent handles permission requests. Valid values: `default`, `acceptEdits`, `bypassPermissions`, `plan` |
+| `skills` | CSV String | None | Comma-separated list of skills to auto-load. Note: Agents do NOT inherit skills from parent conversation |
+
+### Permission Modes Explained
+
+| Mode | Behavior |
+|------|----------|
+| `default` | Standard permission handling - prompts for confirmation |
+| `acceptEdits` | Automatically accept file edits without prompting |
+| `bypassPermissions` | Skip permission requests entirely |
+| `plan` | Plan mode - research and planning without execution |
+
+### Model Options
+
+| Model | Description |
+|-------|-------------|
+| `sonnet` | Claude Sonnet (default for subagents) |
+| `opus` | Claude Opus |
+| `haiku` | Claude Haiku (faster, lighter) |
+| `inherit` | Use same model as main conversation |
+
+### Deprecation Note
+
+The `capabilities` field is **NOT** in official Anthropic docs and may be deprecated. Use `tools` for agents (not `allowed-tools` which is for skills).
+
 **For complete details on agents**, see:
-- [Subagents documentation](/en/docs/claude-code/sub-agents)
-- [Plugin agents reference](/en/docs/claude-code/plugins-reference#agents)
+- [Subagents documentation](https://code.claude.com/docs/en/sub-agents)
+- [Plugin agents reference](https://code.claude.com/docs/en/plugins-reference#agents)
 
 ## Error Handling
 
@@ -405,15 +451,17 @@ Specializes in security analysis:
 Does everything related to code.
 ```
 
-### 2. Clear Capabilities
+### 2. Clear Tool Configuration
 
-List 2-5 specific capabilities:
+Configure appropriate tools for the agent's purpose:
 ```yaml
-capabilities: [
-  "security-vulnerability-detection",
-  "authentication-analysis",
-  "dependency-audit"
-]
+# For read-only analysis agents:
+tools: Read, Grep, Glob
+
+# For agents that can modify files:
+tools: Read, Edit, Write, Bash, Grep, Glob
+
+# Omit to inherit all tools from main thread
 ```
 
 ### 3. Structured Output
@@ -513,14 +561,14 @@ For comprehensive review, delegate to the code-reviewer agent.
 
 ## Common Mistakes to Avoid
 
-❌ **Too broad scope**
+❌ **Too broad description**
 ```yaml
-capabilities: ["everything", "all-tasks", "general-help"]
+description: Does everything related to code
 ```
 
-✅ **Focused capabilities**
+✅ **Focused description with clear purpose**
 ```yaml
-capabilities: ["security-audit", "vulnerability-scan", "compliance-check"]
+description: Security audit specialist. Scans for vulnerabilities, reviews authentication, and checks compliance. Use PROACTIVELY after code changes.
 ```
 
 ❌ **Vague instructions**
@@ -541,11 +589,14 @@ Analyze the code and find problems.
 After creating an agent:
 ```
 □ Agent file created in agents/ directory
-□ Frontmatter includes description
-□ Capabilities listed (2-5 items)
-□ Clear workflow defined
+□ Frontmatter includes required 'name' field (lowercase with hyphens)
+□ Frontmatter includes required 'description' field
+□ Optional: 'tools' field configured (or inherits all)
+□ Optional: 'model' field set (sonnet/opus/haiku/inherit)
+□ Optional: 'permissionMode' configured if needed
+□ Optional: 'skills' listed for auto-loading
+□ Clear workflow defined in body
 □ Output format specified
-□ Agent name is kebab-case
-□ plugin.json has agents field
+□ plugin.json has agents field (if using custom paths)
 □ Purpose is focused and specific
 ```

plugins/plugin-development/commands/add-command.md

@@ -111,6 +111,9 @@ If validation fails, provide clear feedback.
 ---
 description: $2
 argument-hint: [arg1] [arg2]
+allowed-tools: Write, Edit
+model: claude-3-5-haiku-20241022
+disable-model-invocation: false
 ---
 
 # $1 Command
@@ -166,7 +169,10 @@ Next steps:
 2. Update frontmatter fields if needed:
    - argument-hint: [arg1] [arg2] (optional)
    - allowed-tools: Tool restrictions (optional)
-3. Test with /plugin-development:test-local
+   - model: Specify different model (optional)
+   - disable-model-invocation: Prevent SlashCommand tool invocation (optional)
+3. Use @path/to/file syntax to reference files in instructions
+4. Test with /plugin-development:test-local
 
 Command will be invoked as: /<plugin-name>:$1
 ```
@@ -200,9 +206,34 @@ Command will be invoked as: /<plugin-name>:$1
 description: Brief, third-person description (shows in /help)
 argument-hint: [arg1] [arg2]  # Optional, shows expected arguments
 allowed-tools: Write, Edit    # Optional, restricts tool access
+model: claude-3-5-haiku-20241022  # Optional, specify different model
+disable-model-invocation: true    # Optional, prevents SlashCommand tool from invoking
 ---
 ```
 
+#### Frontmatter Reference
+
+| Field | Purpose | Default |
+|-------|---------|---------|
+| `description` | Brief description of the command | First line of prompt |
+| `argument-hint` | Expected arguments (shown in auto-complete) | None |
+| `allowed-tools` | List of tools the command can use | Inherits from conversation |
+| `model` | Specific model to use (full ID like `claude-3-5-haiku-20241022`) | Inherits from conversation |
+| `disable-model-invocation` | Prevent SlashCommand tool from calling this command | false |
+
+#### Multiple Invocation Patterns
+
+Use pipe syntax in `argument-hint` to define multiple invocation patterns:
+
+```yaml
+---
+description: Manage project tags
+argument-hint: add [tagId] | remove [tagId] | list
+---
+```
+
+This shows users the different ways to invoke the command.
+
 ### Using Arguments
 
 In the command instructions:
@@ -214,6 +245,20 @@ Example:
 If the user provided a name via `$1`, use it: "Hello, $1!"
 ```
 
+### File References
+
+Include file contents using the `@` prefix within your command instructions:
+
+```markdown
+# Reference a specific file
+Review the implementation in @src/utils/helpers.js
+
+# Reference multiple files
+Compare @src/old-version.js with @src/new-version.js
+```
+
+The file contents will be included inline when the command is executed.
+
 ### Command Instructions
 
 Write clear, step-by-step instructions for Claude:
@@ -252,6 +297,53 @@ Analyze the output and report:
 - **Error handling**: Describe what to do when things go wrong
 - **Examples**: Include usage examples in the template
 
+## SlashCommand Tool
+
+The `SlashCommand` tool allows Claude to execute custom slash commands programmatically during a conversation.
+
+### Requirements for SlashCommand Tool Support
+
+For Claude to be able to invoke your command via the SlashCommand tool:
+
+1. **Required**: The `description` frontmatter field must be populated
+2. The command must be user-defined (not a built-in command like `/compact`)
+
+### Character Budget
+
+- **Default limit**: 15,000 characters for slash command content
+- **Customization**: Set `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable to adjust
+- **What counts**: Command name, arguments, and description all count toward the budget
+- **When exceeded**: Claude sees only a subset of available commands
+- **Monitoring**: Use `/context` to see warnings displayed as "M of N commands"
+
+### Enabling Claude to Use Commands
+
+Reference the command in prompts or `CLAUDE.md`:
+
+```
+> Run /write-unit-test when you are about to start writing tests.
+```
+
+### Disabling SlashCommand Tool Invocation
+
+To prevent a specific command from being invoked by the SlashCommand tool, add to frontmatter:
+
+```yaml
+---
+description: My command description
+disable-model-invocation: true
+---
+```
+
+### Permission Rules
+
+SlashCommand permissions support exact and prefix matching:
+
+```
+SlashCommand:/commit          # Allows only /commit with no arguments
+SlashCommand:/review-pr:*     # Allows /review-pr with any arguments
+```
+
 ## Common Mistakes to Avoid
 
 ❌ **camelCase or PascalCase names**

plugins/plugin-development/skills/plugin-authoring/SKILL.md

@@ -36,8 +36,13 @@ Activate whenever context includes `.claude-plugin/`, `plugin.json`, `marketplac
 □ Component dirs at plugin root (commands/, agents/, skills/, hooks/)
 □ Do NOT put components inside .claude-plugin/ directory
 □ Commands use kebab-case naming
-□ Skills have valid frontmatter (name + description required)
-□ Skills name matches directory (lowercase-hyphenated, max 64 chars)
+□ Skills have valid frontmatter (name + description required, optional: model, allowed-tools)
+□ Skills name validation:
+  - Matches directory name
+  - Lowercase letters, numbers, hyphens only
+  - Max 64 characters
+  - No reserved words ('anthropic', 'claude')
+  - No XML tags
 □ Hooks use ${CLAUDE_PLUGIN_ROOT} for paths (not relative paths)
 □ All scripts are executable (chmod +x)
 ```
@@ -82,17 +87,18 @@ Activate whenever context includes `.claude-plugin/`, `plugin.json`, `marketplac
 1. Run `/plugin-development:add-skill <name> <when-to-use>`
 2. Edit `skills/<name>/SKILL.md` with your instructions
 3. **Frontmatter requirements**:
-   - `name`: lowercase, hyphenated, max 64 chars (required)
-   - `description`: include both WHAT the Skill does AND WHEN to use it, max 1024 chars (required)
-   - `allowed-tools`: comma-separated list of tools (optional, restricts tool access)
-4. Keep SKILL.md concise; place details in sibling files (reference.md, examples.md, scripts/)
+   - `name`: lowercase letters, numbers, and hyphens only, max 64 chars (required). Cannot contain reserved words 'anthropic' or 'claude'. Cannot contain XML tags.
+   - `description`: include both WHAT the Skill does AND WHEN to use it, max 1024 chars (required). Cannot contain XML tags.
+   - `model`: specify which Claude model to use, e.g., `model: claude-sonnet-4-20250514` (optional, defaults to conversation's model)
+   - `allowed-tools`: comma-separated list of tools (optional). Tools listed don't require permission to use when Skill is active. If omitted, Skill doesn't restrict tools.
+4. Keep SKILL.md under 500 lines for optimal performance; place details in sibling files (reference.md, examples.md, scripts/)
 
 ### Troubleshooting
 
 - **Plugin not loading?** Check `plugin.json` paths are relative to plugin root. Do NOT include `commands`, `agents`, `skills`, or `hooks` fields for standard directories.
 - **Commands not showing?** Verify `commands/` directory exists at plugin root with `.md` files. Do NOT add `commands` field to `plugin.json` for standard paths.
 - **Hooks not running?** Ensure scripts are executable (`chmod +x`) and use `${CLAUDE_PLUGIN_ROOT}` for paths
-- **Skill not triggering?** Check `name` matches directory and is lowercase-hyphenated (max 64 chars). Ensure `description` includes both what and when to use (max 1024 chars)
+- **Skill not triggering?** Check `name` matches directory and uses lowercase letters, numbers, and hyphens only (max 64 chars). Ensure `description` includes both what and when to use (max 1024 chars). Neither field can contain XML tags.
 
 ## Notes