# Prompt Optimizer

> Skill: Prompt Optimizer (patron AutoResearch)

- Skill: `gonzalezpazmonica/prompt-optimizer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add gonzalezpazmonica/prompt-optimizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gonzalezpazmonica/prompt-optimizer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gonzalezpazmonica (https://skillmd.com/u/gonzalezpazmonica)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/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)

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

### 2. Test fixture (input + checklist)

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

```yaml
# 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

```
.opencode/skills/{nombre}/SKILL.optimized.md     → skill
.opencode/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
```