2. Anatomía de un Plugin — Agents, Skills, Hooks y MCP Servers

Descripción

Antes de crear un plugin, necesitas entender qué contiene y cómo se estructura. Un plugin no es una carpeta arbitraria con archivos — tiene una anatomía precisa: un manifiesto (package.json) que declara qué es el plugin, directorios estándar para cada tipo de componente (agents/, skills/), configuración de hooks, y opcionalmente MCP servers scoped a los subagents del plugin. Cada pieza tiene su lugar, su propósito, y sus reglas.

En esta cápsula desglosas la estructura completa de un plugin. Verás el package.json campo por campo, entenderás por qué agents/ y skills/ son directorios separados, cómo los hooks se configuran dentro del plugin, y cómo un MCP server se scopea a un subagent específico. Al terminar, podrás mirar cualquier plugin y entender exactamente qué contiene y cómo encaja cada pieza.

⚠️ FEATURE EXPERIMENTAL

La estructura de plugins descrita refleja la especificación disponible a marzo 2026. Los campos del manifiesto, la convención de directorios, y la forma de declarar hooks pueden cambiar. Los principios de organización (separar agents de skills, manifiesto declarativo, scoping de servidores) son estables.

Última verificación: Marzo 2026

Estructura de Directorios

La anatomía visual

my-plugin/
├── package.json              ← Manifiesto del plugin
├── agents/                   ← Subagent files
│   ├── reviewer.md           ← Agente especializado
│   └── implementer.md        ← Agente especializado
├── skills/                   ← Skill files
│   └── api-conventions.md    ← Conocimiento de dominio
├── hooks/                    ← Hook scripts (opcional)
│   └── pre-review.sh         ← Script ejecutado por un hook
└── README.md                 ← Documentación del plugin

Cada directorio tiene una responsabilidad única:

Reglas de estructura

1. Los nombres de directorio son convenciones — agents/ y skills/ deben llamarse exactamente así
2. Archivos en la raíz — Solo package.json, README.md, y archivos de configuración
3. Sin anidación profunda — Los agent files van directamente en agents/, no en subdirectorios
4. Todo incluido en files — El campo files de package.json debe listar todos los directorios que el plugin distribuye

El Manifiesto: package.json

Campos requeridos

El package.json de un plugin es un manifiesto npm estándar con un campo adicional:

{
  "name": "@team/code-quality-plugin",
  "version": "1.0.0",
  "description": "Code quality agents with reviewer and implementer",
  "claudeCodePlugin": true,
  "files": [
    "agents",
    "skills"
  ]
}

Analicemos campo por campo:

name — Identidad del plugin

"name": "@team/code-quality-plugin"

• Usa scoped packages (@org/name) para plugins de equipo
• Usa nombres descriptivos que indiquen qué hace el plugin
• Evita nombres genéricos como my-plugin o claude-tools

Convenciones de naming:

@team/code-quality-plugin     ← Plugin de calidad de código del equipo
@team/api-standards-plugin    ← Plugin de estándares de API
@team/testing-agents-plugin   ← Plugin con agentes de testing
claude-react-agents           ← Plugin público para React
claude-fastapi-quality        ← Plugin público para FastAPI

version — Versionado semver

"version": "1.0.0"

Sigue semver estricto:

MAJOR.MINOR.PATCH

1.0.0 → 1.0.1   Patch: corrección de bug en un agent file
1.0.0 → 1.1.0   Minor: nuevo skill agregado, agents existentes sin cambios
1.0.0 → 2.0.0   Major: agent renombrado, skill eliminado, breaking change

claudeCodePlugin — El marcador

"claudeCodePlugin": true

Este campo es obligatorio. Sin él, Claude Code trata el paquete como una dependencia npm normal y no carga sus components. Es un booleano — true o no existe.

files — Qué se distribuye

"files": [
  "agents",
  "skills"
]

Lista los directorios que npm debe incluir al publicar. Si olvidas un directorio aquí, no se incluirá en el paquete publicado aunque exista localmente.

Campos opcionales relevantes

• keywords — Incluye "claude-code" y "plugin" para discoverability
• author — Quién mantiene el plugin
• license — MIT para público, propietario para interno
• repository — URL del repositorio para issues y contribuciones
• engines — Versión mínima de Node.js (">=18.0.0")

Componente 1: agents/ — Subagent Files

Qué va en agents/

