Anatomía de un skill de Claude Code: cómo se construye un flujo de agentes

Un desarrollador pidió a deep-research, el skill que viene con Claude Code, un informe sobre el estado del arte de un tema. La única pasada le devolvió 27 fuentes, 123 afirmaciones extraídas y 25 verificadas —18 confirmadas y 7 refutadas— con resumen ejecutivo, salvedades y preguntas abiertas. Lo que le sorprendió no fue el volumen, sino que todo saliera de un solo skill, así que fue a leer el código: no está en .claude/skills/ ni en ~/.claude, va compilado dentro del binario de Claude Code, son 349 líneas de JavaScript y un comentario delata su procedencia, "Ported from bughunter architecture".

Tres prompts con la misma forma

En el archivo hay tres prompts y los tres comparten estructura: un rol en el título, el contexto —la pregunta original más la entrada concreta—, la tarea como lista numerada, un criterio de decisión explícito y el formato de salida. El verificador es el más claro, y se reproduce tal cual:

Be SKEPTICAL. Try to REFUTE this claim. ≥2/3 refutations kill it.
...
refuted=false ONLY if: well-supported, current, and source quality matches claim strength.
Default to refuted=true if uncertain.
Structured output only. Evidence MUST be specific.

Dos detalles que el autor señala como poco habituales: el criterio se escribe como regla y los empates se resuelven por defecto hacia el lado conservador. Un prompt que no dice qué hacer en caso de duda deja esa decisión al modelo, y de ahí salen las respuestas ordenadas pero sin fundamento.

Seis piezas, no un prompt largo

Lo que hay en el archivo se reparte en seis bloques. La metadata de disparo declara nombre, descripción y las cinco fases, pero lo relevante es whenToUse: es lo que lee el modelo para decidir si invoca el skill, e incluye una instrucción previa para que haga dos o tres preguntas aclaratorias si la petición viene incompleta. Las constantes de ajuste viven arriba, sin números mágicos enterrados en el código: tres votos por afirmación, dos refutaciones necesarias para tumbarla, un máximo de 15 descargas y 25 afirmaciones a verificar. Cada tipo de agente devuelve JSON validado contra un esquema, y eso es lo que hace componible la tubería: la salida de uno es la entrada tipada del siguiente.

Los prompts son funciones, toman la entrada y devuelven el texto, así que no se copian: se instancian. La orquestación es explícita. Búsqueda y descarga van en pipeline, de modo que cada ángulo pasa a descargar sus fuentes sin esperar a los demás, y antes de verificar hay una barrera que el propio código marca como intencionada, porque el conjunto de afirmaciones tiene que estar completo antes de ordenarlo. Después, un parallel anidado de 25 afirmaciones por 3 votos. Y diseño defensivo: cada salida temprana devuelve un resultado con estadísticas en lugar de lanzar una excepción, un voto nulo cuenta como abstención y no como aprobado, y el resultado final lleva agentCalls con el coste calculado como 1 + ángulos + fuentes + afirmaciones × 3 + 1.

El autor reutilizó el patrón para comprobar que lo había entendido. Dos ejecuciones posteriores se cortaron por límite de sesión antes de verificar, así que escribió reverify-linea-c con la misma metadata, las mismas constantes y el mismo verificador de tres votos, pero sin búsqueda ni descarga: esas fases las sustituyó por un array de 22 afirmaciones ya extraídas. Volvieron las 22 confirmadas. Su conclusión es que un buen skill no es un prompt largo, sino uno corto y bien formado, instanciado muchas veces por una orquestación que sabe dónde esperar, dónde no, y que mide lo que gasta. Conviene recordar que esto es la lectura de un particular sobre un binario, no documentación oficial: cualquiera puede copiar el patrón, pero el skill puede cambiar de una versión a otra sin avisar.