From 71ab1585e8d389d6fda9688cbd6f4e83ffdcc508 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 24 Jan 2026 19:33:57 -0500
Subject: [PATCH 1/8] docs: align tools/allowed-tools format with official
 Claude Code docs

- Use comma-separated format for tools and allowed-tools fields
  (e.g., `tools: Read, Write, Grep` not `tools: ["Read", "Write"]`)
- Fix code fence nesting in complete-agent-examples.md
- Add "Fields NOT Available for Agents" section clarifying skill-only
  fields (context: fork, user-invocable, disable-model-invocation)
- Add portable paths note about ${CLAUDE_PLUGIN_ROOT} for agents
- Remove YAML array format examples from frontmatter-reference.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../skills/agent-development/SKILL.md         | 24 ++++++++++++++++++
 .../examples/agent-creation-prompt.md         |  4 +--
 .../examples/complete-agent-examples.md       | 18 ++++++-------
 .../references/frontmatter-reference.md       |  9 ++-----
 .../skills/mcp-integration/SKILL.md           | 17 ++++---------
 .../mcp-integration/references/tool-usage.md  | 25 ++++---------------
 6 files changed, 46 insertions(+), 51 deletions(-)

diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md
index 01b423f..e1fa8c4 100644
--- a/plugins/plugin-dev/skills/agent-development/SKILL.md
+++ b/plugins/plugin-dev/skills/agent-development/SKILL.md
@@ -293,6 +293,20 @@ permissionMode: acceptEdits
 
 **Security note:** Use restrictive modes (`plan`, `acceptEdits`) for untrusted agents. `bypassPermissions` should only be used for fully trusted agents.
 
+### Fields NOT Available for Agents
+
+Some frontmatter fields are specific to skills and do not apply to agents:
+
+| Skill-Only Field             | Purpose                                | Why Not for Agents                                      |
+| ---------------------------- | -------------------------------------- | ------------------------------------------------------- |
+| `context: fork`              | Run skill in separate subagent context | Agents already run as subprocesses by design            |
+| `agent`                      | Specify agent type for forked context  | Only applies when `context: fork` is set                |
+| `user-invocable`             | Control slash menu visibility          | Agents aren't invoked via slash commands                |
+| `disable-model-invocation`   | Block programmatic Skill tool usage    | Agents use Task tool, not Skill tool                    |
+| `allowed-tools`              | Restrict tool access (skill syntax)    | Agents use `tools` field instead (different field name) |
+
+**Key distinction:** Skills provide knowledge and guidance that loads into context. Agents are autonomous subprocesses that execute independently. This architectural difference explains why context-forking options don't apply to agents—they're already isolated processes.
+
 ## System Prompt Design
 
 The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
@@ -441,6 +455,16 @@ plugin-name/
 
 All `.md` files in `agents/` are auto-discovered.
 
