3. Crear un Plugin desde Scaffold — Estructura, Manifiesto y Testing Local

Descripción

Entiendes la anatomía de un plugin. Ahora lo construyes. En esta cápsula creas un plugin desde cero — desde npm init hasta verificar que sus agentes cargan correctamente en una sesión de Claude Code. No vas a publicarlo todavía (eso es cápsula 04). Primero lo creas, lo estructuras, y lo testeas localmente.

El proceso sigue una secuencia natural: inicializar el paquete npm, crear la estructura de directorios, escribir el manifiesto con los campos correctos, crear los agent files diseñados para distribución, agregar skills, instalar localmente con claude plugins add ./, y verificar que todo funciona. Cada paso tiene su verificación — no avanzas al siguiente hasta que el actual funciona.

Al terminar tendrás un plugin funcional instalado localmente, con sus agentes disponibles en tu sesión de Claude Code y su skill precargada. Listo para publicar en la cápsula 04.

⚠️ FEATURE EXPERIMENTAL

Los comandos claude plugins add y la carga automática de componentes de plugins reflejan la funcionalidad disponible a marzo 2026. Si los comandos cambian, los principios (crear paquete npm con estructura estándar, testear localmente antes de publicar) se mantienen.

Última verificación: Marzo 2026

Paso 1: Inicializar el Paquete

Crear el directorio y el package.json

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

npm init -y

npm init -y genera un package.json básico. Ahora adáptalo para plugin:

{
  "name": "@your-org/code-quality-plugin",
  "version": "1.0.0",
  "description": "Code quality agents: reviewer and implementer with team conventions",
  "claudeCodePlugin": true,
  "files": [
    "agents",
    "skills"
  ],
  "keywords": [
    "claude-code",
    "plugin",
    "code-quality",
    "reviewer"
  ],
  "author": "Your Name",
  "license": "MIT"
}

Verificar el manifiesto

cat package.json | grep claudeCodePlugin

Si ves "claudeCodePlugin": true, el manifiesto está correcto.

Campos que puedes omitir

El package.json generado por npm init -y incluye campos que un plugin no necesita:

{
  "main": "index.js",       // ← No necesario (no es una librería JS)
  "scripts": {
    "test": "echo ..."      // ← Opcional (útil para CI pero no requerido)
  }
}

Puedes eliminarlos o dejarlos — no afectan el funcionamiento del plugin.

Paso 2: Crear la Estructura de Directorios

mkdir -p agents skills

Estructura resultante:

my-quality-plugin/
├── package.json
├── agents/          ← Vacío por ahora
└── skills/          ← Vacío por ahora

Verificar

ls -la

Deberías ver package.json, agents/, y skills/.

Paso 3: Crear el Primer Agent File

El reviewer agent

Crea agents/reviewer.md — un agente read-only que analiza código sin modificarlo:

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

## Role

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

## What You Review

1. **Code Quality** — Duplication, complexity, naming, error handling
2. **Security** — Hardcoded secrets, injection, unvalidated input
3. **Conventions** — Read CLAUDE.md, check file organization and naming

## Process

1. Read CLAUDE.md for project conventions
2. Use Glob to discover project structure
3. Analyze each file against quality, security, and convention criteria
4. Produce structured report

## Output Format

### Code Review Report
**Scope:** [directories/files reviewed]
**Issues found:** [critical: N, warning: N, info: N]

#### Critical Issues
- **[file:line]** — [issue] — Risk: [risk] — Fix: [action]

#### Warnings
- **[file:line]** — [issue] — Recommendation: [suggestion]

#### Info
- **[file:line]** — [observation]

**Overall Assessment:** PASS | NEEDS_WORK | CRITICAL_ISSUES

Por qué este agent file es plugin-ready

1. Sin paths hardcoded — Descubre estructura con Glob y lee CLAUDE.md
2. Sin framework-specific — Funciona con Python, JavaScript, Go, cualquier lenguaje
3. Read-only — Solo Read, Glob, Grep en tools, nunca modifica archivos
4. Output estructurado — Formato consistente que cualquier equipo puede usar
5. Autocontenido — No referencia otros agent files ni archivos externos

Paso 4: Crear el Segundo Agent File

El implementer agent

Crea agents/implementer.md — un agente que implementa cambios siguiendo convenciones:

---
name: implementer
description: Implements code changes following project conventions. Reports all changes with rationale.
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
maxTurns: 25
---

## Role

You implement code changes following project conventions.
You report every change with rationale.

## Before Implementing

1. Read CLAUDE.md for project conventions
2. Examine existing code patterns in the relevant directory
3. Check for existing utilities to reuse

## Standards

