Qué son los plugins de Claude Code y cuánto cuestan

Qué es un plugin de Claude Code

Un plugin de Claude Code es un directorio de componentes que Claude Code carga y gestiona como una unidad única. Estos componentes son habilidades, agentes, hooks, servidores MCP, servidores LSP y monitores en segundo plano. Instalar un plugin añade todas sus partes a la vez, bajo un mismo nombre, y deshabilitarlo las elimina de la misma forma.

Un plugin no otorga al agente ninguna capacidad que no tuviera ya. Cada parte dentro de un plugin es algo que usted puede escribir manualmente en un directorio .claude/. El plugin es la capa de empaquetado: una forma de versionar esas partes, entregarlas a quince personas y actualizarlas más tarde sin pedir a nadie que copie archivos. Esa es la idea completa, y la mayor parte de la confusión sobre los plugins proviene de esperar que sean un nuevo tipo de capacidad.

El manifiesto opcional en .claude-plugin/plugin.json nombra al plugin, y ese nombre se convierte en un espacio de nombres. Una habilidad en un plugin llamado commit-commands se invoca como /commit-commands:commit, por lo que dos plugins pueden incluir cada uno una habilidad llamada commit sin que una oculte a la otra. Los agentes de los plugins tienen el mismo ámbito en la lista de menciones @, como plugin-name:agent-name.

Plugin, skill, servidor MCP o archivo de reglas

Estos cuatro términos se utilizan a menudo como si fueran competidores. No lo son, y vale la pena definir sus límites una vez.

• Una skill es una unidad de instrucción que Claude carga cuando la tarea lo requiere. Consulte qué es realmente una Agent Skill.
• Un servidor MCP es un proceso independiente que expone herramientas al agente mediante un protocolo; a menudo es un servicio de red que usted mismo ejecuta.
• Un archivo de reglas como CLAUDE.md es contexto del proyecto que se lee al iniciar la sesión y se aplica a todo.
• Un plugin es un contenedor que puede agrupar skills, agentes, hooks y definiciones de servidores MCP, además de un número de versión y un canal de distribución.

Por lo tanto, la pregunta que responde un plugin no es "¿qué puede hacer el agente?". Es "¿cómo distribuyo esto a mi equipo y lo actualizo el próximo mes?". Si está decidiendo entre los tres primeros, la comparación entre skills, servidores MCP y archivos de reglas cubre esa decisión en detalle. Si lo que le interesa es la parte de MCP, ejecutar sus propios servidores MCP en un VPS cubre el aspecto del alojamiento.

Ubicación de los plugins y su estructura interna

Un plugin instalado desde un marketplace se copia en una caché local en ~/.claude/plugins/cache en lugar de ejecutarse desde la ubicación donde se clonó. Cada versión instalada obtiene su propio directorio. Al actualizar o desinstalar, el directorio de la versión anterior se marca como huérfano y se elimina unas dos semanas después; esto permite que una sesión que ya cargó la versión antigua siga funcionando en lugar de fallar durante una tarea.

Debido a que la ruta cambia con cada actualización, un plugin nunca debe incluir su propia ubicación de forma estática (hardcoded). Los hooks y las configuraciones de MCP dentro de un plugin utilizan ${CLAUDE_PLUGIN_ROOT}, que se resuelve en el directorio de instalación actual. El estado que debe persistir tras una actualización se almacena en ${CLAUDE_PLUGIN_DATA}, que se resuelve en un directorio estable bajo ~/.claude/plugins/data/.

Solo el directorio del plugin se copia en la caché, lo cual tiene una consecuencia que suele detectarse tarde. Una ruta que apunta fuera de la raíz del plugin, como ../shared-utils, funciona mientras se desarrolla con una ruta local, pero falla tras la instalación porque dichos archivos nunca se copiaron.

La estructura es la siguiente.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

Solo plugin.json va dentro de .claude-plugin/. Todo lo demás se sitúa en la raíz del plugin. Colocar skills/ o hooks/ dentro de .claude-plugin/ es la razón más común por la que un plugin se instala correctamente pero no realiza ninguna acción: Claude Code busca esos directorios en la raíz, no encuentra ninguno y carga un plugin sin componentes.

