Plugins — Empaquetando Todo — Dominando Claude Code

Qué Son los Plugins

A lo largo de este curso has construido piezas individuales de automatización: skills que guían el comportamiento de Claude, hooks que imponen barreras de protección, servidores MCP que conectan datos externos y subagentes que manejan tareas especializadas. Un plugin es la capa de empaquetado que agrupa todas esas piezas en una sola unidad distribuible.

Piensa en un plugin como una caja de herramientas. En lugar de pedirle a cada desarrollador de tu equipo que copie manualmente un SKILL.md aquí, una configuración de hook allá y una definición de servidor MCP en otro lugar, creas un solo plugin que contiene todo. Cualquiera puede instalarlo con un solo comando e inmediatamente acceder a toda la funcionalidad que incluye.

Los plugins resuelven tres problemas a la vez: distribución (llevar tus herramientas a otras personas), consistencia (todos ejecutan la misma versión) y organización (las piezas relacionadas viven juntas en lugar de dispersas en archivos de configuración).

Estructura de un Plugin

Todo plugin sigue un layout de directorios estándar que Claude Code reconoce automáticamente:

my-plugin/
  plugin.json          # manifiesto — nombre, version, componentes
  commands/            # slash commands
    deploy.md
    review.md
  skills/              # skills auto-invocados
    code-style.md
    testing-standards.md
  hooks/               # definiciones de hooks
    pre-commit-lint.sh
  agents/              # definiciones de subagentes
    security-reviewer.md
  .mcp.json            # configuraciones de servidores MCP

El archivo plugin.json es el manifiesto. Le dice a Claude Code qué componentes proporciona el plugin y cómo conectarlos. Los directorios restantes contienen los archivos de componentes reales usando los mismos formatos que ya aprendiste en lecciones anteriores.

Anatomía de plugin.json

Aquí tienes un manifiesto completo para un plugin de desarrollo full-stack:

{
  "name": "fullstack-toolkit",
  "description": "Full-stack development workflows with linting, testing, and deployment",
  "version": "1.2.0",
  "author": "yourname",
  "components": {
    "commands": ["commands/deploy.md", "commands/review.md"],
    "skills": ["skills/code-style.md", "skills/testing-standards.md"],
    "hooks": ["hooks/pre-commit-lint.sh"],
    "agents": ["agents/security-reviewer.md"],
    "mcp": [".mcp.json"]
  },
  "settings": {
    "defaultBranch": "main",
    "testCommand": "npm test"
  }
}

El objeto components mapea cada tipo de componente a sus rutas de archivo dentro del directorio del plugin. El objeto opcional settings define valores configurables que los componentes pueden referenciar. Los números de versión siguen versionado semántico para que los consumidores sepan cuándo ocurren cambios que rompen compatibilidad.

Instalación de Plugins

Hay varias formas de agregar un plugin a tu entorno de Claude Code:

# Instalar desde un repositorio Git
/plugin install https://github.com/yourname/fullstack-toolkit

# Instalar desde un directorio local (util durante desarrollo)
/plugin install ./my-plugin

# Instalar desde npm
/plugin install @yourname/fullstack-toolkit

# Listar plugins instalados
/plugin list

# Eliminar un plugin
/plugin remove fullstack-toolkit

Cuando instalas un plugin, Claude Code copia su contenido en tu directorio local de plugins y registra cada componente. Los comandos se vuelven disponibles como slash commands, los skills se cargan en el sistema de auto-invocación, los hooks se registran en tu configuración y los servidores MCP se configuran en tu .mcp.json.

Creando un Plugin Desde Cero

Construyamos un plugin que imponga estándares de calidad de código. Comienza creando la estructura:

mkdir -p quality-gate/{commands,skills,hooks,agents}
cd quality-gate

Crea el manifiesto:

{
  "name": "quality-gate",
  "description": "Automated code quality enforcement with linting, testing, and security checks",
  "version": "0.1.0",
  "components": {
    "commands": ["commands/check.md"],
    "skills": ["skills/quality-standards.md"],
    "hooks": ["hooks/pre-push-tests.sh"]
  }
}

Agrega un comando en commands/check.md:

---
name: check
description: Run the full quality gate — lint, test, security scan
---

Ejecuta las siguientes verificaciones en secuencia y reporta resultados:

1. Ejecutar el linter del proyecto: `npm run lint`
2. Ejecutar la suite de tests: `npm test`
3. Ejecutar una auditoria de seguridad: `npm audit --production`

Resume todos los resultados en una tabla mostrando estado aprobado/fallido para cada paso.
Si algun paso falla, sugiere correcciones especificas para los problemas encontrados.

Agrega un skill en skills/quality-standards.md:

---
triggers:
  - file_write
  - file_edit
