Skills vs. docs en agentes Claude: 250 evals y sin respuesta fácil

El equipo de ingeniería de Wix se hizo una pregunta que muchos equipos que trabajan con agentes Claude llevan meses aplazando: ¿merece la pena empaquetar el conocimiento operativo en skills, o basta con pasar buena documentación al contexto? Para responderla no recurrieron a intuición ni a benchmarks genéricos: corrieron 250 evaluaciones propias y publicaron sus conclusiones en Wix Engineering Blog. El hilo en Hacker News llegó el 12 de mayo con poca discusión todavía, pero el artículo en sí tiene suficiente densidad técnica para merecer atención independiente.

Qué probaron y cómo

El experimento de Wix se centró en tareas reales de su pipeline interno: generación de código, consultas sobre APIs propietarias y secuencias de acción multi-paso. Para cada tarea diseñaron dos variantes de instrucción al agente: una usando skills —paquetes de instrucciones y contexto estructurado que Claude invoca bajo demanda— y otra proporcionando documentación textual equivalente inyectada directamente en el prompt. Las 250 evals se distribuyeron entre ambas condiciones con variaciones de complejidad y longitud de tarea.

El criterio de éxito no fue único. Midieron tasa de completitud correcta, número de llamadas a herramientas necesarias, coherencia entre pasos en tareas encadenadas y, algo menos habitual en este tipo de estudios, cuántas veces el agente solicitó aclaración innecesaria. Ese último indicador resulta especialmente relevante en entornos de producción donde cada interrupción tiene coste real.

La respuesta incómoda

El hallazgo principal, resumido honestamente en el propio titular del artículo, es que la respuesta es más complicada de lo esperado. Los skills no ganan siempre. La documentación no pierde siempre. El rendimiento relativo depende de al menos tres variables que el equipo identifica con claridad:

• Familiaridad del dominio: en tareas sobre APIs o convenciones muy específicas de Wix, los skills mostraron ventaja clara. El agente necesitaba menos tokens de contexto para llegar a la acción correcta y cometía menos errores de alucinación sobre parámetros propietarios.
• Longitud y encadenamiento: en tareas cortas de un solo paso, la diferencia era estadísticamente marginal. La brecha se amplió en secuencias de cuatro o más pasos, donde los skills actuaron como anclas de coherencia.
• Mantenimiento del conocimiento: aquí la documentación tiene una ventaja práctica que los autores no minimizan. Actualizar un bloque de texto es más rápido que versionar un skill, especialmente cuando los cambios son frecuentes o el equipo no tiene un workflow de publicación de skills consolidado.

Por qué importa esto más allá de Wix

El debate skills-vs-docs no es baladí. Desde que Claude Code incorporó soporte estable para skills y subagentes, los equipos de ingeniería se enfrentan a una decisión de arquitectura con implicaciones a medio plazo: invertir en construir una librería de skills mantenida, o apostar por una estrategia de documentación bien estructurada que cualquier miembro del equipo pueda editar sin tocar la configuración del agente.

El trabajo de Wix aporta algo que escaseaba: datos propios, en producción, con metodología explícita. No es un paper académico y no pretende serlo. Es el tipo de ingeniería empírica que los equipos que llevan meses trabajando con agentes Claude necesitan ver para tomar decisiones informadas, no basadas en las promesas del ecosistema.

También pone el foco en un aspecto que la documentación oficial de Anthropic trata de forma relativamente abstracta: el coste operativo de mantener skills. Construir el paquete inicial es una cosa; garantizar que refleja el estado actual de una API interna en constante cambio es otra.

Para quién es útil

Este análisis es directamente relevante para equipos que ya tienen agentes Claude desplegados o en fase de evaluación seria, especialmente si trabajan con bases de código propias o APIs internas que el modelo no conoce de entrenamiento. También es útil para quienes diseñan estrategias de onboarding de conocimiento en Claude Code: antes de decidir si construir skills o mantener un corpus de documentación, conviene entender en qué condiciones cada enfoque falla.

Para equipos que todavía están en las primeras fases, el artículo funciona como mapa de las preguntas que tendrán que hacerse más adelante.

---

Desde EP, la lectura que nos quedamos es esta: los skills son una apuesta con retorno claro en dominios estables y tareas complejas, pero no son una bala de plata. El rigor con el que Wix documentó su metodología es, en sí mismo, un estándar que el ecosistema debería replicar más a menudo.