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"
          }
        ]
      }
    ]
  }
}

: soporte de sugerencias inteligentes para el lenguaje Go

{
  "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ánticoMAJOR.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 pluginCHANGELOG.md, para registrar el contenido de las actualizaciones de versión
Otras extensiones