Probar plugins de Claude Code con claude plugin eval

claude plugin eval es el comando de Claude Code que prueba un plugin con casos de prueba, puntúa cada resultado y lo compara con una ejecución sin el plugin. Sirve para comprobar si tu skill de verdad cambia lo que hace Claude, en lugar de suponerlo. Llegó en la versión 2.1.269, en la semana del 7 al 11 de septiembre de 2026, y esta guía resume cómo usarlo según la documentación oficial.

Qué hace exactamente

Una suite de evaluación vive en una carpeta evals/ dentro de tu plugin. Cada caso es un prompt realista, de los que escribiría una persona que usa tu plugin, más uno o varios graders. Un grader es una comprobación de aprobado o suspenso sobre lo que produjo Claude: una expresión regular sobre la respuesta, si se llamó a cierta herramienta o una rúbrica que juzga un segundo modelo.

• Cada caso se ejecuta tres veces por defecto, porque una sola ejecución de un agente no determinista dice poco.
• La puntuación de una ejecución es la fracción de graders que pasaron; la del caso es la media de sus ejecuciones.
• Cada ejecución se repite sin el plugin (la línea base). Así obtienes dos notas, WITH y W/OUT, y su diferencia Δ es lo que el plugin aporta de verdad.
• Si un caso saca 1.0 con y sin plugin, el plugin no es lo que lo hizo pasar.

Qué necesitas antes de empezar

• Claude Code 2.1.269 o superior (comprueba con claude --version y actualiza con claude update).
• Git 2.31 o superior, si tienes git instalado; con una versión anterior el comando se detiene antes de ejecutar ningún caso.
• Un plugin con manifiesto plugin.json o .claude-plugin/plugin.json, o un plugin de tipo skills-directory.
• La misma autenticación y proveedor de modelos que usas en tus sesiones normales.

Un aviso importante: cada ejecución y cada grader que usa un juez son llamadas reales al modelo y cuentan contra el uso de tu plan o contra tu factura de API. El costo que muestra el comando es una estimación a precio de lista.

Paso a paso: tu primera suite

1. Crear los casos

Desde la raíz de tu plugin, ejecuta:

claude plugin eval init

Si Claude Code aún no confía en el directorio, te pregunta si lo confías. Después se abre una sesión interactiva donde Claude lee tu plugin, te pregunta qué significa un buen resultado, propone prompts que deberían y que no deberían activar el plugin, diseña los graders, hace una prueba y escribe un directorio por caso dentro de evals/. Cuando te avise de que la suite está lista, sal con /exit o Ctrl+D.

2. Ejecutar la suite

claude plugin eval .

Cada caso corre tres veces con el plugin y tres sin él, es decir, seis ejecuciones por caso. Verás una línea de progreso por cada ejecución, con su nota y el veredicto de cada grader.

3. Leer la tabla de resumen

Al terminar aparece una tabla con esta forma (los valores son de ejemplo):

CASE        WITH  W/OUT  Δ      RUNS  COST
mi-caso     1.00  0.33   +0.67  6     $0.41

WITH es la nota con tu plugin, W/OUT la nota sin él y un Δ positivo indica que el plugin mejoró el resultado. COST es la estimación del costo. El detalle de cada grader está en report.html, dentro de evals/results/.

Cómo es un caso por dentro

Los casos son archivos de texto que puedes editar. Esta es la estructura que genera init:

mi-plugin/
├── .claude-plugin/plugin.json
├── skills/...
└── evals/
    ├── primer-caso/
    │   ├── prompt.md
    │   └── graders/
    │       ├── criterio.md
    │       └── skill-activada.md
    └── results/

En prompt.md el cuerpo es el mensaje que recibe Claude y el encabezado fija los límites de la ejecución, como max_turns (10 por defecto), timeout_seconds (300 por defecto) y allowed_tools. Cada ejecución parte de un directorio de trabajo vacío, así que todo lo que la tarea necesite debe ir en el propio prompt. Para comprobar que tu skill fue la que respondió, un grader de tipo tool_used sirve bien:

---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?nombre-de-tu-skill'
---

Hay seis tipos de grader:

Tipo	Qué comprueba	¿Llama a un modelo?
regex	Una expresión regular sobre la respuesta, la traza o un archivo	No
tool_used	Cuántas veces se llamó a una herramienta	No
tool_order	Que una herramienta se llamó antes que otra	No
file_exists	Que Claude creó un archivo con cierta ruta	No
llm	Una rúbrica que juzga un segundo modelo	Sí
baseline	Que el resultado es al menos tan bueno como una transcripción de referencia	Sí