1. Follow existing patterns — match surrounding code style
2. One responsibility per function
3. Error handling for every operation that can fail
4. Type safety where the project uses it
5. No dead code — no commented-out code or unused imports

## Output Format

### Implementation Report
**Task:** [description]
**Status:** DONE | PARTIAL | BLOCKED
**Files created:** [path] — [purpose]
**Files modified:** [path] — [what and why]
**Decisions made:** [decision] — [rationale]

Paso 5: Crear el Skill File

api-conventions skill

Crea skills/api-conventions.md — un archivo de conocimiento de dominio que los agentes consumen como contexto:

---
name: api-conventions
description: Team API conventions covering endpoint design, response format, error handling, and authentication patterns.
---

## Endpoint Design
- URLs: kebab-case (`/user-profiles`), plural nouns (`/users`)
- Nested resources: `/users/{id}/posts`
- HTTP methods: GET (read), POST (create→201), PUT (full update), PATCH (partial), DELETE (→204)

## Response Format
- Success: `{ "data": {...}, "meta": { "timestamp": "...", "request_id": "..." } }`
- Error: `{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }`
- Status codes: 200/201/204 for success, 400/401/403/404/422/500 for errors

## Authentication
- Bearer token in Authorization header (JWT)
- Claims: sub, role, exp, iat

## Pagination
- Cursor-based: `?cursor=<opaque>&limit=20` (max 100)
- Response includes `next_cursor` in meta

## Validation
- Validate all input at the API boundary with schema validation
- Return 400 with field-level error details

Paso 6: Verificar la Estructura

find . -type f | head -20

Deberías ver:

./package.json
./agents/reviewer.md
./agents/implementer.md
./skills/api-conventions.md

Checklist de estructura

✅ package.json con claudeCodePlugin: true
✅ package.json con files: ["agents", "skills"]
✅ agents/reviewer.md con frontmatter YAML válido
✅ agents/implementer.md con frontmatter YAML válido
✅ skills/api-conventions.md con frontmatter YAML válido
✅ Sin paths hardcoded en los agent files
✅ Sin dependencias de proyecto específico

Paso 7: Instalar Localmente

El comando de instalación local

cd ~/your-test-project

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

Este comando le dice a Claude Code: "carga este plugin desde un path local." No se publica a ningún registry — es instalación directa desde el filesystem.

Verificar instalación

claude plugins list

Deberías ver tu plugin listado:

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

Verificar que los agentes están disponibles

Inicia una sesión de Claude Code:

claude

Dentro de la sesión, verifica:

/agents

Deberías ver reviewer e implementer en la lista de agentes disponibles, marcados como provenientes del plugin.

Paso 8: Testear los Agentes del Plugin

Test del reviewer

En la sesión de Claude Code:

Usa el agente reviewer para analizar este proyecto. 
Enfócate en los últimos archivos modificados.

Lo que esperas: El reviewer lee CLAUDE.md, descubre la estructura, analiza archivos, y produce un reporte con el formato definido en su agent file.

Lo que verificas:

• ✅ El reviewer se invoca correctamente
• ✅ Lee CLAUDE.md para contexto
• ✅ Produce el formato de reporte definido
• ✅ No intenta modificar archivos (solo Read, Glob, Grep)

Test del implementer

Usa el agente implementer para crear una función helper 
que valide formato de email. Colócala donde tenga sentido 
según la estructura del proyecto.

Lo que esperas: El implementer lee la estructura, identifica el directorio correcto, crea el archivo con convenciones del proyecto, y reporta qué hizo.

Lo que verificas:

• ✅ El implementer se invoca correctamente
• ✅ Lee el proyecto antes de implementar
• ✅ Sigue las convenciones existentes
• ✅ Produce el formato de reporte definido

Test de la skill

Usa el agente reviewer para analizar los endpoints API 
de este proyecto contra las convenciones del equipo.

Lo que esperas: El reviewer aplica las convenciones de api-conventions (kebab-case, response format, status codes) al analizar los endpoints.

Lo que verificas:

• ✅ El reviewer menciona convenciones del skill (kebab-case, response format)
• ✅ Las reglas de la skill se aplican en el review
• ✅ El reporte referencia convenciones específicas del equipo

Paso 9: Iterar sobre el Plugin

Ciclo de desarrollo local

1. Editar agent file en ~/plugins-workshop/my-quality-plugin/agents/
2. Reinstalar: claude plugins add ~/plugins-workshop/my-quality-plugin
3. Testear en nueva sesión de Claude Code
4. Repetir hasta satisfecho

Ajustes comunes después del primer test

Si el reviewer es demasiado verbose:

## Output Rules
- Maximum 5 critical issues, 10 warnings, 5 info
- Each issue description: maximum 2 lines
- Skip issues with severity below WARNING unless asked