Los archivos en agents/ son subagent files idénticos a los que creaste en el módulo 1. La única diferencia: están diseñados para ser genéricos (funcionan en cualquier proyecto).

agents/
├── reviewer.md       ← Revisa código por calidad y convenciones
└── implementer.md    ← Implementa cambios siguiendo convenciones

Agent file dentro de un plugin

---
name: reviewer
description: Reviews code for quality, security, and convention compliance. Read-only agent that produces structured reports.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 15
---

## Role

You are a code reviewer. You analyze code for:
1. Code quality (duplication, complexity, naming)
2. Security issues (injection, exposed secrets, unsafe operations)
3. Convention compliance (based on CLAUDE.md and project patterns)

## Boundaries

- You ONLY read code. You NEVER modify files.
- You analyze ALL file types in the project.
- You report findings in structured format.

## Output Format

### Review Report
**Scope:** [files/directories reviewed]
**Issues found:** [count by severity]

#### Critical
- [file:line] — [issue] — [recommendation]

#### Warning
- [file:line] — [issue] — [recommendation]

#### Info
- [file:line] — [suggestion]

**Overall assessment:** [PASS | NEEDS_WORK | CRITICAL_ISSUES]

Diferencias con agent files locales

Regla clave: paths genéricos

Un agent file local puede decir:

You work in src/api/routes/ and src/api/schemas/

Un agent file de plugin debe ser genérico:

You work in API-related directories (routes, schemas, controllers).
Check CLAUDE.md for project-specific directory conventions.

El plugin no sabe cómo está organizado el proyecto del usuario. El agent file debe adaptarse leyendo CLAUDE.md o las convenciones del proyecto.

Componente 2: skills/ — Knowledge Files

Qué va en skills/

Los skills son archivos Markdown con conocimiento de dominio que los agentes pueden precargar. No son agentes — son contexto.

skills/
└── api-conventions.md    ← Convenciones de API del equipo

Skill file dentro de un plugin

---
name: api-conventions
description: API design conventions for the team. Covers endpoint naming, response format, error handling, and versioning.
---

## Endpoint Naming
- Use kebab-case for URLs: `/user-profiles`, not `/userProfiles`
- Use plural nouns for collections: `/users`, not `/user`
- Version in URL: `/api/v1/users`

## Response Format
- Success: `{ "data": {...}, "meta": { "timestamp": "ISO-8601", "request_id": "uuid" } }`
- Error: `{ "error": { "code": "...", "message": "...", "details": [] } }`

## Authentication
- Bearer token in Authorization header (JWT with sub, role, exp)

## Pagination
- Cursor-based: `?cursor=abc&limit=20`, response includes `next_cursor`

Skills vs Agents: la diferencia

AGENT = comportamiento + herramientas + restricciones
        → HACE cosas (lee, escribe, analiza)

SKILL = conocimiento + convenciones + contexto
        → INFORMA al agente sobre cómo hacer las cosas

Un reviewer agent sin skills revisa con criterio genérico. Un reviewer agent con el skill api-conventions revisa contra las convenciones específicas de tu equipo.

Cómo un agent usa un skill

En el agent file, referencia la skill:

---
name: reviewer
description: Reviews code for quality and convention compliance
tools: Read, Glob, Grep
model: sonnet
---

## Knowledge

Load the `api-conventions` skill for API endpoint reviews.
Apply those conventions when reviewing route handlers,
response schemas, and error handling.

Cuando Claude Code carga el reviewer del plugin, también carga las skills asociadas y las inyecta como contexto adicional.

Componente 3: Hooks en Plugins

Qué son hooks en contexto de plugins

Los hooks son acciones automáticas que se ejecutan en eventos específicos de Claude Code. En un plugin, los hooks se declaran en el package.json o en un archivo de configuración, y se activan automáticamente cuando el plugin está instalado.

Tipos de hooks disponibles

PreToolUse    → Antes de que un agente use una herramienta
PostToolUse   → Después de que un agente usa una herramienta
SessionStart  → Al iniciar una sesión de Claude Code
Notification  → Cuando Claude Code necesita notificar algo

Configuración de hooks en package.json

{
  "name": "@team/code-quality-plugin",
  "version": "1.0.0",
  "claudeCodePlugin": true,
  "files": ["agents", "skills", "hooks"],
  "claudeCodeHooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "node hooks/pre-write-check.js $FILE"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "node hooks/post-write-lint.js $FILE"
      }
    ]
  }
}

Ejemplo: hook de pre-review

