Agentes que se mejoran a sí mismos mediante habilidades: reutilización, selección, reparación y verificación.

Un agente de programación que se topa dos veces con el mismo problema suele carecer de un lugar permanente donde guardar lo que ha aprendido. La idea detrás de un complemento llamado Whetstone es que el trabajo que realiza un agente hoy debería mejorar el trabajo del día siguiente. Una herramienta que el agente haya escrito y probado debería estar disponible la próxima vez. Un flujo de trabajo que necesite correcciones debe generar cambios duraderos que alguien pueda revisar. Y antes de entregar un resultado, las verificaciones que se sabe que son necesarias ya deberían haberse realizado.

Esos son hábitos de ingeniería comunes, pero tienden a quedar en la mente de una persona y a repetirse al final de cada sesión. Whetstone los organiza en cuatro habilidades que actúan sobre otras habilidades: reutilizar código probado, mejorar la forma en que se seleccionan las habilidades, registrar lecciones procedimentales y verificar la salida antes de devolverla al usuario.

El enfoque es el de “agentes de auto-mejora” en un sentido deliberadamente modesto. El agente ayuda a mejorar sus propias instrucciones y herramientas, un humano revisa los cambios y decide qué se vuelve permanente; el modelo en sí no se vuelve a entrenar, y nada funciona sin supervisión en segundo plano para aprender por sí solo.

Una auditoría inicial de 383 archivos de habilidades proporcionó al complemento un campo de pruebas concreto. Sin embargo, lo más transferible es el diseño: dónde debe residir el trabajo reutilizable, cómo elegir la intervención adecuada y qué pruebas se deben exigir antes de mantener un cambio. Ese razonamiento es aplicable tanto con el complemento como con una versión desarrollada según tus propios flujos de trabajo.

La parte de un agente que realmente se puede mejorar

Una habilidad es una carpeta que contiene un archivo SKILL.md con instrucciones y, opcionalmente, scripts y documentos de referencia. La especificación abierta Agent Skills establece un formato común, con un nombre breve y una descripción al inicio del archivo. El equipo de ingeniería de Anthropic ha descrito las habilidades como una forma de dotar a los agentes de uso general de conocimientos reutilizables, y su ventaja radica en que se puede mejorar un procedimiento sin tener que reconstruir el entorno de ejecución.

Se involucran dos tareas separadas: el agente debe elegir la habilidad adecuada, y esa habilidad elegida debe guiar adecuadamente el trabajo. Corregir una no soluciona automáticamente la otra.

Whetstone asigna a cada una de sus cuatro habilidades una única responsabilidad:

• dry-promotion conserva el código reutilizable.
• skill-audit examina la información utilizada para la selección de habilidades.

skill-repair propone cambios en los procedimientos.

verify-before-return verifica el resultado.

Lo que hace que esta división funcione es que cada operación modifica algo diferente. Un complemento podría merecer ser guardado aunque no haya habido ningún error. Una descripción vaga podría requerir atención aunque el procedimiento subyacente funcione perfectamente. Pasar cada solicitud por las cuatro operaciones juntas uniría tareas no relacionadas, mientras que puntos de entrada separados permiten invocar solo la parte que necesita una tarea.

Cada operación termina con algo que se puede observar: un archivo en el disco, un informe de auditoría, una diferencia sugerida o evidencia de verificación. Esto facilita la depuración y proporciona al revisor algo concreto para aprobar. La ayuda del agente es bienvenida, pero una explicación convincente por sí sola nunca hace que un cambio sea permanente.

1. DRY: conservar el trabajo que ya funcionó

DRY significa “no te repitas”, y también se refiere a un agente que incluye el código funcional que ya generó anteriormente. Cuando cada solicitud de presentación obliga a reconstruir el renderizador, este debe resolver un problema técnico anterior antes de poder procesar el nuevo contenido.

El renderizador es la maquinaria reutilizable, mientras que el contenido es lo que varía. La documentación de Anthropic ilustra este punto con una habilidad en PDF que ejecuta un script de extracción preescrito: el código se encarga de la parte mecánica estable, mientras que el modelo toma las decisiones específicas para la tarea.

Ese es el propósito de dry-promotion. Copia una herramienta útil a la carpeta scripts/ de la habilidad y reescribe las instrucciones para que se ejecute el script. Guardar un archivo por sí solo no basta: aunque la habilidad sigue indicando al agente que escriba un script, nada le señala el archivo ya guardado.