Cómo interpretar los resultados

• Δ cerca de cero y el grader tool_used: Skill fallando: suele ser un hallazgo real. Claude no elige tu skill con frases naturales. Ajusta el description de la skill y vuelve a ejecutar.
• Δ negativo con la skill activada: sospecha primero del juez. Repite con --judge-model sonnet y afina la rúbrica para que el formato no decida el veredicto.
• Salidas largas: evalúalas con un grader regex sobre el archivo generado, que da un resultado estable, y deja los graders llm para salidas cortas.
• Iterar rápido: claude plugin eval . --case nombre --runs 1 --ablation none ejecuta un solo caso, una vez y sin línea base. Confirma cualquier cambio con las tres ejecuciones por defecto, porque una sola es ruidosa.

Usarlo en integración continua

El comando devuelve un código de salida que puedes usar para bloquear cambios: 0 si todos los casos alcanzan el umbral, 1 si alguno queda por debajo o hay un error, y 2 si la ejecución quedó parcial por llegar al tope de costo. Un ejemplo adaptado de la documentación. En un entorno real conviene fijar también el modelo del agente y el del juez con --model y --judge-model, para que un cambio de modelo no se confunda con una regresión del plugin:

claude plugin eval . \
  --trust-plugin \
  --json results.json \
  --threshold 0.8 \
  --no-publish \
  --max-cost-usd 20

--trust-plugin omite la pregunta de confianza y solo debe usarse con plugins cuyo código ejecutarías en tu propia máquina. --max-cost-usd pone un tope al costo estimado y --threshold define la nota mínima para aprobar (1.0 por defecto).

Costos y seguridad

• En total, una suite hace aproximadamente casos × ejecuciones llamadas al agente con el plugin y otras tantas sin él, más tres llamadas cortas de juez por cada grader llm o baseline en cada ejecución.
• Con --ablation none corres solo la rama con plugin y reduces el costo a la mitad, a cambio de perder el Δ.
• Evaluar un plugin carga sus skills, hooks y agentes en tu máquina, con tu usuario. Es la misma decisión de confianza que claude --plugin-dir: evalúa solo plugins en los que confíes.
• Las ejecuciones no piden permisos: las herramientas que requieren concesión, como Bash, Write o WebFetch, se quitan salvo que las otorgues con --allow-tools. Si otorgas Bash, corre dentro de un sandbox del sistema operativo.

Qué significa para quien programa con IA

Si ya escribes skills o plugins para Claude Code, esta herramienta convierte la pregunta de si funcionan en un número que puedes comparar entre versiones o tras un cambio de modelo. Si todavía no los usas, conviene empezar por lo básico: aprende a escribir un buen CLAUDE.md y a construir un agente en Python sin frameworks. Ten en cuenta que existe otra vía, el plugin skill-creator, que compara una sola skill dentro de una conversación con su propio formato de casos; ninguna de las dos herramientas lee los archivos de la otra.

Preguntas frecuentes

¿Necesito escribir los casos a mano?

No. claude plugin eval init propone los casos y los graders y los prueba una vez. Si prefieres hacerlo tú, claude plugin eval init --bare nombre-del-caso crea una plantilla vacía.

¿Cuánto cuesta ejecutar una suite?

Depende del número de casos, de las ejecuciones por caso y del modelo. Cada ejecución y cada juez son llamadas reales. El comando muestra una estimación a precio de lista y puedes limitarla con --max-cost-usd.

¿Sirve para probar un plugin que no he escrito yo?

Puedes evaluar un plugin instalado indicando su nombre, pero ejecutarlo equivale a confiar en su código y en sus hooks. La documentación recomienda evaluar solo plugins de confianza y tratar las notas como orientativas si incluye hooks o servidores MCP reales que no escribiste.

Fuentes

• Test plugins with evals, documentación oficial de Claude Code.
• What’s new, semana 37 de 2026, resumen semanal oficial de Claude Code.

Última revisión: 12 de noviembre de 2026. Los comandos y los archivos de ejemplo proceden de la documentación oficial y no los ejecuté con un plugin propio. Este artículo se preparó con ayuda de IA; consulta cómo usamos la IA.