// hooks/pre-write-check.js
const fs = require('fs');
const path = require('path');

const file = process.argv[2];
if (!file) process.exit(0);

const ext = path.extname(file);
const apiDirs = ['routes', 'api', 'endpoints'];

const isApiFile = apiDirs.some(dir => file.includes(dir));

if (isApiFile && ext === '.py') {
  console.log('API_FILE_MODIFIED: Consider running reviewer agent after this change');
}

Este hook se ejecuta cada vez que un agente escribe un archivo. Si el archivo es parte de la API, sugiere correr el reviewer.

Hooks vs Agent behavior

Usa hooks para validaciones automáticas que deben ocurrir siempre. Usa agent behavior para lógica que depende del contexto de la tarea.

Componente 4: MCP Servers en Plugins (Opcional)

Un plugin puede incluir un MCP (Model Context Protocol) server scoped a sus subagents. La configuración va en el package.json:

{
  "claudeCodeMcp": {
    "servers": {
      "quality-metrics": {
        "command": "node",
        "args": ["mcp/metrics-server.js"],
        "scope": "plugin"
      }
    }
  }
}

Usa MCP servers cuando el plugin necesita acceso a APIs externas (Jira, GitHub, Slack) o herramientas custom. No los necesitas cuando las herramientas built-in (Read, Write, Bash) son suficientes. Para este módulo, los MCP servers son opcionales — la mayoría de plugins útiles se construyen con agents + skills + hooks.

Comparación: Plugin vs Configuración Manual

Side-by-side

CONFIGURACIÓN MANUAL                 PLUGIN
────────────────────                 ──────

.claude/agents/reviewer.md          @team/quality/agents/reviewer.md
.claude/agents/implementer.md       @team/quality/agents/implementer.md
.claude/skills/conventions.md       @team/quality/skills/conventions.md
settings.json (hooks)               package.json (claudeCodeHooks)

Instalación:                         Instalación:
  cp -r archivos/ .claude/            claude plugins add @team/quality

Actualización:                       Actualización:
  cp -r archivos-nuevos/ .claude/     npm update @team/quality

Versionado:                          Versionado:
  (ninguno)                           "version": "1.2.3"

Compartir:                           Compartir:
  zip + Slack + instrucciones          npm publish + un comando

Consistencia entre proyectos:        Consistencia entre proyectos:
  Manual, propensa a errores           Automática, versionada

Cuándo NO necesitas un plugin

No todo debe ser un plugin:

NO es plugin:
├── Configuración específica de UN proyecto (quédate con .claude/agents/)
├── Un solo agent file que solo tú usas
├── Configuración experimental que cambia cada día
└── Skills que dependen de paths específicos del proyecto

SÍ es plugin:
├── Configuración que reutilizas en 3+ proyectos
├── Agents + skills que tu equipo debe usar consistentemente
├── Hooks de calidad que quieres estandarizar
└── Cualquier configuración que has compartido por Slack más de 2 veces

Ciclo de Vida de un Plugin

Desde la creación hasta el uso

1. CREATE          2. DEVELOP         3. TEST
   npm init           agents/            claude plugins add ./
   + claudeCodePlugin skills/            verificar carga
                      hooks/             probar agents

4. PUBLISH         5. INSTALL         6. UPDATE
   npm publish        claude plugins     npm update
   (registry)         add @pkg/name      version bump

Lo que pasa cuando Claude Code carga un plugin

Sesión inicia
    │
    ├── Lee plugins instalados
    │
    ├── Para cada plugin:
    │   ├── Lee package.json
    │   ├── Verifica claudeCodePlugin: true
    │   ├── Carga agents/ → disponibles como subagents
    │   ├── Carga skills/ → disponibles como knowledge
    │   ├── Registra hooks → se activan en eventos
    │   └── Inicia MCP servers → herramientas disponibles
    │
    └── Sesión lista con todos los plugins activos

Ejercicios

Ejercicio 1: Identificar componentes de un plugin (Fácil)

Para cada archivo listado, indica a qué componente del plugin pertenece (agent, skill, hook, manifest, o ninguno):

1. package.json
2. agents/linter.md
3. skills/python-style.md
4. hooks/post-lint.sh
5. src/utils.js
6. README.md
7. agents/helpers/format.md

Ejercicio 2: Corregir un package.json roto (Fácil)

Identifica los 4 errores en este package.json y corrígelos:

{
  "name": "my plugin",
  "version": "1.0",
  "plugin": true,
  "files": ["src"]
}

