Cómo instalar plugins en Claude Code

El sistema de plugins depende de la versión de Claude Code, así que lo primero es asegurarte de que no estás en una versión antigua. Si lo instalaste hace tiempo con npm, conviene migrar al instalador nativo, que es el método recomendado actualmente y se autoactualiza. Ejecuta el comando de tu sistema operativo; si ya lo tienes instalado, reinstalar no borra tu configuración de ~/.claude. Después comprueba la versión y fuerza una actualización por si acaso. Cuando termine, abre tu proyecto de prueba y lanza claude. Escribe /plugin en el prompt: si aparece el gestor de plugins (un menú interactivo para explorar marketplaces y plugins), estás listo. Si Claude Code te responde que no reconoce el comando, tu versión no es la correcta o tienes dos instalaciones conviviendo en el PATH.

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
# irm https://claude.ai/install.ps1 | iex

# Comprobar versión y actualizar
claude --version
claude update

# Detectar instalaciones duplicadas (macOS/Linux)
which -a claude

En Claude Code los plugins no se instalan sueltos: viven en marketplaces, que son repositorios (o carpetas) con un archivo .claude-plugin/marketplace.json que lista los plugins disponibles. Antes de instalar nada tienes que registrar al menos uno. Dentro de una sesión de Claude Code usa /plugin marketplace add seguido de la fuente. Lo más habitual es un repositorio de GitHub en formato usuario/repo, pero también acepta una URL git completa o una ruta local, muy útil para probar plugins que estás desarrollando o para entornos corporativos sin acceso a GitHub público. Anthropic mantiene marketplaces oficiales en GitHub, y la comunidad (también en España y LATAM) publica los suyos; consulta la documentación oficial de Claude Code para ver los repositorios actuales. Cuando el marketplace se añade, Claude Code te muestra su nombre: apúntalo, porque lo necesitarás para instalar plugins con la sintaxis plugin@marketplace.

# Dentro de Claude Code (prompt interactivo)

# Desde GitHub (formato usuario/repo)
/plugin marketplace add mi-org/claude-plugins

# Desde una URL git completa
/plugin marketplace add https://gitlab.com/mi-org/claude-plugins.git

# Desde una carpeta local que contiene .claude-plugin/marketplace.json
/plugin marketplace add ./mis-plugins

# Ver los marketplaces registrados
/plugin marketplace list

Tienes dos caminos. El visual: escribe /plugin y navega por el menú interactivo hasta la opción de explorar plugins, elige el marketplace, revisa la descripción de cada plugin (qué comandos, agentes, hooks o servidores MCP trae) y confirma la instalación. El directo, más rápido cuando ya sabes lo que quieres: /plugin install nombre-plugin@nombre-marketplace. El sufijo @marketplace es importante porque dos marketplaces distintos pueden tener plugins con el mismo nombre. Durante la instalación Claude Code puede preguntarte el ámbito: para ti en todos tus proyectos (usuario) o solo para el proyecto actual. Como regla práctica, instala a nivel de usuario las utilidades personales (por ejemplo, un plugin de commits) y a nivel de proyecto lo que dependa del stack concreto. Tras instalar, Claude Code suele indicarte que reinicies la sesión para cargar todos los componentes.

# Dentro de Claude Code

# Instalación directa
/plugin install formateador-commits@mi-org-plugins

# O abre el gestor interactivo y explora
/plugin

# Después, sal y vuelve a entrar para cargar el plugin
/exit

Que la instalación diga 'ok' no significa que todo funcione. Reinicia Claude Code en tu proyecto y comprueba cada tipo de componente que el plugin declara. Si trae comandos slash, escribe / y verás el autocompletado con los nuevos comandos (o usa /help). Si trae subagentes, ábrelos con /agents. Si incluye servidores MCP, /mcp te muestra su estado: conectado, fallido o pendiente de autenticación. Los hooks no se ven a simple vista: provoca el evento que los dispara (por ejemplo, editar un archivo si es un hook tras edición) y observa la salida. Si algo falla, arranca Claude Code en modo debug: verás en la terminal los errores de carga del plugin, como un JSON mal formado o un binario que el servidor MCP no encuentra. Finalmente, prueba el plugin con una tarea real pequeña y pide a Claude que te explique qué herramienta del plugin ha usado.

# Reinicia en modo debug para ver errores de carga
claude --debug

# Ya dentro de Claude Code, comprueba los componentes:
/help      # comandos slash nuevos
/agents    # subagentes añadidos
/mcp       # estado de servidores MCP del plugin
/plugin    # estado del plugin (instalado / habilitado)

Con el tiempo acumularás plugins, y cada uno añade contexto, comandos y posibles hooks. Mantén solo lo que usas. Puedes desactivar un plugin sin desinstalarlo, ideal cuando sospechas que un hook está interfiriendo y quieres descartarlo rápido. Si ya no lo necesitas, desinstálalo. Para recibir nuevas versiones, actualiza el marketplace: Claude Code vuelve a leer el repositorio y detecta cambios. Si un marketplace deja de interesarte, elimínalo y sus plugins dejarán de estar disponibles. Todo esto también puedes hacerlo desde el menú interactivo de /plugin si prefieres no recordar la sintaxis. Recuerda reiniciar la sesión después de cambios importantes para que el estado en memoria coincida con la configuración.

# Dentro de Claude Code

# Desactivar / reactivar sin desinstalar
/plugin disable formateador-commits@mi-org-plugins
/plugin enable formateador-commits@mi-org-plugins

# Desinstalar
/plugin uninstall formateador-commits@mi-org-plugins

# Actualizar el catálogo de un marketplace
/plugin marketplace update mi-org-plugins

# Eliminar un marketplace
/plugin marketplace remove mi-org-plugins

Si trabajas en equipo, no tiene sentido que cada developer añada marketplaces a mano. Claude Code permite declararlos en el archivo .claude/settings.json del repositorio. Con extraKnownMarketplaces registras los marketplaces y con enabledPlugins indicas qué plugins deben estar habilitados. Cuando un compañero abra el proyecto y confíe en la carpeta, Claude Code le propondrá instalar esos marketplaces y plugins. Haz commit del archivo y todo el equipo, esté en Madrid, Ciudad de México o Bogotá, trabajará con las mismas herramientas. Para preferencias personales que no quieras imponer, usa .claude/settings.local.json, que no debería subirse al repo. Valida el JSON antes de hacer commit: una coma de más rompe la carga de toda la configuración del proyecto, no solo de los plugins.

{
  "extraKnownMarketplaces": {
    "mi-org-plugins": {
      "source": {
        "source": "github",
        "repo": "mi-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "formateador-commits@mi-org-plugins": true,
    "revisor-seguridad@mi-org-plugins": true
  }
}