Manual de referencia de plugins de Claude Code
Los plugins son elnúcleo de extensión de funcionalidades, te permiten añadir capacidades como comandos slash personalizados, subagentes, hooks de automatización, etc. Este tutorial aborda desdecomponentes principales、especificaciones de configuración、gestión CLItres dimensiones para que domines rápidamente los puntos clave del uso y desarrollo de plugins.
Componentes principales de los plugins: 5 tipos de capacidades de extensión
Los plugins logran la extensión de funciones mediante 5 tipos de componentes, cada uno con una ubicación de almacenamiento fija y requisitos de formato.
| Tipo de componente | Ubicación de almacenamiento | Formato de archivo | Función principal |
|---|---|---|---|
| Comando | Directorio raíz del plugincommands/ |
Archivo Markdown con metadatos frontmatter | Añade comandos slash personalizados, por ejemplo/deploy /code-review |
| Agente | Directorio raíz del pluginagents/ |
Archivo Markdown | Proporciona subagentes exclusivos, como agentes de revisión de código o agentes de pruebas de rendimiento |
| Skill | Directorio raíz del pluginskills/ |
que contieneSKILL.mdel directorio |
Permite que Claude reconozca automáticamente el escenario y lo invoque, como el análisis de PDF o la visualización de datos |
| Hook | Directorio raíz del pluginhooks/hooks.jsonoplugin.jsonInline |
Archivo de configuración JSON | Escucha los eventos de Claude y responde automáticamente, por ejemplo, formatear el código automáticamente después de editar un archivo |
| Servidor MCP | Directorio raíz del plugin.mcp.jsonoplugin.jsonInline |
Archivo de configuración JSON | Conecta herramientas externas (como GitHub, Jira) y convierte sus funciones en herramientas utilizables por Claude |
| Servidor LSP | Directorio raíz del plugin.lsp.jsonoplugin.jsonInline |
Archivo de configuración JSON | Proporciona capacidades de inteligencia de código, como verificación de sintaxis, ir a la definición e información al pasar el cursor |
Ejemplos de componentes clave
1. Ejemplo de configuración de Hook: formateo automático después de editar el archivo
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
}
]
}
]
}
}
{
"go": {
"command": "gopls",
"args": ["serve"],
"extensionToLanguage": {
".go": "go"
}
}
}
Especificaciones básicas de los plugins: alcance de instalación y manifiesto
1. Alcance de instalación: determina el ámbito de uso del plugin
Al instalar un plugin, debes seleccionar un alcance; los diferentes alcances corresponden a diferentes archivos de configuración y casos de uso:
| Alcance | Ruta del archivo de configuración | Caso de uso aplicable |
|---|---|---|
user |
~/.claude/settings.json |
Común a todos los proyectos personales (predeterminado) |
project |
.claude/settings.json |
Compartido por el equipo, sincronizado con el repositorio de código |
local |
.claude/settings.local.json |
Exclusivo del proyecto, ignorado por.gitignoreignorado |
managed |
managed-settings.json |
Plugin alojado, de solo lectura y actualización automática |
2. Manifiesto del plugin:plugin.jsonPuntos clave imprescindibles
plugin.jsones elarchivo de configuración principal, se encuentra en el.claude-plugin/directorio; se utiliza para definir los metadatos del plugin y las rutas de los componentes.
a. Campos obligatorios
| Campo | Tipo | Requisito | Ejemplo |
|---|---|---|---|
name |
string | Identificador único, en formato kebab-case | "go-code-helper" |
b. Campos de metadatos principales
{
"version": "1.0.0", // 语义化版本
"description": "提供 Go 语言代码智能和调试能力",
"author": {
"name": "Dev Team",
"email": "dev@example.com"
},
"license": "MIT"
}
c. Campos de ruta de componentes
Se utiliza para especificar la ubicación de los componentes personalizados; la ruta debeser relativa al directorio raíz del pluginy debe comenzar./con:
{
"commands": ["./custom-commands/deploy.md"],
"agents": "./custom-agents/",
"hooks": "./hooks.json"
}
d. Variable de entorno
${CLAUDE_PLUGIN_ROOT}: la ruta absoluta del directorio raíz del plugin, utilizada en scripts y configuraciones para hacer referencia a los archivos del plugin y evitar errores de ruta.
3. Estructura estándar del directorio de plugins
my-plugin/ ├── .claude-plugin/ # 元数据目录 │ └── plugin.json # 插件清单(必需) ├── commands/ # 自定义斜杠命令 ├── agents/ # 子代理定义 ├── skills/ # 自动技能 ├── hooks/ # 事件钩子配置 ├── .mcp.json # MCP 服务器配置 ├── .lsp.json # LSP 服务器配置 └── scripts/ # 钩子执行脚本
Nota:
commands/agents/Los directorios de componentes mencionados deben estar en eldirectorio raíz, no pueden ubicarse.claude-plugin/dentro de.
Gestión de plugins: referencia rápida de comandos CLI
Mediante la CLI de Claude Code puedes completar rápidamente operaciones como instalar, desinstalar, habilitar/deshabilitar plugins, adecuado para entornos de scripting y automatización.
| Comando | Uso | Ejemplo |
|---|---|---|
claude plugin install <插件名> -s <范围> |
Instalar plugin | claude plugin install go-lsp --scope project |
claude plugin uninstall <插件名> |
Desinstalar plugin | claude plugin uninstall go-lsp |
claude plugin enable <插件名> |
Habilitar un plugin deshabilitado | claude plugin enable go-lsp |
claude plugin disable <插件名> |
Deshabilitar plugin (sin desinstalar) | claude plugin disable go-lsp |
claude plugin update <插件名> |
Actualizar plugin a la última versión | claude plugin update go-lsp |
Depuración y resolución de problemas: solución de problemas comunes
1. Comandos de depuración
Ejecuta el siguiente comando para ver los detalles de carga del plugin y localizar problemas de configuración y carga:
claude --debug
Se puede ver: estado de carga del plugin, errores de sintaxis del manifiesto, registro de componentes y registros de inicialización de los servidores MCP/LSP.
2. Problemas frecuentes y soluciones
| Problema | Causa | Solución |
|---|---|---|
| El plugin no se carga | plugin.jsonError de sintaxis o falta de campos obligatorios |
usarclaude plugin validateValida la sintaxis JSON y añade losnamecampos |
| Los comandos personalizados no se muestran | El archivo del comando está en el.claude-plugin/dentro |
va acommands/directorio; muévelo al directorio raíz del plugin |
| El script de Hook no se ejecuta | El script no tiene permiso de ejecución | Ejecutachmod +x scripts/your-script.shpara otorgar el permiso |
Aviso del LSPExecutable not found |
No se ha instalado el servidor de lenguaje correspondiente | Instala el binario (por ejemplo, para Go se necesita instalargopls) |
| Error al iniciar el servidor MCP | La ruta utiliza una ruta absoluta; no se ha usado${CLAUDE_PLUGIN_ROOT} |
reemplázala con una referencia a variable de entorno, como${CLAUDE_PLUGIN_ROOT}/server |
Gestión de versiones y distribución
- Especificación de versiones: seguir el versionado semántico
MAJOR.MINOR.PATCH, por ejemplo1.2.3 - Canal de distribución: se distribuye a través del mercado de plugins, o se comparte directamente el directorio del plugin (debe incluir la estructura completa)
- Registro de cambios: se recomienda añadir en el directorio raíz del plugin
CHANGELOG.md, para registrar el contenido de las actualizaciones de versión