+### Portable Paths
+
+When referencing files within your plugin (scripts, references, etc.) from agent system prompts, use `${CLAUDE_PLUGIN_ROOT}` for portable paths:
+
+```markdown
+Run the validation script at `${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`
+```
+
+This variable resolves to the plugin's installation directory at runtime, ensuring paths work regardless of where the plugin is installed.
+
 ### Namespacing
 
 Agents are namespaced automatically:
diff --git a/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md b/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md
index f41bb34..9d3be60 100644
--- a/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md
+++ b/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md
@@ -47,7 +47,7 @@ name: [identifier from JSON]
 description: [whenToUse from JSON]
 model: inherit
 color: [choose: blue/cyan/green/yellow/magenta/red]
-tools: ["Read", "Write", "Grep"] # Optional: restrict tools
+tools: Read, Write, Grep  # Optional: restrict tools
 ---
 
 [systemPrompt from JSON]
@@ -101,7 +101,7 @@ Explicit review request triggers the agent.
 
 model: inherit
 color: blue
-tools: ["Read", "Grep", "Glob"]
+tools: Read, Grep, Glob
 ---
 
 You are an expert code quality reviewer specializing in identifying issues in software implementations.
diff --git a/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md b/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md
index f31848a..6bd3c02 100644
--- a/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md
+++ b/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md
@@ -43,7 +43,7 @@ assistant: "I'll use the code-reviewer agent to validate the changes."
 
 model: inherit
 color: blue
-tools: ["Read", "Grep", "Glob"]
+tools: Read, Grep, Glob
 ---
 
 You are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and opportunities for improvement in software implementations.
@@ -152,7 +152,7 @@ Direct test generation request triggers the agent.
 
 model: inherit
 color: green
-tools: ["Read", "Write", "Grep", "Bash"]
+tools: Read, Write, Grep, Bash
 ---
 
 You are an expert test engineer specializing in creating comprehensive, maintainable unit tests that ensure code correctness and reliability.
@@ -214,7 +214,6 @@ describe('[module name]', () => {
   // More tests...
 })
 ```
-````
 
 **Edge Cases:**
 
@@ -223,14 +222,13 @@ describe('[module name]', () => {
 - Unclear behavior: Add tests for observable behavior, note uncertainties
 - Complex mocking: Prefer integration tests or minimal mocking
 - Untestable code: Suggest refactoring for testability
-
 ````
 
 ## Example 3: Documentation Generator
 
 **File:** `agents/docs-generator.md`
 
-```markdown
+````markdown
 ---
 name: docs-generator
 description: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples:
@@ -256,7 +254,7 @@ Explicit documentation request triggers the agent.
 
 model: inherit
 color: cyan
-tools: ["Read", "Write", "Grep", "Glob"]
+tools: Read, Write, Grep, Glob
 ---
 
 You are an expert technical writer specializing in creating clear, comprehensive documentation for software projects.
@@ -341,7 +339,7 @@ Explicit security review request triggers the agent.
 
 model: inherit
 color: red
-tools: ["Read", "Grep", "Glob"]
+tools: Read, Grep, Glob
 ---
 
 You are an expert security analyst specializing in identifying vulnerabilities and security issues in software implementations.
@@ -429,9 +427,9 @@ Take these templates and customize:
 
 Restrict or expand based on agent needs:
 
-- **Read-only agents**: `["Read", "Grep", "Glob"]`
-- **Generator agents**: `["Read", "Write", "Grep"]`
-- **Executor agents**: `["Read", "Write", "Bash", "Grep"]`
+- **Read-only agents**: `Read, Grep, Glob`
+- **Generator agents**: `Read, Write, Grep`
+- **Executor agents**: `Read, Write, Bash, Grep`
 - **Full access**: Omit tools field
 
 ### Customize Colors
diff --git a/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md b/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md
index b43bb47..885d840 100644
--- a/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md
+++ b/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md
@@ -65,7 +65,7 @@ description: Generate API documentation
 
 ### allowed-tools
 
-**Type:** String or Array of strings
+**Type:** Comma-separated string
 **Required:** No
 **Default:** Inherits from conversation permissions
 
@@ -85,13 +85,8 @@ allowed-tools: Read
 allowed-tools: Read, Write, Edit
 ```
 
-**Multiple tools (array):**
-
 ```yaml
-allowed-tools:
-  - Read
-  - Write
-  - Bash(git:*)
+allowed-tools: Read, Write, Bash(git:*)
 ```
 
 **Tool Patterns:**
diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md
index 150ce1c..462c90d 100644
--- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md
+++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md
@@ -285,11 +285,7 @@ Pre-allow specific MCP tools in command frontmatter:
 
 ```markdown
 ---
-allowed-tools:
-  [
-    "mcp__plugin_asana_asana__asana_create_task",
-    "mcp__plugin_asana_asana__asana_search_tasks",
-  ]
+allowed-tools: mcp__plugin_asana_asana__asana_create_task, mcp__plugin_asana_asana__asana_search_tasks
 ---
 ```
 
@@ -297,7 +293,7 @@ allowed-tools:
 
 ```markdown
 ---
-allowed-tools: ["mcp__plugin_asana_asana__*"]
+allowed-tools: mcp__plugin_asana_asana__*
 ---
 ```
 
@@ -380,7 +376,7 @@ Commands use MCP tools with user interaction:
 
 ---
 
-## allowed-tools: ["mcp__plugin_name_server__create_item"]
+allowed-tools: mcp__plugin_name_server__create_item
 
 Steps:
 
@@ -456,12 +452,9 @@ Always use secure connections:
 Pre-allow only necessary MCP tools:
 
 ```markdown
-✅ allowed-tools: [
-"mcp__plugin_api_server__read_data",
-"mcp__plugin_api_server__create_item"
-]
+✅ allowed-tools: mcp__plugin_api_server__read_data, mcp__plugin_api_server__create_item
 
-❌ allowed-tools: ["mcp__plugin_api_server__*"]
+❌ allowed-tools: mcp__plugin_api_server__*
 ```
 
 ### Managed MCP Controls (Enterprise)
diff --git a/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md b/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
index 4d9b79a..0754608 100644
--- a/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
+++ b/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
@@ -52,7 +52,7 @@ Specify MCP tools in command frontmatter:
 ```markdown
 ---
 description: Create a new Asana task
-allowed-tools: ["mcp__plugin_asana_asana__asana_create_task"]
+allowed-tools: mcp__plugin_asana_asana__asana_create_task
 ---
 
 # Create Task Command
@@ -68,12 +68,7 @@ To create a task:
 
 ```markdown
 ---
-allowed-tools:
-  [
-    "mcp__plugin_asana_asana__asana_create_task",
-    "mcp__plugin_asana_asana__asana_search_tasks",
-    "mcp__plugin_asana_asana__asana_get_project",
-  ]
+allowed-tools: mcp__plugin_asana_asana__asana_create_task, mcp__plugin_asana_asana__asana_search_tasks, mcp__plugin_asana_asana__asana_get_project
 ---
 ```
 
@@ -81,7 +76,7 @@ allowed-tools:
 
 ```markdown
 ---
-allowed-tools: ["mcp__plugin_asana_asana__*"]
+allowed-tools: mcp__plugin_asana_asana__*
 ---
 ```
 
@@ -94,11 +89,7 @@ allowed-tools: ["mcp__plugin_asana_asana__*"]
 ```markdown
 ---
 description: Search and create Asana tasks
-allowed-tools:
-  [
-    "mcp__plugin_asana_asana__asana_search_tasks",
-    "mcp__plugin_asana_asana__asana_create_task",
-  ]
+allowed-tools: mcp__plugin_asana_asana__asana_search_tasks, mcp__plugin_asana_asana__asana_create_task
 ---
 
 # Asana Task Management
@@ -489,13 +480,7 @@ Steps:
 
 ```markdown
 ---
-allowed-tools:
-  [
-    "mcp__plugin_api_server__create_item",
-    "mcp__plugin_api_server__read_item",
-    "mcp__plugin_api_server__update_item",
-    "mcp__plugin_api_server__delete_item",
-  ]
+allowed-tools: mcp__plugin_api_server__create_item, mcp__plugin_api_server__read_item, mcp__plugin_api_server__update_item, mcp__plugin_api_server__delete_item
 ---
 
 # Item Management

From a43b5c4f36c182f1b58b3f0a770d65e2e5b399e8 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 24 Jan 2026 19:42:29 -0500
Subject: [PATCH 2/8] docs(agent-development): trim SKILL.md to target word
 count

Remove redundant content to bring word count from 2,409 to 2,199:
- Condense System Prompt Design section (detailed templates in references/)
- Remove Implementation Workflow (duplicates Creating Agents)
- Remove Minimal Agent from Quick Reference (duplicates Quick Start)
- Remove duplicate skill cross-references (covered in See also block)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../skills/agent-development/SKILL.md         | 103 ++----------------
 1 file changed, 11 insertions(+), 92 deletions(-)

diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md
index e1fa8c4..21d571a 100644
--- a/plugins/plugin-dev/skills/agent-development/SKILL.md
+++ b/plugins/plugin-dev/skills/agent-development/SKILL.md
@@ -80,8 +80,6 @@ For complete format with all options, see [Agent File Structure](#agent-file-str
 - Action should not happen automatically
 - Workflow requires user confirmation at each step
 
-For command development guidance, see the `command-development` skill.
-
 ### Choose Skills When
 
 - Providing knowledge or procedural guidance
@@ -89,8 +87,6 @@ For command development guidance, see the `command-development` skill.
 - No autonomous execution needed
 - Information should be available contextually on-demand
 
-For skill development guidance, see the `skill-development` skill.
-
 ## Agent File Structure
 
 ### Complete Format
@@ -311,64 +307,23 @@ Some frontmatter fields are specific to skills and do not apply to agents:
 
 The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
 
-### Structure
-
-**Standard template:**
-
-```markdown
-You are [role] specializing in [domain].
-
-**Your Core Responsibilities:**
-
-1. [Primary responsibility]
-2. [Secondary responsibility]
-3. [Additional responsibilities...]
-
-**Analysis Process:**
-
-1. [Step one]
-2. [Step two]
-3. [Step three]
-   [...]
-
-**Quality Standards:**
-
-- [Standard 1]
-- [Standard 2]
-
-**Output Format:**
-Provide results in this format:
-
-- [What to include]
-- [How to structure]
-
-**Edge Cases:**
-Handle these situations:
-
-- [Edge case 1]: [How to handle]
-- [Edge case 2]: [How to handle]
-```
+**Key elements:**
 
-### Best Practices
+- Role definition ("You are [role] specializing in [domain]")
+- Core responsibilities (numbered list)
+- Process steps (concrete, actionable)
+- Quality standards (measurable criteria)
+- Output format (specific structure)
+- Edge cases (how to handle exceptions)
 
-✅ **DO:**
+**Best practices:**
 
 - Write in second person ("You are...", "You will...")
-- Be specific about responsibilities
-- Provide step-by-step process
-- Define output format
-- Include quality standards
-- Address edge cases
+- Be specific, not vague
 - Keep under 10,000 characters
+- Include concrete steps, not generic instructions
 
-❌ **DON'T:**
-
-- Write in first person ("I am...", "I will...")
-- Be vague or generic
-- Omit process steps
-- Leave output format undefined
-- Skip quality guidance
-- Ignore error cases
+For detailed templates and patterns (Analysis, Generation, Validation, Orchestration agents), see `references/system-prompt-design.md`.
 
 ## Creating Agents
 
@@ -513,26 +468,6 @@ Ensure system prompt is complete:
 
 ## Quick Reference
 
-### Minimal Agent
-
-```markdown
----
-name: simple-agent
-description: Use this agent when... Examples: <example>...</example>
-model: inherit
-color: blue
----
-
-You are an agent that [does X].
-
-Process:
-
-1. [Step 1]
-2. [Step 2]
-
-Output: [What to provide]
-```
-
 ### Frontmatter Fields Summary
 
 | Field          | Required | Format                     | Example                  |
@@ -591,19 +526,3 @@ Development tools in `scripts/`:
 - **`create-agent-skeleton.sh`** - Generate new agent file from template
 - **`validate-agent.sh`** - Validate agent file structure
 - **`test-agent-trigger.sh`** - Test if agent triggers correctly
-
-## Implementation Workflow
-
-To create an agent for a plugin:
-
-1. Define agent purpose and triggering conditions
-2. Choose creation method (AI-assisted or manual)
-3. Create agent file using skeleton: `./skills/agent-development/scripts/create-agent-skeleton.sh agent-name agents/`
-4. Write frontmatter with all required fields
-5. Write system prompt following best practices
-6. Include 2-4 triggering examples in description
-7. Validate with `./skills/agent-development/scripts/validate-agent.sh agents/your-agent.md`
-8. Test triggering with real scenarios
-9. Document agent in plugin README
-
-Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.

From 4fa4c791ba1489e5b1c4eef9d51fc949166da1cf Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 24 Jan 2026 20:07:06 -0500
Subject: [PATCH 3/8] docs(lsp-integration): expand skill with official docs
 alignment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add .lsp.json separate file configuration option
- Document 8 missing optional fields (transport, initializationOptions,
  settings, workspaceFolder, startupTimeout, shutdownTimeout,
  restartOnCrash, maxRestarts)
- Add "What Claude Gains from LSP" section
- Update pre-built plugins table with 11 languages
- Create references/lsp-capabilities.md (was referenced but missing)
- Add examples/minimal-lsp-plugin/ with complete Go LSP plugin
- Add examples/lsp-json-configs.md with 10 configuration patterns

Word count: 961 → 1,284 (now within 1,000-2,200 target)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../skills/lsp-integration/SKILL.md           | 119 ++++++---
 .../examples/lsp-json-configs.md              | 242 ++++++++++++++++++
 .../.claude-plugin/plugin.json                |  14 +
 .../examples/minimal-lsp-plugin/README.md     |  40 +++
 .../references/lsp-capabilities.md            | 157 ++++++++++++
 5 files changed, 533 insertions(+), 39 deletions(-)
 create mode 100644 plugins/plugin-dev/skills/lsp-integration/examples/lsp-json-configs.md
 create mode 100644 plugins/plugin-dev/skills/lsp-integration/examples/minimal-lsp-plugin/.claude-plugin/plugin.json
 create mode 100644 plugins/plugin-dev/skills/lsp-integration/examples/minimal-lsp-plugin/README.md
 create mode 100644 plugins/plugin-dev/skills/lsp-integration/references/lsp-capabilities.md

diff --git a/plugins/plugin-dev/skills/lsp-integration/SKILL.md b/plugins/plugin-dev/skills/lsp-integration/SKILL.md
index 828aa7b..4f35db4 100644
--- a/plugins/plugin-dev/skills/lsp-integration/SKILL.md
+++ b/plugins/plugin-dev/skills/lsp-integration/SKILL.md
@@ -38,6 +38,31 @@ Plugins can provide LSP servers in the plugin manifest:
 }
 ```
 
+### Separate File Configuration
+
+LSP servers can also be configured in a separate `.lsp.json` file at the plugin root:
+
+```json
+{
+  "go": {
+    "command": "gopls",
+    "args": ["serve"],
+    "extensionToLanguage": {
+      ".go": "go"
+    }
+  }
+}
+```
+
+Reference this file in `plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "lspServers": "./.lsp.json"
+}
+```
+
 ### Configuration Fields
 
 **command** (required): The LSP server executable
@@ -66,59 +91,70 @@ Plugins can provide LSP servers in the plugin manifest:
 }
 ```
 
