From 8d4b3a2e4458e28d25a243b274af6cd8ce6866a1 Mon Sep 17 00:00:00 2001 From: Steve Nims Date: Sat, 24 Jan 2026 17:56:05 -0500 Subject: [PATCH 1/2] feat: sync documentation with official Claude Code docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comprehensive update to align plugin-dev documentation with official Claude Code documentation. Adds missing features, corrects outdated information, and introduces new LSP integration skill. ## Skills Updated - **hook-development**: Add 3 missing events (Setup, PostToolUseFailure, SubagentStart), update event count to 12 - **skill-development**: Add context/agent/skills frontmatter, dynamic context injection, string substitutions - **agent-development**: Add skills/permissionMode frontmatter, --agents CLI flag documentation - **mcp-integration**: Add @resource syntax, Tool Search, managed controls - **plugin-structure**: Add lspServers/outputStyles components, caching docs ## New Content - **lsp-integration skill**: New skill documenting LSP server configuration, extensionToLanguage mappings, pre-built plugins ## Agents/Commands Updated - **plugin-validator**: Add LSP validation, expand skills list - **skill-reviewer**: Update optional fields for new frontmatter - **agent-creator**: Add skills/permissionMode to configuration - **create-plugin**: Add LSP to component planning and Phase 5 ## Version Bump - 0.2.1 → 0.3.0 (9 skills, was 8) Co-Authored-By: Claude Opus 4.5 --- .claude-plugin/marketplace.json | 6 +- CLAUDE.md | 4 +- plugins/plugin-dev/.claude-plugin/plugin.json | 4 +- plugins/plugin-dev/agents/agent-creator.md | 5 + plugins/plugin-dev/agents/plugin-validator.md | 15 +- plugins/plugin-dev/agents/skill-reviewer.md | 2 +- plugins/plugin-dev/commands/create-plugin.md | 15 +- .../skills/agent-development/SKILL.md | 72 +++- .../skills/hook-development/SKILL.md | 100 ++++- .../skills/lsp-integration/SKILL.md | 374 ++++++++++++++++++ .../references/popular-lsp-servers.md | 269 +++++++++++++ .../skills/mcp-integration/SKILL.md | 79 ++++ .../skills/plugin-structure/SKILL.md | 99 ++++- .../skills/skill-development/SKILL.md | 108 +++++ 14 files changed, 1119 insertions(+), 33 deletions(-) create mode 100644 plugins/plugin-dev/skills/lsp-integration/SKILL.md create mode 100644 plugins/plugin-dev/skills/lsp-integration/references/popular-lsp-servers.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 863d7e6..3699036 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.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/", diff --git a/CLAUDE.md b/CLAUDE.md index 156530b..5412074 100644 --- a/CLAUDE.md +++ b/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) diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index f495e5f..0abff44 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/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" diff --git a/plugins/plugin-dev/agents/agent-creator.md b/plugins/plugin-dev/agents/agent-creator.md index 0106a1b..df43b88 100644 --- a/plugins/plugin-dev/agents/agent-creator.md +++ b/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] diff --git a/plugins/plugin-dev/agents/plugin-validator.md b/plugins/plugin-dev/agents/plugin-validator.md index 76fcc7b..7cfc4b7 100644 --- a/plugins/plugin-dev/agents/plugin-validator.md +++ b/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,13 +139,22 @@ First, determine what type of validation is needed: - Type-specific fields present - Check ${CLAUDE_PLUGIN_ROOT} usage for portability -9. **Check File Organization**: +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 -10. **Security Checks**: +11. **Security Checks**: - No hardcoded credentials in any files - MCP servers use HTTPS/WSS not HTTP/WS - Hooks don't have obvious security issues diff --git a/plugins/plugin-dev/agents/skill-reviewer.md b/plugins/plugin-dev/agents/skill-reviewer.md index 283e7ca..fc81775 100644 --- a/plugins/plugin-dev/agents/skill-reviewer.md +++ b/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): diff --git a/plugins/plugin-dev/commands/create-plugin.md b/plugins/plugin-dev/commands/create-plugin.md index 42cbe9d..a4fb35f 100644 --- a/plugins/plugin-dev/commands/create-plugin.md +++ b/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) diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index 1d24756..01b423f 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/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... ... | -| 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... ... | +| 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. diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index 30eefde..6f419c9 100644 --- a/plugins/plugin-dev/skills/hook-development/SKILL.md +++ b/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 diff --git a/plugins/plugin-dev/skills/lsp-integration/SKILL.md b/plugins/plugin-dev/skills/lsp-integration/SKILL.md new file mode 100644 index 0000000..828aa7b --- /dev/null +++ b/plugins/plugin-dev/skills/lsp-integration/SKILL.md @@ -0,0 +1,374 @@ +--- +name: lsp-integration +description: This skill should be used when the user asks to "add LSP server", "configure language server", "set up LSP in plugin", "add code intelligence", "integrate language server protocol", "use pyright-lsp", "use typescript-lsp", "use rust-lsp", mentions LSP servers, or discusses extensionToLanguage mappings. Provides guidance for integrating Language Server Protocol servers into Claude Code plugins for enhanced code intelligence. +--- + +# LSP Integration for Claude Code Plugins + +## Overview + +Language Server Protocol (LSP) servers provide code intelligence features like go-to-definition, find references, and hover information. Claude Code plugins can bundle or configure LSP servers to enhance Claude's understanding of code. + +**Key capabilities:** + +- Enable go-to-definition for code navigation +- Find all references to symbols +- Get hover information and documentation +- Support language-specific features (completions, diagnostics) + +## LSP Server Configuration + +Plugins can provide LSP servers in the plugin manifest: + +### Basic Configuration + +```json +{ + "name": "my-plugin", + "lspServers": { + "python": { + "command": "pyright-langserver", + "args": ["--stdio"], + "extensionToLanguage": { + ".py": "python", + ".pyi": "python" + } + } + } +} +``` + +### Configuration Fields + +**command** (required): The LSP server executable + +**args** (optional): Command-line arguments for the server + +**extensionToLanguage** (required): Maps file extensions to language IDs + +```json +{ + "extensionToLanguage": { + ".py": "python", + ".pyi": "python", + ".pyw": "python" + } +} +``` + +**env** (optional): Environment variables for the server process + +```json +{ + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/lib" + } +} +``` + +## Pre-built LSP Plugins + +Claude Code provides official LSP plugins for common languages: + +### pyright-lsp + +Python language server using Pyright: + +```bash +# Install from marketplace +claude /install-plugin pyright-lsp +``` + +Features: + +- Type checking and inference +- Go-to-definition +- Find references +- Hover documentation +- Completions + +### typescript-lsp + +TypeScript/JavaScript language server: + +```bash +# Install from marketplace +claude /install-plugin typescript-lsp +``` + +Features: + +- TypeScript and JavaScript support +- Type information on hover +- Go-to-definition +- Find references +- Rename symbol + +### rust-lsp + +Rust language server using rust-analyzer: + +```bash +# Install from marketplace +claude /install-plugin rust-lsp +``` + +Features: + +- Full rust-analyzer capabilities +- Trait resolution +- Macro expansion +- Go-to-definition and references + +## Creating Custom LSP Integration + +### Step 1: Choose or Build LSP Server + +Options: + +1. **Use existing LSP server** - Most languages have official or community servers +2. **Bundle with plugin** - Include server binary in plugin +3. **Require user installation** - Document server installation in README + +### Step 2: Configure in plugin.json + +```json +{ + "name": "go-lsp", + "version": "1.0.0", + "description": "Go language server integration", + "lspServers": { + "go": { + "command": "gopls", + "args": ["serve"], + "extensionToLanguage": { + ".go": "go", + ".mod": "go.mod" + } + } + } +} +``` + +### Step 3: Bundle Server (Optional) + +For self-contained plugins, bundle the server: + +``` +my-lsp-plugin/ +├── .claude-plugin/ +│ └── plugin.json +└── servers/ + └── my-lsp-server +``` + +Use `${CLAUDE_PLUGIN_ROOT}` for the command path: + +```json +{ + "lspServers": { + "mylang": { + "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-lsp-server", + "args": ["--stdio"] + } + } +} +``` + +### Step 4: Document Requirements + +In your plugin README: + +- List required external dependencies +- Provide installation instructions +- Note supported language versions +- Describe available features + +## Extension to Language Mapping + +The `extensionToLanguage` field maps file extensions to LSP language identifiers: + +### Common Mappings + +```json +{ + "extensionToLanguage": { + ".py": "python", + ".js": "javascript", + ".ts": "typescript", + ".jsx": "javascriptreact", + ".tsx": "typescriptreact", + ".rs": "rust", + ".go": "go", + ".java": "java", + ".rb": "ruby", + ".php": "php", + ".c": "c", + ".cpp": "cpp", + ".h": "c", + ".hpp": "cpp", + ".cs": "csharp" + } +} +``` + +### Multiple Extensions + +A single language can have multiple extensions: + +```json +{ + "extensionToLanguage": { + ".ts": "typescript", + ".mts": "typescript", + ".cts": "typescript", + ".d.ts": "typescript" + } +} +``` + +## LSP Server Lifecycle + +### Startup + +LSP servers start automatically when: + +1. Claude Code session begins +2. Plugin with LSP server is enabled +3. User opens a file matching configured extensions + +### Communication + +- Uses stdio for client-server communication +- Follows LSP specification for messages +- Claude Code manages the connection + +### Shutdown + +Servers terminate when: + +- Claude Code session ends +- Plugin is disabled +- Server crashes (auto-restart may occur) + +## Best Practices + +### Performance + +1. **Lazy initialization** - Servers start when needed, not at session start +2. **Minimal configuration** - Only enable features you need +3. **Resource limits** - Consider memory/CPU impact of servers + +### Compatibility + +1. **Check LSP version** - Ensure server supports required protocol version +2. **Test cross-platform** - Verify on macOS, Linux, Windows +3. **Handle missing servers** - Gracefully degrade if server not installed + +### Documentation + +1. **List prerequisites** - External tools, versions required +2. **Provide setup guide** - Step-by-step installation +3. **Document features** - Which LSP capabilities are supported + +## Troubleshooting + +### Server Not Starting + +**Check:** + +- Command path is correct +- Server is installed and executable +- Required dependencies are available +- `${CLAUDE_PLUGIN_ROOT}` is used for bundled servers + +### No Code Intelligence + +**Check:** + +- File extension matches `extensionToLanguage` mapping +- Language ID is correct for the server +- Server supports the requested feature + +### Debug Mode + +Enable debug logging: + +```bash +claude --debug +``` + +Look for: + +- LSP server startup messages +- Communication logs +- Error responses + +## Quick Reference + +### Minimal LSP Configuration + +```json +{ + "lspServers": { + "language": { + "command": "server-command", + "extensionToLanguage": { + ".ext": "language-id" + } + } + } +} +``` + +### Full LSP Configuration + +```json +{ + "lspServers": { + "language": { + "command": "${CLAUDE_PLUGIN_ROOT}/servers/lsp-server", + "args": ["--stdio", "--log-level", "warn"], + "extensionToLanguage": { + ".ext1": "language", + ".ext2": "language" + }, + "env": { + "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config" + } + } + } +} +``` + +### Best Practices Summary + +**DO:** + +- Use `${CLAUDE_PLUGIN_ROOT}` for bundled server paths +- Map all relevant file extensions +- Document external dependencies +- Test on multiple platforms +- Handle server unavailability gracefully + +**DON'T:** + +- Hardcode absolute paths +- Assume servers are pre-installed +- Bundle large binaries without consideration +- Ignore server startup errors + +## Additional Resources + +### Reference Files + +For detailed information, consult: + +- **`references/popular-lsp-servers.md`** - Curated list of LSP servers by language +- **`references/lsp-capabilities.md`** - LSP protocol capabilities reference + +### External Resources + +- **LSP Specification**: +- **Claude Code Plugins Reference**: +- **Language Server List**: diff --git a/plugins/plugin-dev/skills/lsp-integration/references/popular-lsp-servers.md b/plugins/plugin-dev/skills/lsp-integration/references/popular-lsp-servers.md new file mode 100644 index 0000000..5a18956 --- /dev/null +++ b/plugins/plugin-dev/skills/lsp-integration/references/popular-lsp-servers.md @@ -0,0 +1,269 @@ +# Popular LSP Servers by Language + +Curated list of recommended Language Server Protocol servers for common programming languages. + +## Official/Recommended Servers + +### Python + +**Pyright** (Recommended) + +- Fast, full-featured type checker +- Command: `pyright-langserver --stdio` +- Install: `npm install -g pyright` + +```json +{ + "lspServers": { + "python": { + "command": "pyright-langserver", + "args": ["--stdio"], + "extensionToLanguage": { + ".py": "python", + ".pyi": "python" + } + } + } +} +``` + +**Pylsp** (Alternative) + +- Plugin-based, highly extensible +- Command: `pylsp` +- Install: `pip install python-lsp-server` + +### TypeScript/JavaScript + +**TypeScript Language Server** (Recommended) + +- Official TypeScript server +- Command: `typescript-language-server --stdio` +- Install: `npm install -g typescript-language-server typescript` + +```json +{ + "lspServers": { + "typescript": { + "command": "typescript-language-server", + "args": ["--stdio"], + "extensionToLanguage": { + ".ts": "typescript", + ".tsx": "typescriptreact", + ".js": "javascript", + ".jsx": "javascriptreact" + } + } + } +} +``` + +### Rust + +**rust-analyzer** (Recommended) + +- Official Rust language server +- Command: `rust-analyzer` +- Install: `rustup component add rust-analyzer` + +```json +{ + "lspServers": { + "rust": { + "command": "rust-analyzer", + "extensionToLanguage": { + ".rs": "rust" + } + } + } +} +``` + +### Go + +**gopls** (Official) + +- Official Go language server +- Command: `gopls serve` +- Install: `go install golang.org/x/tools/gopls@latest` + +```json +{ + "lspServers": { + "go": { + "command": "gopls", + "args": ["serve"], + "extensionToLanguage": { + ".go": "go" + } + } + } +} +``` + +### Java + +**Eclipse JDT Language Server** + +- Full-featured Java server +- Command: Varies by installation +- Install: Download from Eclipse + +**jdtls** (Wrapper) + +- Simplified jdtls wrapper +- Install: Package managers or manual + +### C/C++ + +**clangd** (Recommended) + +- LLVM-based, fast +- Command: `clangd` +- Install: Part of LLVM/Clang + +```json +{ + "lspServers": { + "cpp": { + "command": "clangd", + "extensionToLanguage": { + ".c": "c", + ".cpp": "cpp", + ".cc": "cpp", + ".h": "c", + ".hpp": "cpp" + } + } + } +} +``` + +### C # + +**OmniSharp** + +- .NET/C# language server +- Command: `OmniSharp --languageserver` +- Install: `dotnet tool install -g OmniSharp` + +### Ruby + +**Solargraph** + +- Ruby language server +- Command: `solargraph stdio` +- Install: `gem install solargraph` + +```json +{ + "lspServers": { + "ruby": { + "command": "solargraph", + "args": ["stdio"], + "extensionToLanguage": { + ".rb": "ruby", + ".rake": "ruby" + } + } + } +} +``` + +### PHP + +**Intelephense** + +- Fast PHP server +- Command: `intelephense --stdio` +- Install: `npm install -g intelephense` + +**Phpactor** + +- Vim-focused, extensible +- Command: `phpactor language-server` +- Install: Via Composer + +## Web Technologies + +### HTML/CSS + +**vscode-html-languageserver** + +- HTML language features +- Command: `html-languageserver --stdio` +- Install: `npm install -g vscode-langservers-extracted` + +**vscode-css-languageserver** + +- CSS/SCSS/Less support +- Command: `css-languageserver --stdio` +- Install: `npm install -g vscode-langservers-extracted` + +### JSON + +**vscode-json-languageserver** + +- JSON with schema support +- Command: `json-languageserver --stdio` +- Install: `npm install -g vscode-langservers-extracted` + +### YAML + +**yaml-language-server** + +- YAML with schema support +- Command: `yaml-language-server --stdio` +- Install: `npm install -g yaml-language-server` + +## Other Languages + +### Lua + +**lua-language-server** + +- Full Lua support +- Install: GitHub releases or package managers + +### Kotlin + +**kotlin-language-server** + +- Kotlin support +- Install: GitHub releases + +### Swift + +**sourcekit-lsp** + +- Official Swift server +- Part of Swift toolchain + +### Elixir + +**elixir-ls** + +- Elixir/Phoenix support +- Install: GitHub releases + +### Haskell + +**haskell-language-server** + +- Full Haskell support +- Install: `ghcup install hls` + +## Installation Verification + +Test if a server is working: + +```bash +# Check if command exists +which + +# Check version + --version + +# Test stdio mode (should accept LSP messages) +echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | +``` diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md index 6bb57c0..150ce1c 100644 --- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md @@ -227,6 +227,58 @@ When MCP servers provide tools, they're automatically prefixed: - Tool: `create_task` - **Full name:** `mcp__plugin_asana_asana__asana_create_task` +## MCP Resources + +MCP servers can expose resources that Claude can access using the `@` syntax: + +### Resource Syntax + +``` +@server-name:protocol://path +``` + +**Examples:** + +``` +@filesystem:file:///Users/me/project/README.md +@database:postgres://localhost/mydb/users +@github:https://github.com/user/repo +``` + +### Using Resources in Prompts + +Reference resources directly in your prompts: + +``` +Look at @filesystem:file:///path/to/config.json and suggest improvements +``` + +Claude will fetch the resource content and include it in context. + +### Resource Types + +- **file://** - Local file system paths +- **https://** - HTTP resources +- **Custom protocols** - Server-specific (postgres://, s3://, etc.) + +## Tool Search + +For MCP servers with many tools, use Tool Search to find relevant tools: + +**When to use:** + +- Server provides 10+ tools +- You don't know exact tool names +- Exploring server capabilities + +**How it works:** + +1. Claude Code indexes MCP tool names and descriptions +2. Search by natural language or partial names +3. Get filtered list of matching tools + +This feature is automatic - just ask Claude about available tools or describe what you want to do. + ### Using MCP Tools in Commands Pre-allow specific MCP tools in command frontmatter: @@ -412,6 +464,33 @@ Pre-allow only necessary MCP tools: ❌ allowed-tools: ["mcp__plugin_api_server__*"] ``` +### Managed MCP Controls (Enterprise) + +Organizations can control MCP server access through managed settings: + +**Restrict allowed servers:** + +```json +{ + "mcpServers": { + "allowedServers": ["github", "internal-api"], + "blockedServers": ["*"] + } +} +``` + +**Disable MCP entirely:** + +```json +{ + "mcpServers": { + "enabled": false + } +} +``` + +These settings are configured by administrators and cannot be overridden by users or plugins. + ## Error Handling ### Connection Failures diff --git a/plugins/plugin-dev/skills/plugin-structure/SKILL.md b/plugins/plugin-dev/skills/plugin-structure/SKILL.md index dd1e18f..6e7837c 100644 --- a/plugins/plugin-dev/skills/plugin-structure/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-structure/SKILL.md @@ -1,6 +1,6 @@ --- name: plugin-structure -description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices. +description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "add lspServers", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices. --- # Plugin Structure for Claude Code @@ -281,6 +281,57 @@ hooks/ **Usage**: MCP servers integrate seamlessly with Claude Code's tool system +### LSP Servers + +**Location**: Inline in `plugin.json` under `lspServers` field +**Format**: JSON configuration for Language Server Protocol servers +**Auto-start**: Servers start when files matching extensions are opened + +**Example format**: + +```json +{ + "lspServers": { + "python": { + "command": "pyright-langserver", + "args": ["--stdio"], + "extensionToLanguage": { + ".py": "python", + ".pyi": "python" + } + } + } +} +``` + +**Usage**: LSP servers provide code intelligence (go-to-definition, find references, hover) + +For detailed LSP configuration, see the `lsp-integration` skill. + +### Output Styles + +**Location**: Inline in `plugin.json` under `outputStyles` field +**Format**: JSON configuration for custom output formatting +**Purpose**: Customize how Claude formats responses + +**Example format**: + +```json +{ + "outputStyles": { + "code-blocks": { + "style": "fenced", + "language": "auto" + }, + "headers": { + "numbering": true + } + } +} +``` + +**Usage**: Plugins can define consistent output formatting for their domain + ## Portable Path References ### ${CLAUDE_PLUGIN_ROOT} @@ -489,6 +540,52 @@ my-plugin/ └── SKILL.md ``` +## Plugin Caching + +Claude Code caches plugin content for performance. Understanding caching behavior helps with development and debugging. + +### What Gets Cached + +- Plugin manifest (plugin.json) +- Component files (commands, agents, skills) +- Configuration files (hooks.json, .mcp.json) + +### Cache Invalidation + +Cached content refreshes when: + +- Claude Code session restarts +- Plugin is reinstalled or updated +- User runs `/plugins refresh` (if available) + +### Why External Paths Fail + +**Important:** Paths outside the plugin directory may not work reliably because: + +1. **Security boundary** - Plugins are sandboxed to their directory +2. **Caching** - External paths aren't monitored for changes +3. **Portability** - External paths break on different machines + +**Always use:** + +- `${CLAUDE_PLUGIN_ROOT}` for paths within the plugin +- Bundled resources instead of external file references +- Environment variables for user-specific paths + +### Development Workflow + +During development, reload plugins by: + +1. Exiting Claude Code +2. Making changes to plugin files +3. Restarting Claude Code + +Or use `--plugin-dir` for testing without installation: + +```bash +claude --plugin-dir /path/to/plugin +``` + ## Troubleshooting **Component not loading**: diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md index 9d95366..ac475a8 100644 --- a/plugins/plugin-dev/skills/skill-development/SKILL.md +++ b/plugins/plugin-dev/skills/skill-development/SKILL.md @@ -64,6 +64,68 @@ Use `allowed-tools` for: When specified, Claude can only use the listed tools without needing permission. If omitted, Claude follows the standard permission model. +##### context + +Control how the skill's context is loaded: + +```yaml +--- +name: analysis-skill +description: Perform deep code analysis... +context: fork +--- +``` + +**Values:** + +- `fork` - Run skill in a subagent (separate context), preserving main agent's context +- Not specified - Run in main agent's context (default) + +Use `context: fork` for: + +- Skills that load large reference files +- Skills that might pollute the main context +- Expensive operations you want isolated + +##### agent + +Specify which agent type handles the skill when `context: fork` is set: + +```yaml +--- +name: exploration-skill +description: Explore codebase patterns... +context: fork +agent: Explore +--- +``` + +**Values:** + +- `Explore` - Fast agent for codebase exploration +- `Plan` - Architect agent for implementation planning +- `general` - General-purpose agent (default if `context: fork`) + +Requires `context: fork` to be set. + +##### skills + +Load other skills into the forked agent's context: + +```yaml +--- +name: comprehensive-review +description: Full code review with testing... +context: fork +agent: general +skills: + - testing-patterns + - security-audit +--- +``` + +Requires `context: fork` to be set. Only skills from the same plugin can be loaded. + ##### user-invocable Control whether the skill appears in the slash command menu: @@ -139,6 +201,49 @@ Files not intended to be loaded into context, but rather used within the output - **When to include**: When the skill needs files that will be used in the final output - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for templates +### Dynamic Content in Skills + +Skills support dynamic content injection and variable substitution for context-aware behavior. + +#### String Substitutions + +Use variables in skill content that get replaced at runtime: + +```markdown +The session ID is: ${CLAUDE_SESSION_ID} +Arguments passed: $ARGUMENTS +``` + +**Available substitutions:** + +- `$ARGUMENTS` - Arguments passed when skill is invoked (e.g., `/skill-name arg1 arg2`) +- `${CLAUDE_SESSION_ID}` - Current session identifier +- `${CLAUDE_PLUGIN_ROOT}` - Plugin directory path + +#### Dynamic Context Injection + +Execute commands to inject their output into skill context using backtick syntax: + +```markdown +## Current Project Status + +The git status is: +!`git status --short` + +Recent commits: +!`git log --oneline -5` +``` + +**Syntax:** `` !`command` `` + +**Use cases:** + +- Load current project state (git status, package.json) +- Include dynamic configuration +- Fetch environment-specific information + +**Security note:** Commands execute in the user's environment. Only use trusted commands. + ### Progressive Disclosure Design Principle Skills use a three-level loading system to manage context efficiently: @@ -250,6 +355,9 @@ Before finalizing a skill: - [ ] Name uses only lowercase letters, numbers, and hyphens (max 64 chars) - [ ] Description is under 1024 characters - [ ] (Optional) `allowed-tools` field if restricting tool access +- [ ] (Optional) `context: fork` if running in subagent +- [ ] (Optional) `agent` field if specifying agent type (requires `context: fork`) +- [ ] (Optional) `skills` array if loading other skills (requires `context: fork`) - [ ] (Optional) `user-invocable` field if hiding from slash menu - [ ] (Optional) `disable-model-invocation` field if blocking programmatic use - [ ] Markdown body is present and substantial From 75ebcb721b27f3a37cf1a66eba19f02ccbe58d7a Mon Sep 17 00:00:00 2001 From: Steve Nims Date: Sat, 24 Jan 2026 18:00:26 -0500 Subject: [PATCH 2/2] fix: resolve markdown lint and prettier issues - Fix list indentation in plugin-validator.md - Convert bold server names to proper #### headings in popular-lsp-servers.md - Fix C# heading escape character - Apply prettier formatting Co-Authored-By: Claude Opus 4.5 --- plugins/plugin-dev/agents/plugin-validator.md | 18 ++++---- .../skills/hook-development/SKILL.md | 30 ++++++------- .../references/popular-lsp-servers.md | 44 +++++++++---------- 3 files changed, 47 insertions(+), 45 deletions(-) diff --git a/plugins/plugin-dev/agents/plugin-validator.md b/plugins/plugin-dev/agents/plugin-validator.md index 7cfc4b7..9b50a11 100644 --- a/plugins/plugin-dev/agents/plugin-validator.md +++ b/plugins/plugin-dev/agents/plugin-validator.md @@ -149,16 +149,18 @@ First, determine what type of validation is needed: - 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 + +- 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 + +- 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:** diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index 6f419c9..1626ddb 100644 --- a/plugins/plugin-dev/skills/hook-development/SKILL.md +++ b/plugins/plugin-dev/skills/hook-development/SKILL.md @@ -718,21 +718,21 @@ echo "$output" | jq . ### Hook Events Summary -| 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 | +| 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 diff --git a/plugins/plugin-dev/skills/lsp-integration/references/popular-lsp-servers.md b/plugins/plugin-dev/skills/lsp-integration/references/popular-lsp-servers.md index 5a18956..bf32eb4 100644 --- a/plugins/plugin-dev/skills/lsp-integration/references/popular-lsp-servers.md +++ b/plugins/plugin-dev/skills/lsp-integration/references/popular-lsp-servers.md @@ -6,7 +6,7 @@ Curated list of recommended Language Server Protocol servers for common programm ### Python -**Pyright** (Recommended) +#### Pyright (Recommended) - Fast, full-featured type checker - Command: `pyright-langserver --stdio` @@ -27,7 +27,7 @@ Curated list of recommended Language Server Protocol servers for common programm } ``` -**Pylsp** (Alternative) +#### Pylsp (Alternative) - Plugin-based, highly extensible - Command: `pylsp` @@ -35,7 +35,7 @@ Curated list of recommended Language Server Protocol servers for common programm ### TypeScript/JavaScript -**TypeScript Language Server** (Recommended) +#### TypeScript Language Server (Recommended) - Official TypeScript server - Command: `typescript-language-server --stdio` @@ -60,7 +60,7 @@ Curated list of recommended Language Server Protocol servers for common programm ### Rust -**rust-analyzer** (Recommended) +#### rust-analyzer (Recommended) - Official Rust language server - Command: `rust-analyzer` @@ -81,7 +81,7 @@ Curated list of recommended Language Server Protocol servers for common programm ### Go -**gopls** (Official) +#### gopls (Official) - Official Go language server - Command: `gopls serve` @@ -103,20 +103,20 @@ Curated list of recommended Language Server Protocol servers for common programm ### Java -**Eclipse JDT Language Server** +#### Eclipse JDT Language Server - Full-featured Java server - Command: Varies by installation - Install: Download from Eclipse -**jdtls** (Wrapper) +#### jdtls (Wrapper) - Simplified jdtls wrapper - Install: Package managers or manual ### C/C++ -**clangd** (Recommended) +#### clangd (Recommended) - LLVM-based, fast - Command: `clangd` @@ -139,9 +139,9 @@ Curated list of recommended Language Server Protocol servers for common programm } ``` -### C # +### C\# -**OmniSharp** +#### OmniSharp - .NET/C# language server - Command: `OmniSharp --languageserver` @@ -149,7 +149,7 @@ Curated list of recommended Language Server Protocol servers for common programm ### Ruby -**Solargraph** +#### Solargraph - Ruby language server - Command: `solargraph stdio` @@ -172,13 +172,13 @@ Curated list of recommended Language Server Protocol servers for common programm ### PHP -**Intelephense** +#### Intelephense - Fast PHP server - Command: `intelephense --stdio` - Install: `npm install -g intelephense` -**Phpactor** +#### Phpactor - Vim-focused, extensible - Command: `phpactor language-server` @@ -188,13 +188,13 @@ Curated list of recommended Language Server Protocol servers for common programm ### HTML/CSS -**vscode-html-languageserver** +#### vscode-html-languageserver - HTML language features - Command: `html-languageserver --stdio` - Install: `npm install -g vscode-langservers-extracted` -**vscode-css-languageserver** +#### vscode-css-languageserver - CSS/SCSS/Less support - Command: `css-languageserver --stdio` @@ -202,7 +202,7 @@ Curated list of recommended Language Server Protocol servers for common programm ### JSON -**vscode-json-languageserver** +#### vscode-json-languageserver - JSON with schema support - Command: `json-languageserver --stdio` @@ -210,7 +210,7 @@ Curated list of recommended Language Server Protocol servers for common programm ### YAML -**yaml-language-server** +#### yaml-language-server - YAML with schema support - Command: `yaml-language-server --stdio` @@ -220,35 +220,35 @@ Curated list of recommended Language Server Protocol servers for common programm ### Lua -**lua-language-server** +#### lua-language-server - Full Lua support - Install: GitHub releases or package managers ### Kotlin -**kotlin-language-server** +#### kotlin-language-server - Kotlin support - Install: GitHub releases ### Swift -**sourcekit-lsp** +#### sourcekit-lsp - Official Swift server - Part of Swift toolchain ### Elixir -**elixir-ls** +#### elixir-ls - Elixir/Phoenix support - Install: GitHub releases ### Haskell -**haskell-language-server** +#### haskell-language-server - Full Haskell support - Install: `ghcup install hls`