🧠 Case Study: Agents-Flows-Recipes

Proyecto: Agents-Flows-Recipes — un repositorio de 21 skills documentadas para agentes de IA.

Estadísticas:

• 241 archivos en el repo
• ~5K líneas de código
• 21 skills documentadas con frontmatter YAML
• _registry con manifest.yaml y skill provider
• Sistema POML opcional para orquestación declarativa

El proyecto es un skills repo: cada skill vive en su propio directorio bajo skills/, con un SKILL.md que define su identidad, descripción y trigger mediante frontmatter. Un _registry/manifest.yaml centraliza el catálogo y un skill-provider.py permite cargarlas dinámicamente.

Breakdown por subsistema:

• Instructions: 85%
• State: 80%
• Verification: 0% — el bottleneck principal
• Scope: 62.5%
• Lifecycle: 70%
• Skills: 66.7%

Total: 61.5% — clasificación BUENO

El score revela un patrón común: excelente documentación y estructura de skills, pero una ausencia total de verificación automatizada. Sin tests, CI/CD ni linters, el repo depende enteramente de revisión manual.

1. Skills con frontmatter validado en todos

Cada uno de los 21 skills tiene un SKILL.md con frontmatter YAML que incluye name, description y trigger. Esto permite que cualquier agente entienda cuándo y cómo usar cada skill sin adivinar.

2. Registry system con provider + manifest

El _registry/manifest.yaml actúa como índice central. El skill-provider.py carga skills dinámicamente desde el manifest, evitando hardcodear rutas y permitiendo descubrimiento automático.

3. Documentación extensa (131 markdown files)

Con 131 archivos markdown, el repo prioriza la documentación. Cada skill, cada subsistema y cada decisión de diseño están explicados en texto plano, máxima portabilidad para cualquier agente.

1. Verification 0%: sin tests, sin CI/CD, sin linter

Es el gap más crítico. No hay tests unitarios, ni de integración, ni pipeline de CI/CD. No hay linter ni type checker. Cualquier cambio rompe silenciosamente hasta que alguien lo nota manualmente.

2. Lifecycle mejorable: 70%

Faltan hooks de lifecycle automatizados, init.sh no verifica dependencias y no hay un sistema de clean-state garantizado al final de cada sesión.

3. Scope parcial: 62.5%

No hay un Definition of Done explícito por feature ni un TASK.md que limite el trabajo a una sola tarea a la vez. El agente puede overreach fácilmente.

1. Documenta skills con frontmatter desde el día 1

El frontmatter no es overhead: es el contrato que permite que un agente descubra y use tu skill sin intervención humana. Invierte 3 líneas de YAML al crear cada skill.

2. Un _registry centralizado evita skills huérfanas

Sin manifest, las skills se pierden en subdirectorios. Un _registry con provider garantiza que el agente sepa qué existe y dónde encontrarlo.

3. El Verification gap es el enemigo común

Documentar sin verificar es como escribir un mapa sin comprobar que los caminos existen. Si solo puedes mejorar una cosa, pon tests. Un 0% en verification arrastra todo el score.

4. 21 skills > 5 skills genéricos

Es mejor tener 21 skills pequeñas y específicas que 5 monolitos. Las skills atómicas se componen, se versionan y se debuguean más fácilmente.

Antes de considerar completo el análisis de este case study, verifica:

• Todos los SKILL.md tienen frontmatter con name, description y trigger
• _registry/manifest.yaml lista las 21 skills con paths correctos
• El skill-provider carga skills sin errores desde el manifest
• La documentación tiene fecha de última actualización visible
• Se identificó el bottleneck principal (Verification 0%)
• Se propusieron acciones concretas para cerrar cada gap
• El score total del proyecto se recalcula tras cada mejora
• No hay skills sin directorio propio o sin SKILL.md

Usa el scanner de harness para evaluar cualquier repo de skills:

harness scan . --json

Para ver solo el subsistema de verification:

harness scan . --json | jq '.subsystems[] | select(.id=="verification")'

Para generar archivos faltantes automáticamente:

harness fix .

Meta: llevar el score total de 61.5% a ≥ 80%. Eso requiere principalmente cerrar el gap de verification (llevarlo de 0% a ≥ 70%) y mejorar scope a ≥ 80%.