-## Pre-built LSP Plugins
+**transport** (optional): Communication transport - `stdio` (default) or `socket`
 
-Claude Code provides official LSP plugins for common languages:
+**initializationOptions** (optional): Options passed to the server during LSP initialization
 
-### pyright-lsp
+**settings** (optional): Settings passed via `workspace/didChangeConfiguration`
 
-Python language server using Pyright:
+**workspaceFolder** (optional): Workspace folder path for the server
 
-```bash
-# Install from marketplace
-claude /install-plugin pyright-lsp
-```
+**startupTimeout** (optional): Maximum time to wait for server startup in milliseconds
 
-Features:
+**shutdownTimeout** (optional): Maximum time to wait for graceful shutdown in milliseconds
 
-- Type checking and inference
-- Go-to-definition
-- Find references
-- Hover documentation
-- Completions
+**restartOnCrash** (optional): Whether to automatically restart the server if it crashes
 
-### typescript-lsp
+**maxRestarts** (optional): Maximum number of restart attempts before giving up
 
-TypeScript/JavaScript language server:
+## What Claude Gains from LSP
 
-```bash
-# Install from marketplace
-claude /install-plugin typescript-lsp
-```
+When an LSP plugin is installed and its language server binary is available, Claude gains two key capabilities:
+
+### Automatic Diagnostics
+
+After every file edit Claude makes, the language server analyzes the changes and reports errors and warnings back automatically. Claude sees type errors, missing imports, and syntax issues without needing to run a compiler or linter. If Claude introduces an error, it notices and fixes the issue in the same turn.
+
+### Code Navigation
 
-Features:
+Claude can use the language server to:
 
-- TypeScript and JavaScript support
-- Type information on hover
-- Go-to-definition
-- Find references
-- Rename symbol
+- Jump to definitions
+- Find all references to a symbol
+- Get type information on hover
+- List symbols in a file
+- Find implementations of interfaces
+- Trace call hierarchies
 
-### rust-lsp
+These operations give Claude more precise navigation than grep-based search.
 
-Rust language server using rust-analyzer:
+## Pre-built LSP Plugins
+
+Claude Code provides official LSP plugins for common languages. Install from the marketplace:
+
+| Language   | Plugin              | Binary Required              |
+| ---------- | ------------------- | ---------------------------- |
+| C/C++      | `clangd-lsp`        | `clangd`                     |
+| C#         | `csharp-lsp`        | `csharp-ls`                  |
+| Go         | `gopls-lsp`         | `gopls`                      |
+| Java       | `jdtls-lsp`         | `jdtls`                      |
+| Kotlin     | `kotlin-lsp`        | `kotlin-language-server`     |
+| Lua        | `lua-lsp`           | `lua-language-server`        |
+| PHP        | `php-lsp`           | `intelephense`               |
+| Python     | `pyright-lsp`       | `pyright-langserver`         |
+| Rust       | `rust-analyzer-lsp` | `rust-analyzer`              |
+| Swift      | `swift-lsp`         | `sourcekit-lsp`              |
+| TypeScript | `typescript-lsp`    | `typescript-language-server` |
+
+Install the language server binary first, then install the plugin:
 
 ```bash
-# Install from marketplace
-claude /install-plugin rust-lsp
+# Example: Python
+pip install pyright  # or: npm install -g pyright
+claude /install-plugin pyright-lsp
 ```
 
-Features:
-
-- Full rust-analyzer capabilities
-- Trait resolution
-- Macro expansion
-- Go-to-definition and references
+**Troubleshooting**: If you see `Executable not found in $PATH` in the `/plugin` Errors tab, install the required binary from the table above.
 
 ## Creating Custom LSP Integration
 
@@ -364,11 +400,16 @@ Look for:
 
 For detailed information, consult:
 
-- **`references/popular-lsp-servers.md`** - Curated list of LSP servers by language
-- **`references/lsp-capabilities.md`** - LSP protocol capabilities reference
+- **`references/popular-lsp-servers.md`** - Curated list of LSP servers by language with installation commands
+- **`references/lsp-capabilities.md`** - LSP protocol capabilities and what they enable
+
+### Examples
+
+- **`examples/minimal-lsp-plugin/`** - Complete directory structure for a minimal LSP plugin
+- **`examples/lsp-json-configs.md`** - Various `.lsp.json` configuration patterns
 
 ### External Resources
 
 - **LSP Specification**: <https://microsoft.github.io/language-server-protocol/>
-- **Claude Code Plugins Reference**: <https://docs.claude.com/en/docs/claude-code/plugins-reference>
+- **Claude Code Plugins Reference**: <https://docs.anthropic.com/en/docs/claude-code/plugins-reference>
 - **Language Server List**: <https://langserver.org/>
