Módulo 5: Plugins — Crear y Distribuir

5. Proyecto — Plugin de Code Quality Completo

Siguiente →

5. Proyecto — Plugin de Code Quality Completo

Descripción del Proyecto

Has aprendido la anatomía de un plugin, creaste uno desde scaffold, lo testeaste localmente, y entiendes cómo funciona el versionado y la publicación en registries. Ahora integras todo en un plugin de producción: un paquete de code quality con dos subagents especializados y un skill file de convenciones, completo con manifiesto profesional, documentación, y publicación en un registry local.

El plugin que construirás empaqueta un quality-reviewer (analiza código en modo read-only y produce reportes estructurados), un quality-implementer (aplica fixes siguiendo convenciones), y un skill team-conventions (reglas compartidas del equipo que ambos agentes consumen). No son agentes genéricos — están diseñados para trabajar como flujo: el reviewer detecta problemas, el implementer los corrige, y ambos usan las mismas convenciones como fuente de verdad.

Este proyecto es el cierre del Módulo 5. Si el plugin se instala con un comando, los agentes cargan automáticamente, las convenciones se aplican en el review, y puedes publicarlo en verdaccio para que otro desarrollador lo instale — has dominado la creación y distribución de plugins.

⚠️ FEATURE EXPERIMENTAL

El sistema de plugins de Claude Code es experimental. Si claude plugins add no está disponible en tu versión, este proyecto incluye una sección de alternativa manual con un script de instalación. Los agent files y skills funcionan como subagents estándar en ambos casos.

Última verificación: Marzo 2026

Objetivo del Proyecto

Construir un plugin de code quality completo con 2 subagent files + 1 skill file, testearlo localmente, y publicarlo en un registry local (verdaccio).

Al completar este proyecto:

  • ✅ Tendrás un paquete npm con claudeCodePlugin: true y estructura correcta
  • ✅ El quality-reviewer producirá reportes estructurados usando las convenciones del skill
  • ✅ El quality-implementer aplicará fixes siguiendo las mismas convenciones
  • ✅ El plugin se instalará con un solo comando y cargará automáticamente
  • ✅ Los agentes descubrirán la estructura del proyecto dinámicamente (sin paths hardcoded)
  • ✅ El plugin estará publicado en un registry local, instalable por otros desarrolladores
  • ✅ El package.json tendrá versionado semver y campos profesionales

Duración estimada: 1.5-2 horas (setup: 15 min + agent files: 30 min + skill: 15 min + testing: 30 min + publicación: 15 min + iteración: 15 min).

Especificaciones Técnicas

Stack Tecnológico

  • Herramienta: Claude Code (versión reciente con soporte de plugins)
  • Paquete: npm con claudeCodePlugin
  • Registry local: Verdaccio (npm registry privado)
  • Agent files: Markdown con frontmatter YAML
  • Proyecto de prueba: Cualquier proyecto con código fuente (Python, JavaScript, TypeScript)

Requisitos

RequisitoMínimoIdeal
Node.jsv18+v20+
npmv9+v10+
Claude CodeCon soporte de pluginsÚltima versión
VerdaccioInstalado globalmenteCorriendo en background
Proyecto de prueba5+ archivos de códigoCon CLAUDE.md y convenciones

Estructura Final del Plugin

@your-org/code-quality-plugin/
├── package.json                ← Manifiesto profesional
├── README.md                   ← Documentación de uso
├── CHANGELOG.md                ← Historial de cambios
├── agents/
│   ├── quality-reviewer.md     ← Revisor de código (read-only)
│   └── quality-implementer.md  ← Implementador de fixes
└── skills/
    └── team-conventions.md     ← Convenciones compartidas

Paso 1: Inicializar el Paquete

mkdir -p ~/plugins-workshop/code-quality-plugin
cd ~/plugins-workshop/code-quality-plugin

mkdir -p agents skills

Crea el package.json:

