Claude Code ya permite probar plugins antes de romper tus flujosClaude Code ya permite probar plugins antes de romper tus flujos

El problema no era crear un skill, era saber si funcionaba

Un plugin de Claude Code puede parecer útil después de dos pruebas manuales y fallar justo cuando alguien formula la petición de otra forma. Eso ocurre con skills para revisar proyectos Laravel, preparar despliegues o documentar servicios de un homelab: el comportamiento depende del prompt, del modelo y de las herramientas disponibles. Hasta ahora, comprobarlo era bastante artesanal y difícil de repetir.

La incorporación de claude plugin eval ataca ese problema con una idea sencilla: convertir situaciones reales en casos de prueba. Cada caso contiene un prompt y uno o varios graders que comprueban si el resultado cumple lo esperado. No se trata de validar que el manifiesto del plugin sea correcto, sino de verificar que el plugin guía al agente hacia un resultado útil.

Qué mide realmente una evaluación

Claude Code ejecuta cada caso en una sesión no interactiva y aislada, con el plugin cargado. Después puede comprobar la respuesta final, el rastro de herramientas utilizadas o los archivos creados durante la ejecución. También puede usar un modelo juez para decidir si una respuesta cumple una rúbrica definida en lenguaje natural.

La documentación oficial contempla seis tipos de grader: regex, tool_used, tool_order, file_exists, llm y baseline. Los cuatro primeros revisan datos de la ejecución o archivos generados; llm y baseline realizan llamadas adicionales a un modelo juez. Conviene empezar por comprobaciones deterministas siempre que sea posible, porque dan señales más estables y son más fáciles de entender cuando algo falla.

La comparación sin plugin es la parte importante

Un caso que aprueba con el plugin cargado no demuestra, por sí solo, que el plugin haya aportado algo. Claude podría haber resuelto la tarea igualmente sin instrucciones adicionales, especialmente en peticiones pequeñas o genéricas. Por eso las evaluaciones ejecutan por defecto cada caso con el plugin y también sin él.

El resumen muestra las columnas WITH, W/OUT y Δ. Ese delta representa la diferencia entre el resultado con plugin y el resultado sin plugin, así que es una referencia más útil que un aprobado aislado. Si ambos resultados son iguales, toca preguntarse si el skill aporta una regla práctica o solo repite algo que el modelo ya sabe hacer.

Un caso pequeño para un plugin de Laravel

Yo empezaría con una petición que un miembro del equipo escribiría de forma natural, sin mencionar el nombre del skill. Para un plugin que ayuda a mantener convenciones en una aplicación Laravel, el caso podría comprobar que Claude activa el skill y responde con criterios concretos de arquitectura. El formato vive dentro de evals/, junto al plugin, y se puede crear una plantilla inicial con claude plugin eval init --bare nombre-del-caso.

mi-plugin/
├── .claude-plugin/plugin.json
├── skills/
│   └── laravel-review/
│       └── SKILL.md
└── evals/
    └── revisar-servicio/
        ├── prompt.md
        └── graders/
            ├── criterios.md
            └── skill-activado.md

El archivo prompt.md admite frontmatter para limitar turnos y declarar las herramientas de solo lectura que necesita el caso. El cuerpo debe ser el prompt real que recibiría Claude, no una orden artificial diseñada únicamente para hacer aprobar la prueba. Si el escenario necesita código, ficheros o un repositorio preparado, hay que añadir fixtures mediante case.yaml en lugar de confiar en el estado de la máquina local.

---
max_turns: 10
allowed_tools: [Read, Glob, Grep, Skill]
---
Revisa este servicio de Laravel y dime qué cambios harías
para que no mezcle validación, acceso a datos y lógica de negocio.

Comprobar el resultado y el recorrido

Una rúbrica llm sirve para evaluar una respuesta cuyo formato puede variar, pero cuya calidad importa. Para una regla crítica prefiero concretar muy bien qué significa aprobar y qué significa fallar. Si el resultado se puede comprobar con un patrón, con un archivo o con una llamada de herramienta, elegiría antes uno de los graders no basados en modelo.

---
type: llm
---
PASS si la respuesta separa claramente validación, persistencia
y lógica de negocio, y propone cambios aplicables en Laravel.
FAIL si se limita a recomendaciones genéricas sin relacionarlas
con la estructura del servicio.

También merece la pena comprobar el camino seguido por el agente. Un tool_used puede confirmar que el skill se invocó, mientras que un grader de resultado comprueba que esa invocación sirvió para algo. La documentación advierte que los graders que solo tienen sentido con el plugin, como comprobar el uso de Skill, se tratan como indicadores para no inflar artificialmente el delta frente a la ejecución sin plugin.

Del homelab a una prueba repetible

Esto encaja igual de bien en un homelab. Un plugin con procedimientos para Proxmox, copias de seguridad, Docker o servicios autoalojados puede probarse con prompts habituales: restaurar un contenedor, revisar una política de backups o preparar un cambio de red. La diferencia es que no conviene lanzar esas pruebas contra infraestructura real por defecto.

Claude Code permite definir mocks para servidores MCP y respuestas de herramientas. Así se puede comprobar qué llamada intentaría hacer el agente y con qué datos, sin arrancar el servicio real. Para flujos que generan archivos, una prueba puede revisar el contenido de un fichero del workspace aislado o confirmar que se creó con file_exists.

Convertirlo en una puerta de CI

Cuando la suite deja de cambiar a cada iteración, tiene sentido llevarla a CI. El comando puede escribir el resultado en JSON, mantener el informe HTML en local y terminar con error si un caso no supera el umbral configurado. También conviene fijar el modelo del agente y el modelo juez para que un cambio de modelo no parezca una regresión del plugin.

claude plugin eval . \
  --trust-plugin \
  --json results.json \
  --threshold 0.8 \
  --model claude-sonnet-5 \
  --judge-model claude-haiku-4-5 \
  --no-publish \
  --max-cost-usd 20

El informe HTML se guarda junto a los resultados de la evaluación y es útil para revisar qué grader falló en cada ejecución. El JSON permite archivarlo como artefacto de CI o procesarlo en otra herramienta. No trataría un único resultado como una verdad absoluta: estos agentes no son deterministas y la propia documentación recomienda confirmar los cambios con las ejecuciones repetidas por defecto.

La letra pequeña antes de automatizarlo

Una evaluación no convierte un plugin en seguro. Claude Code carga skills y hooks del plugin en tu máquina, y el aislamiento protege al agente evaluado, no actúa como barrera frente al código propio del plugin, sus hooks o sus servidores MCP reales. Solo usaría --trust-plugin, --scaffold, --allow-real-servers o --mocks off con código que revisaría y ejecutaría por mi cuenta.

Tampoco es una prueba unitaria gratuita ni instantánea. Las ejecuciones y los graders que usan juez consumen llamadas de modelo, y el límite --max-cost-usd es un tope sobre una estimación de precio de lista, no una garantía exacta de consumo. Si el límite se alcanza, puede haber resultados parciales, y no deberían mezclarse sin más con series históricas de calidad.

Por último, un buen resultado mide exactamente lo que has escrito en los casos, no todo lo que hace el plugin. Si los prompts son demasiado amables, las rúbricas vagas o los mocks irreales, la suite puede aprobar mientras el uso real sigue siendo mediocre. La utilidad de claude plugin eval está en obligarnos a guardar ejemplos incómodos y repetibles de nuestro trabajo diario, no en añadir una insignia verde más al repositorio.

Fuente: MarkTechPost

Documentación oficial: Test plugins with evals

Notas de la versión: Claude Code v2.1.269