Si el implementer no sigue las convenciones del proyecto:

## MANDATORY First Steps
1. Read CLAUDE.md COMPLETELY before any implementation
2. List at least 3 conventions found in CLAUDE.md
3. Read 2 existing files similar to what you'll create
4. Match their patterns EXACTLY

Si la skill es demasiado genérica:

Agrega secciones específicas a la skill con reglas más concretas. Las skills pueden ser tan detalladas como necesites — no hay límite de longitud.

Comparación: Plugin Local vs Plugin Publicado

Cuándo quedarte con local

• Estás iterando rápidamente sobre los agent files
• Solo tú usas el plugin
• No tienes acceso a un npm registry
• Es un prototipo que puede cambiar drásticamente

Cuándo publicar

• El equipo necesita acceso
• Quieres versionado formal
• Necesitas reproducibilidad entre máquinas
• El plugin está estable y probado

Alternativa Manual: Script de Setup

Si claude plugins add no está disponible, crea un script de instalación:

#!/bin/bash
# install-quality-plugin.sh

PLUGIN_DIR="$(dirname "$0")"
TARGET="${1:-.}"

echo "Installing code quality plugin to $TARGET"

mkdir -p "$TARGET/.claude/agents"
mkdir -p "$TARGET/.claude/skills"

cp "$PLUGIN_DIR/agents/"*.md "$TARGET/.claude/agents/"
cp "$PLUGIN_DIR/skills/"*.md "$TARGET/.claude/skills/"

echo "Installed:"
echo "  Agents: $(ls "$TARGET/.claude/agents/"*.md | wc -l) files"
echo "  Skills: $(ls "$TARGET/.claude/skills/"*.md | wc -l) files"
echo ""
echo "Done. Start Claude Code to use the new agents."

Uso:

bash ~/plugins-workshop/my-quality-plugin/install-quality-plugin.sh ~/my-project

No es un plugin formal, pero cumple la función de distribución básica. Pierdes versionado automático y carga dinámica, pero ganas portabilidad inmediata.

Ejercicios

Ejercicio 1: Plugin mínimo viable (Fácil)

Crea un plugin con un solo agent file que haga linting básico (revisa naming conventions) y nada más. Instálalo localmente y verifica que el agente aparece disponible.

mkdir -p ~/mini-plugin/agents
cd ~/mini-plugin

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

---
name: linter
description: Checks naming conventions across the project. Read-only.
tools: Read, Glob, Grep
model: haiku
maxTurns: 10
---

## Role
Check file names and variable names follow conventions.

## Rules
- Files: kebab-case (my-component.tsx, user-service.py)
- Functions: camelCase (JS/TS) or snake_case (Python)
- Classes: PascalCase
- Constants: UPPER_SNAKE_CASE

## Output
List files/functions that violate conventions with recommended names.

cd ~/your-project
claude plugins add ~/mini-plugin
claude  # iniciar sesión
# dentro: /agents → verificar que "linter" aparece

Ejercicio 2: Agregar un tercer agente (Fácil)

Al plugin de quality que creaste en esta cápsula, agrega un tercer agent file: test-writer.md que genera tests unitarios basados en el código existente. Reinstala y verifica.

---
name: test-writer
description: Generates unit tests for existing code. Reads source files and creates corresponding test files.
tools: Read, Write, Glob, Grep, Bash
model: sonnet
maxTurns: 20
---

## Role
Write unit tests for existing functions and classes.

## Process
1. Read CLAUDE.md for testing conventions
2. Discover test framework (pytest, jest, vitest, etc.)
3. Read the source file to test
4. Create test file following project structure
5. Write tests covering: happy path, edge cases, error cases

## Standards
- One test file per source file
- Follow existing test patterns in the project
- Descriptive test names: test_[function]_[scenario]_[expected]
- No mocking unless necessary

## Output
**Source:** [file tested]
**Test file:** [created test file]
**Tests written:** [count]
**Coverage:** [functions/methods covered]

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

Ejercicio 3: Skill multi-sección (Medio)

Crea un skill file python-standards.md que cubra: naming conventions, import ordering, type hints, docstrings, y error handling — todo específico para Python. Agrégalo al plugin y verifica que el reviewer lo usa al analizar código Python.

---
name: python-standards
description: Python coding standards covering naming, imports, type hints, docstrings, and error handling.
---

## Naming
- Functions/variables: snake_case
- Classes: PascalCase
- Constants: UPPER_SNAKE_CASE
- Private: _prefixed
- Dunder methods: __name__

## Import Ordering
1. Standard library (os, sys, pathlib)
2. Third-party (fastapi, pydantic, sqlalchemy)
3. Local imports (from . import, from app import)
Separate each group with a blank line. Use isort.