El manifiesto en sí es pequeño.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0"
}

Cómo instalar un plugin de Claude Code

La instalación consta de dos pasos, y el primero no instala nada. Debe añadir un marketplace, que es un catálogo de plugins, y luego instalar los plugins individuales desde él. El marketplace oficial de Anthropic, claude-plugins-official, se registra automáticamente la primera vez que inicia Claude Code de forma interactiva. Los demás debe añadirlos usted mismo.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

Tenga en cuenta que el repositorio es anthropics/claude-code, mientras que el marketplace se denomina claude-code-plugins. El nombre proviene del archivo de catálogo dentro del repositorio, no de la ruta del repositorio; por lo tanto, consulte el nombre del marketplace en la pestaña Marketplaces de /plugin antes de escribir un comando de instalación.

Tras la instalación, lea la línea de resumen. Plugin is now active. indica que los componentes se han cargado en esta sesión. Run /reload-plugins to activate. significa que no lo han hecho y que debe ejecutar ese comando. Si /reload-plugins advierte que volvería a leer la conversación, ejecútelo de nuevo como /reload-plugins --force. A continuación, confirme que el plugin está realmente presente: /plugin lo muestra en la pestaña Installed, /help enumera sus habilidades en Custom commands, y cualquier elemento que no se haya cargado aparecerá en la pestaña Errors junto con el motivo.

La instalación solicita un ámbito (scope), el cual determina quién tiene acceso al plugin. El ámbito de usuario (user scope) es usted, en todos los proyectos. El ámbito de proyecto (project scope) escribe el plugin en el archivo .claude/settings.json del repositorio bajo enabledPlugins, de modo que se le ofrezca a cualquiera que clone el repositorio. El ámbito local (local scope) es usted, solo en este repositorio.

Para un script, un Dockerfile o cualquier sesión donde no esté disponible un panel interactivo, utilice la forma de shell. Esta instala el plugin en el ámbito de usuario a menos que pase el flag --scope.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

claude plugin install se ejecuta fuera de una sesión, por lo que una sesión que ya esté abierta no verá el nuevo plugin hasta que ejecute /reload-plugins o inicie una sesión nueva.

La gestión de los elementos instalados sigue el mismo patrón en ambos casos. /plugin list muestra lo que está instalado y acepta --enabled o --disabled. /plugin disable name@marketplace desactiva un plugin sin eliminarlo, /plugin enable lo vuelve a activar y /plugin uninstall lo elimina. Las formas de comando con barra diagonal abren el panel de plugins para aplicar el cambio; por eso, los equivalentes de shell claude plugin ... son los que deben usarse en los scripts.

Para proporcionar un marketplace a todo un equipo, inclúyalo en el archivo .claude/settings.json del proyecto. A los miembros se les solicitará instalarlo una vez que confíen en la carpeta del repositorio.

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

Mientras desarrolla su propio plugin, omita el marketplace por completo. claude --plugin-dir ./my-plugin carga un directorio para esa sesión, /reload-plugins detecta sus ediciones sin necesidad de reiniciar y claude plugin validate ./my-plugin verifica el manifiesto, la habilidad y el frontmatter del agente, así como hooks/hooks.json, antes de que nadie más pueda verlo.

¿Cuánto cuesta un plugin de Claude Code?

El mecanismo es gratuito. A fecha de agosto de 2026, no existe cargo alguno por añadir un marketplace, instalar un plugin o mantenerlo habilitado. Los marketplaces oficiales y comunitarios son repositorios git públicos, y un plugin es un directorio de archivos de texto.

Lo que cuesta un plugin son tokens, y los tokens son lo que mide realmente su suscripción o su factura de API. Ese coste se presenta de tres formas distintas, y su comportamiento varía.