{
  "name": "my-plugin",
  "version": "1.0.0",
  "claudeCodePlugin": true,
  "files": ["agents", "skills"]
}

Ejercicio 3: Diseñar la estructura de un plugin (Medio)

Diseña la estructura de directorios para un plugin de testing que contiene:

• Un agente que escribe tests unitarios
• Un agente que escribe tests de integración
• Una skill con las convenciones de testing del equipo (naming, structure, assertions)
• Un hook que corre tests automáticamente después de que un agente escribe un archivo en tests/

Escribe el árbol de directorios y el package.json completo.

@team/testing-agents-plugin/
├── package.json
├── agents/
│   ├── unit-tester.md
│   └── integration-tester.md
├── skills/
│   └── testing-conventions.md
├── hooks/
│   └── auto-run-tests.sh
└── README.md

{
  "name": "@team/testing-agents-plugin",
  "version": "1.0.0",
  "description": "Testing agents with unit and integration test specialists",
  "claudeCodePlugin": true,
  "files": [
    "agents",
    "skills",
    "hooks"
  ],
  "claudeCodeHooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "bash hooks/auto-run-tests.sh $FILE"
      }
    ]
  },
  "keywords": ["claude-code", "plugin", "testing", "pytest"],
  "license": "MIT"
}

Ejercicio 4: Agent file local → plugin-ready (Medio)

Convierte este agent file local (project-specific) a uno plugin-ready (genérico):

---
name: api-reviewer
description: Reviews FastAPI code in src/api/routes/ and src/api/schemas/
tools: Read, Glob, Grep
model: sonnet
maxTurns: 15
---

## Role
Review all Python files in src/api/routes/ and src/api/schemas/.
Check for compliance with our Pydantic v2 conventions defined in
/Users/mike/projects/backend/docs/api-standards.md.

## Rules
- Check src/api/routes/ for endpoint naming
- Check src/api/schemas/ for Pydantic model patterns
- Reference /Users/mike/projects/backend/CLAUDE.md for style guide

---
name: api-reviewer
description: Reviews API code for quality, naming conventions, and schema patterns. Read-only agent compatible with FastAPI, Express, and Django projects.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 15
---

## Role

Review API-related files (routes, schemas, controllers, serializers)
for quality and convention compliance. You work with any backend
framework.

## How to Find API Files

1. Read CLAUDE.md for project-specific directory conventions
2. Use Glob to find route/endpoint files: **/*route*, **/*endpoint*, **/*view*
3. Use Glob to find schema files: **/*schema*, **/*model*, **/*serializer*
4. Adapt to the project's actual structure

## Rules

- Discover project conventions from CLAUDE.md (do not assume paths)
- Check endpoint naming against conventions
- Check schema/model patterns for consistency
- Report findings in structured format

## Output Format

### Review Report
**Project structure:** [detected framework and directories]
**Files reviewed:** [count]
**Issues:** [count by severity]

Ejercicio 5: Plugin con hook y agent coordinados (Difícil)

Diseña un plugin donde el hook y el agent trabajan juntos:

• Hook PostToolUse detecta cuando se crea un archivo nuevo en src/
• El hook escribe el path del archivo nuevo a un archivo temporal .claude/new-files.log
• El agent new-file-reviewer lee .claude/new-files.log y revisa cada archivo nuevo

Escribe: el package.json, el script del hook, y el agent file.

{
  "name": "@team/new-file-reviewer-plugin",
  "version": "1.0.0",
  "claudeCodePlugin": true,
  "files": ["agents", "hooks"],
  "claudeCodeHooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "bash hooks/log-new-file.sh $FILE"
      }
    ]
  }
}

#!/bin/bash
FILE="$1"

if [[ -z "$FILE" ]]; then
  exit 0
fi

