Skill Auditor — Evaluación de Depreciación de Capacidad y Ajuste en Agentes
Resumen
Un skill es un activo que se deprecia. Las versiones de modelo se lanzan cada pocos meses. Un skill que funcionaba bien el trimestre pasado puede degradarse silenciosamente: forma de salida incorrecta, llamadas a herramientas rotas, disparos fallidos, y nadie le dice al usuario que su agente se ha vuelto más tonto.
Este skill es la metodología de evaluación. Responde a tres preguntas:
- ¿Se está degradando un skill? — regresión de capacidad entre versiones de modelo.
- ¿Es realmente bueno un nuevo skill? — efectividad vs. costo.
- ¿Se ajusta este skill a ESTE usuario? — precisión de disparo + entorno + estilo.
Incluye cinco puntos de entrada ejecutables:
scripts/console.py— la consola residente (capa de datos): mantieneregistry.<host>.jsonpor host, detecta cambios de versión del modelo (bump/check) y emite el panel de recomendar/eliminar. ConsultaUSAGE.mdpara el conjunto completo de comandos.scripts/regress.py— dados los resultados de reproducción del conjunto dorado, calcula la matriz de tasa de aprobación, señala degradación (umbral + dirección) y marcaFINGERPRINT-DRIFTcuando un asset fue editado en lugar de degradado.scripts/baseline.py— crea una lista de verificación de reproducción y luego fusiona los veredictos grabados enbaseline-results.json(por asset;--replacepara sobrescritura completa). Los casos dorados borrador se omiten a menos que se use--allow-draft.scripts/fingerprint.py— CLI de informe independiente; un envoltorio ligero sobre el mismo código de hash que usascan. Escribefingerprint-report.*solamente; no escribe el registro.scripts/install.py— instala este skill en todos los hosts de agente de la máquina (~/.workbuddy-ai/skills,~/.claude/skills,~/.agents/skills,~/.dsh/skills,~/.codex/skills). Verifica después de instalar; nunca deja un directorio vacío atrás; nunca copia datos personales.
Principio fundamental: No hay medición sin una línea base. Degradación = caída significativa en la tasa de aprobación bajo una huella digital sin cambios — nunca "se siente más tonto".
Arquitectura Multi-Host (skills vs plugins)
Un motor central, adaptadores por host. La misma lógica de huella digital / línea base / regresión / recomendar / sugerencia de necesidad se ejecuta en todas partes; un adaptador solo sabe dónde viven los assets y cómo leer su manifiesto.
| host | tipo | raíz predeterminada | manifiesto |
|---|---|---|---|
| workbuddy | skill | raíz de skills que contiene este skill | SKILL.md |
| claude-code | skill | ~/.claude/skills | SKILL.md |
| deepseek | plugin | ~/.dsh/profiles/desktop (lee deps de package.json) | package.json / plugin.json |
| genérico | asset | pasar --root | plugin.json / manifest.json / SKILL.md / package.json |
- Cada host mantiene su propio registro:
registry.<host>.json— sin sobrescritura entre hosts. - Los resultados de línea base + conjuntos dorados se comparten, indexados por nombre de asset.
- Ejecuta con
--host <nombre> --root <ruta>; agrega hosts personalizados enhosts.json. console.py hostsmuestra cada perfil, su raíz resuelta y el recuento de assets detectados.
Por lo tanto, en WorkBuddy evalúas skills; en DeepSeek harness evalúas plugins — mismos comandos, adaptador diferente. Agregar un nuevo host es una entrada en hosts.json (tipo + raíz + nombres de manifiesto), sin cambios de código.
Cuándo Usarlo
- Antes de desplegar un nuevo skill o plugin ("haz un skill, sigue el proceso de evaluación").
- Después de un cambio de versión del modelo, para verificar si los skills existentes han regresionado.
- Cuando un skill "se siente extraño" — confirma con datos, no con sensaciones.
- Al decidir si conservar, reescribir o retirar un skill.
- Al recomendar un skill o plugin a un usuario (ajuste + evidencia).
Cuándo NO usarlo: tareas únicas sin skill reutilizable; documentos puramente narrativos.
Concepto Clave: La Huella Digital de Versión
La huella digital es la fila de la matriz de depreciación.
huella_digital = hash(contenido_archivos_superficie_capacidad + ruta_relativa) # calibre v2-superficie-capacidad
Lo que cuenta como superficie de capacidad (los archivos cuyo cambio realmente altera el comportamiento):
- incluidos:
SKILL.md,scripts/*,lib/*,dist/*,package.json,plugin.json,cordis.patch.yml, plantillas - excluidos:
README*,CHANGELOG*,LICENSE*, imágenes/audio/fuentes,*.map, archivos de bloqueo,node_modules/,test*/,docs/
Por qué excluir: una edición en el README no cambia la capacidad, pero al generar el hash, mueve la huella digital y produce un falso FINGERPRINT-DRIFT ("el asset fue editado") cuando no cambió nada funcional. Los plugins empeoran esto: un plugin instalado puede incluir 16 MB de salida empaquetada más un README de 57 KB.
Reglas:
- Huella digital sin cambios ⇒ la fila persiste; una caída en la tasa de aprobación es regresión del modelo.
- Huella digital cambiada ⇒ el cambio es responsabilidad del skill, no del modelo. Las filas antigua y nueva coexisten, por lo que las ediciones del skill nunca se atribuyen erróneamente a la deriva del modelo.
Ejecuta python scripts/console.py scan para calcular las huellas digitales y almacenarlas en el registro. fingerprint.py es un envoltorio de informe independiente; no toca el registro.
Superficie de Capacidad (por qué los plugins necesitan un segundo eje)
La huella digital dice "¿cambiaron los archivos?". No puede decir "¿todavía ofrece lo mismo?".
Por lo tanto, scan también registra una superficie de capacidad por asset y la compara con el escaneo anterior:
| Tipo de asset | Lo que registra la superficie |
|---|---|
| plugin | patch (dsh.bundle.patch), main/module, bin, exports, deps, skills, mcp, hooks, insert (filas cordis), scripts |
| skill | tools (recuento de herramientas permitidas), scripts |
Cuando cambia, scan lo muestra explícitamente:
[caps] 1 asset tiene cambios en su superficie de capacidad (esto es "lo que ofrece externamente ha cambiado", no está relacionado con la tasa de aprobación):
plug-a +bin
Por qué esto es importante para los plugins: un plugin se degrada al no registrar sus herramientas / dar 404 en sus rutas / no ejecutar sus hooks — no por "responder peor". Un conjunto dorado de prompts mide lo incorrecto para un plugin. El diff de superficie detecta "v1.1.0 eliminó un punto de entrada" sin necesidad de iniciar el host.
Límite conocido (no lo disimules): la superficie es capacidad declarada, no capacidad observada. Para un plugin cuyo manifiesto miente (declara un parche que falla al cargar), esto no puede detectarlo.
Evidencia de Tiempo de Ejecución (el tercer eje, y lo que no puede hacer)
Hay dos cosas muy diferentes llamadas "sonda de tiempo de ejecución". No las confundas:
| Sonda activa | Evidencia pasiva — implementada | |
|---|---|---|
| lo que hace | iniciar el host, preguntar "qué herramientas registraste realmente" | leer el registro que el host ya escribe |
| costo | Perfil desktop de DSH es exclusivo de Electron — dsh --profile desktop --dump-config es rechazado; sin entrada headless → ingeniería inversa de IPC o conducir la UI | una lectura de archivo, ~10 ms |
| detecta | todo, incluyendo un plugin cuyo manifiesto miente | cualquier cosa que el plugin registró |
| estado | no construida | console.py probe / skill_audit_probe |
probe lee ~/.dsh/logs/*.log (configurable por host mediante "logs" en hosts.json), analiza <iso> [nivel] [fuente] mensaje, atribuye líneas cuyo source coincide con un nombre de asset instalado, y marca líneas que coinciden con vocabulario de fallo (fail|error|ENOENT|unavailable|timeout|…).
Captura real, en esta máquina:
@wxg-prc-cpg/browser-skill-dsh-plugin 2 indicios de fallo
sonda bsk falló (spawn bsk ENOENT); las herramientas del navegador reportarán guía de instalación…
Archivos presentes, manifiesto válido, caps=4 — todas las comprobaciones estáticas pasan. El plugin está cargado y sus herramientas están registradas, pero no pueden funcionar: la CLI bsk a la que llama no está en PATH. Ninguna cantidad de hash de archivos encuentra esto.
Puntos ciegos (menciónalos, nunca los ocultes): un plugin que no registra nada es invisible; la rotación de registros borra fallos antiguos; un plugin que nadie ha usado no tiene evidencia; los fallos de nivel info se detectan por coincidencia de palabras clave, por lo que tanto omisiones como falsos positivos son posibles. La ausencia de evidencia no es evidencia de salud — probe imprime esa misma frase en lugar de una marca verde.
Implementado vs Solo Metodología (no difumines esta línea)
La metodología a continuación es más amplia que el código. Los usuarios deben saber qué mitad tienen en sus manos:
| Área | Estado |
|---|---|
Huella digital sobre la superficie de capacidad, scan/status, diff de capacidad | implementado |
| Creación de línea base dorada + ingesta de línea base (fusionar por asset, protección de borrador) | implementado (baseline.py) |
Matriz de tasa de aprobación, umbral ≥20pp + dirección, FINGERPRINT-DRIFT | implementado (regress.py) |
Detección de cambio de modelo (bump/check), marcas por host | implementado — pero la fuente del evento es manual; una check programada se mantiene verde hasta que alguien hace bump |
| Panel de recomendar/eliminar, sugerencia de necesidad, borradores extraídos del historial | implementado (heurístico; las sugerencias no son evidencia) |
| Evidencia de tiempo de ejecución desde registros del host | implementado (pasivo; solo lo que el plugin registró) |
| Ablación, tasa de adopción en modo sombra, valor neto / telemetría de tokens | solo metodología — sin código |
| Precisión/recuperación de disparo, reconciliación de entorno, línea base de estilo | solo metodología — sin código |
| Reproducciones K≥3, validación cruzada de juez LLM | no implementado; los veredictos actuales son autoevaluación K=1 |
columna risk | proxy de superficie de mantenimiento — no valor |
Si una afirmación en este archivo no se puede rastrear a una fila marcada como "implementado", trátala como un consejo para el humano que realiza la auditoría, no como algo que la herramienta hará por ellos.
Juicio 1 — Degradación de Capacidad
Cuatro pasos:
- Construye el conjunto dorado a partir del historial, no a mano. Extrae sesiones pasadas: el usuario adoptó sin resistencia → reproducción positiva; el usuario se resistió / pidió reescritura → negativa. La reproducción ES la regresión. El propio historial de uso del usuario es el corpus — no hay conjunto de prueba inventado.
- Ejecuta ambos modelos en el mismo conjunto dorado, K≥3 (casos de puntuación de juez LLM: K≥5, porque el juez es ruidoso). Registra la tasa de aprobación por (huella digital, versión del modelo).
- Regla de decisión: caída ≥20pp Y direccionalmente consistente → reportar degradación; por debajo del umbral → "vigilancia de volatilidad". Esto convierte "esta salida es extraña" en un criterio reproducible.
- Atribuye, no solo marques. Inspecciona artefactos intermedios:
- Error de llamada a herramienta / formato cambiado → corrige la descripción de la herramienta.
- Estructura de salida correcta, contenido incorrecto → reescribe las instrucciones.
- Debería haberse disparado pero no lo hizo → corrige la descripción del disparador.
- Todos los intermedios correctos, solo el final incorrecto → regresión interna del modelo; marca el skill como "dependiente de un solo modelo", espera la corrección del modelo.
La línea "7 degradados, 2 recomendados para reescritura" es el subconjunto atribuible de la salida del paso 4 — eso es lo que hace que el informe sea accionable.
Juicio 2 — ¿Es Bueno un Nuevo Skill?
Divídelo en dos ejes medibles: efectividad (mejores resultados) y economía (menor costo).
- Ablación previa al despliegue. Mismo lote de tareas, dos brazos: A sin skill, B con skill. Registra tasa de éxito, recuento de correcciones humanas, costo de tokens.
beneficio neto = mejora_tasa_éxito × frecuencia_tarea − costo_marginalUn skill que mejora el éxito en un 30% pero se dispara 3×/año con +50k tokens cada vez es un pasivo, no un activo. - Modo sombra posterior al despliegue. El nuevo skill se ejecuta en silencio: produce sugerencias pero no auto-ejecuta; registra "qué habría pasado". Monitorea la tasa de adopción (aceptadas vs. anuladas). La tasa de adopción es el juez último de "bueno", más honesta que cualquier métrica fuera de línea. Límite: los skills de operaciones de escritura (eliminar archivo, enviar correo) solo pueden simular/anotar en modo sombra, nunca ejecutar realmente.
- Tarjeta de valor neto. Un panel por skill: recuento de llamadas, tasa de éxito, tasa de adopción, tokens promedio, beneficio neto acumulado. 90 días con valor neto negativo → sugerir reescribir o retirar. Este es el lado del consumidor de la tabla de depreciación.
Juicio 3 — ¿Se Ajusta a ESTE Usuario?
"Te ajusta" = dispara con precisión + las suposiciones se cumplen + el estilo coincide. Todo automatizable:
- Precisión del disparador (más afecta la sensación, más se omite). Muestra positivos del historial (debería disparar) y negativos (similar, no debería — "arregla este error" vs "explica qué es un error"). Reproduce → precisión/recuperación. Baja precisión = molesto (sobre-dispara); baja recuperación = instalación desperdiciada. Primero etiqueta manualmente 10–20, luego semi-auto, costo LLM cero.
- Reconciliación del entorno (instalado ≠ funciona). Los metadatos del skill declaran dependencias: qué herramientas / MCP / permisos / hábitos de ruta / idioma, además de suposiciones implícitas de capacidad del modelo (contexto largo, ejecución de código, multimodal). Reconcílialo con el entorno real del usuario; faltante → bandera roja. "Asume macOS", "genera japonés", "necesita 200k de contexto" — las suposiciones invisibles son la razón #1 por la que un skill no se usa. Esto también retroalimenta el Juicio 1: una suposición de capacidad fallida = degradación silenciosa.
- Línea base de estilo (menor peso). Usa la salida histórica del usuario + USER.md como referencia; el juez LLM compara formato, idioma, verbosidad. Solo se usa para desempatar entre skills con puntuaciones iguales.
Flujo de Trabajo Integrado (para "crear un nuevo skill")
Cuando el usuario pide crear un skill, ejecuta el protocolo en línea antes de entregar:
- Reconciliación del entorno — ¿el entorno del usuario cumple con las dependencias declaradas + suposiciones de capacidad del skill?
- Reproducción del disparador — reproduce 10–20 casos muestreados; reporta precisión/recuperación.
- Ablación — en un lote pequeño de tareas, mide la mejora vs. el costo.
- Iniciar monitoreo — al pasar, registra la huella digital + conjunto dorado; la consola residente se vuelve a ejecutar en cada cambio de modelo.
Sugerencia Basada en Necesidad (cuando ningún skill coincide)
Este es el comportamiento de "estante vacío": un usuario (especialmente uno con cero skills/plugins) pide algo que ningún skill instalado cubre. No digas simplemente "no puedo" — muestra la brecha y ofrece llenarla.
- Detecta la necesidad de la conversación: tipo de tarea + dominio (ej. "informe financiero trimestral" → finanzas/análisis; "elimina el tono de IA" → humanizador; "construye un panel" → frontend/gráficos).
- Revisa el registro primero —
python scripts/console.py suggest --need "<necesidad>". Devuelve:✓ Ya tienes un skill/plugin disponible: <nombre>→ úsalo, no instales nada; o💡 Sugerencia de nuevo: [install:<slug>] <título>→ sin cobertura, recomienda la categoría.
- Si no está cubierto, busca en el marketplace candidatos reales (skills/plugins/expertos) y presenta una tarjeta con evidencia: qué hace, por qué se ajusta a esta necesidad, fuente. Nunca auto-instales — el usuario elige.
- Al instalar, ejecuta el flujo de trabajo integrado (punto anterior).
Glosario de Comandos (consola residente)
| Comando | Acción |
|---|---|
python console.py scan | Escanea todos los assets del host actual, calcula huellas digitales y superficies de capacidad |
python console.py status | Muestra el estado actual del registro: last_scan, last_bump, recuento de assets |
python console.py bump | Marca el host con una nueva versión de modelo (inicia el contador de degradación) |
python console.py check | Verifica si se ha ejecutado scan después del último bump; si no, reporta assets sin evaluar |
python console.py hosts | Lista todos los perfiles de host configurados, sus raíces y recuento de assets |
python console.py suggest --need "..." | Sugiere un skill/plugin existente o recomienda uno nuevo del marketplace |
python console.py probe | Lee los logs del host actual y reporta evidencia de fallos de tiempo de ejecución |
Dependencias y Archivos de Configuración
hosts.json: Define perfiles de host personalizados (tipo, raíz, nombres de manifiesto, ruta de logs).registry.<host>.json: Registro por host que almacena huellas digitales, versiones de modelo, timestamps y metadatos de assets.baseline-results.json: Resultados de línea base fusionados por asset, utilizados para el cálculo de regresión.fingerprint-report.*: Informe independiente de huella digital (sin modificar el registro).