gonzalezpazmonica/prompt-optimizer

Skill: Prompt Optimizer (patron AutoResearch)

Inspirado en: AutoResearch Loop (Eric Risco / Karpathy) "Si los prompts son codigo, necesitan un compilador que los optimice."

Cuando usar

• Tras crear un skill o agente nuevo, para afinar su prompt
• Cuando un skill produce outputs inconsistentes o de baja calidad
• Para calibrar agentes de digestion contra documentos reales
• Periodicamente: re-optimizar skills con mas uso

Que necesita

1. Target (skill o agente a optimizar)

.claude/skills/{nombre}/SKILL.md    → skill
.claude/agents/{nombre}.md          → agente

2. Test fixture (input + checklist)

Fichero en .claude/skills/{nombre}/test-fixtures/ o .claude/agents/test-fixtures/{nombre}/:

# test-fixture.yaml
name: "fixture-basic"
input: |
  [El input que normalmente le pasarias al skill/agente.
   Para digest agents: ruta a un documento real.
   Para spec-writer: descripcion de una task real.
   Para NL resolver: frase en lenguaje natural.]
checklist:
  - id: CHK-01
    criterion: "Extrae todas las entidades mencionadas"
    weight: 2
  - id: CHK-02
    criterion: "Resuelve ambiguedades con contexto del proyecto"
    weight: 2
  - id: CHK-03
    criterion: "Output dentro de 150 lineas"
    weight: 1
  - id: CHK-04
    criterion: "Formato correcto segun template"
    weight: 1
  - id: CHK-05
    criterion: "No inventa datos no presentes en el input"
    weight: 3
context:
  project: "proyecto-alpha"  # opcional: proyecto para cargar contexto

Si no existe fixture: el comando lo crea interactivamente.

3. Scorer (G-Eval adaptado)

Cada item del checklist se puntua 0-10. Score global = media ponderada por weight.

Flujo del bucle

1. Cargar target + fixture + guardar backup
2. LOOP: ejecutar → puntuar (G-Eval) → registrar
3. Si score >= 8.0 en 3 consecutivas → PARAR (exito)
4. Si score < 8.0 → analizar items bajos → proponer cambio → aplicar → re-ejecutar
5. Si score subio → guardar cambio. Si bajo → revertir, intentar otro
6. Si max_iterations → PARAR (timeout)

Tipos de cambio que puede hacer

Cambios permitidos al prompt del skill/agente:

• Reordenar instrucciones (priorizar lo que falla)
• Añadir ejemplos concretos (few-shot para items bajos)
• Hacer explicitas restricciones implicitas
• Simplificar instrucciones redundantes
• Añadir paso de verificacion para items que fallan

Cambios PROHIBIDOS:

• Cambiar el nombre o description del frontmatter
• Cambiar tools, model o permissionMode
• Eliminar reglas de seguridad o confidencialidad
• Añadir dependencias externas no presentes

Output

Fichero optimizado

.claude/skills/{nombre}/SKILL.optimized.md     → skill
.claude/agents/{nombre}.optimized.md            → agente

El original NO se modifica. El PM decide si adoptar la version optimizada.

Log de optimizacion

output/prompt-optimizer/{nombre}-{timestamp}.jsonl — una linea JSON por iteracion con: iteration, score, scores_by_item, change_applied, change_kept, timestamp.

Resumen en chat

Score inicial → final, items mejorados, cambios aplicados/intentados, ruta del output.

Restricciones

NUNCA → Modificar el fichero original (solo crear .optimized.md)
NUNCA → Eliminar reglas de seguridad del prompt
NUNCA → Cambiar frontmatter (name, tools, model)
NUNCA → Ejecutar mas de 10 iteraciones por defecto
SIEMPRE → Guardar backup antes de empezar
SIEMPRE → Registrar cada iteracion en el log
SIEMPRE → Mostrar progreso al PM entre iteraciones