if [[ "$FILE" == src/* ]]; then
  mkdir -p .claude
  echo "$FILE" >> .claude/new-files.log
fi

---
name: new-file-reviewer
description: Reviews recently created files logged by the new-file hook. Read-only analysis.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 20
---

## Role

You review files listed in .claude/new-files.log. These are files
recently created during this session.

## Process

1. Read .claude/new-files.log
2. For each file listed:
   a. Read the file
   b. Check for common issues (missing types, no error handling, etc.)
   c. Record findings
3. Produce a consolidated review report
4. Clear .claude/new-files.log after review

## Output Format

### New File Review
**Files reviewed:** [count]
Per file:
- **[path]** — [status: OK | NEEDS_WORK] — [brief note]

**Summary:** [overall assessment]

Troubleshooting

Problema 1: "El plugin se instala pero los agentes no aparecen"

Síntoma: claude plugins add ./my-plugin no da error, pero los subagents no están disponibles.

Causas y soluciones:

1. claudeCodePlugin no está en package.json — Verifica que el campo existe y es true
2. files no incluye agents — Sin este campo, npm no empaqueta el directorio
3. Agent files sin frontmatter — Cada archivo en agents/ necesita el bloque --- con name y description
4. Nombre de directorio incorrecto — Debe ser agents/, no agent/ ni subagents/

# Diagnóstico rápido
cat my-plugin/package.json | grep claudeCodePlugin
ls my-plugin/agents/
head -5 my-plugin/agents/reviewer.md

Problema 2: "El skill no se precarga — el agente no lo conoce"

Síntoma: El agente del plugin no tiene el contexto de la skill.

Causas y soluciones:

1. Directorio skills/ no incluido en files — Agrega "skills" al array files
2. Skill file sin frontmatter — Necesita name y description en el bloque YAML
3. El agent file no referencia la skill — Agrega una sección en el system prompt del agente indicando qué skill cargar

Problema 3: "El hook del plugin no se ejecuta"

Síntoma: El evento ocurre pero el hook no se dispara.

Causas y soluciones:

1. claudeCodeHooks mal formateado — Verifica la estructura JSON (matcher, command)
2. Script no tiene permisos de ejecución — chmod +x hooks/pre-review.sh
3. Path del script relativo al plugin, no al proyecto — Los hooks deben usar paths relativos al directorio del plugin
4. Matcher no coincide — El matcher debe coincidir con el nombre exacto de la herramienta (Write, no write)

Problema 4: "Error al publicar — 'files not found'"

Síntoma: npm publish falla o el paquete publicado está vacío.

Causas y soluciones:

1. .npmignore excluye directorios del plugin — Verifica que agents/ y skills/ no están en .npmignore
2. files en package.json no lista todos los directorios — Agrega cada directorio que debe incluirse
3. Prueba con npm pack antes de publicar — Genera un .tgz para inspeccionar el contenido

npm pack
tar -tzf *.tgz

Problema 5: "Conflicto de nombres con otro plugin"

Síntoma: Dos plugins tienen un agent con el mismo name field.

Causas y soluciones:

1. Usa prefijos — @team/quality/reviewer vs @team/testing/reviewer
2. Nombres únicos por plugin — En lugar de reviewer, usa quality-reviewer o test-reviewer
3. Verifica plugins instalados — claude plugins list muestra todos los agentes disponibles

Resumen

• Un plugin tiene 4 componentes principales: agents/ (subagents), skills/ (conocimiento), hooks (acciones automáticas), y opcionalmente MCP servers
• El package.json es el manifiesto — claudeCodePlugin: true es obligatorio, files lista qué directorios se distribuyen
• Agent files en plugins deben ser genéricos — paths descubiertos dinámicamente, sin dependencias de proyecto específico
• Skills proveen conocimiento de dominio — convenciones, patrones, estándares que los agentes consumen como contexto
• Hooks automatizan acciones en eventos — validaciones pre-write, linting post-write, notificaciones
• MCP servers se scopean al plugin — proveen herramientas adicionales solo para los agentes del plugin
• Un plugin tiene sentido cuando la configuración se reutiliza en 3+ proyectos o se comparte con el equipo
• Agent files locales (.claude/agents/) siguen siendo la opción correcta para configuración específica de un proyecto

Recursos Adicionales

1. Claude Code Sub-Agents (Anthropic Docs) — Agent files y frontmatter YAML
2. Create Custom Subagents — Referencia completa de agent files
3. Claude Code Settings — Hooks, permisos, y configuración de sesión
4. npm package.json Reference — Campos del manifiesto npm
5. Semantic Versioning — Estándar de versionado para plugins
6. Claude Code Best Practices — Organización y distribución
7. Model Context Protocol — Referencia de MCP para plugins con servidores custom
8. npm Files Field — Cómo controlar qué se publica

Siguiente cápsula: En la cápsula 03 crearás un plugin desde cero — desde npm init hasta claude plugins add ./my-plugin. Paso a paso: estructura de directorios, package.json, agent files genéricos, skill files, testing local, y verificación de que todo carga correctamente.