diff --git a/plugins/plugin-dev/skills/lsp-integration/examples/lsp-json-configs.md b/plugins/plugin-dev/skills/lsp-integration/examples/lsp-json-configs.md
new file mode 100644
index 0000000..82dbae5
--- /dev/null
+++ b/plugins/plugin-dev/skills/lsp-integration/examples/lsp-json-configs.md
@@ -0,0 +1,242 @@
+# LSP Configuration Patterns
+
+Copy-paste ready `.lsp.json` configurations for common scenarios.
+
+## Minimal Configuration
+
+The simplest possible LSP configuration:
+
+```json
+{
+  "python": {
+    "command": "pyright-langserver",
+    "args": ["--stdio"],
+    "extensionToLanguage": {
+      ".py": "python"
+    }
+  }
+}
+```
+
+## Multiple Languages
+
+Configure multiple language servers in one file:
+
+```json
+{
+  "python": {
+    "command": "pyright-langserver",
+    "args": ["--stdio"],
+    "extensionToLanguage": {
+      ".py": "python",
+      ".pyi": "python"
+    }
+  },
+  "typescript": {
+    "command": "typescript-language-server",
+    "args": ["--stdio"],
+    "extensionToLanguage": {
+      ".ts": "typescript",
+      ".tsx": "typescriptreact",
+      ".js": "javascript",
+      ".jsx": "javascriptreact"
+    }
+  }
+}
+```
+
+## With Environment Variables
+
+Pass environment variables to the server:
+
+```json
+{
+  "python": {
+    "command": "pyright-langserver",
+    "args": ["--stdio"],
+    "extensionToLanguage": {
+      ".py": "python"
+    },
+    "env": {
+      "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/lib",
+      "VIRTUAL_ENV": "${CLAUDE_PLUGIN_ROOT}/.venv"
+    }
+  }
+}
+```
+
+## With Initialization Options
+
+Pass options during server initialization:
+
+```json
+{
+  "rust": {
+    "command": "rust-analyzer",
+    "extensionToLanguage": {
+      ".rs": "rust"
+    },
+    "initializationOptions": {
+      "cargo": {
+        "buildScripts": {
+          "enable": true
+        }
+      },
+      "procMacro": {
+        "enable": true
+      }
+    }
+  }
+}
+```
+
+## With Runtime Settings
+
+Pass settings after initialization:
+
+```json
+{
+  "typescript": {
+    "command": "typescript-language-server",
+    "args": ["--stdio"],
+    "extensionToLanguage": {
+      ".ts": "typescript"
+    },
+    "settings": {
+      "typescript": {
+        "inlayHints": {
+          "parameterNames": {
+            "enabled": "all"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## With Timeouts and Restart Policy
+
+Configure server lifecycle:
+
+```json
+{
+  "java": {
+    "command": "jdtls",
+    "extensionToLanguage": {
+      ".java": "java"
+    },
+    "startupTimeout": 60000,
+    "shutdownTimeout": 5000,
+    "restartOnCrash": true,
+    "maxRestarts": 3
+  }
+}
+```
+
+## Bundled Server
+
+Reference a server bundled with the plugin:
+
+```json
+{
+  "custom": {
+    "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-lsp-server",
+    "args": ["--stdio"],
+    "extensionToLanguage": {
+      ".custom": "custom-lang"
+    },
+    "env": {
+      "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config/server.json"
+    }
+  }
+}
+```
+
+## Socket Transport
+
+Use socket instead of stdio:
+
+```json
+{
+  "php": {
+    "command": "intelephense",
+    "args": ["--socket=6000"],
+    "transport": "socket",
+    "extensionToLanguage": {
+      ".php": "php"
+    }
+  }
+}
+```
+
+## Full Configuration Example
+
+All options together:
+
+```json
+{
+  "go": {
+    "command": "gopls",
+    "args": ["serve", "-rpc.trace"],
+    "transport": "stdio",
+    "extensionToLanguage": {
+      ".go": "go",
+      ".mod": "go.mod",
+      ".sum": "go.sum"
+    },
+    "env": {
+      "GOFLAGS": "-mod=vendor"
+    },
+    "initializationOptions": {
+      "usePlaceholders": true,
+      "completeUnimported": true
+    },
+    "settings": {
+      "gopls": {
+        "staticcheck": true,
+        "analyses": {
+          "unusedparams": true
+        }
+      }
+    },
+    "workspaceFolder": "${workspaceFolder}",
+    "startupTimeout": 30000,
+    "shutdownTimeout": 5000,
+    "restartOnCrash": true,
+    "maxRestarts": 5
+  }
+}
+```
+
+## Inline in plugin.json
+
+Instead of a separate `.lsp.json`, configure inline:
+
+```json
+{
+  "name": "my-lsp-plugin",
+  "version": "1.0.0",
+  "description": "Language server integration",
+  "lspServers": {
+    "python": {
+      "command": "pyright-langserver",
+      "args": ["--stdio"],
+      "extensionToLanguage": {
+        ".py": "python"
+      }
+    }
+  }
+}
+```
+
+Or reference an external file:
+
+```json
+{
+  "name": "my-lsp-plugin",
+  "version": "1.0.0",
+  "description": "Language server integration",
+  "lspServers": "./.lsp.json"
+}
+```
diff --git a/plugins/plugin-dev/skills/lsp-integration/examples/minimal-lsp-plugin/.claude-plugin/plugin.json b/plugins/plugin-dev/skills/lsp-integration/examples/minimal-lsp-plugin/.claude-plugin/plugin.json
new file mode 100644
index 0000000..607c377
--- /dev/null
+++ b/plugins/plugin-dev/skills/lsp-integration/examples/minimal-lsp-plugin/.claude-plugin/plugin.json
@@ -0,0 +1,14 @@
+{
+  "name": "go-lsp",
+  "version": "1.0.0",
+  "description": "Go language server integration for Claude Code",
+  "lspServers": {
+    "go": {
+      "command": "gopls",
+      "args": ["serve"],
+      "extensionToLanguage": {
+        ".go": "go"
+      }
+    }
+  }
+}
diff --git a/plugins/plugin-dev/skills/lsp-integration/examples/minimal-lsp-plugin/README.md b/plugins/plugin-dev/skills/lsp-integration/examples/minimal-lsp-plugin/README.md
new file mode 100644
index 0000000..56a2b63
--- /dev/null
+++ b/plugins/plugin-dev/skills/lsp-integration/examples/minimal-lsp-plugin/README.md
@@ -0,0 +1,40 @@
+# Go LSP Plugin
+
+Provides Go language server integration for Claude Code.
+
+## Prerequisites
+
+Install gopls (the Go language server):
+
+```bash
+go install golang.org/x/tools/gopls@latest
+```
+
+Ensure `gopls` is in your PATH:
+
+```bash
+which gopls
+```
+
+## Installation
+
+```bash
+claude /install-plugin /path/to/go-lsp
+```
+
+## Features
+
+Once installed, Claude gains:
+
+- **Automatic diagnostics** - Type errors and issues reported after edits
+- **Go to definition** - Jump to where functions and types are defined
+- **Find references** - Locate all usages of a symbol
+- **Hover information** - See type info and documentation
+
+## Troubleshooting
+
+If you see "Executable not found in $PATH":
+
+1. Verify gopls is installed: `which gopls`
+2. Add Go bin to PATH: `export PATH=$PATH:$(go env GOPATH)/bin`
+3. Restart Claude Code
diff --git a/plugins/plugin-dev/skills/lsp-integration/references/lsp-capabilities.md b/plugins/plugin-dev/skills/lsp-integration/references/lsp-capabilities.md
new file mode 100644
index 0000000..a002c35
--- /dev/null
+++ b/plugins/plugin-dev/skills/lsp-integration/references/lsp-capabilities.md
@@ -0,0 +1,157 @@
+# LSP Protocol Capabilities
+
+Overview of Language Server Protocol capabilities and what they enable for Claude Code.
+
+## Core Capabilities
+
+### Text Document Synchronization
+
+How the client and server keep document content in sync.
+
+| Capability               | Description                        |
+| ------------------------ | ---------------------------------- |
+| `textDocument/didOpen`   | Notify server when document opens  |
+| `textDocument/didChange` | Send document changes to server    |
+| `textDocument/didSave`   | Notify server on save              |
+| `textDocument/didClose`  | Notify server when document closes |
+
+### Diagnostics
+
+Server-pushed notifications about code issues.
+
+| Capability                        | Description                     |
+| --------------------------------- | ------------------------------- |
+| `textDocument/publishDiagnostics` | Receive errors, warnings, hints |
+
+**Diagnostic severities:**
+
+- Error (1) - Compilation errors, type mismatches
+- Warning (2) - Unused variables, deprecated APIs
+- Information (3) - Style suggestions
+- Hint (4) - Minor suggestions
+
+## Navigation Capabilities
+
+### Go to Definition
+
+Jump to where a symbol is defined.
+
+| Capability                    | Description                                    |
+| ----------------------------- | ---------------------------------------------- |
+| `textDocument/definition`     | Find definition location                       |
+| `textDocument/typeDefinition` | Find type definition                           |
+| `textDocument/implementation` | Find interface implementations                 |
+| `textDocument/declaration`    | Find declaration (if separate from definition) |
+
+### Find References
+
+Locate all usages of a symbol.
+
+| Capability                    | Description                         |
+| ----------------------------- | ----------------------------------- |
+| `textDocument/references`     | Find all references to a symbol     |
+| `callHierarchy/incomingCalls` | Find callers of a function          |
+| `callHierarchy/outgoingCalls` | Find functions called by a function |
+
+### Symbol Information
+
+Get information about code symbols.
+
+| Capability                    | Description                     |
+| ----------------------------- | ------------------------------- |
+| `textDocument/hover`          | Get documentation and type info |
+| `textDocument/documentSymbol` | List symbols in a document      |
+| `workspace/symbol`            | Search symbols across workspace |
+| `textDocument/signatureHelp`  | Get function signature info     |
+
+## Code Intelligence Capabilities
+
+### Completions
+
+| Capability                | Description                       |
+| ------------------------- | --------------------------------- |
+| `textDocument/completion` | Get completion suggestions        |
+| `completionItem/resolve`  | Get additional completion details |
+
+### Code Actions
+
+| Capability                | Description                          |
+| ------------------------- | ------------------------------------ |
+| `textDocument/codeAction` | Get available fixes and refactorings |
+| `codeAction/resolve`      | Get full edit for a code action      |
+
+### Refactoring
+
+| Capability                     | Description                  |
+| ------------------------------ | ---------------------------- |
+| `textDocument/rename`          | Rename a symbol across files |
+| `textDocument/prepareRename`   | Validate rename is possible  |
+| `textDocument/formatting`      | Format entire document       |
+| `textDocument/rangeFormatting` | Format selected range        |
+
+## Workspace Capabilities
+
+| Capability                         | Description                           |
+| ---------------------------------- | ------------------------------------- |
+| `workspace/didChangeConfiguration` | Notify server of settings changes     |
+| `workspace/didChangeWatchedFiles`  | Notify server of file system changes  |
+| `workspace/applyEdit`              | Server requests client to apply edits |
+
+## Capability Support by Server
+
+Not all servers support all capabilities. Common support levels:
+
+### Full Support (Most Servers)
+
+- Diagnostics
+- Go to definition
+- Find references
+- Hover
+- Document symbols
+- Completions
+
+### Partial Support (Varies)
+
+- Rename
+- Code actions
+- Call hierarchy
+- Type hierarchy
+- Formatting
+
+### Limited Support (Few Servers)
+
+- Semantic tokens
+- Inlay hints
+- Linked editing ranges
+
+## Checking Server Capabilities
+
+Servers declare supported capabilities during initialization. Claude Code automatically uses available features.
+
+To see what a server supports, check the server's documentation or the initialize response:
+
+```json
+{
+  "capabilities": {
+    "textDocumentSync": 2,
+    "completionProvider": { "triggerCharacters": ["."] },
+    "hoverProvider": true,
+    "definitionProvider": true,
+    "referencesProvider": true,
+    "documentSymbolProvider": true,
+    "renameProvider": true
+  }
+}
+```
+
+## Claude Code Usage
+
+Claude Code primarily uses these capabilities:
+
+1. **Diagnostics** - Automatic error detection after edits
+2. **Definition** - Understanding code structure
+3. **References** - Finding all usages for safe refactoring
+4. **Hover** - Getting type information and documentation
+5. **Document symbols** - Navigating file structure
+
+These provide more precise code understanding than text-based search alone.

From af27e5868a5083dde977d2e5f717c5a858cf0741 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 24 Jan 2026 20:28:02 -0500
Subject: [PATCH 4/8] docs: update ci-cd workflow list and fix formatting

- Update docs/ci-cd.md to reflect current workflows (add yaml-lint.yml,
  remove weekly-maintenance.yml which no longer exists)
- Apply prettier formatting to 4 skill files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/ci-cd.md                                      |  2 +-
 .../plugin-dev/skills/agent-development/SKILL.md   | 14 +++++++-------
 .../examples/agent-creation-prompt.md              |  2 +-
 .../examples/complete-agent-examples.md            |  9 +++++++--
 plugins/plugin-dev/skills/mcp-integration/SKILL.md |  6 +++---
 5 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/docs/ci-cd.md b/docs/ci-cd.md
index 5fa8fbf..5cce2ac 100644
--- a/docs/ci-cd.md
+++ b/docs/ci-cd.md
@@ -11,6 +11,7 @@ Documentation for GitHub Actions workflows, labels, and templates.
 | `component-validation.yml` | Plugin components changed      | Validate plugin components |
 | `version-check.yml`        | Version files changed          | Ensure version consistency |
 | `validate-workflows.yml`   | `.github/workflows/**` changed | Lint GitHub Actions        |
+| `yaml-lint.yml`            | `.github/workflows/**` changed | Lint YAML files            |
 | `claude-pr-review.yml`     | All PRs (non-draft)            | AI-powered code review     |
 
 ## Other Workflows
@@ -19,7 +20,6 @@ Documentation for GitHub Actions workflows, labels, and templates.
 - `stale.yml` - Manages stale issues/PRs (Mon/Wed/Fri)
 - `semantic-labeler.yml` - Auto-labels issues/PRs
 - `ci-failure-analysis.yml` - Analyzes CI failures
-- `weekly-maintenance.yml` - Scheduled maintenance tasks
 - `sync-labels.yml` - Synchronizes repository labels
 - `greet.yml` - Greets new contributors
 
diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md
index 21d571a..f3af0bb 100644
--- a/plugins/plugin-dev/skills/agent-development/SKILL.md
+++ b/plugins/plugin-dev/skills/agent-development/SKILL.md
@@ -293,13 +293,13 @@ permissionMode: acceptEdits
 
 Some frontmatter fields are specific to skills and do not apply to agents:
 
-| Skill-Only Field             | Purpose                                | Why Not for Agents                                      |
-| ---------------------------- | -------------------------------------- | ------------------------------------------------------- |
-| `context: fork`              | Run skill in separate subagent context | Agents already run as subprocesses by design            |
-| `agent`                      | Specify agent type for forked context  | Only applies when `context: fork` is set                |
-| `user-invocable`             | Control slash menu visibility          | Agents aren't invoked via slash commands                |
-| `disable-model-invocation`   | Block programmatic Skill tool usage    | Agents use Task tool, not Skill tool                    |
-| `allowed-tools`              | Restrict tool access (skill syntax)    | Agents use `tools` field instead (different field name) |
+| Skill-Only Field           | Purpose                                | Why Not for Agents                                      |
+| -------------------------- | -------------------------------------- | ------------------------------------------------------- |
+| `context: fork`            | Run skill in separate subagent context | Agents already run as subprocesses by design            |
+| `agent`                    | Specify agent type for forked context  | Only applies when `context: fork` is set                |
+| `user-invocable`           | Control slash menu visibility          | Agents aren't invoked via slash commands                |
+| `disable-model-invocation` | Block programmatic Skill tool usage    | Agents use Task tool, not Skill tool                    |
+| `allowed-tools`            | Restrict tool access (skill syntax)    | Agents use `tools` field instead (different field name) |
 
 **Key distinction:** Skills provide knowledge and guidance that loads into context. Agents are autonomous subprocesses that execute independently. This architectural difference explains why context-forking options don't apply to agents—they're already isolated processes.
 
diff --git a/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md b/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md
index 9d3be60..63029c0 100644
--- a/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md
+++ b/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md
@@ -47,7 +47,7 @@ name: [identifier from JSON]
 description: [whenToUse from JSON]
 model: inherit
 color: [choose: blue/cyan/green/yellow/magenta/red]
-tools: Read, Write, Grep  # Optional: restrict tools
+tools: Read, Write, Grep # Optional: restrict tools
 ---
 
 [systemPrompt from JSON]
diff --git a/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md b/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md
index 6bd3c02..51fbbb2 100644
--- a/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md
+++ b/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md
@@ -228,7 +228,7 @@ describe('[module name]', () => {
 
 **File:** `agents/docs-generator.md`
 
-````markdown
+```markdown
 ---
 name: docs-generator
 description: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples:
@@ -260,12 +260,14 @@ tools: Read, Write, Grep, Glob
 You are an expert technical writer specializing in creating clear, comprehensive documentation for software projects.
 
 **Your Core Responsibilities:**
+
 1. Generate accurate, clear documentation from code
 2. Follow project documentation standards
 3. Include examples and usage patterns
 4. Ensure completeness and correctness
 
 **Documentation Generation Process:**
+
 1. **Analyze Code**: Read implementation to understand:
    - Public interfaces and APIs
    - Parameters and return values
@@ -286,6 +288,7 @@ You are an expert technical writer specializing in creating clear, comprehensive
 5. **Validate**: Ensure accuracy and completeness
 
 **Quality Standards:**
+
 - Documentation matches actual code behavior
 - Examples are runnable and correct
 - All public APIs documented
@@ -294,6 +297,7 @@ You are an expert technical writer specializing in creating clear, comprehensive
 
 **Output Format:**
 Create documentation in project's standard format:
+
 - Function/method signatures
 - Description of behavior
 - Parameters with types and descriptions
@@ -303,11 +307,12 @@ Create documentation in project's standard format:
 - Notes or warnings if applicable
 
 **Edge Cases:**
+
 - Private/internal code: Document only if requested
 - Complex APIs: Break into sections, provide multiple examples
 - Deprecated code: Mark as deprecated with migration guide
 - Unclear behavior: Document observable behavior, note assumptions
-````
+```
 
 ## Example 4: Security Analyzer
 
diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md
index 462c90d..c1d7ead 100644
--- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md
+++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md
@@ -376,7 +376,7 @@ Commands use MCP tools with user interaction:
 
 ---
 
-allowed-tools: mcp__plugin_name_server__create_item
+allowed-tools: mcp**plugin_name_server**create_item
 
 Steps:
 
@@ -452,9 +452,9 @@ Always use secure connections:
 Pre-allow only necessary MCP tools:
 
 ```markdown
-✅ allowed-tools: mcp__plugin_api_server__read_data, mcp__plugin_api_server__create_item
+✅ allowed-tools: mcp**plugin_api_server**read_data, mcp**plugin_api_server**create_item
 
-❌ allowed-tools: mcp__plugin_api_server__*
+❌ allowed-tools: mcp**plugin_api_server**\*
 ```
 
 ### Managed MCP Controls (Enterprise)

From b7a62af5a29d2cab287266702a64e477079d6c18 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 24 Jan 2026 20:31:25 -0500
Subject: [PATCH 5/8] chore: prepare release v0.3.2

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude-plugin/marketplace.json               |  4 ++--
 CHANGELOG.md                                  | 13 ++++++++++++-
 CLAUDE.md                                     |  2 +-
 plugins/plugin-dev/.claude-plugin/plugin.json |  2 +-
 4 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 91eb31f..478fd8a 100644
--- a/.claude-plugin/marketplace.json
+++ b/.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.3.1"
+    "version": "0.3.2"
   },
   "plugins": [
     {
       "name": "plugin-dev",
       "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.1",
+      "version": "0.3.2",
       "author": {
         "name": "Daisy Hollman",
         "url": "https://github.com/anthropics/claude-code/",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 28865d8..3339ece 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-01-24
+
+### Documentation
+
+- **Expand LSP integration skill** - Aligned with official Claude Code docs for comprehensive LSP server guidance
+- **Optimize agent-development skill** - Trimmed SKILL.md to target word count for faster loading
+- **Align tools/allowed-tools format** - Updated documentation to match official Claude Code docs terminology
+- **Update CI/CD workflow documentation** - Fixed workflow list in docs/ci-cd.md (added yaml-lint.yml, removed non-existent weekly-maintenance.yml)
+- **Apply prettier formatting** - Fixed formatting in 4 skill files
+
 ## [0.3.1] - 2026-01-24
 
 ### Fixed
@@ -219,7 +229,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Based on original plugin by Daisy Hollman at Anthropic
 - Expanded with enhanced skills, additional utilities, and CI/CD infrastructure
 
-[Unreleased]: https://github.com/sjnims/plugin-dev/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/sjnims/plugin-dev/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/sjnims/plugin-dev/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/sjnims/plugin-dev/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/sjnims/plugin-dev/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/sjnims/plugin-dev/compare/v0.2.0...v0.2.1
diff --git a/CLAUDE.md b/CLAUDE.md
index 76b482e..35b4477 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository.
 
 Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 9 skills, 3 agents, 3 slash commands.
 
-**Version**: v0.3.1 | [CHANGELOG.md](CHANGELOG.md)
+**Version**: v0.3.2 | [CHANGELOG.md](CHANGELOG.md)
 
 ## MCP Tool Requirements (CRITICAL)
 
diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json
index 4b7da39..47ac0c3 100644
--- a/plugins/plugin-dev/.claude-plugin/plugin.json
+++ b/plugins/plugin-dev/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "plugin-dev",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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",

From 41da12b54e940f5d8b6ad657d73dee6ee6483e65 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 24 Jan 2026 20:40:03 -0500
Subject: [PATCH 6/8] fix: restore MCP tool naming patterns corrupted by
 prettier

Prettier was converting `__` to `**` in MCP tool names like
`mcp__plugin_name__tool`, treating double underscores as emphasis.

- Restore correct `mcp__` patterns in SKILL.md and tool-usage.md
- Add .prettierignore to exclude these files from prettier formatting

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .prettierignore                               |  4 ++
 .../skills/mcp-integration/SKILL.md           | 10 ++---
 .../mcp-integration/references/tool-usage.md  | 38 +++++++++----------
 3 files changed, 28 insertions(+), 24 deletions(-)
 create mode 100644 .prettierignore

diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000..5c2833c
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1,4 @@
+# MCP integration docs use mcp__plugin_*__* patterns that prettier
+# incorrectly converts __ to ** (treating as emphasis)
+plugins/plugin-dev/skills/mcp-integration/SKILL.md
+plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md
index c1d7ead..c1966ac 100644
--- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md
+++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md
@@ -376,12 +376,12 @@ Commands use MCP tools with user interaction:
 
 ---
 
-allowed-tools: mcp**plugin_name_server**create_item
+allowed-tools: `mcp__plugin_name_server__create_item`
 
 Steps:
 
 1. Gather item details from user
-2. Use mcp**plugin_name_server**create_item
+2. Use `mcp__plugin_name_server__create_item`
 3. Confirm creation
 ```
 
@@ -396,7 +396,7 @@ Agents use MCP tools autonomously:
 
 Analysis Process:
 
-1. Query data via mcp**plugin_db_server**query
+1. Query data via `mcp__plugin_db_server__query`
 2. Process and analyze results
 3. Generate insights report
 ```
@@ -452,9 +452,9 @@ Always use secure connections:
 Pre-allow only necessary MCP tools:
 
 ```markdown
-✅ allowed-tools: mcp**plugin_api_server**read_data, mcp**plugin_api_server**create_item
+✅ allowed-tools: `mcp__plugin_api_server__read_data`, `mcp__plugin_api_server__create_item`
 
-❌ allowed-tools: mcp**plugin_api_server**\*
+❌ allowed-tools: mcp__plugin_api_server__*
 ```
 
 ### Managed MCP Controls (Enterprise)
diff --git a/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md b/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
index 0754608..f774734 100644
--- a/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
+++ b/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
@@ -60,7 +60,7 @@ allowed-tools: mcp__plugin_asana_asana__asana_create_task
 To create a task:
 
 1. Gather task details from user
-2. Use mcp**plugin_asana_asana**asana_create_task with the details
+2. Use mcp__\1__asana_create_task with the details
 3. Confirm creation to user
 ```
 
@@ -98,7 +98,7 @@ allowed-tools: mcp__plugin_asana_asana__asana_search_tasks, mcp__plugin_asana_as
 
 To search for tasks:
 
-1. Use mcp**plugin_asana_asana**asana_search_tasks
+1. Use mcp__\1__asana_search_tasks
 2. Provide search filters (assignee, project, etc.)
 3. Display results to user
 
@@ -112,7 +112,7 @@ To create a task:
    - Project
    - Assignee
    - Due date
-2. Use mcp**plugin_asana_asana**asana_create_task
+2. Use mcp__\1__asana_create_task
 3. Show confirmation with task link
 ```
 
@@ -136,10 +136,10 @@ Autonomous agent for generating Asana project status reports.
 
 ## Process
 
-1. **Query tasks**: Use mcp**plugin_asana_asana**asana_search_tasks to get all tasks
+1. **Query tasks**: Use mcp__\1__asana_search_tasks to get all tasks
 2. **Analyze progress**: Calculate completion rates and identify blockers
 3. **Generate report**: Create formatted status update
-4. **Update Asana**: Use mcp**plugin_asana_asana**asana_create_comment to post report
+4. **Update Asana**: Use mcp__\1__asana_create_comment to post report
 
 ## Available Tools
 
@@ -164,7 +164,7 @@ Single tool call with validation:
 Steps:
 
 1. Validate user provided required fields
-2. Call mcp**plugin_api_server**create_item with validated data
+2. Call mcp__\1__create_item with validated data
 3. Check for errors
 4. Display confirmation
 ```
@@ -176,9 +176,9 @@ Chain multiple tool calls:
 ```markdown
 Steps:
 
-1. Search for existing items: mcp**plugin_api_server**search
-2. If not found, create new: mcp**plugin_api_server**create
-3. Add metadata: mcp**plugin_api_server**update_metadata
+1. Search for existing items: mcp__\1__search
+2. If not found, create new: mcp__\1__create
+3. Add metadata: mcp__\1__update_metadata
 4. Return final item ID
 ```
 
@@ -191,7 +191,7 @@ Steps:
 
 1. Get list of items to process
 2. For each item:
-   - Call mcp**plugin_api_server**update_item
+   - Call mcp__\1__update_item
    - Track success/failure
 3. Report results summary
 ```
@@ -203,7 +203,7 @@ Graceful error handling:
 ```markdown
 Steps:
 
-1. Try to call mcp**plugin_api_server**get_data
+1. Try to call mcp__\1__get_data
 2. If error (rate limit, network, etc.):
    - Wait and retry (max 3 attempts)
    - If still failing, inform user
@@ -328,7 +328,7 @@ Steps:
 ```markdown
 Steps:
 
-1. Call mcp**plugin_api_server**search with filters:
+1. Call mcp__\1__search with filters:
    - project_id: "123"
    - status: "active"
    - limit: 100
@@ -341,7 +341,7 @@ Steps:
 Steps:
 
 1. For each item ID:
-   - Call mcp**plugin_api_server**get_item
+   - Call mcp__\1__get_item
    - Process item
 ```
 
@@ -350,7 +350,7 @@ Steps:
 ```markdown
 Steps:
 
-1. Call expensive MCP operation: mcp**plugin_api_server**analyze
+1. Call expensive MCP operation: mcp__\1__analyze
 2. Store results in variable for reuse
 3. Use cached results for subsequent operations
 4. Only re-fetch if data changes
@@ -364,9 +364,9 @@ When tools don't depend on each other, call in parallel:
 Steps:
 
 1. Make parallel calls (Claude handles this automatically):
-   - mcp**plugin_api_server**get_project
-   - mcp**plugin_api_server**get_users
-   - mcp**plugin_api_server**get_tags
+   - mcp__\1__get_project
+   - mcp__\1__get_users
+   - mcp__\1__get_tags
 2. Wait for all to complete
 3. Combine results
 ```
@@ -381,7 +381,7 @@ Steps:
 Steps:
 
 1. Inform user: "Searching Asana tasks..."
-2. Call mcp**plugin_asana_asana**asana_search_tasks
+2. Call mcp__\1__asana_search_tasks
 3. Show progress: "Found 15 tasks, analyzing..."
 4. Present results
 ```
@@ -507,7 +507,7 @@ Use delete_item with item ID (ask for confirmation first)...
 ```markdown
 Steps:
 
-1. **Search**: mcp**plugin_api_server**search with filters
+1. **Search**: mcp__\1__search with filters
 2. **Filter**: Apply additional local filtering if needed
 3. **Transform**: Process each result
 4. **Present**: Format and display to user

From 941ec26b505e763c10da4c51f47bc9769f828f94 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 24 Jan 2026 20:40:28 -0500
Subject: [PATCH 7/8] docs(changelog): add MCP tool pattern fix to 0.3.2
 release notes

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CHANGELOG.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3339ece..8d2a7d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,13 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.3.2] - 2026-01-24
 
+### Fixed
+
+- **Restore MCP tool naming patterns** - Fixed `mcp__plugin_*__*` patterns in mcp-integration docs that prettier corrupted to `mcp**plugin_*__*`; added .prettierignore to prevent recurrence
+
 ### Documentation
 
 - **Expand LSP integration skill** - Aligned with official Claude Code docs for comprehensive LSP server guidance
 - **Optimize agent-development skill** - Trimmed SKILL.md to target word count for faster loading
 - **Align tools/allowed-tools format** - Updated documentation to match official Claude Code docs terminology
 - **Update CI/CD workflow documentation** - Fixed workflow list in docs/ci-cd.md (added yaml-lint.yml, removed non-existent weekly-maintenance.yml)
-- **Apply prettier formatting** - Fixed formatting in 4 skill files
 
 ## [0.3.1] - 2026-01-24
 

From f773dab7ecf964489c4ab4fa502d03a3dd3ac871 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 24 Jan 2026 20:45:32 -0500
Subject: [PATCH 8/8] fix: properly restore MCP tool patterns in tool-usage.md

Previous sed command left \1 regex remnants. Restored from main
and applied clean perl replacement for mcp__*__ patterns.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../mcp-integration/references/tool-usage.md  | 63 ++++++++++++-------
 1 file changed, 39 insertions(+), 24 deletions(-)

diff --git a/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md b/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
index f774734..bd61bfe 100644
--- a/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
+++ b/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
@@ -52,7 +52,7 @@ Specify MCP tools in command frontmatter:
 ```markdown
 ---
 description: Create a new Asana task
-allowed-tools: mcp__plugin_asana_asana__asana_create_task
+allowed-tools: ["mcp__plugin_asana_asana__asana_create_task"]
 ---
 
 # Create Task Command
@@ -60,7 +60,7 @@ allowed-tools: mcp__plugin_asana_asana__asana_create_task
 To create a task:
 
 1. Gather task details from user
-2. Use mcp__\1__asana_create_task with the details
+2. Use mcp__plugin_asana_asana__asana_create_task with the details
 3. Confirm creation to user
 ```
 
@@ -68,7 +68,12 @@ To create a task:
 
 ```markdown
 ---
-allowed-tools: mcp__plugin_asana_asana__asana_create_task, mcp__plugin_asana_asana__asana_search_tasks, mcp__plugin_asana_asana__asana_get_project
+allowed-tools:
+  [
+    "mcp__plugin_asana_asana__asana_create_task",
+    "mcp__plugin_asana_asana__asana_search_tasks",
+    "mcp__plugin_asana_asana__asana_get_project",
+  ]
 ---
 ```
 
@@ -76,7 +81,7 @@ allowed-tools: mcp__plugin_asana_asana__asana_create_task, mcp__plugin_asana_asa
 
 ```markdown
 ---
-allowed-tools: mcp__plugin_asana_asana__*
+allowed-tools: ["mcp__plugin_asana_asana__*"]
 ---
 ```
 
@@ -89,7 +94,11 @@ allowed-tools: mcp__plugin_asana_asana__*
 ```markdown
 ---
 description: Search and create Asana tasks
-allowed-tools: mcp__plugin_asana_asana__asana_search_tasks, mcp__plugin_asana_asana__asana_create_task
+allowed-tools:
+  [
+    "mcp__plugin_asana_asana__asana_search_tasks",
+    "mcp__plugin_asana_asana__asana_create_task",
+  ]
 ---
 
 # Asana Task Management
@@ -98,7 +107,7 @@ allowed-tools: mcp__plugin_asana_asana__asana_search_tasks, mcp__plugin_asana_as
 
 To search for tasks:
 
-1. Use mcp__\1__asana_search_tasks
+1. Use mcp__plugin_asana_asana__asana_search_tasks
 2. Provide search filters (assignee, project, etc.)
 3. Display results to user
 
@@ -112,7 +121,7 @@ To create a task:
    - Project
    - Assignee
    - Due date
-2. Use mcp__\1__asana_create_task
+2. Use mcp__plugin_asana_asana__asana_create_task
 3. Show confirmation with task link
 ```
 
@@ -136,10 +145,10 @@ Autonomous agent for generating Asana project status reports.
 
 ## Process
 
-1. **Query tasks**: Use mcp__\1__asana_search_tasks to get all tasks
+1. **Query tasks**: Use mcp__plugin_asana_asana__asana_search_tasks to get all tasks
 2. **Analyze progress**: Calculate completion rates and identify blockers
 3. **Generate report**: Create formatted status update
-4. **Update Asana**: Use mcp__\1__asana_create_comment to post report
+4. **Update Asana**: Use mcp__plugin_asana_asana__asana_create_comment to post report
 
 ## Available Tools
 
@@ -164,7 +173,7 @@ Single tool call with validation:
 Steps:
 
 1. Validate user provided required fields
-2. Call mcp__\1__create_item with validated data
+2. Call mcp__plugin_api_server__create_item with validated data
 3. Check for errors
 4. Display confirmation
 ```
@@ -176,9 +185,9 @@ Chain multiple tool calls:
 ```markdown
 Steps:
 
-1. Search for existing items: mcp__\1__search
-2. If not found, create new: mcp__\1__create
-3. Add metadata: mcp__\1__update_metadata
+1. Search for existing items: mcp__plugin_api_server__search
+2. If not found, create new: mcp__plugin_api_server__create
+3. Add metadata: mcp__plugin_api_server__update_metadata
 4. Return final item ID
 ```
 
@@ -191,7 +200,7 @@ Steps:
 
 1. Get list of items to process
 2. For each item:
-   - Call mcp__\1__update_item
+   - Call mcp__plugin_api_server__update_item
    - Track success/failure
 3. Report results summary
 ```
@@ -203,7 +212,7 @@ Graceful error handling:
 ```markdown
 Steps:
 
-1. Try to call mcp__\1__get_data
+1. Try to call mcp__plugin_api_server__get_data
 2. If error (rate limit, network, etc.):
    - Wait and retry (max 3 attempts)
    - If still failing, inform user
@@ -328,7 +337,7 @@ Steps:
 ```markdown
 Steps:
 
-1. Call mcp__\1__search with filters:
+1. Call mcp__plugin_api_server__search with filters:
    - project_id: "123"
    - status: "active"
    - limit: 100
@@ -341,7 +350,7 @@ Steps:
 Steps:
 
 1. For each item ID:
-   - Call mcp__\1__get_item
+   - Call mcp__plugin_api_server__get_item
    - Process item
 ```
 
@@ -350,7 +359,7 @@ Steps:
 ```markdown
 Steps:
 
-1. Call expensive MCP operation: mcp__\1__analyze
+1. Call expensive MCP operation: mcp__plugin_api_server__analyze
 2. Store results in variable for reuse
 3. Use cached results for subsequent operations
 4. Only re-fetch if data changes
@@ -364,9 +373,9 @@ When tools don't depend on each other, call in parallel:
 Steps:
 
 1. Make parallel calls (Claude handles this automatically):
-   - mcp__\1__get_project
-   - mcp__\1__get_users
-   - mcp__\1__get_tags
+   - mcp__plugin_api_server__get_project
+   - mcp__plugin_api_server__get_users
+   - mcp__plugin_api_server__get_tags
 2. Wait for all to complete
 3. Combine results
 ```
@@ -381,7 +390,7 @@ Steps:
 Steps:
 
 1. Inform user: "Searching Asana tasks..."
-2. Call mcp__\1__asana_search_tasks
+2. Call mcp__plugin_asana_asana__asana_search_tasks
 3. Show progress: "Found 15 tasks, analyzing..."
 4. Present results
 ```
@@ -480,7 +489,13 @@ Steps:
 
 ```markdown
 ---
-allowed-tools: mcp__plugin_api_server__create_item, mcp__plugin_api_server__read_item, mcp__plugin_api_server__update_item, mcp__plugin_api_server__delete_item
+allowed-tools:
+  [
+    "mcp__plugin_api_server__create_item",
+    "mcp__plugin_api_server__read_item",
+    "mcp__plugin_api_server__update_item",
+    "mcp__plugin_api_server__delete_item",
+  ]
 ---
 
 # Item Management
@@ -507,7 +522,7 @@ Use delete_item with item ID (ask for confirmation first)...
 ```markdown
 Steps:
 
-1. **Search**: mcp__\1__search with filters
+1. **Search**: mcp__plugin_api_server__search with filters
 2. **Filter**: Apply additional local filtering if needed
 3. **Transform**: Process each result
 4. **Present**: Format and display to user