Un contador de caracteres es un buen ejemplo dentro de un flujo de trabajo de escritura. Un subtítulo tiene un límite de longitud, y un programa sencillo puede calcular ese número mientras el modelo se concentra en redactar el texto. La instrucción correspondiente podría ser más o menos así:

Antes de devolver un subtítulo, ejecute el contador de caracteres almacenado. Si el resultado supera el límite, acorte el texto y vuelva a contar. Nunca intente adivinar el número, ni reconstruya el contador.

Esto permite contar con una implementación estable que se pueda inspeccionar y probar. No hace que todo el flujo de trabajo sea determinista, ya que el propio subtítulo aún puede variar, y un programa puede repetir fielmente una definición incorrecta. El contador debe decidir si cuenta puntos de código Unicode o caracteres visibles, y cómo tratar los espacios y saltos de línea.

Prepare un ayudante antes de promoverlo: elimine las rutas vinculadas a una sesión específica, haga que las entradas sean explícitas y pruébelo en casos distintos al que lo inspiró. Luego ejecute nuevamente el flujo de trabajo y verifique que el archivo guardado sea el que se está utilizando. Un ejecución que crea silenciosamente otro contador anula el propósito de la reutilización, incluso cuando las cifras finales coinciden.

El mismo principio se aplica a las plantillas y las referencias compartidas. Cuando varias habilidades comparten un contrato de salida, mantenga una copia autoritativa y haga que las demás hagan referencia a ella. No fuerce dos flujos de trabajo realmente diferentes a través de un mismo ayudante solo porque sus primeros ejemplos se parezcan. La reutilización debe preservar un funcionamiento estable y no ocultar diferencias importantes.

2. Ayude al agente a elegir la habilidad adecuada

Con la divulgación progresiva, un agente comienza con metadatos ligeros y carga las instrucciones completas de una habilidad solo una vez que selecciona dicha habilidad. La razón práctica es que cargar todos los procedimientos de antemano consume recursos en tareas que podrían no solicitarse nunca.

Para la selección automática, el nombre y la descripción funcionan como información de enrutamiento. La explicación cuidadosamente redactada a mitad del archivo podría incluso no estar disponible cuando el modelo decida si debe abrirlo.

Las descripciones no son el único medio de selección. Claude Code también admite invocaciones explícitas, y la configuración en tiempo de ejecución afecta lo que está disponible. Aun así, la descripción es la señal de selección que controla el autor de la habilidad.

Al escanear la biblioteca de habilidades de una persona, contando los duplicados con el mismo nombre aparte de las colisiones, se obtuvo este resumen:

383 skills scanned
  missing description           0
  no trigger language         306
  colliding pairs               3
  duplicate names              23
  skills with >=1 defect      306  (79%)

El 79% corresponde a un cálculo truncado de 306 dividido entre 383, lo que equivale a aproximadamente el 79,9%. Esas descripciones fallaron en la verificación de redacción, lo cual no es lo mismo que los 306 casos observados de uso incorrecto de una habilidad. El escáner solo verifica frases desencadenantes literales como “usar cuando” o “cuando el usuario”. Un modelo puede seguir una descripción que carezca de esas palabras, y una descripción que las contenga aún puede ser demasiado amplia como para ser útil. El resultado es una lista para investigar y no una medida de cuán defectuoso está el agente.

Asigna tareas diferentes a las habilidades vecinas

Considere dos descripciones reales de dos habilidades en el mismo complemento:

Uno de ellos se presenta como experto en la creación de sistemas de generación mejorada mediante recuperación de información, utilizando bases de datos vectoriales, embeddings y estrategias avanzadas de recuperación. El otro se presenta como experto en la selección, configuración y ajuste de bases de datos vectoriales como Pinecone, Weaviate, Chroma, Qdrant y Milvus para búsquedas semánticas y aplicaciones RAG.

Ambos tienen un buen nivel de redacción, así que, ¿cuál es la mejor opción para un usuario que necesita ayuda para elegir una base de datos vectorial para una aplicación RAG? Un modelo competente podría favorecer al segundo, cuyo enfoque es más específico, aunque el primero también afirma tener las mismas competencias. No está claro qué habilidades posee cada uno, por lo que el modelo debe inferir las diferencias.

Una redacción más clara establecería una distinción más firme entre ellos. Hasta ahora no se han realizado pruebas de rendimiento al respecto:

name: vector-database-selection
description: >-
  Compare vector databases against workload, filtering,
  deployment, and operating-cost requirements. Use when
  choosing or replacing a vector store. For retrieval-pipeline
  design with an already chosen store, use rag-pipeline-design.

