feat: sync documentation with official Claude Code docs

.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unofficial plugin-dev plugin marketplace for plugin-dev Claude Code plugin - the plugin itself was initially created by Daisy Hollman at Anthropic.",
-    "version": "0.2.1"
+    "version": "0.3.0"
   },
   "plugins": [
     {
       "name": "plugin-dev",
-      "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 8 expert skills covering hooks, MCP integration, commands, agents, marketplaces, and best practices. AI-assisted plugin creation and validation.",
-      "version": "0.2.1",
+      "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 9 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices. AI-assisted plugin creation and validation.",
+      "version": "0.3.0",
       "author": {
         "name": "Daisy Hollman",
         "url": "https://github.com/anthropics/claude-code/",

CLAUDE.md

@@ -4,9 +4,9 @@ Guidance for Claude Code working in this repository.
 
 ## What This Is
 
-Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 8 skills, 3 agents, 3 slash commands.
+Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 9 skills, 3 agents, 3 slash commands.
 
-**Version**: v0.2.1 | [CHANGELOG.md](CHANGELOG.md)
+**Version**: v0.3.0 | [CHANGELOG.md](CHANGELOG.md)
 
 ## MCP Tool Requirements (CRITICAL)
 

plugins/plugin-dev/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plugin-dev",
-  "version": "0.2.1",
-  "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 8 expert skills covering hooks, MCP integration, commands, agents, marketplaces, and best practices. AI-assisted plugin creation and validation.",
+  "version": "0.3.0",
+  "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 9 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices. AI-assisted plugin creation and validation.",
   "author": {
     "name": "Daisy Hollman",
     "email": "daisy@anthropic.com"

plugins/plugin-dev/agents/agent-creator.md

@@ -118,6 +118,8 @@ When a user describes what they want an agent to do, you will:
      - red: Security, critical
      - magenta: Transformation, creative
    - **Tools**: Recommend minimal set needed, or omit for full access
+   - **Skills**: Include relevant skills if agent needs domain expertise
+   - **Permission Mode**: Set if agent needs special permissions (acceptEdits, dontAsk, plan)
 
 4. **Generate Agent File**: Use Write tool to create `agents/[identifier].md`:
 
@@ -128,6 +130,9 @@ When a user describes what they want an agent to do, you will:
    model: inherit
    color: [chosen-color]
    tools: Tool1, Tool2 # Optional
+   skills: # Optional - load domain skills
+     - skill-name
+   permissionMode: acceptEdits # Optional - for auto-accepting edits
    ---
 
    [Complete system prompt]

plugins/plugin-dev/agents/plugin-validator.md

@@ -41,7 +41,7 @@ Marketplace created, validate schema and plugin entries.
 model: inherit
 color: yellow
 tools: Read, Grep, Glob, Bash
-skills: plugin-structure, hook-development, command-development, skill-development, agent-development
+skills: plugin-structure, hook-development, command-development, skill-development, agent-development, lsp-integration, mcp-integration
 ---
 
 You are an expert plugin and marketplace validator specializing in comprehensive validation of Claude Code plugin structure, configuration, components, and plugin marketplaces.
@@ -139,17 +139,28 @@ First, determine what type of validation is needed:
      - Type-specific fields present
    - Check ${CLAUDE_PLUGIN_ROOT} usage for portability
 
-9. **Check File Organization**:
-   - README.md exists and is comprehensive
-   - No unnecessary files (node_modules, .DS_Store, etc.)
-   - .gitignore present if needed
-   - LICENSE file present
-
-10. **Security Checks**:
-    - No hardcoded credentials in any files
-    - MCP servers use HTTPS/WSS not HTTP/WS
-    - Hooks don't have obvious security issues
-    - No secrets in example files
+9. **Validate LSP Configuration** (if `lspServers` in manifest):
+   - Check each LSP server configuration:
+     - `command` field is present
+     - `extensionToLanguage` mapping is present
+     - Extension keys start with `.`
+     - Language IDs are valid strings
+   - Verify ${CLAUDE_PLUGIN_ROOT} usage for bundled servers
+   - Check that referenced server commands exist (if local)
+
+10. **Check File Organization**:
+
+- README.md exists and is comprehensive
+- No unnecessary files (node_modules, .DS_Store, etc.)
+- .gitignore present if needed
+- LICENSE file present
+
+11. **Security Checks**:
+
+- No hardcoded credentials in any files
+- MCP servers use HTTPS/WSS not HTTP/WS
+- Hooks don't have obvious security issues
+- No secrets in example files
 
 **Marketplace Validation Process:**
 

plugins/plugin-dev/agents/skill-reviewer.md

@@ -64,7 +64,7 @@ You are an expert skill architect specializing in reviewing and improving Claude
 2. **Validate Structure**:
    - Frontmatter format (YAML between `---`)
    - Required fields: `name`, `description`
-   - Optional fields: `version` (others may exist per Claude Code updates)
+   - Optional fields: `allowed-tools`, `context`, `agent`, `skills`, `user-invocable`, `disable-model-invocation`
    - Body content exists and is substantial
 
 3. **Evaluate Description** (Most Critical):

plugins/plugin-dev/commands/create-plugin.md

@@ -60,6 +60,7 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
    - **Agents**: Autonomous tasks? (validation, generation, analysis)
    - **Hooks**: Event-driven automation? (validation, notifications)
    - **MCP**: External service integration? (databases, APIs)
+   - **LSP**: Code intelligence? (go-to-definition, find references)
    - **Settings**: User configuration? (.local.md files)
 3. For each component type needed, identify:
    - How many of each type
@@ -177,6 +178,7 @@ git commit -m "feat: initial plugin structure"
 - Agents: Load agent-development skill
 - Hooks: Load hook-development skill
 - MCP: Load mcp-integration skill
+- LSP: Load lsp-integration skill
 - Settings: Load plugin-settings skill
 
 **Actions for each component**:
@@ -239,6 +241,17 @@ git commit -m "feat: initial plugin structure"
 3. Document required env vars in README
 4. Provide setup instructions
 
+### For LSP
+
+1. Load lsp-integration skill using Skill tool
+2. Add lspServers configuration to plugin.json:
+   - Server command and args
+   - extensionToLanguage mapping
+   - Environment variables if needed
+3. Bundle LSP server binary if self-contained
+4. Or document external server installation in README
+5. Test with language files matching configured extensions
+
 ### For Settings
 
 1. Load plugin-settings skill using Skill tool
@@ -427,7 +440,7 @@ git commit -m "feat: initial plugin structure"
 ### 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, command-development, agent-development, hook-development, mcp-integration, lsp-integration, plugin-settings (as needed)
 - **Phase 6**: (agents will use skills automatically)
 - **Phase 8**: marketplace-structure (if publishing to marketplace)
 

plugins/plugin-dev/skills/agent-development/SKILL.md

@@ -255,6 +255,44 @@ tools: Read, Write, Grep, Bash
 
 > **Important:** Agents use `tools` while Skills use `allowed-tools`. The field names differ between component types. For skill tool restrictions, see the `skill-development` skill.
 
+### skills (optional)
+
+Load specific skills into the agent's context:
+
+```yaml
+skills:
+  - testing-patterns
+  - security-audit
+  - api-design
+```
+
+**Use cases:**
+
+- Give agent domain expertise via skills
+- Combine multiple skills for comprehensive workflows
+- Share knowledge between agents and skills
+
+Skills must be from the same plugin. The skill's SKILL.md content loads into the agent's context.
+
+### permissionMode (optional)
+
+Control how the agent handles permission requests:
+
+```yaml
+permissionMode: acceptEdits
+```
+
+**Values:**
+
+- `acceptEdits` - Auto-accept file edit operations (Write, Edit)
+- `dontAsk` - Skip permission dialogs for all operations
+- `bypassPermissions` - Full bypass (requires trust)
+- `plan` - Planning mode, propose changes without executing
+
+**Default:** Standard permission model (asks user)
+
+**Security note:** Use restrictive modes (`plan`, `acceptEdits`) for untrusted agents. `bypassPermissions` should only be used for fully trusted agents.
+
 ## System Prompt Design
 
 The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
@@ -421,6 +459,24 @@ Create test scenarios to verify agent triggers correctly:
 3. Check Claude loads the agent
 4. Verify agent provides expected functionality
 
+### Load Agents at Session Start
+
+Use the `--agents` CLI flag to pre-load specific agents:
+
+```bash
+# Load single agent
+claude --agents code-reviewer
+
+# Load multiple agents
+claude --agents "code-reviewer,test-generator"
+```
+
+**Use cases:**
+
+- Testing agent behavior without triggering
+- Workflows requiring specific agents
+- Debugging agent system prompts
+
 ### Test System Prompt
 
 Ensure system prompt is complete:
@@ -455,13 +511,15 @@ Output: [What to provide]
 
 ### Frontmatter Fields Summary
 
-| Field       | Required | Format                     | Example                  |
-| ----------- | -------- | -------------------------- | ------------------------ |
-| name        | Yes      | lowercase-hyphens          | code-reviewer            |
-| description | Yes      | Text + examples            | Use when... <example>... |
-| model       | Yes      | inherit/sonnet/opus/haiku  | inherit                  |
-| color       | Yes      | Color name                 | blue                     |
-| tools       | No       | Comma-separated tool names | Read, Grep               |
+| Field          | Required | Format                     | Example                  |
+| -------------- | -------- | -------------------------- | ------------------------ |
+| name           | Yes      | lowercase-hyphens          | code-reviewer            |
+| description    | Yes      | Text + examples            | Use when... <example>... |
+| model          | Yes      | inherit/sonnet/opus/haiku  | inherit                  |
+| color          | Yes      | Color name                 | blue                     |
+| tools          | No       | Comma-separated tool names | Read, Grep               |
+| skills         | No       | Array of skill names       | [testing, security]      |
+| permissionMode | No       | Permission mode string     | acceptEdits              |
 
 > **Note:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. The field names differ between component types.
 

plugins/plugin-dev/skills/hook-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hook-development
-description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
+description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, SubagentStop, SubagentStart, Setup, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
 ---
 
 # Hook Development for Claude Code Plugins
@@ -235,6 +235,33 @@ Execute after tool completes. Use to react to results, provide feedback, or log.
 - Exit 2: stderr fed back to Claude
 - systemMessage included in context
 
+### PostToolUseFailure
+
+Execute when a tool fails after PostToolUse hooks have run. Use to handle errors or provide fallback actions.
+
+**Example:**
+
+```json
+{
+  "PostToolUseFailure": [
+    {
+      "matcher": "Edit",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Error occurred during edit. Provide fallback action or ask for user input."
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Output behavior:**
+
+- Exit 2: stderr fed back to Claude
+- systemMessage included in context
+
 ### Stop
 
 Execute when main agent considers stopping. Use to validate completeness.
@@ -273,6 +300,50 @@ Execute when subagent considers stopping. Use to ensure subagent completed its t
 
 Similar to Stop hook, but for subagents.
 
+### SubagentStart
+
+Execute when a subagent is started. Use to initialize subagent state or perform setup.
+
+**Example:**
+
+```json
+{
+  "SubagentStart": [
+    {
+      "matcher": "mcp__subagent_name",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/subagent-init.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Setup
+
+Execute once at session start to perform global setup or initialize resources.
+
+**Example:**
+
+```json
+{
+  "Setup": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/session-setup.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
 ### UserPromptSubmit
 
 Execute when user submits a prompt. Use to add context, validate, or block prompts.
@@ -647,18 +718,21 @@ echo "$output" | jq .
 
 ### Hook Events Summary
 
-| Event             | When              | Use For                  |
-| ----------------- | ----------------- | ------------------------ |
-| PreToolUse        | Before tool       | Validation, modification |
-| PermissionRequest | Permission dialog | Auto-allow/deny          |
-| PostToolUse       | After tool        | Feedback, logging        |
-| UserPromptSubmit  | User input        | Context, validation      |
-| Stop              | Agent stopping    | Completeness check       |
-| SubagentStop      | Subagent done     | Task validation          |
-| SessionStart      | Session begins    | Context loading          |
-| SessionEnd        | Session ends      | Cleanup, logging         |
-| PreCompact        | Before compact    | Preserve context         |
-| Notification      | User notified     | Logging, reactions       |
+| Event              | When               | Use For                  |
+| ------------------ | ------------------ | ------------------------ |
+| Setup              | Session init       | Global initialization    |
+| PreToolUse         | Before tool        | Validation, modification |
+| PermissionRequest  | Permission dialog  | Auto-allow/deny          |
+| PostToolUse        | After tool success | Feedback, logging        |
+| PostToolUseFailure | After tool fails   | Error handling           |
+| UserPromptSubmit   | User input         | Context, validation      |
+| Stop               | Agent stopping     | Completeness check       |
+| SubagentStart      | Subagent begins    | Subagent setup           |
+| SubagentStop       | Subagent done      | Task validation          |
+| SessionStart       | Session begins     | Context loading          |
+| SessionEnd         | Session ends       | Cleanup, logging         |
+| PreCompact         | Before compact     | Preserve context         |
+| Notification       | User notified      | Logging, reactions       |
 
 ### Best Practices