{
  "name": "@your-org/code-quality-plugin",
  "version": "1.0.0",
  "description": "Code quality plugin for Claude Code. Includes quality-reviewer (read-only analysis), quality-implementer (applies fixes), and team-conventions skill.",
  "claudeCodePlugin": true,
  "files": [
    "agents",
    "skills"
  ],
  "keywords": [
    "claude-code",
    "plugin",
    "code-quality",
    "reviewer",
    "linting",
    "conventions"
  ],
  "author": "Your Name <you@email.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/code-quality-plugin"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

Inicializa git:

git init
echo "node_modules/" > .gitignore
git add .
git commit -m "Initial plugin scaffold"

Paso 2: Crear el Quality Reviewer

Este agente analiza código sin modificarlo. Produce reportes estructurados con severidad, ubicación exacta, y recomendaciones actionables. Usa las convenciones del skill team-conventions como criterio de evaluación.

Crea agents/quality-reviewer.md:

---
name: quality-reviewer
description: Analyzes code for quality issues, security vulnerabilities, and convention violations. Read-only agent that produces actionable reports with severity levels. Uses team-conventions skill as evaluation criteria.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 25
---

## Role

You are a senior code reviewer. You analyze codebases for quality
issues, security vulnerabilities, and convention violations. You
NEVER modify files — you only read, analyze, and report.

Your reviews are thorough but focused. You prioritize issues that
have real impact over stylistic nitpicks.

## Knowledge

Load the `team-conventions` skill. Apply those conventions as your
primary evaluation criteria. When the project has a CLAUDE.md,
merge its conventions with team-conventions (project-specific rules
take precedence).

## Review Process

1. **Discover project structure**
   - Use Glob to map the directory tree
   - Read CLAUDE.md if it exists
   - Identify the tech stack (language, framework, patterns)

2. **Scope the review**
   - If given specific files/directories, focus there
   - If given the full project, prioritize: API routes, data models,
     auth logic, then utilities and helpers
   - Skip generated files, node_modules, vendor/

3. **Analyze each file against criteria**
   - Code quality: complexity, duplication, naming, dead code
   - Security: secrets, injection, auth bypass, input validation
   - Conventions: check against team-conventions and CLAUDE.md
   - Architecture: separation of concerns, dependency direction

4. **Classify findings by severity**
   - CRITICAL: Security vulnerability or data loss risk
   - WARNING: Code quality issue that will cause problems
   - INFO: Style or convention suggestion

5. **Generate actionable report**

## What Makes a Good Finding

A good finding has:
- Exact file and line reference
- Clear description of the problem
- Why it matters (risk or consequence)
- Specific fix recommendation
- Which convention it violates (if applicable)

A bad finding:
- "Code could be improved" (vague)
- "Consider refactoring" (no specific action)
- Style preferences without convention backing

## Output Format

### Code Quality Review

**Project:** [detected tech stack]
**Scope:** [files/directories reviewed]
**Conventions applied:** [team-conventions + CLAUDE.md rules found]
**Files analyzed:** [count]
**Summary:** Critical: [n] | Warning: [n] | Info: [n]

---

#### Critical Issues

**[C1]** `[file]:[line]`
- **Issue:** [clear description]
- **Risk:** [what could go wrong]
- **Convention:** [which rule is violated, or "security best practice"]
- **Fix:** [specific action to take]

---

#### Warnings

**[W1]** `[file]:[line]`
- **Issue:** [description]
- **Impact:** [technical debt, maintainability, performance]
- **Convention:** [rule reference]
- **Suggestion:** [recommended change]

---

#### Info

**[I1]** `[file]:[line]` — [brief observation and suggestion]

---

#### Positive Patterns Found
- [well-implemented pattern worth noting]

---

### Implementer Handoff

For each CRITICAL and WARNING, structured for the quality-implementer:

| ID | File | Line | Action Required | Convention |
|----|------|------|-----------------|------------|

**Priority order:** [C1, C2, ..., W1, W2, ...]

Paso 3: Crear el Quality Implementer

Este agente recibe tareas de implementación o corrección y las ejecuta siguiendo las convenciones del equipo. Puede trabajar independientemente o recibir el output del reviewer como guía.

Crea agents/quality-implementer.md:

---
name: quality-implementer
description: Implements code changes and fixes following team conventions. Can work from reviewer reports or direct task descriptions. Reports all changes with rationale and convention references.
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
maxTurns: 30
---

## Role

You are a senior developer responsible for implementing code changes
that meet team quality standards. You receive either:
- Direct implementation tasks ("create endpoint X")
- Fix lists from the quality-reviewer ("fix issues C1, W2, W3")

In both cases, you follow team conventions strictly and report
every change with rationale.

## Knowledge

Load the `team-conventions` skill. These are your implementation
standards. When the project has a CLAUDE.md, merge its conventions
(project-specific rules take precedence over team-conventions).

## Implementation Process

### For Direct Tasks

1. Read CLAUDE.md and examine existing code patterns
2. Plan the implementation (state your plan before writing code)
3. Implement following conventions and existing patterns
4. Verify: run linter/tests if available (Bash)
5. Report all changes

### For Reviewer Fix Lists

1. Read the reviewer's report (Implementer Handoff section)
2. Process fixes in priority order (Critical first, then Warning)
3. For each fix:
   a. Read the file and understand the context
   b. Apply the fix following the stated convention
   c. Verify the fix doesn't break adjacent code
   d. If the fix requires changes in other files, make them
4. Report each fix applied

## Implementation Standards

### Code Quality
- Functions: single responsibility, max 40 lines
- Naming: match project conventions (read 3 existing files first)
- Error handling: every operation that can fail has error handling
- No dead code: remove commented-out code, unused imports
- Type safety: add types where the project uses them

### File Organization
- Discover project structure before creating files
- Place new files where similar files exist
- Follow the project's module/package organization
- If unsure, check CLAUDE.md or ask

### Dependencies
- Prefer built-in/existing utilities over new dependencies
- If a new dependency is needed, document why
- Check if a similar utility already exists in the project

## When Fixing Reviewer Issues

### Mapping severity to action
- **CRITICAL:** Fix immediately, no questions asked
- **WARNING:** Fix unless there's a documented reason not to
- **INFO:** Fix only if explicitly asked

### What to do when unsure
- If the fix is ambiguous, state both options and pick the safer one
- If the fix could break other code, note the risk in the report
- If the fix requires a design decision, escalate in the report

## Output Format

### Implementation Report

**Task type:** [Direct implementation | Reviewer fixes]
**Conventions applied:** [team-conventions + CLAUDE.md rules]

#### Changes Applied

**[1]** `[file]`
- **Action:** [created | modified | deleted]
- **What:** [description of the change]
- **Why:** [rationale — which convention, what problem it solves]
- **Convention:** [specific rule from team-conventions]
```diff
- [old code]
+ [new code]

[2] [file]

  • ...

Verification

  • Linter: [ran / not available — result]
  • Tests: [ran / not available — result]
  • Manual check: [what I verified manually]

Decisions Made

  • [decision] — [rationale]

Remaining Issues

  • [anything not fixed and why]

Status: COMPLETE | PARTIAL (with explanation)


---

## Paso 4: Crear el Skill de Convenciones

Este skill es la fuente de verdad compartida entre el reviewer y el implementer. Ambos lo referencian, ambos lo aplican. Así se garantiza consistencia: el reviewer detecta violaciones de las mismas reglas que el implementer sigue al corregir.

Crea `skills/team-conventions.md`:

```markdown
---
name: team-conventions
description: Shared team conventions for code quality, API design, naming, error handling, and file organization. Used by quality-reviewer and quality-implementer as the primary evaluation and implementation standard.
---

## Naming Conventions

### Files
- Components/Classes: PascalCase (`UserProfile.tsx`, `OrderService.py`)
- Utilities/helpers: camelCase (JS/TS) or snake_case (Python)
- Test files: same name as source + `.test` or `_test` suffix
- Config files: lowercase with dots (`tsconfig.json`, `pyproject.toml`)

### Code
- Variables: camelCase (JS/TS) or snake_case (Python)
- Constants: UPPER_SNAKE_CASE
- Classes: PascalCase
- Functions: camelCase (JS/TS) or snake_case (Python)
- Private: prefix with underscore in Python, # in JS/TS
- Boolean variables: prefix with is/has/should/can

### API Endpoints
- URLs: kebab-case (`/user-profiles`, not `/userProfiles`)
- Collections: plural nouns (`/users`, not `/user`)
- Nested resources: `/users/{id}/posts`
- Actions: verb as sub-resource (`/orders/{id}/cancel`)

## Code Structure

### Functions
- Maximum 40 lines per function
- Single responsibility: one function does one thing
- Max 4 parameters; use options object beyond that
- Return early for guard clauses (avoid deep nesting)
- Max 3 levels of nesting

### Files
- Maximum 300 lines per file
- One class/component per file (with exceptions for tightly coupled)
- Imports organized: stdlib → third-party → local (blank line between)
- Exports at the bottom or alongside definitions (be consistent)

### Error Handling
- Catch specific errors, never catch-all without re-throwing
- Custom error classes with error codes
- Log errors with context (what operation, what input)
- API error responses: `{ "error": { "code": "...", "message": "..." } }`
- Never expose stack traces or internal details in API responses

## API Design

### Request/Response
- All endpoints have typed request and response schemas
- Response envelope: `{ "data": {...}, "meta": {...} }`
- Error envelope: `{ "error": { "code": "...", "message": "...", "details": [...] } }`
- Use appropriate HTTP status codes (don't return 200 for errors)

### Pagination
- Cursor-based for large collections
- Query: `?cursor=<opaque>&limit=20`
- Max limit: 100
- Response includes `next_cursor` in meta

### Authentication
- Bearer token in Authorization header
- Consistent auth middleware/dependency
- Protected endpoints return 401 (not authenticated) or 403 (not authorized)

## Testing

### Structure
- Test file mirrors source file path
- Test names: describe what is tested and expected outcome
- Arrange-Act-Assert pattern
- No test interdependencies (each test is independent)

### Coverage Expectations
- Business logic: 80%+ coverage
- API endpoints: integration tests for happy path + error cases
- Utilities: unit tests for edge cases
- UI components: render tests + interaction tests

## Security

### Input Validation
- Validate ALL external input at the API boundary
- Use schema validation (Pydantic, Zod, Joi)
- Sanitize strings: trim whitespace, normalize unicode
- Validate IDs format before database queries

### Secrets
- NEVER hardcode secrets, API keys, or passwords
- Use environment variables
- Never log secrets (even partially)
- .env files in .gitignore

### Data
- Parameterized queries only (prevent SQL injection)
- Hash passwords with bcrypt (never store plaintext)
- Sanitize user input in HTML output (prevent XSS)

Paso 5: Crear el README

Crea README.md:

# @your-org/code-quality-plugin

Code quality plugin for Claude Code with quality-reviewer (read-only analysis)
and quality-implementer (applies fixes) sharing team-conventions as standard.

## Installation

```bash
claude plugins add @your-org/code-quality-plugin
# or from local: claude plugins add ./path/to/code-quality-plugin

Agents

quality-reviewer

Read-only analysis: quality, security, conventions. Usage: "Use quality-reviewer to analyze src/ for code quality issues"

quality-implementer

Implements fixes following conventions. Usage: "Use quality-implementer to fix the critical issues from this review: [paste]"

Skills

team-conventions

Naming, structure, error handling, API design, testing, security standards.

Workflow

  1. Run quality-reviewer → get structured report
  2. Pass Critical/Warning items to quality-implementer
  3. Verify fixes

Respects CLAUDE.md (project rules override team-conventions). Requires Claude Code (latest) + Node.js 18+.


---

## Paso 6: Crear el CHANGELOG

Crea `CHANGELOG.md`:

```markdown
# Changelog

## [1.0.0] — 2026-03-13

### Added
- quality-reviewer agent: read-only code analysis with structured reports
- quality-implementer agent: implements fixes following team conventions
- team-conventions skill: shared naming, structure, API, testing, security rules
- README with usage instructions
- Plugin manifest with claudeCodePlugin support

Paso 7: Verificar la Estructura

find . -type f -not -path './.git/*' -not -path './node_modules/*'

Output esperado:

./package.json
./README.md
./CHANGELOG.md
./.gitignore
./agents/quality-reviewer.md
./agents/quality-implementer.md
./skills/team-conventions.md

Checklist pre-testing

✅ package.json tiene claudeCodePlugin: true
✅ package.json tiene files: ["agents", "skills"]
✅ package.json tiene version: "1.0.0"
✅ agents/quality-reviewer.md tiene frontmatter YAML válido
✅ agents/quality-implementer.md tiene frontmatter YAML válido
✅ skills/team-conventions.md tiene frontmatter YAML válido
✅ quality-reviewer solo tiene Read, Glob, Grep (no puede modificar)
✅ quality-implementer tiene Read, Write, Edit, Glob, Grep, Bash
✅ Ambos agentes referencian team-conventions en su system prompt
✅ Sin paths hardcoded en ningún agent file
✅ README.md documenta instalación y uso

Paso 8: Testing Local

Instalar en un proyecto de prueba

cd ~/your-test-project

claude plugins add ~/plugins-workshop/code-quality-plugin

Verificar instalación

claude plugins list

Output esperado:

Installed plugins:
  @your-org/code-quality-plugin (1.0.0) — local
    agents: quality-reviewer, quality-implementer
    skills: team-conventions

Test 1: Reviewer carga y analiza

Dentro de la sesión: "Usa quality-reviewer para analizar este proyecto. Enfócate en los archivos de la API."

Verifica: el reviewer se invoca, descubre la estructura con Glob, lee CLAUDE.md, produce reporte con formato definido (Critical/Warning/Info), referencia convenciones del skill, no modifica archivos, e incluye tabla de "Implementer Handoff."

Test 2: Implementer ejecuta

"Usa quality-implementer para crear una función helper que valide formato de email. Sigue las convenciones del equipo."

Verifica: el implementer lee el proyecto antes de implementar, sigue naming conventions de team-conventions, crea el archivo en el directorio correcto, produce reporte con cambios y rationale.

Test 3: Flujo review → fix

"Primero, usa quality-reviewer para analizar src/. Después, usa quality-implementer para corregir los issues Critical y Warning."

Verifica: el reviewer produce findings con la tabla de handoff, el implementer procesa esos findings, los fixes siguen las mismas convenciones que el reviewer usó para detectar.

Test 4: Convenciones del skill se aplican

"Usa quality-reviewer para analizar un archivo específico. Quiero ver qué convenciones aplica."

Verifica: el reviewer menciona reglas específicas del skill (naming, error handling), los findings referencian la convención violada, no inventa convenciones que no están en el skill.

Paso 9: Iterar sobre el Plugin

Ajustes comunes después del testing

Si el reviewer produce demasiados findings INFO:

Agrega al agent file del reviewer:

## Severity Threshold

Default: Report Critical and Warning. Include Info only when
explicitly asked ("include info-level findings").

When reviewing a large codebase (50+ files), limit to:
- Max 10 Critical findings
- Max 15 Warning findings
- Info: suppressed unless asked

Si el implementer no sigue las convenciones consistentemente:

Refuerza en el agent file:

## MANDATORY Convention Check

Before writing ANY code:
1. List the 3 most relevant conventions from team-conventions
2. State how each applies to this specific task
3. Only then write the code

After writing code, verify:
- Does the naming match convention? [yes/no + which rule]
- Is error handling per convention? [yes/no + which rule]
- Is the file in the right location? [yes/no + which pattern]

Si las convenciones del skill son demasiado genéricas para tu equipo:

Personaliza skills/team-conventions.md con reglas más específicas para tu stack. Las convenciones genéricas son un punto de partida — tu equipo debería adaptarlas.

Commit del plugin después de ajustes

cd ~/plugins-workshop/code-quality-plugin
git add .
git commit -m "Refine agent files after testing"

Paso 10: Publicar en Registry Local

Opción A: Verdaccio (recomendado para equipos)

Arrancar verdaccio (si no está corriendo):

verdaccio &

Crear usuario (primera vez):

npm adduser --registry http://localhost:4873

Publicar:

cd ~/plugins-workshop/code-quality-plugin

npm publish --registry http://localhost:4873

Output esperado:

npm notice
npm notice 📦  @your-org/code-quality-plugin@1.0.0
npm notice Tarball Contents
npm notice 1.2kB  package.json
npm notice 2.8kB  README.md
npm notice 680B   CHANGELOG.md
npm notice 3.1kB  agents/quality-reviewer.md
npm notice 2.9kB  agents/quality-implementer.md
npm notice 2.4kB  skills/team-conventions.md
npm notice === Tarball Details ===
npm notice name:          @your-org/code-quality-plugin
npm notice version:       1.0.0
npm notice
+ @your-org/code-quality-plugin@1.0.0

Verificar publicación:

npm view @your-org/code-quality-plugin --registry http://localhost:4873

Instalar desde registry en otro proyecto:

cd ~/another-project

claude plugins add @your-org/code-quality-plugin --registry http://localhost:4873

Opción B: Instalar directamente desde path local

Si no quieres usar verdaccio:

cd ~/your-project

claude plugins add ~/plugins-workshop/code-quality-plugin

Funciona igual. La diferencia: solo funciona en tu máquina, no en la de tus colegas.

Opción C: npm pack + compartir tarball

Para compartir sin registry:

cd ~/plugins-workshop/code-quality-plugin

npm pack

Genera your-org-code-quality-plugin-1.0.0.tgz. Comparte este archivo y el receptor instala con:

claude plugins add ./your-org-code-quality-plugin-1.0.0.tgz

Paso 11: Verificar Instalación desde Registry

Después de publicar e instalar desde el registry (no desde path local), verifica que todo funciona idéntico:

claude plugins list
Installed plugins:
  @your-org/code-quality-plugin (1.0.0) — registry
    agents: quality-reviewer, quality-implementer
    skills: team-conventions

Nota que ahora dice "registry" en lugar de "local."

Repite los 4 tests del Paso 8 para confirmar que el plugin publicado funciona igual que la versión local.

Alternativa Manual: Script de Instalación

Si claude plugins no está disponible:

#!/bin/bash
# install.sh — Manual installation of code-quality-plugin
set -e
PLUGIN_DIR="$(cd "$(dirname "$0")" && pwd)"
TARGET="${1:-.}"

mkdir -p "$TARGET/.claude/agents" "$TARGET/.claude/skills"
cp "$PLUGIN_DIR/agents/"*.md "$TARGET/.claude/agents/"
cp "$PLUGIN_DIR/skills/"*.md "$TARGET/.claude/skills/"
echo "Installed: quality-reviewer, quality-implementer, team-conventions"

Uso: chmod +x install.sh && ./install.sh ~/my-project

Errores Comunes y Soluciones

Error 1: "El reviewer no aplica las convenciones del skill"

Síntoma: El reporte del reviewer no menciona convenciones de team-conventions. Analiza con criterio genérico.

Causa: El agent file no referencia la skill explícitamente, o Claude Code no asocia automáticamente skills del mismo plugin con sus agentes.

Solución:

Refuerza la referencia en el agent file del reviewer:

## Knowledge (CRITICAL)

You MUST load and apply the `team-conventions` skill before
any review. This skill defines your evaluation criteria:
- Naming: check files, variables, endpoints against conventions
- Structure: check function length, nesting, file organization
- Error handling: check against the error handling standard
- API design: check response format, status codes, pagination
- Security: check input validation, secrets, data handling

If you cannot load the skill, state this in your report header.

Error 2: "El implementer crea archivos en el directorio incorrecto"

Síntoma: El implementer pone un nuevo archivo donde no corresponde según la estructura del proyecto.

Causa: El implementer no examinó la estructura existente antes de crear archivos.

Solución:

Agrega al system prompt:

## MANDATORY: Discover Before Create

Before creating ANY new file:
1. Glob the project to understand directory structure
2. Find 3 existing files similar to what you'll create
3. Note their location pattern
4. Place your new file following the same pattern
5. If no similar files exist, check CLAUDE.md for guidance
6. State in your report: "Placed at [path] because [pattern found]"

Error 3: "npm publish falla con 'You do not have permission'"

Síntoma: Error de permisos al publicar un scoped package.

Causa: Scoped packages (@org/name) requieren permisos especiales en npm público.

Solución:

# Para npm público — necesitas ser miembro de la org
npm publish --access public

# Para verdaccio — crear usuario primero
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

Error 4: "Plugin se instala pero los agentes tienen nombres genéricos"

Síntoma: Los agentes aparecen como reviewer e implementer sin el prefijo quality-.

Causa: El campo name en el frontmatter YAML no tiene el prefijo.

Solución:

Verifica que el frontmatter tiene el nombre correcto:

---
name: quality-reviewer    # NO "reviewer"
---

El name en el frontmatter es lo que Claude Code usa para identificar al agente.

Error 5: "El flujo review → fix pierde contexto"

Síntoma: El implementer no recibe los findings del reviewer, o los recibe en formato difícil de procesar.

Causa: El formato "Implementer Handoff" del reviewer no es lo suficientemente estructurado.

Solución:

La tabla de handoff debe ser parseable:

### Implementer Handoff

| ID | File | Line | Action Required | Convention |
|----|------|------|-----------------|------------|
| C1 | src/api/users.py | 45 | Add input validation | Security: Input Validation |
| W1 | src/utils/format.py | 12 | Rename to snake_case | Naming: Functions |

El implementer lee esta tabla y procesa fila por fila.

Error 6: "npm pack no incluye agents/ o skills/"

Síntoma: El tarball generado no contiene los directorios del plugin.

Causa: El campo files en package.json no los lista, o un .npmignore los excluye.

Solución:

# Verificar contenido del tarball
npm pack
tar -tzf *.tgz

# Debe mostrar:
# package/package.json
# package/README.md
# package/agents/quality-reviewer.md
# package/agents/quality-implementer.md
# package/skills/team-conventions.md

Si falta un directorio:

  1. Verifica "files" en package.json incluye "agents" y "skills"
  2. Verifica que no hay .npmignore excluyendo esos directorios
  3. Verifica que los archivos existen realmente en esos directorios

Error 7: "El reviewer y el implementer usan criterios diferentes"

Síntoma: El reviewer detecta un naming violation, pero el implementer al corregir usa un estilo diferente al que el reviewer esperaba.

Causa: Ambos agentes interpretan las convenciones de manera ligeramente diferente.

Solución:

Las convenciones en team-conventions.md deben ser específicas, no ambiguas:

# Ambiguo (genera interpretaciones diferentes):
- Use consistent naming

# Específico (un solo resultado posible):
- Functions: snake_case in Python, camelCase in JS/TS
- Example: get_user_profile (Python), getUserProfile (JS/TS)

Agrega ejemplos concretos a cada convención. Los ejemplos eliminan ambigüedad.

Error 8: "No puedo instalar el plugin de un colega desde verdaccio"

Síntoma: npm install contra verdaccio falla con connection refused o 404.

Causa: El colega publicó en su verdaccio local, no en uno compartido.

Solución:

Para compartir via verdaccio, el registry debe estar en un servidor accesible:

# En el servidor compartido
verdaccio --listen 0.0.0.0:4873

# Los colegas configuran
npm set registry http://server:4873

Si no hay servidor compartido, usa la opción de npm pack + compartir tarball, o publica en GitHub Packages.

Recursos del Proyecto

  1. Claude Code Sub-Agents (Anthropic Docs) — Agent files y frontmatter YAML
  2. Create Custom Subagents — Referencia de agent files
  3. Claude Code CLI Reference — Comandos de plugins
  4. Verdaccio Documentation — Registry npm local
  5. npm publish — Publicación de paquetes npm
  6. Semantic Versioning — Estándar de versionado

Conexión con el Siguiente Módulo

Has creado un plugin completo con dos agentes y un skill compartido. Lo empaquetaste, testeaste, y publicaste. Pero el plugin tiene una limitación: es estático. Los agentes hacen lo que dice su system prompt y nada más. No reaccionan a eventos, no se activan automáticamente, no se integran con herramientas externas más allá de lo que Claude Code provee.

El Módulo 6: Hooks Avanzados y SDK Headless agrega exactamente esas capacidades. Los hooks avanzados (SessionStart, PostToolUse, TaskCompleted) permiten que tus plugins reaccionen a eventos — el reviewer puede activarse automáticamente cuando un agente crea un archivo nuevo. El SDK headless permite invocar tus agentes desde scripts Python o TypeScript — tu plugin se convierte en una API programática.

Los agent files que creaste aquí son la base. En el módulo 6, les agregarás hooks que automatizan su invocación y SDK que permite controlarlos desde código externo. El plugin pasa de "herramienta manual" a "sistema automatizado."

Resumen

  • Construiste un plugin completo con quality-reviewer + quality-implementer + team-conventions
  • El quality-reviewer analiza código en modo read-only y produce reportes con severity, referencia a convenciones, y tabla de handoff para el implementer
  • El quality-implementer aplica fixes o implementa features siguiendo las convenciones del skill compartido
  • team-conventions es la fuente de verdad compartida — naming, structure, error handling, API design, security
  • El flujo review → fix funciona porque ambos agentes usan las mismas convenciones como criterio
  • El plugin se instala con un comando (claude plugins add) y los agentes cargan automáticamente
  • Tres opciones de distribución: verdaccio (equipos), npm público (open source), npm pack + tarball (ad-hoc)
  • El README.md documenta instalación, agentes disponibles, workflows, y configuración
  • Los agent files son genéricos — descubren la estructura del proyecto dinámicamente, funcionan en cualquier codebase
  • Todo es copy-paste ready — puedes crear este plugin ahora mismo con los archivos de esta cápsula

Siguiente módulo: El Módulo 6 (Hooks Avanzados y SDK Headless) agrega automatización y control programático a todo lo que construiste. Hooks avanzados activan tus agentes automáticamente en eventos. SDK headless permite invocar plugins desde scripts Python y TypeScript. Tu plugin pasa de herramienta manual a sistema automatizado.

← Anterior4. Dynamic Loading y Versioning — Carga, Semver, y RegistriesSiguiente →1. Introducción al Módulo — Hooks como Sistema Nervioso, SDK como Control Programático