name: rag-pipeline-design
description: >-
  Design ingestion, chunking, retrieval, reranking, and
  evaluation for a RAG application. Use when building or
  diagnosing a retrieval pipeline. For a standalone vector
  database selection, use vector-database-selection.

El primero es responsable de elegir la base de datos, mientras que el segundo se ocupa de encontrar el camino desde los documentos hasta el contexto útil para obtener una respuesta. Alguno del vocabulario se mantiene compartido, ya que las tareas realmente se superponen.

Redacte las solicitudes de prueba antes de tocar cualquier redacción. “Comparar almacenes vectoriales para una aplicación de búsqueda de documentos autohospedada” debería referirse a la selección de la base de datos. “¿Dónde deberían almacenarse nuestros embeddings? Ayúdame a decidir” significa lo mismo con otras palabras. “Ya tenemos un almacén vectorial, pero la recuperación no encuentra los párrafos relevantes” pertenece al diagnóstico del proceso.

Luego agregue una solicitud que ninguna de las habilidades debería manejar, como arreglar el espaciado de un botón de búsqueda en dispositivos móviles. Sin esto, solo ha probado cuál de las dos habilidades gana y no si el agente puede rechazar ambas.

Pruébelos en sesiones nuevas con un modelo idéntico, habilidades habilitadas y contexto del proyecto similares. Omita el nombre de la habilidad deseada en cualquier prueba de selección automática, ya que nombrarla modifica el experimento. Allí donde el tiempo de ejecución lo revele, registre qué habilidad se cargó y conserve la respuesta o el artefacto generado. Un registro que muestre el archivo que se abrió es una prueba más sólida que la afirmación del agente de que utilizó la habilidad correcta.

Compare los resultados antes y después, y excluya algunas paráfrasis de la sesión de reescritura para no ajustar los parámetros únicamente para sus propios ejemplos. Este pequeño conjunto de pruebas de regresión indica si un cambio fue útil en las solicitudes relevantes.

3. Convertir la experiencia en instrucciones reutilizables

Al detectar un problema surge una pregunta más útil: ¿dónde debe realizarse la corrección?

skill-repair escribe sus propuestas como diferencias que debe aprobar una persona, basadas en un objetivo que está bajo control de versiones. El objetivo es realizar la edición más mínima posible para solucionar el fallo detectado, de modo que un revisor pueda leerla y revertirla si afecta a algo más.

Imagínese una habilidad para redactar informes que devuelve un resumen sin consultar el documento original. Pedirle que “sea más cuidadoso” le da al agente muy poca información para actuar. Lo que solucione el problema depende de por qué se omitió la verificación:

• El procedimiento nunca requirió el documento original: cambie el procedimiento.
• Se requiere el documento original, pero no se indica su ubicación: proporcione ese contexto o solicite la información faltante.
• Se leyó el documento original, pero una figura se copió incorrectamente: se necesita otra verificación.

Una advertencia genérica aplicada en todos los casos evitaría por completo el diagnóstico.

Guarde la solicitud fallida junto con la edición propuesta, describa el comportamiento esperado y conserve el archivo que reveló el fallo. Ejecute nuevamente la solicitud en una sesión nueva y luego pruebe una solicitud similar que debería seguir funcionando. De lo contrario, es fácil aprobar un cambio porque su redacción resulta convincente, lo cual es una forma cómoda de pasar la tarde sin mejorar nada.

También es importante el alcance. Una preferencia relacionada con un informe permanece en ese informe. Una regla para cada informe que genere la habilidad se incluye en dicha habilidad. Un dato que cambia con frecuencia puede encajar mejor en una referencia a la que acceda la habilidad. Si cada corrección queda registrada en las instrucciones permanentes, un procedimiento reutilizable se convierte gradualmente en un registro de la última sesión de una sola persona.

Los éxitos merecen la misma atención. Cuando una secuencia funciona de manera fiable, se debe conservar el orden útil, las entradas y los ejemplos, y no solo las advertencias sobre lo que salió mal. La guía de creación de habilidades de Agent Skills recomienda basar las habilidades en trabajos reales y perfeccionarlas a través de su ejecución. Una habilidad debe contener el conocimiento que falta en la siguiente ejecución, no una transcripción de todo lo que ocurrió.

Cuando la guía compartida necesita reparación