Coste de contexto permanente. Lo que un plugin aporta permanece en su contexto y se vuelve a leer en cada turno de la sesión. Antes de instalarlo, la vista de detalles /plugin muestra una estimación Context cost en tokens, además de una sección Will install que enumera los comandos, habilidades, agentes, hooks y servidores MCP y LSP que está a punto de añadir. Lea ambos. Los plugins de marketplaces locales o personalizados podrían no proporcionar esos datos; en ese caso, deberá realizar una estimación manual. Un plugin que incluye un servidor MCP suele ser el más pesado, ya que las definiciones de herramientas son extensas, aunque en modelos que soportan la búsqueda de herramientas MCP, dichas definiciones se posponen hasta que se necesita la herramienta.

Coste de invocación. Ejecutar la habilidad de un plugin añade sus instrucciones a la conversación, por lo que solo paga por el cuerpo de la habilidad cuando se utiliza. Un agente es diferente. Un subagente ejecuta su propia conversación con su propio prompt de sistema y su propia caché, comenzando sin aciertos de caché; por lo tanto, un plugin cuyo flujo de trabajo genera agentes cuesta considerablemente más de lo que sugiere su estimación de contexto.

Coste de caché. Habilitar o deshabilitar un plugin a mitad de una sesión puede forzar a que la siguiente petición reprocese toda su conversación. Las habilidades, comandos, agentes, hooks, servidores LSP, monitores y temas nunca provocan esto: lo que añaden se adjunta después del historial existente, por lo que la siguiente petición paga por el nuevo contenido y sigue leyendo todo lo anterior desde la caché. La excepción es un plugin que proporciona un servidor MCP. Si sus herramientas se posponen mediante la búsqueda de herramientas, la caché sobrevive. Si se cargan en el prefijo del prompt, la siguiente petición vuelve a leer toda la conversación como entrada no cacheada. Esa es precisamente la razón por la que /reload-plugins advierte y se niega en ese caso hasta que usted pase --force.

Puede monitorizar esto en lugar de adivinarlo. Cada respuesta de la API informa de cache_read_input_tokens y cache_creation_input_tokens, y una línea de estado personalizada que muestra el uso de tokens en tiempo real le presenta ambos datos. Una sesión saludable lee mucho más de lo que crea. Si la creación se mantiene alta turno tras turno, algo en su prefijo está cambiando en cada turno. Para obtener una visión más amplia de qué está llenando la ventana, consulte cómo gestionar la ventana de contexto de Claude Code y qué significan realmente esos recuentos de tokens.

Una tarea de mantenimiento se paga sola. La pestaña Installed agrupa los plugins que no ha utilizado en al menos dos semanas bajo un encabezado Not used recently, con una línea Last used en la vista de detalles. Esos plugins siguen costándole tiempo de inicio y contexto en cada sesión. Deshabilítelos o desinstálelos.

Un plugin se ejecuta con sus permisos

La documentación de Anthropic es directa al respecto: los plugins y los marketplaces son componentes de alta confianza que pueden ejecutar código arbitrario en su máquina con los privilegios de su usuario. Esto no es hipotético. Los hooks de un plugin ejecutan comandos de shell en eventos de sesión, incluyendo antes y después de las llamadas a herramientas. Su directorio bin/ se añade al PATH de la herramienta Bash mientras el plugin está habilitado. Sus servidores MCP son procesos que el plugin inicia. Nada de esto está aislado de su cuenta de usuario.

En un equipo portátil, ese riesgo está limitado a lo que su usuario de escritorio puede alcanzar. En un servidor, normalmente no es así. La cuenta que ejecuta el agente a menudo posee claves SSH, tokens de despliegue, una sesión de CLI en la nube y acceso al socket de Docker, por lo que "código arbitrario como su usuario" significa la máquina completa. Si Claude Code se ejecuta en un VPS, lea cómo ejecutar Claude Code de forma segura en un VPS antes de instalar nada, y cómo mantener las credenciales fuera del alcance de un agente antes de instalar un plugin que se comunique con un servicio externo.

