YouTip

Plugins are the **core of functional extensions** for Claude Code, helping you add custom slash commands, sub-agents, automated hooks, and other capabilities. This tutorial covers three dimensions—**core components**, **configuration specifications**, and **CLI management**—to help you quickly master the essentials of using and developing plugins.\n\n* * *\n\n## Plugin Core Components: 5 Types of Extension Capabilities\n\nPlugins implement functional extensions through 5 types of components, each with a fixed storage location and format requirements.\n\n| Component Type | Storage Location | File Format | Core Function |\n| --- | --- | --- | --- |\n| **Commands** | Plugin root directory `commands/` | Markdown files with frontmatter metadata | Add custom slash commands, such as `/deploy`, `/code-review` |\n| **Agents** | Plugin root directory `agents/` | Markdown files | Provide dedicated sub-agents, such as a code review agent, performance testing agent |\n| **Skills** | Plugin root directory `skills/` | Directory containing `SKILL.md` | Allow Claude to automatically recognize scenarios and invoke them, such as PDF parsing, data visualization |\n| **Hooks** | Plugin root directory `hooks/hooks.json` or inline in `plugin.json` | JSON configuration file | Listen to Claude events and respond automatically, such as automatically formatting code after file editing |\n| **MCP Servers** | Plugin root directory `.mcp.json` or inline in `plugin.json` | JSON configuration file | Connect external tools (e.g., GitHub, Jira), turning their functionality into tools available to Claude |\n| **LSP Servers** | Plugin root directory `.lsp.json` or inline in `plugin.json` | JSON configuration file | Provide code intelligence capabilities, such as syntax checking, go-to-definition, hover hints |\n\n### Key Component Examples\n\n**1. Hook Configuration Example**: Automatically format after file editing\n\n{ "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh" } ] } ] }\n}\n\n: Supports Go language intelligent hints\n\n{ "go": { "command": "gopls", "args": , "extensionToLanguage": { ".go": "go" } }}\n\n* * *\n\n## Plugin Basic Specifications: Installation Scopes and Manifest\n\n### 1. Installation Scope: Determines the Plugin's Availability\n\nWhen installing a plugin, you must choose a scope. Different scopes correspond to different configuration files and use cases:\n\n| Scope | Configuration File Path | Use Case |\n| --- | --- | --- |\n| `user` | `~/.claude/settings.json` | Universal for all personal projects (default) |\n| `project` | `.claude/settings.json` | Team sharing, synced with the code repository |\n| `local` | `.claude/settings.local.json` | Project-specific, ignored by `.gitignore` |\n| `managed` | `managed-settings.json` | Managed plugins, read-only and auto-updating |\n\n### 2. Plugin Manifest: `plugin.json` Must-Knows\n\n`plugin.json` is the **core configuration file** of the plugin, located in the `.claude-plugin/` directory, used to define plugin metadata and component paths.\n\n#### a. Required Fields\n\n| Field | Type | Requirement | Example |\n| --- | --- | --- | --- |\n| `name` | string | Unique identifier, kebab-case format | `"go-code-helper"` |\n\n#### b. Core Metadata Fields\n\n{ "version": "1.0.0", // Semantic Versioning "description": "Provides Go language code intelligence and debugging capabilities", "author": { "name": "Dev Team", "email": "dev@example.com" }, "license": "MIT"}\n#### c. Component Path Fields\n\nUsed to specify the location of custom components. Paths must be **relative to the plugin root directory** and start with `./`:\n\n{ "commands": ["./custom-commands/deploy.md"], "agents": "./custom-agents/", "hooks": "./hooks.json"}\n#### d. Environment Variables\n\n`${CLAUDE_PLUGIN_ROOT}`: The absolute path to the plugin root directory, used in scripts and configurations to reference files within the plugin, avoiding path errors.\n\n### 3. Standard Plugin Directory Structure\n\nmy-plugin/├── .claude-plugin/ # Metadata Directory│ └── plugin.json # Plugin Manifest (Required)├── commands/ # Custom Slash Commands├── agents/ # Sub-agent Definition├── skills/ # Auto Skills├── hooks/ # Event Hook Configuration├── .mcp.json # MCP Server Configuration├── .lsp.json # LSP Server Configuration└── scripts/ # Hook Execution Script\n> Note: Component directories like `commands/` and `agents/` must be in the plugin **root directory**, and cannot be placed inside `.claude-plugin/`.\n\n* * *\n\n## Plugin Management: CLI Command Quick Reference\n\nThrough the Claude Code CLI, you can quickly complete plugin installation, uninstallation, enable/disable, and other operations, which is suitable for scripting and automation scenarios.\n\n| Command | Purpose | Example |\n| --- | --- | --- |\n| `claude plugin install -s ` | Install plugin | `claude plugin install go-lsp --scope project` |\n| `claude plugin uninstall ` | Uninstall plugin | `claude plugin uninstall go-lsp` |\n| `claude plugin enable ` | Enable disabled plugin | `claude plugin enable go-lsp` |\n| `claude plugin disable ` | Disable plugin (without uninstalling) | `claude plugin disable go-lsp` |\n| `claude plugin update ` | Update plugin to latest version | `claude plugin update go-lsp` |\n\n* * *\n\n## Debugging and Troubleshooting: Common Problem Solutions\n\n### 1. Debugging Command\n\nRun the following command to view plugin loading details and locate configuration and loading issues:\n\nclaude --debug\nViewable items: Plugin loading status, manifest syntax errors, component registration status, MCP/LSP server initialization logs.\n\n### 2. High-Frequency Issues and Solutions\n\n| Issue | Cause | Solution |\n| --- | --- | --- |\n| Plugin not loaded | `plugin.json` syntax error or missing required fields | Use `claude plugin validate` to verify JSON syntax, add the `name` field |\n| Custom command not showing | Command file placed inside `.claude-plugin/` | Move the `commands/` directory to the plugin root directory |\n| Hook script not executing | Script lacks executable permissions | Run `chmod +x scripts/your-script.sh` to grant permissions |\n| LSP prompts `Executable not found` | Corresponding language server not installed | Install the binary file (e.g., Go requires installing `gopls`) |\n| MCP server fails to start | Path uses absolute path instead of `${CLAUDE_PLUGIN_ROOT}` | Replace with environment variable reference, e.g., `${CLAUDE_PLUGIN_ROOT}/server` |\n\n* * *\n\n## Version Management and Distribution\n\n* **Version Specification**: Follow semantic versioning `MAJOR.MINOR.PATCH`, such as `1.2.3`\n* **Distribution Channels**: Distribute via the plugin marketplace, or directly share the plugin directory (must include the complete structure)\n* **Changelog**: It is recommended to add a `CHANGELOG.md` in the plugin root directory to record version update contents