Módulo 5: Plugins — Crear y Distribuir

1. Introducción al Módulo — De Configuraciones Locales a Plugins Distribuibles

Siguiente →

1. Introducción al Módulo — De Configuraciones Locales a Plugins Distribuibles

Descripción

En los módulos anteriores creaste subagents con identidad propia, les diste memoria persistente, los coordinaste en paralelo, y los organizaste en equipos con team lead y task board. Todo funciona. Pero hay un problema que probablemente ya notaste: tus configuraciones viven en .claude/agents/ de un proyecto específico. Si mañana empiezas un proyecto nuevo, copias los archivos manualmente. Si un colega quiere tu configuración de team lead + backend-agent + frontend-agent, le compartes una carpeta por Slack y le dices "ponla en .claude/agents/." Si actualizas un agent file, cada proyecto que lo usa tiene una versión diferente.

Eso es el equivalente de distribuir código copiando archivos entre máquinas. Funcionó en los años 90. Hoy tenemos package managers por una razón: versionado, distribución, dependencias, y actualizaciones. Los plugins de Claude Code aplican ese mismo principio a tus configuraciones de agentes.

Un plugin es un paquete npm que bundlea subagents, skills, hooks, y MCP servers en una unidad instalable. En lugar de copiar archivos, ejecutas claude plugins add @your-org/code-quality-plugin y tienes todo configurado — los agentes, las skills que precargan, los hooks de validación, todo. Si publicas una actualización, tus colegas la reciben con un update. Si necesitas pinear una versión porque la nueva rompe algo, lo haces en el manifiesto.

Este módulo te enseña a crear, testear, y distribuir plugins. Pasas de "scripts en mi máquina" a "paquetes que cualquiera puede instalar."

⚠️ FEATURE EXPERIMENTAL

El sistema de plugins de Claude Code es una feature experimental. La API de claudeCodePlugin, la estructura de directorios, y los comandos de instalación pueden cambiar entre versiones. Este módulo enseña el modelo mental (empaquetar configuraciones para distribución) y la implementación práctica según la especificación disponible a marzo 2026.

Si el sistema de plugins no está accesible en tu versión de Claude Code, cada cápsula incluye alternativas usando distribución manual (git submodules, scripts de setup). Los patrones de organización son transferibles.

Última verificación de funcionalidad: Marzo 2026

¿Dónde Estamos en la Guía?

Contexto en la Guía

Esta guía tiene 8 módulos organizados en 3 phases:

Phase 1: Subagents Avanzados (Módulos 1-3)           ← COMPLETADA
├── Módulo 1: Custom Subagents                        ✅
├── Módulo 2: Agent Memory y Scopes                   ✅
└── Módulo 3: Parallel Sub-Agent Delegation            ✅

Phase 2: Agent Teams y Plugins (Módulos 4-6)
├── Módulo 4: Agent Teams                              ✅
├── Módulo 5: Plugins: Crear y Distribuir              ← ESTÁS AQUÍ
└── Módulo 6: Hooks Avanzados y SDK Headless

Phase 3: Orquestación (Módulos 7-8)
├── Módulo 7: Remote Control y CLAUDE.md para Equipos
└── Módulo 8: Proyecto: Sistema Multi-Agente Completo

Duración total estimada: 8-10 horas (self-paced).

¿Qué cambia con Plugins?

En el módulo 4 construiste un equipo de 3 agentes con agent files locales. Funcionan perfectamente dentro de ese proyecto. Plugins resuelven lo que los agent files locales no pueden: distribución, versionado, y reutilización entre proyectos y equipos.

El cambio mental es: dejas de pensar en "archivos de configuración" y empiezas a pensar en "paquetes de funcionalidad." Un plugin no es una carpeta con agent files — es un producto: tiene versión, documentación, dependencias, y un contrato claro de qué provee.

El Problema: Copiar Archivos No Escala

Lo que viviste en los módulos anteriores

En el módulo 4, creaste 3 agent files:

.claude/agents/
├── team-lead.md
├── frontend-agent.md
└── backend-agent.md

Funcionaron. Pero aparecen fricciones cuando intentas reutilizar:

Fricción 1: Nuevo proyecto, misma configuración.