La biblioteca de una persona es su propio desorden acumulado, auditado por su propia herramienta; por lo tanto, se aplicó el mismo proceso de auditoría a un repositorio público de complementos mantenido por un equipo universitario especializado en software de investigación. En esa captura se encontraban 76 habilidades distribuidas en 12 complementos.

Las banderas se agruparon por plugin. Siete plugins fueron marcados en su totalidad, y un plugin de Python científico tuvo cuatro de cinco elementos marcados. Ese agrupamiento motivó la búsqueda de plantillas y convenciones comunes, y resultó que la guía de contribución era la fuente. En ella se solicitaba “una descripción clara del agente y su propósito” y se ofrecía una plantilla de ejemplo que indicaba qué hace el agente. Nunca se preguntaba cuándo utilizarlo. Treinta y seis habilidades siguieron correctamente la guía, pero el problema radicaba en la propia guía.

Según se informó, se abrieron dos problemas públicos, uno para la guía y otro para las 36 descripciones, y el orden es importante. Hay que actualizar la convención, mostrar un buen ejemplo y solo entonces ajustar las descripciones existentes. De lo contrario, el siguiente colaborador seguirá perfectamente la guía e introducirá nuevamente el mismo patrón.

Una verificación de CI puede ser útil, pero comiéncenla como algo consultivo. Si la regla conoce solo unas pocas frases desencadenantes, hacer que constituya un fallo grave incentiva a los colaboradores a pegar esas frases hasta que la compilación tenga éxito, lo que aumenta la cifra sin mejorar las habilidades. La verdadera prueba de aceptación sigue necesitando solicitudes representativas, incluidas aquellas que la habilidad debería ignorar.

4. Verificar antes de la entrega

verify-before-return proporciona a una habilidad criterios de aceptación y un ciclo de revisión. Escribir un archivo en el disco es solo un punto intermedio, y el flujo de trabajo aún debe inspeccionar el resultado utilizando pruebas adecuadas para la tarea:

• En el caso de una presentación, es necesario renderizarla y luego buscar texto recortado, etiquetas ilegibles o elementos fuera del área de visualización.
• En el caso de un informe de investigación, abrir las fuentes y verificar que respalden las afirmaciones hechas.
• En el caso de código, ejecutar pruebas que prueben el comportamiento requerido.

Cualquier afirmación de que se ha completado el trabajo debe referirse a lo que realmente se verificó.

Defina esos criterios antes de generar el contenido. Luego, pida al sistema que redacte, revise, corrija los errores y vuelva a realizar las verificaciones afectadas por las correcciones. Establezca un límite para el ciclo de revisiones y exija que se informe sobre todo lo que aún no esté resuelto, ya que “continuar mejorando” podría convertirse en una edición interminable sin un resultado claro.

El trabajo subjetivo requiere una revisión diferente. Un principiante simulado puede señalar términos inexplicados, y un lector escéptico puede cuestionar los argumentos. Ambos son útiles, pero ambos son críticas generadas por modelos y no comentarios de miembros reales del público; por lo tanto, evalúe cada sugerencia en función del propósito del texto en lugar de aceptar todas las objeciones. La decisión sobre el gusto y la estrategia corresponde a quien encargó el trabajo.

Ejecutar una verificación no es lo mismo que ejecutar la correcta, y las pruebas realizadas por el auditor demuestran por qué.

Qué pruebas modificó el auditor

Las pruebas mostraron que el auditor debía tratar las instalaciones duplicadas y las descripciones superpuestas como hallazgos separados. La primera ejecución reportó 81 pares candidatos, muchos de ellos correspondientes a habilidades idénticas presentes en diferentes versiones cacheadas del plugin. Al analizar esos pares, se separaron las duplicadas con el mismo nombre de la análisis de colisiones, lo que redujo el número de candidatos a 3.

Por eso, los registros que sustentan un resumen merecen ser examinados antes de que se implemente cualquier cambio. Los archivos duplicados requieren una verificación de inventario, mientras que las descripciones contradictorias necesitan una prueba de enrutamiento. Agruparlos de forma incorrecta lleva a soluciones erróneas.

Al separar los nombres duplicados también se detectaron 23 nombres presentes en más de una ruta escaneada. Las copias en caché no demuestran que las versiones antiguas estuvieran activas, lo cual requiere verificar los plugins habilitados en el entorno de ejecución y las rutas resueltas. De igual manera, los 383 registros corresponden a archivos escaneados pero no activos, habilidades únicas, y excluir las comparaciones de nombres idénticos no elimina por completo los duplicados del inventario.

