Plugins de Claude Code: instalar, comprobar y eliminar

Un plugin permite trasladar instrucciones o herramientas entre proyectos. Para comprobar la instalación, empieza con un paquete propio que contenga una sola skill de invocación explícita y devuelva una cadena conocida. No necesitas instalar un paquete ajeno con hooks desconocidos.

El ejemplo parte de macOS/Linux y Claude Code ya configurado. En Windows puedes crear los mismos archivos JSON y Markdown con un editor; los comandos de shell requieren Bash o Zsh. La respuesta del modelo necesita conexión. La estructura del paquete se valida por separado.

Crea tres archivos

Desde un directorio nuevo y vacío:

mkdir -p plugin-lab/.claude-plugin
mkdir -p plugin-lab/plugins/load-check/.claude-plugin
mkdir -p plugin-lab/plugins/load-check/skills/ping

Guarda el manifiesto en plugin-lab/plugins/load-check/.claude-plugin/plugin.json:

{
  "name": "load-check",
  "version": "1.0.0",
  "description": "Local plugin loading exercise"
}

En plugin-lab/plugins/load-check/skills/ping/SKILL.md:

---
description: Return a marker to verify this local plugin is loaded.
disable-model-invocation: true
---

Return exactly PLUGIN_READY. Do not use tools or change files.

En plugin-lab/.claude-plugin/marketplace.json:

{
  "name": "local-load-lab",
  "owner": {"name": "Local developer"},
  "plugins": [
    {"name": "load-check", "source": "./plugins/load-check"}
  ]
}

El marketplace indica dónde está el paquete. Dentro de este, .claude-plugin contiene el manifiesto y skills va a su lado. No coloques skills dentro de .claude-plugin: incumpliría la estructura documentada.

Valida e instala

Desde el directorio inicial:

claude --version
claude plugin validate ./plugin-lab/plugins/load-check
claude plugin validate ./plugin-lab
claude

Si el validador falla, corrige el archivo señalado. Una estructura válida no demuestra la calidad de las instrucciones ni la seguridad de un plugin cualquiera.

En la sesión de Claude Code:

/plugin marketplace add ./plugin-lab
/plugin install load-check@local-load-lab

Selecciona Local en el panel de instalación para limitar la prueba al proyecto actual. Antes de confirmar, lee dónde se guardará el ajuste. Si el resumen solicita recargar los plugins, ejecuta /reload-plugins. Consulta la guía de marketplaces.

Comprueba qué skill se ha cargado

/plugin list
/load-check:ping

El primer comando debe mostrar el paquete instalado; el segundo debe devolver PLUGIN_READY. El nombre completo /load-check:ping incluye el plugin y lo distingue de una skill homónima de otro paquete.

Comprueba también el directorio: la skill no debe modificar archivos. La instrucción de no usar herramientas se dirige al modelo; no crea una barrera de permisos del sistema. El acceso se controla con los permisos de Claude Code.

Si falta el comando, revisa en este orden el nombre del manifiesto, la ruta skills/ping/SKILL.md, el alcance elegido, el estado enabled y la necesidad de recarga. Prueba por separado la carga mediante marketplace y el arranque con --plugin-dir.

Desactiva, actualiza o elimina

claude plugin disable load-check@local-load-lab --scope local
claude plugin enable load-check@local-load-lab --scope local
claude plugin update load-check@local-load-lab --scope local
claude plugin uninstall load-check@local-load-lab --scope local

Ejecuta los comandos uno a uno desde el mismo proyecto y comprueba el resultado. --scope local corresponde al alcance elegido; sin él, update y uninstall usan user por defecto. Reinicia tras actualizar si lo pide el CLI. Después de desactivar o eliminar, abre una sesión nueva y confirma que la skill ya no está disponible. Después de activarla, repite la prueba.

Para comprobar cambios de contenido, modifica el marcador de la skill original y aumenta la versión del paquete. Después actualiza el marketplace y el plugin instalado según la guía de gestión. Editar el archivo original no necesariamente cambia una copia instalada en caché.

Antes de instalar un plugin ajeno

Inspecciona su contenido. Una skill de texto, un hook con comandos de shell y un servidor MCP tienen consecuencias distintas. Revisa comandos, servicios externos e instrucciones que pidan secretos. No concedas permisos adicionales solo para hacer desaparecer un error.

En un proyecto de trabajo, repite el ciclo: alcance conocido, componente visible, acción esperada, revisión de archivos y una forma clara de desactivarlo. El manual de plugins detalla el formato y el validador.