cd new-project/
mkdir -p .claude/agents/
cp ../previous-project/.claude/agents/*.md .claude/agents/

Copiaste los archivos. Pero el team lead referencia teammates por nombre — ¿siguen siendo los mismos? Las paths del system prompt mencionan src/api/ — ¿existe en el nuevo proyecto? Empiezas a editar los archivos copiados y ahora tienes dos versiones divergentes.

Fricción 2: Compartir con el equipo.

Slack: "Hey, copien estos 3 archivos a .claude/agents/"
Colega: "¿Dónde los pongo exactamente?"
Tú: "En la raíz del proyecto, en .claude/agents/"
Colega: "Ya tengo un frontend-agent.md diferente ahí"
Tú: "Renómbralo, o mergea... no sé"

Sin convenciones de naming, sin versionado, sin resolución de conflictos. Cada persona termina con una versión ligeramente diferente.

Fricción 3: Actualización.

Mejoraste el system prompt del team lead después de 2 semanas de uso. Ahora tienes 4 proyectos con la versión vieja. ¿Los actualizas a mano? ¿Cuáles cambiaste localmente y cuáles no?

El patrón es familiar

Estos son exactamente los problemas que npm resolvió para bibliotecas de código:

Sin package managerCon package manager
Copias archivos entre proyectosnpm install @pkg/name
Versión incierta"@pkg/name": "^1.2.0"
Actualizaciones manualesnpm update
Conflictos sin resolverSemver + lockfile
"Funciona en mi máquina"Registry centralizado

Los plugins de Claude Code aplican este mismo modelo a configuraciones de agentes.

Qué Es un Plugin

Definición concreta

Un plugin de Claude Code es un paquete npm que contiene:

my-plugin/
├── package.json          # Manifiesto con claudeCodePlugin: true
├── agents/               # Subagent files (.md)
│   ├── reviewer.md
│   └── implementer.md
├── skills/               # Skill files (.md)
│   └── api-conventions.md
└── README.md

El package.json incluye un campo especial:

{
  "name": "@team/code-quality-plugin",
  "version": "1.0.0",
  "claudeCodePlugin": true,
  "files": ["agents", "skills"]
}

claudeCodePlugin: true le dice a Claude Code: "este paquete contiene configuraciones de agente, cárgalas automáticamente."

Qué puede contener un plugin

┌────────────────────────────────────┐
│           PLUGIN                    │
│                                     │
│  ┌──────────┐  ┌──────────┐        │
│  │ agents/  │  │ skills/  │        │
│  │ .md      │  │ .md      │        │
│  └──────────┘  └──────────┘        │
│                                     │
│  ┌──────────┐  ┌──────────┐        │
│  │ hooks    │  │ MCP      │        │
│  │ (config) │  │ servers  │        │
│  └──────────┘  └──────────┘        │
│                                     │
│  ┌──────────────────────────┐      │
│  │ package.json (manifest)  │      │
│  └──────────────────────────┘      │
└────────────────────────────────────┘
  • agents/ — Archivos .md con frontmatter YAML. Se cargan como subagents disponibles.
  • skills/ — Archivos .md con conocimiento de dominio. Se precargan para dar contexto.
  • hooks — Configuraciones de hooks (PreToolUse, PostToolUse, etc.) que se activan automáticamente.
  • MCP servers — Servidores MCP scoped a los subagents del plugin.

Instalación

Desde npm:

claude plugins add @team/code-quality-plugin

Desde un path local (para desarrollo):

claude plugins add ./my-plugin

Los plugins se pueden scoping a proyecto o a usuario, similar a cómo Claude Code maneja settings.

De Agent Files a Plugin: El Salto Mental

Lo que tienes (agent files locales)

project-a/
└── .claude/agents/
    ├── team-lead.md
    ├── frontend-agent.md
    └── backend-agent.md
  • ✅ Funciona en este proyecto
  • ❌ No se transfiere automáticamente
  • ❌ Sin versionado
  • ❌ Sin distribución

Lo que quieres (plugin)

@your-org/dev-team-plugin/
├── package.json
├── agents/
│   ├── team-lead.md
│   ├── frontend-agent.md
│   └── backend-agent.md
├── skills/
│   └── team-conventions.md
└── README.md
  • ✅ Instalable con un comando
  • ✅ Versionado con semver
  • ✅ Actualizable
  • ✅ Compartible via npm registry

El cambio de mentalidad

ANTES: "Tengo archivos de configuración útiles"
         → Los comparto por Slack/email/copy-paste
         → Cada proyecto tiene su versión
         → Sin garantía de consistencia

DESPUÉS: "Tengo un producto de tooling"
          → Lo publico en un registry
          → Cualquiera lo instala con un comando
          → Versiones explícitas, updates controlados

No se trata de complejidad técnica — crear un plugin no es más difícil que crear un paquete npm básico. Se trata de mentalidad: tratar tus configuraciones de agentes como un producto que otros (o tú en el futuro) van a consumir.

Objetivo del Módulo

Al terminar este módulo serás capaz de:

  • ✅ Explicar la anatomía de un plugin: manifest, agents, skills, hooks, MCP servers
  • ✅ Crear un plugin desde cero con la estructura correcta de directorios y package.json
  • ✅ Escribir agent files y skill files diseñados para distribución (paths relativos, configuración genérica)
  • ✅ Testear un plugin localmente con claude plugins add ./my-plugin
  • ✅ Entender dynamic loading: cómo Claude Code carga plugins al inicio de sesión
  • ✅ Publicar un plugin en un registry local (verdaccio) o npm
  • ✅ Manejar versionado con semver y versión pinning

Objetivo profesional

Si trabajas en equipo, plugins son la forma de estandarizar workflows. En lugar de documentar "cómo configurar Claude Code para nuestro proyecto" en un wiki que nadie lee, empaquetas la configuración en un plugin que se instala con un comando. Eso es infraestructura de equipo real.

Roadmap del Módulo

Mapa de cápsulas

#CápsulaQué aprenderásTipo
01Introducción (esta)Contexto, qué son plugins, por qué importanIntro
02Anatomía de un PluginEstructura de directorios, package.json, agents, skills, hooks, MCPTécnica
03Crear Plugin desde ScaffoldPaso a paso: crear, configurar, testear localmenteTécnica
04Dynamic Loading y VersioningCómo se cargan plugins, semver, registries, updatesTécnica
05Proyecto: Plugin CompletoPlugin con 2 subagents + 1 skill, publicado localmenteProyecto

Flujo de aprendizaje

Primero entenderás la anatomía de un plugin — qué contiene, cómo se estructura el manifest, y cómo cada componente (agents, skills, hooks, MCP) encaja en la estructura (cápsula 02). Después crearás un plugin desde scaffold — paso a paso, desde npm init hasta claude plugins add ./my-plugin con verificación de que todo carga correctamente (cápsula 03). Luego aprenderás dynamic loading y versionado — cómo Claude Code descubre y carga plugins, cómo funciona semver para plugins, y cómo publicar en registries privados y públicos (cápsula 04). Finalmente, construirás un plugin completo de code quality con reviewer + implementer + conventions skill, lo testearás y lo publicarás (cápsula 05).

La progresión es: entender estructura → crear plugin → versionar y distribuir → construir producto completo.

Cada cápsula construye sobre la anterior. No puedes crear un plugin (03) sin entender su anatomía (02). No puedes publicarlo (04) sin haberlo creado y testeado (03).

Duración estimada del módulo: 1.25-1.5 horas.

Conexión con el Proyecto

Proyecto del módulo: Plugin de Code Quality

En la cápsula 05 crearás un plugin completo:

  1. reviewer agent — Revisa código buscando problemas de calidad, seguridad, y convenciones
  2. implementer agent — Implementa cambios siguiendo las convenciones del equipo
  3. api-conventions skill — Conocimiento de dominio sobre las convenciones de API del equipo
@your-org/code-quality-plugin/
├── package.json
├── agents/
│   ├── reviewer.md       ← Revisa código, reporta problemas
│   └── implementer.md    ← Implementa siguiendo convenciones
├── skills/
│   └── api-conventions.md ← Convenciones de API del equipo
└── README.md

El plugin se instalará localmente, se verificará que los agentes cargan correctamente, y se probará con un escenario real de review + implementation.

Conexión con el proyecto final (Módulo 8)

En el módulo 8, el proyecto integrador usa plugins para encapsular la configuración de cada agente especializado del sistema multi-agente. En lugar de configurar 5+ agentes manualmente, instalas plugins que traen toda la funcionalidad. Los plugins que crees aquí son los building blocks del sistema completo.

Prerequisitos

Conocimientos necesarios

  • ✅ Módulos 1-4 completados — Subagents, memory, delegación paralela, Agent Teams
  • ✅ Agent files — Sabes crear archivos .md con frontmatter YAML
  • ✅ npm básico — Sabes qué es package.json, npm init, npm install
  • ✅ Terminal — Navegas directorios, ejecutas comandos
  • ✅ Git — Versionas tu código (el plugin también se versiona)

Verificación rápida

Si puedes responder "sí" a estas preguntas, estás listo:

  1. ¿Puedes crear un agent file con frontmatter YAML en menos de 5 minutos?
  2. ¿Sabes la diferencia entre npm install y npm install --save-dev?
  3. ¿Entiendes qué es semver? (major.minor.patch)
  4. ¿Has creado al menos un package.json antes?
  5. ¿Puedes explicar por qué copiar archivos entre proyectos es frágil?

No necesitas

  • ❌ Experiencia previa con plugins de Claude Code — se cubre completamente aquí
  • ❌ Cuenta npm publicada — usaremos un registry local
  • ❌ Conocimiento de MCP servers — se introduce lo necesario dentro del módulo
  • ❌ Experiencia con monorepos o workspaces avanzados

Setup para el Módulo

Lo que necesitas tener listo

1. Claude Code actualizado:

claude --version

Asegúrate de tener la versión más reciente. El sistema de plugins requiere soporte para claude plugins.

2. Node.js y npm:

node --version   # v18+ recomendado
npm --version    # v9+ recomendado

3. Verificar soporte de plugins:

claude plugins --help

Si el comando plugins aparece, tienes soporte. Si no, consulta la sección de alternativa manual en cada cápsula.

4. Directorio de trabajo:

mkdir -p ~/plugins-workshop
cd ~/plugins-workshop

Trabajaremos fuera de un proyecto existente para crear plugins independientes.

Límites: Qué NO Se Cubre en Este Módulo

  • ❌ Hooks avanzados y SDK headless — Se cubren en el Módulo 6. Aquí usamos hooks básicos cuando el plugin los necesita
  • ❌ MCP servers desde cero — Se introduce cómo incluir un MCP server en un plugin, no cómo crear uno
  • ❌ Publicación en npm público — Cubrimos registries locales y privados. Publicar en npm público sigue el mismo proceso pero requiere cuenta npm
  • ❌ Monorepos de plugins — Un plugin por paquete es suficiente para este módulo
  • ❌ Plugin marketplaces — Si Claude Code implementa un marketplace, los fundamentos de este módulo aplican directamente

Alternativa Manual: Si Plugins No Está Disponible

Si tu versión de Claude Code no soporta el sistema de plugins, puedes lograr distribución con herramientas existentes:

Plugin npm               →  Git repo con agent files + script de setup
claude plugins add ...   →  git clone + cp -r agents/ .claude/agents/
Versionado semver        →  Git tags (v1.0.0, v1.1.0)
Registry npm             →  GitHub/GitLab como registry
Actualizaciones           →  git pull + re-copy

Cada cápsula incluye una sección "Alternativa manual" con el equivalente. El modelo mental es idéntico — la diferencia es que con plugins la instalación y carga es automática, y sin ellos la gestionas con scripts.

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

  • ✅ Puedes crear un plugin con la estructura correcta (package.json + agents/ + skills/)
  • ✅ El plugin se instala localmente con claude plugins add ./path
  • ✅ Los agentes del plugin aparecen disponibles en una sesión de Claude Code
  • ✅ Las skills del plugin se precargan automáticamente
  • ✅ Puedes explicar la diferencia entre un plugin y una carpeta de agent files
  • ✅ Entiendes versión pinning y por qué importa en equipo
  • ✅ Puedes publicar en un registry local y que otro desarrollador lo instale

Test rápido de autoevaluación

Si puedes responder estas preguntas al terminar:

  1. ¿Qué campo en package.json marca un paquete como plugin de Claude Code?
  2. ¿Cuál es la diferencia entre agents/ y skills/ en un plugin?
  3. ¿Cómo testeas un plugin antes de publicarlo?
  4. ¿Qué pasa si publicas una versión con breaking changes sin incrementar major?
  5. ¿Por qué un plugin es mejor que copiar archivos?

Resumen

  • Este módulo marca la transición de configuraciones locales a paquetes distribuibles — de archivos en .claude/agents/ a plugins npm instalables
  • Un plugin es un paquete npm con claudeCodePlugin: true que bundlea agents, skills, hooks, y MCP servers
  • El problema que resuelven: copiar archivos entre proyectos no escala — sin versionado, sin distribución automática, sin consistencia
  • Plugins aplican el modelo npm a configuraciones de agentes: versionado semver, registries, install/update con un comando
  • El proyecto del módulo crea un plugin de code quality con reviewer + implementer + conventions skill
  • Todo lo aprendido en módulos 1-4 (subagents, memoria, teams) es el contenido que empaquetas — plugins son el vehículo de distribución
  • El sistema de plugins es experimental (última verificación: marzo 2026) — el módulo proporciona alternativas manuales

Recursos Adicionales

  1. Claude Code Sub-Agents (Anthropic Docs) — Documentación oficial de subagents como componentes de plugins
  2. Create Custom Subagents — Referencia de agent files, frontmatter YAML
  3. Claude Code CLI Reference — Comandos de plugins y configuración
  4. Claude Code Settings — Configuración de permisos, hooks, y scopes
  5. npm Documentation — package.json — Referencia del manifiesto npm
  6. Semantic Versioning (semver.org) — Estándar de versionado que usan los plugins
  7. Claude Code Best Practices — Buenas prácticas de organización y distribución
  8. Claude Code Overview — Contexto general de Claude Code como plataforma

Siguiente cápsula: En la cápsula 02 explorarás la anatomía completa de un plugin — la estructura de directorios, el manifiesto en package.json, cómo se organizan los agent files en agents/, las skills en skills/, los hooks en la configuración, y cómo se scopean los MCP servers a subagents del plugin. Al terminar sabrás exactamente qué va dónde y por qué.

← Anterior6. Proyecto — Team de 3 Agentes con Task BoardSiguiente →2. Anatomía de un Plugin — Agents, Skills, Hooks y MCP Servers