feat: sync documentation with official Claude Code docs (#192)

## Description

Comprehensive update to align plugin-dev documentation with official
Claude Code documentation. This PR addresses gaps identified by
comparing the official docs against plugin-dev's teaching content, adds
missing features, corrects outdated information, and introduces a new
LSP integration skill.

## Type of Change

- [x] New feature (non-breaking change that adds functionality)
- [x] Documentation update (improvements to README, CLAUDE.md, or
component docs)

## Component(s) Affected

- [x] Commands (`/plugin-dev:*`)
- [x] Skills (methodology and best practices)
- [x] Agents (plugin-validator, skill-reviewer, agent-creator)
- [x] Marketplace (marketplace.json, distribution)
- [x] Documentation (README.md, CLAUDE.md, SECURITY.md)
- [x] Configuration (.markdownlint.json, plugin.json)

## Motivation and Context

The plugin-dev plugin teaches users how to develop Claude Code plugins,
but some of its documentation had become outdated compared to the
official Claude Code documentation. This PR:

1. Adds 3 missing hook events (Setup, PostToolUseFailure, SubagentStart)
2. Documents new skill frontmatter fields (context, agent, skills)
3. Documents new agent frontmatter fields (skills, permissionMode)
4. Adds MCP resource syntax and Tool Search documentation
5. Creates new LSP integration skill for language server configuration
6. Updates agents and commands to use the new skill

## How Has This Been Tested?

**Test Configuration**:
- Claude Code version: Latest
- GitHub CLI version: 2.x
- OS: macOS Darwin 25.2.0

**Test Steps**:
1. Loaded plugin with `claude --plugin-dir plugins/plugin-dev`
2. Verified all skills load and trigger correctly
3. Confirmed new LSP integration skill appears in skill list
4. Tested skill-reviewer agent recognizes new frontmatter fields

## Checklist

### General

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas
(if applicable)
- [x] My changes generate no new warnings or errors

### Documentation

- [x] I have updated the documentation accordingly (README.md,
CLAUDE.md, or component docs)
- [x] I have updated YAML frontmatter (if applicable)
- [x] I have verified all links work correctly

### Markdown

- [x] My markdown follows the repository style (ATX headers, dash lists,
fenced code blocks)
- [x] I have verified special HTML elements are properly closed (`<p>`,
`<img>`, `<example>`, `<commentary>`)

### Version Management (if applicable)

- [x] I have updated `plugins/plugin-dev/.claude-plugin/plugin.json`
(source of truth)
- [x] I have updated `.claude-plugin/marketplace.json` (metadata.version
AND plugins[0].version)
- [x] I have updated `CLAUDE.md` (version line)
- [ ] I have updated CHANGELOG.md with relevant changes

## Summary of Changes

### Skills Updated

| Skill | Changes |
|-------|---------|
| hook-development | Added Setup, PostToolUseFailure, SubagentStart
events; updated event count to 12 |
| skill-development | Added context/agent/skills frontmatter; dynamic
context injection; string substitutions |
| agent-development | Added skills/permissionMode frontmatter; --agents
CLI flag docs |
| mcp-integration | Added @resource syntax; Tool Search; managed MCP
controls |
| plugin-structure | Added lspServers/outputStyles components; caching
explanation |

### New Skill

| Skill | Description |
|-------|-------------|
| lsp-integration | New skill for LSP server configuration,
extensionToLanguage mappings, pre-built plugins |

### Agents Updated

| Agent | Changes |
|-------|---------|
| plugin-validator | Added LSP validation section; expanded skills list
|
| skill-reviewer | Updated optional fields for new frontmatter |
| agent-creator | Added skills/permissionMode to configuration section |

### Commands Updated

| Command | Changes |
|---------|---------|
| create-plugin | Added LSP to component planning and Phase 5 |

### Version Bump

- 0.2.1 → 0.3.0 (now 9 skills, was 8)

## Reviewer Notes

**Areas that need special attention**:
- New LSP integration skill content accuracy
- Hook events list completeness (now 12 events vs 10 before)
- New frontmatter fields documentation

**Known limitations or trade-offs**:
- CHANGELOG.md not yet updated (can be done before merge)
- Some LSP server recommendations may become outdated as ecosystem
evolves

---

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: sjnims

.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