Existen algunas medidas de seguridad y es útil conocer cuáles son. Un plugin con alcance de proyecto proviene del repositorio y no de usted, por lo que solo se carga después de que usted confíe en el espacio de trabajo; sus servidores MCP aún requieren aprobación por servidor, sus servidores LSP esperan a esa confianza y sus monitores en segundo plano no se cargan en absoluto. Los agentes distribuidos mediante plugins no tienen permitido declarar hooks, servidores MCP ni un modo de permisos. Los plugins del marketplace se copian en la caché omitiendo los enlaces simbólicos que apuntan fuera del marketplace, por lo que un plugin no puede extraer archivos arbitrarios del host.

Nada de esto sustituye la revisión de lo que instala. Compruebe la lista Will install, prefiera plugins cuyo código fuente pueda abrir y leer, mantenga los plugins de su equipo en un repositorio de marketplace que usted controle y ejecute claude plugin validate sobre cualquier cosa que escriba usted mismo.

FAQ

¿Los plugins de Claude Code tienen un coste adicional?

No. No hay ninguna tarifa por el sistema de plugins, por añadir un marketplace o por instalar un plugin. El coste es el consumo de tokens, facturado según su plan o su gasto en la API como cualquier otro contexto. Un plugin añade contexto permanente en cada turno, añade más cuando se invoca una de sus habilidades o agentes, y puede forzar un turno costoso sin caché si proporciona un servidor MCP cuyas herramientas se cargan en el prefijo del prompt. La vista de detalles /plugin muestra una estimación Context cost antes de realizar la instalación.

¿Cuál es la diferencia entre un plugin y una habilidad?

Una habilidad es una unidad única de instrucción. Un plugin es un paquete que puede contener habilidades, agentes, hooks, servidores MCP, servidores LSP y monitores, con un nombre, una versión y un marketplace desde el cual instalarlo. Escriba una habilidad independiente en .claude/ cuando sea para usted y este proyecto. Una habilidad de propósito único como Ponytail, que impulsa al agente hacia el cambio más pequeño que funcione es el caso más claro: un archivo con una regla, hasta el día en que su equipo también la necesite. Conviértala en un plugin cuando otras personas la necesiten y requiera actualizaciones a lo largo del tiempo. Las habilidades de los plugins tienen un espacio de nombres, por lo que una habilidad dentro de un plugin se invoca como /plugin-name:skill-name en lugar de /skill-name.

Mi plugin se instaló pero sus habilidades no aparecen. ¿Qué ocurre?

Primero, revise el resumen de instalación. Si decía Run /reload-plugins to activate., los componentes aún no se han cargado; si la recarga advierte que volverá a leer la conversación, ejecútela de nuevo como /reload-plugins --force. Si se cargó pero no muestra nada, abra /plugin y lea la pestaña Errors. El error estructural más común es colocar skills/, agents/ o hooks/ dentro de .claude-plugin/, donde Claude Code no los busca. Recuerde que las habilidades de los plugins tienen un espacio de nombres, por lo que debe buscar /plugin-name:skill-name en la pestaña Custom commands de /help. Como último recurso, rm -rf ~/.claude/plugins/cache, reinicie y reinstale.

¿Puedo instalar plugins sin el panel interactivo?

Sí. Utilice el comando de shell claude plugin install name@marketplace, que instala en el ámbito del usuario a menos que pase --scope project o --scope local. Funciona en scripts, imágenes y entornos no interactivos donde el panel /plugin no está disponible. Debido a que se ejecuta fuera de una sesión, una sesión que ya esté abierta necesita /reload-plugins antes de que el plugin surta efecto.

¿Es seguro instalar un plugin desde un marketplace que encontré en GitHub?

Trátelo como trataría la ejecución del script de instalación de ese repositorio como usted mismo, porque es prácticamente lo mismo. Un plugin puede ejecutar comandos de shell a través de hooks, añadir ejecutables al PATH de la herramienta Bash e iniciar servidores MCP, todo ello con los privilegios de su usuario. Anthropic no controla ni verifica el contenido de plugins de terceros. Instale desde fuentes que pueda leer, revise la lista Will install antes de confirmar y sea más estricto en un servidor que en un portátil, ya que la cuenta allí suele contener claves y tokens que merece la pena robar.