🧠 Skills & POML

Objetivo: Tener un catálogo de habilidades que cualquier agente pueda cargar y ejecutar.

Una skill es una unidad de conocimiento especializado. Se organiza en el directorio skills/, con un subdirectorio por skill y un archivo SKILL.md dentro de cada uno.

Estructura de archivos:

skills/
├── harness-evaluator-skill/
│   └── SKILL.md
├── web-scraper-skill/
│   └── SKILL.md
└── data-analysis-skill/
    └── SKILL.md

Frontmatter obligatorio en SKILL.md:

---
name: harness-evaluator
description: Cómo usar el Harness Evaluator CLI
trigger: cuando un agente necesita evaluar un proyecto
---

Campos del frontmatter:

• name — identificador único de la skill
• description — qué hace la skill
• trigger — cuándo debe activarse

Tip: El evaluador verifica que todos los SKILL.md tengan frontmatter válido (check 6.5).

Objetivo: Definir flujos de trabajo de agentes en un formato declarativo y validable.

POML (Prompt Orchestration Markup Language) es un formato XML-like para describir cómo un agente debe ejecutar una tarea. Las recetas viven en poml/ o scripts/harness-fix/templates/.

Estructura mínima de una receta:

<poml>
  <let name="template_id">init-sh</let>
  <let name="output">init.sh</let>
  <let name="description">Script de bootstrap</let>
  <let name="triggers">["missing init.sh"]</let>
  <let name="check_ids">["5.1"]</let>
  <let name="weight_recovery">3.0</let>

  <output>
#!/bin/bash
set -e
echo "🔧 Inicializando..."
  </output>
</poml>

Elementos clave:

• <let> — variables con metadatos de la receta
• <output> — el contenido que se generará
• template_id — identificador único
• check_ids — qué checks del evaluador resuelve esta receta
• weight_recovery — cuánto mejora el score al aplicarla

Validación: El evaluador puede validar recetas POML con harness poml validate .. Verifica que tengan topology, role y task.

Objetivo: Centralizar el catálogo de skills para que los agentes puedan descubrirlas.

El manifest es el índice central del sistema de skills. Debe estar en _registry/manifest.yaml y listar todas las skills disponibles.

Ejemplo de manifest.yaml:

registry:
  version: "1.0"
  skills:
    - id: harness-evaluator
      path: skills/harness-evaluator-skill
      description: Evaluar estado del harness
      tags: [scanner, cli]
    - id: web-scraper
      path: skills/web-scraper-skill
      description: Extraer datos de sitios web
      tags: [http, parsing]

Schema de validación: Un archivo schema/recipe.schema.yaml define la estructura esperada de las recetas. Esto permite validar automáticamente que nuevas skills cumplan el formato.

Skill Provider: Un script (_registry/skill-provider.py o .js) carga skills dinámicamente desde el manifest. Esto permite que el agente descubra y ejecute skills sin hardcodearlas.

Objetivo: Que las recetas funcionen con múltiples modelos de IA, no solo uno.

Una receta POML multi-provider especifica cómo adaptar el prompt para diferentes modelos. El evaluador busca recetas que soporten al menos 2 providers.

Providers soportados comúnmente:

• openai — GPT-4, GPT-4o, GPT-3.5
• gemini — Google Gemini Pro / Flash
• qwen — Alibaba Qwen series
• anthropic — Claude 3 / 3.5
• deepseek — DeepSeek-V3 / R1

Tip: El evaluador da puntos extra (check 6.9) si tienes recetas que funcionen con múltiples providers. Esto hace tu proyecto más robusto ante cambios de API o disponibilidad.

Enfoque recomendado: Define la lógica de la skill de forma genérica en SKILL.md, y usa parámetros del frontmatter para ajustar el comportamiento por modelo si es necesario.

Objetivo: Usar el Harness Evaluator para medir y mejorar el subsistema de skills.

El evaluador ejecuta 11 checks en el subsistema Skills & POML. Los más importantes:

• 6.1 — ¿Existe directorio skills/ con SKILL.md? (peso 3.0)
• 6.2 — ¿Existen recetas .poml? (peso 2.0)
• 6.5 — ¿Todos los SKILL.md tienen frontmatter válido? (peso 2.0)
• 6.6 — ¿Las recetas POML definen topology? (peso 1.5)
• 6.7 — ¿Las recetas tienen role y task? (peso 1.5)

Flujo de mejora:

# 1. Escanear
harness scan . --json

# 2. Ver checks fallidos en skills
harness scan . --json | jq '.subsystems[] | select(.id=="skills")'

# 3. Generar archivos faltantes
harness fix .

# 4. Re-escanear
harness scan . --json

Meta: Alcanzar ≥ 80% en el subsistema skills para que el proyecto sea considerado maduro para agentes.

Antes de declarar que el sistema de skills está completo, el agente debe verificar:

• ¿Existe directorio skills/ con al menos un subdirectorio y SKILL.md?
• ¿Todos los SKILL.md tienen frontmatter YAML con name, description y trigger?
• ¿Existen recetas .poml con topology definida?
• ¿Las recetas POML tienen <role> y <task>?
• ¿Existe _registry/manifest.yaml con el catálogo?
• ¿Existe schema/recipe.schema.yaml para validación?
• ¿Hay al menos una receta multi-provider?
• ¿Existe documentación del sistema de skills (SKILLS_SYSTEM.md)?

Score objetivo del subsistema Skills: ≥ 80% en harness scan . --json