## Type Hints
- All function parameters: typed
- All return values: typed (use -> None explicitly)
- Use Optional[X] for nullable, not X | None (for 3.9 compat)
- Complex types: define TypeAlias

## Docstrings
- Google style: Args, Returns, Raises sections
- All public functions must have docstrings
- One-line docstrings for obvious helpers

## Error Handling
- Catch specific exceptions, never bare except
- Custom exceptions inherit from app base exception
- Always log before re-raising
- Use contextlib.suppress for intentional ignoring

Ejercicio 4: Plugin con estructura incorrecta — diagnóstico (Medio)

Este plugin no funciona. Identifica todos los errores sin ejecutar nada:

broken-plugin/
├── package.json
├── agent/                    ← nota: singular
│   └── reviewer.md
├── skill/                    ← nota: singular
│   └── conventions.md
└── src/
    └── helpers.js

{
  "name": "@team/broken plugin",
  "version": "1",
  "claudeCodePlugin": "true",
  "files": ["agent", "skill", "src"]
}

reviewer.md:

name: reviewer
description: Reviews code

You are a reviewer. Read and analyze code.

Ejercicio 5: Plugin con reviewer + implementer coordinados (Difícil)

Modifica los agent files del plugin para que trabajen como flujo: el reviewer produce una sección "Actionable Fixes" (tabla con File, Line, Current, Required, Convention), y el implementer tiene una sección "When Receiving a Review Report" que parsea esa tabla y aplica fixes en orden de prioridad (Critical → Warning).

### Actionable Fixes
| File | Line | Current | Required | Convention |

## When Receiving a Review Report
1. Parse "Actionable Fixes" table
2. Prioritize: CRITICAL first, then WARNING
3. For each: read file, apply fix per convention, verify no breaks
4. Report each fix with before/after

Ejercicio 6: Crear README.md profesional (Difícil)

Escribe un README.md para el plugin que incluya: descripción, instalación (claude plugins add y path local), agentes (capabilities + usage example), skills, workflow (review → fix cycle), y requirements. Máximo 50 líneas.

Troubleshooting

Problema 1: "claude plugins add ./path da error de path"

Síntoma: Error indicando que el path no es un plugin válido.

Solución:

1. Usa path absoluto: claude plugins add /Users/you/plugins-workshop/my-plugin
2. Verifica que package.json existe en la raíz del path
3. Verifica que claudeCodePlugin: true está presente (no como string "true")

Problema 2: "El agente del plugin no recibe el contexto de la skill"

Síntoma: El reviewer no aplica las convenciones de api-conventions al analizar.

Solución:

1. Verifica que skills/ está en el campo files del package.json
2. Verifica que la skill tiene frontmatter YAML con name y description
3. En el agent file, referencia explícitamente la skill en el system prompt

Problema 3: "Después de editar un agent file, los cambios no se reflejan"

Síntoma: Editaste agents/reviewer.md pero Claude Code usa la versión anterior.

Solución:

1. Reinstala el plugin: claude plugins add ./path (sobrescribe la versión anterior)
2. Inicia una sesión nueva de Claude Code (los plugins se cargan al inicio)
3. Verifica la reinstalación: claude plugins list

Resumen

• El proceso es lineal: init → estructura → agents → skills → install local → test → iterar
• npm init -y + claudeCodePlugin: true es todo lo que necesitas para el manifiesto básico
• Agent files de plugin deben ser genéricos — sin paths hardcoded, descubren el proyecto via Glob y CLAUDE.md
• claude plugins add ./path instala desde un directorio local — ideal para desarrollo
• Testear antes de publicar es obligatorio — verifica que los agentes cargan, que las skills se precargan, y que los reportes tienen el formato esperado
• El ciclo de desarrollo es: editar → reinstalar → nueva sesión → probar → repetir
• Un plugin local funciona idéntico a uno publicado — la diferencia es solo el mecanismo de distribución
• La alternativa manual (script de setup + copy) funciona cuando claude plugins no está disponible

Recursos Adicionales

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. npm init Documentation — Inicialización de paquetes npm
5. npm package.json Files Field — Controlar qué se distribuye
6. Claude Code Best Practices — Buenas prácticas para agent files
7. Semantic Versioning — Versionado de plugins
8. Claude Code Settings — Configuración y permisos

Siguiente cápsula: En la cápsula 04 aprenderás cómo Claude Code carga los plugins dinámicamente al inicio de sesión, cómo funciona el versión pinning con semver, cómo publicar en un npm registry (local y remoto), y cómo manejar actualizaciones y breaking changes. Tu plugin local se convierte en un paquete distribuible.