Skill: Doc Quality Feedback
Inspirado en Context Hub: agent annotations que persisten entre sesiones. Loop auto-mejora: agentes usan doc → puntuan → aggregacion → reescritura.
Cuando usar
- Despues de que un agente usa una skill o regla (automatico via protocol)
- Mensualmente para auditar calidad de documentacion
- Cuando un skill produce outputs inconsistentes (posible doc confusa)
Como funciona
Rating por agentes
Cuando un agente usa un skill/regla y termina, puede emitir un rating:
{
"doc": ".opencode/skills/codebase-map/SKILL.md",
"agent": "architect",
"rating": "clear",
"note": "Instructions were unambiguous",
"timestamp": "2026-03-19T02:00:00Z"
}
Ratings posibles:
- clear: instrucciones claras, output correcto al primer intento
- confusing: instrucciones ambiguas, requirio re-interpretacion
- incomplete: falta informacion para completar la tarea
- outdated: informacion desactualizada que causo error
- wrong: informacion incorrecta
Almacenamiento
public-docs-feedback/{doc-name-sanitized}.jsonl — una linea JSON por rating.
Ejemplo: public-docs-feedback/skills--codebase-map--SKILL.jsonl
Aggregacion
/docs-quality-audit lee todos los JSONL y produce:
- Score por doc: % ratings positivos (clear) vs negativos (confusing+incomplete+outdated+wrong)
- Docs con >30% ratings negativos → flagged para reescritura
- Tendencia: ¿mejoran o empeoran los docs con el tiempo?
- Top 5 docs mas usados (por numero de ratings)
- Top 5 docs peor puntuados (candidatos a
/skill-optimize)
Protocolo de emision
Los agentes NO estan obligados a emitir rating en cada ejecucion. El rating es voluntario y se emite cuando el agente detecta una de las condiciones:
- Tuvo que re-interpretar una instruccion ambigua → confusing
- No encontro informacion que necesitaba → incomplete
- Encontro informacion incorrecta → wrong/outdated
- Todo funciono sin friccion → clear (emitir 1 de cada 5 veces para no saturar)
Formato del JSONL
{"doc":"path","agent":"name","rating":"clear|confusing|incomplete|outdated|wrong","note":"...","ts":"ISO"}
Integracion
- skill-auto-activation: docs con rating bajo pierden prioridad de sugerencia
- skill-optimize: docs con rating bajo son candidatos prioritarios
- hub-audit: cruzar ratings con hub score para priorizar reescrituras
- session-init: si hay docs criticos (>50% negativo), alertar al PM