La puntuación es solo una heurística basada en palabras: las palabras compartidas por ambas descripciones, divididas entre las palabras de contenido distintas en cada una, con un umbral predeterminado de 0.35. Una exclusión puede parecerse a una superposición, y dos descripciones de un mismo puesto con redacción diferente pueden pasar desapercibidas. El analizador de frontmatter también solo soporta un subconjunto de YAML. Cualquier indicador necesita ser revisado por un humano antes de que se convierta en una corrección.

Después de que una reparación sea aprobada, conserve el caso fallido junto con uno en el que la versión antigua ya funcionaba correctamente. Juntos muestran si un cambio posterior corrige un comportamiento al dañar otro. No se ha medido ninguna mejora en el éxito de las tareas a nivel de toda la biblioteca para whetstone, y estas verificaciones son la forma en que se evaluaría.

El empaquetado no se transmite; las habilidades sí

Un objetivo era hacer que whetstone fuera utilizable más allá de Claude Code. Compartir el formato SKILL.md ayuda en parte. Una habilidad puede seguir dependiendo de herramientas, permisos o rutas de archivo que otro cliente no proporciona, y cada cliente empaqueta los plugins de manera diferente. El estándar Agent Plugins, la referencia de Claude Code y la documentación OpenCode describen esos diseños.

Whetstone envía ambos manifiestos a través de un único directorio compartido skills/. El procedimiento se mantiene en un solo lugar y la integración de cada cliente se prueba por separado. Las instrucciones portátiles aún no permiten que los modelos sean intercambiables, por lo que ejecute la misma tarea representativa en otro entorno de ejecución compatible y verifique sus llamadas a herramientas, dependencias y resultados antes de asumir que el comportamiento es el mismo.

Probándolo en un flujo de trabajo

No se requiere una biblioteca grande. Elija un flujo de trabajo, como una herramienta auxiliar que el agente vuelve a crear constantemente, dos habilidades que mezcla o un resultado que suele finalizar manualmente. Conserva una solicitud representativa y su resultado para compararlos.

A continuación, elija la intervención adecuada: reutilice un ayudante existente, afine la selección, grabe una lección procedural o agregue una verificación de aceptación que falte. Luego compare la ejecución siguiente con el ejemplo guardado. Un inventario más amplio puede esperar, y no se debe eliminar un caché antiguo solo porque un escaneo recursivo encontró archivos antiguos.

El proyecto está bajo licencia MIT. Para Claude Code, su README proporciona estos comandos de instalación:

claude plugin marketplace add cdcore09/whetstone
claude plugin install whetstone@whetstone

Se exponen cuatro puntos de entrada: /audit, /promote, /repair y /verify. Utilice el que mejor se adapte al flujo de trabajo. Al intentarlo por primera vez, es recomendable que examine los archivos relevantes y proponga cambios antes de aplicar cualquier modificación.

Para estudiar el auditor sin instalar nada, clone el repositorio y lea skills/skill-audit/scripts/audit_skills.py. Desde la parte superior del repositorio, el comando a continuación lo ejecuta, y solo se utiliza la biblioteca estándar de Python:

python3 skills/skill-audit/scripts/audit_skills.py ./skills

Reemplace ./skills por el directorio que desea examinar, comenzando con una pequeña colección que reconozca antes de analizar cada caché de plugins en su máquina. --json genera un informe estructurado, y --threshold 0.25 muestra un conjunto más amplio de descripciones superpuestas.

El script solo lee archivos y nunca reescribe las habilidades. Un estado de salida de 1 indica que encontró indicadores, colisiones entre candidatos o nombres duplicados, pero esto no implica necesariamente una falla de Python. Sus rutas por defecto tampoco abarcan la estructura de instalación de todos los clientes, por lo que indicar una ruta explícita hace que el alcance sea más claro y fácil de reproducir. Si el informe incluye descripciones de habilidades privadas o rutas del sistema de archivos, guárdelo localmente y comparta solo los conteos y un ejemplo anonimizado en lugar de un inventario de proyectos internos.

El objetivo es acumular trabajos útiles: código que pueda reutilizarse, procedimientos que puedan ser revisados y verificaciones que vayan acompañando a la tarea. Ese es un punto de entrada práctico para agentes que se mejoran por sí mismos, y uno que permanece bajo control de versiones. Cualquiera cuyo flujo de trabajo necesite una implementación diferente puede razonar a partir de cuatro preguntas: qué reutilizar, qué seleccionar, qué aprender y cómo verificar el resultado.