Plugins — Empaquetando Todo — Dominando Claude Code

Que Son los Plugins

A lo largo de este curso has construido piezas individuales de automatizacion: skills que guian el comportamiento de Claude, hooks que imponen barreras de proteccion, 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 aqui, una configuracion de hook alla y una definicion 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: distribucion (llevar tus herramientas a otras personas), consistencia (todos ejecutan la misma version) y organizacion (las piezas relacionadas viven juntas en lugar de dispersas en archivos de configuracion).

Estructura de un Plugin

Todo plugin sigue un layout de directorios estandar que Claude Code reconoce automaticamente:

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 que componentes proporciona el plugin y como conectarlos. Los directorios restantes contienen los archivos de componentes reales usando los mismos formatos que ya aprendiste en lecciones anteriores.

Anatomia de plugin.json

Aqui 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 numeros de version siguen versionado semantico para que los consumidores sepan cuando ocurren cambios que rompen compatibilidad.

Instalacion 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-invocacion, los hooks se registran en tu configuracion y los servidores MCP se configuran en tu .mcp.json.

Creando un Plugin Desde Cero

Construyamos un plugin que imponga estandares de calidad de codigo. 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 automaticamente 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 despues de la instalacion.

Dentro de los archivos de tu plugin, usa la variable ${CLAUDE_PLUGIN_ROOT} para referenciar otros archivos relativos a la raiz del plugin. Esto mantiene las rutas portables sin importar donde 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 ejecucion a la ruta real de instalacion del plugin, asi que tus componentes pueden referenciarse entre si sin rutas hardcodeadas.

Servidores MCP en Plugins

Los plugins pueden incluir configuraciones de servidores MCP para que las integraciones externas se instalen automaticamente. Incluye un archivo .mcp.json en la raiz 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 ejecucion. Esto significa que el plugin puede definir que integraciones necesita sin incrustar ninguna credencial.

Configuracion de Plugin Por Proyecto

Despues de instalar un plugin, los proyectos individuales pueden personalizar su comportamiento a traves de un archivo de configuracion 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 configuracion local es leida por Claude Code y fusionada con los valores por defecto del plugin. Permite que cada proyecto adapte el plugin sin modificar el plugin en si.

Distribucion y Comparticion

Una vez que tu plugin esta listo, tienes varias opciones para distribucion:

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.

Comparticion en equipo. Para equipos internos, aloja los plugins en un repositorio Git privado o un directorio compartido. Documenta la instalacion en la guia de onboarding de tu equipo.

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

Mejores Practicas

Manten los plugins enfocados. Un plugin debe resolver una categoria de problemas. Un plugin de "quality gate" esta bien. Un plugin de "quality gate mas despliegue mas gestion de base de datos mas analiticas" es demasiado amplio -- dividelo en multiples plugins.

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

Versiona correctamente. Usa versionado semantico. Incrementa la version 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.

Manten los secretos fuera. Nunca incrustes API keys, tokens o contrasenas en archivos del plugin. Siempre usa referencias a variables de entorno y documenta que 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 mas amplia.