globs: ["**/*.ts", "**/*.tsx"]
---

Al escribir o editar archivos TypeScript, sigue estos estandares:

- Todas las funciones deben tener tipos de retorno explicitos
- Usa `const` por defecto, `let` solo cuando se necesite reasignacion
- Toda funcion exportada requiere un comentario JSDoc
- No usar tipos `any` — usa `unknown` y refina con type guards

Agrega un script de hook en hooks/pre-push-tests.sh:

#!/bin/bash
# Ejecutar tests antes de cualquier operacion git push
echo "Ejecutando quality gate antes del push..."
npm test --silent
if [ $? -ne 0 ]; then
  echo "Los tests fallaron. Push bloqueado."
  exit 1
fi
echo "Todos los tests pasaron. Procediendo con el push."

Auto-Descubrimiento y la Variable Plugin Root

Claude Code descubre automáticamente los componentes escaneando los directorios de plugins. Cuando encuentra un plugin.json, lee el manifiesto y registra cada componente listado. No necesitas conectar nada manualmente después de la instalación.

Dentro de los archivos de tu plugin, usa la variable ${CLAUDE_PLUGIN_ROOT} para referenciar otros archivos relativos a la raíz del plugin. Esto mantiene las rutas portables sin importar dónde se instale el plugin:

Consulta los estandares de codigo definidos en ${CLAUDE_PLUGIN_ROOT}/skills/quality-standards.md
al revisar cambios de codigo.

Esta variable se resuelve en tiempo de ejecución a la ruta real de instalación del plugin, así que tus componentes pueden referenciarse entre sí sin rutas hardcodeadas.

Servidores MCP en Plugins

Los plugins pueden incluir configuraciones de servidores MCP para que las integraciones externas se instalen automáticamente. Incluye un archivo .mcp.json en la raíz del plugin:

{
  "mcpServers": {
    "plugin-github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "plugin-postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Las variables de entorno usan la sintaxis ${VAR_NAME} y se resuelven desde el entorno del usuario en tiempo de ejecución. Esto significa que el plugin puede definir qué integraciones necesita sin incrustar ninguna credencial.

Configuración de Plugin Por Proyecto

Después de instalar un plugin, los proyectos individuales pueden personalizar su comportamiento a través de un archivo de configuración local en .claude/plugin-name.local.md:

# Quality Gate — Configuracion Local

## Sobreescrituras
- Saltar auditoria de seguridad en desarrollo (ejecutar solo en CI)
- Usar `pnpm` en lugar de `npm` para todos los comandos
- Agregar flag `--coverage` a las ejecuciones de tests
- Ruta personalizada de config de lint: `./config/.eslintrc.json`

Esta configuración local es leída por Claude Code y fusionada con los valores por defecto del plugin. Permite que cada proyecto adapte el plugin sin modificar el plugin en sí.

Distribución y Compartición

Una vez que tu plugin está listo, tienes varias opciones para distribución:

Repositorio Git. Sube el directorio del plugin a un repo Git. Cualquiera puede instalarlo con la URL del repo. Etiqueta releases para control de versiones.

Paquete npm. Publica el plugin como un paquete npm para equipos que usan toolchains de Node.js. Agrega un package.json junto al plugin.json y publica normalmente.

Compartición en equipo. Para equipos internos, aloja los plugins en un repositorio Git privado o un directorio compartido. Documenta la instalación en la guía de onboarding de tu equipo.

Prueba esto: crea un plugin simple con un comando y un skill, instálalo localmente y verifica que el comando aparece cuando escribes / en Claude Code.

Mejores Prácticas

Mantén los plugins enfocados. Un plugin debe resolver una categoría de problemas. Un plugin de "quality gate" está bien. Un plugin de "quality gate más despliegue más gestión de base de datos más analíticas" es demasiado amplio -- divídelo en múltiples plugins.

Documenta exhaustivamente. Incluye un README en la raíz de tu plugin que explique qué hace cada componente, qué variables de entorno se necesitan y cualquier prerequisito.

Versiona correctamente. Usa versionado semántico. Incrementa la versión mayor cuando cambies interfaces de componentes, menor para nuevas funcionalidades y parche para correcciones de bugs.

Prueba antes de distribuir. Instala tu plugin en un proyecto limpio y verifica que cada componente funcione. Los plugins rotos erosionan la confianza del equipo en las herramientas.

Mantén los secretos fuera. Nunca incrustes API keys, tokens o contraseñas en archivos del plugin. Siempre usa referencias a variables de entorno y documenta qué variables necesita configurar el usuario.

Con los plugins, todo lo que has aprendido en este curso -- skills, hooks, servidores MCP, subagentes y comandos -- se une en un solo paquete portable que puedes compartir con tu equipo o la comunidad más amplia.