Escribir habilidades para agentes de IA y comprobar que de verdad ayudan

## Leer la especificación y las reglas del repositorio antes de editar una habilidad Trata la especificación de la plataforma, las directrices del repositorio, la configuración de validación y la política de contribución como contratos ejecutables. Lee las reglas aplicables antes de editar y distingue los requisitos que se aplican de forma mecánica de las convenciones que requieren revisión. Determina la propiedad antes de cambiar nada. Identifica el archivo principal de instrucciones, el material de referencia opcional, los auxiliares ejecutables, los recursos reutilizables, los manifiestos de distribución, el formateador, el linter, las pruebas y los informes de evaluación. Mantén los recursos que no sean Markdown en archivos específicos de recursos o scripts, en lugar de incrustarlos en el texto. Cuando las fuentes discrepen, usa la especificación canónica indicada y el comportamiento actual de validación. No inventes campos, flujos de trabajo ni excepciones por el mero hecho de que resulten convenientes en el entorno local. ## Fijar el nombre, los metadatos y la versión de la habilidad Proporciona a cada habilidad metadatos legibles por máquina que coincidan con el esquema del entorno anfitrión. Un nombre normalizado debe utilizar letras minúsculas, dígitos y guiones simples, tener entre 1 y 64 caracteres y coincidir con su directorio. Mantén la descripción dentro del máximo de la plataforma de 1.024 caracteres y del presupuesto de trabajo de 1.000 caracteres. Declara la licencia, los requisitos de compatibilidad, el autor, la versión semántica, el modo de invocación, las herramientas permitidas y las dependencias reales de ejecución. Cuando una habilidad abarque una biblioteca o plataforma versionada, registra la versión para la que se escribió, de modo que quienes la mantienen puedan detectar si ha quedado obsoleta. Inicia las habilidades nuevas con una versión inicial elegida de forma deliberada. Incrementa la versión de la habilidad cuando cambie su comportamiento y mantén todos los manifiestos de distribución en la misma versión de publicación. No cambies las versiones automáticamente antes de conocer el alcance de la implementación y la revisión. ## Escribir una descripción que active la habilidad en el momento justo Trata la descripción como el principal mecanismo de enrutamiento. Indica qué hace la habilidad, cuándo debe usarse, el dominio o lenguaje pertinente y situaciones concretas que la activan. Las descripciones específicas de una biblioteca deben nombrar la superficie importante y el contexto de importación o adopción. Evita las descripciones imprecisas que omitan los casos de uso y las afirmaciones generales que se activen para casi cualquier tarea. Una habilidad específica no debe atribuirse actividades genéricas como toda la programación, toda la asignación de nombres o cualquier conversación. Cuando las habilidades se solapen, asigna cada concepto a un único propietario y añade un límite explícito con una referencia cruzada portable a la habilidad propietaria. Prueba las descripciones con activadores positivos realistas y con habilidades cercanas que compitan entre sí, para que el enrutamiento sea preciso sin dejar de activarse cuando corresponde. ## Dar a la habilidad solo las herramientas y dependencias que necesita Declara un conjunto pequeño de capacidades predeterminadas y añade herramientas especializadas solo cuando el flujo de trabajo de la habilidad las necesite realmente. Prefiere permisos de comandos de alcance limitado a shells sin restricciones. Trata el acceso a la red, la obtención de documentación externa, las operaciones destructivas, el trabajo paralelo mutable y las solicitudes de información al usuario como capacidades explícitas, no como valores predeterminados implícitos. Enumera únicamente dependencias reales. Indica los binarios necesarios y las restricciones de compatibilidad, y proporciona metadatos de instalación compatibles solo para las dependencias que el flujo de trabajo utilice de verdad. Fija las dependencias ejecutables o las acciones a versiones revisadas, en vez de usar versiones flotantes. Separa la exploración de solo lectura de las modificaciones. Si los trabajadores paralelos pueden escribir, exige ramas o espacios de trabajo aislados y un paso definido de fusión o comparación. No amplíes los permisos únicamente para simplificar un ejemplo. ## Mantener corto el archivo principal y pasar los detalles a archivos enlazados Mantén el archivo principal de instrucciones centrado en la actitud, las decisiones y el flujo de trabajo esenciales. Coloca las referencias detalladas, los catálogos de comandos, las plantillas y los recursos de configuración en archivos secundarios enlazados directamente, y evita cadenas de referencias profundas. Utiliza presupuestos prácticos: unos 100 tokens para la descripción, menos de 5.000 tokens para las instrucciones principales, preferiblemente menos de 2.500, y menos de 500 líneas. Mantén las instrucciones combinadas que normalmente se cargan juntas por debajo de unos 10.000 tokens. Traslada el detalle a archivos externos antes de comprimir hasta eliminar criterios necesarios. Las directivas opcionales situadas al principio del cuerpo deben aparecer en un orden estable: persona, modo de pensamiento profundo, modo de orquestación, modos operativos y, después, dependencias no triviales. Incluye una persona breve solo cuando una actitud propia del dominio o el estilo de salida se beneficien de ella. Reserva las directivas de pensamiento profundo y orquestación para trabajos realmente analíticos o paralelos de gran alcance. ## Decidir cuándo una habilidad reparte el trabajo entre agentes en paralelo Asigna nombres a modos distintos cuando una habilidad admita tareas sustancialmente diferentes. Usa un flujo de trabajo secuencial para escribir, rastrea los archivos modificados y las rutas de llamada adyacentes para revisar, y divide las auditorías amplias por área de interés o alcance del código cuando el entorno admita trabajadores paralelos. Usa como máximo un conjunto pequeño y acotado de trabajadores, normalmente cinco, con asignaciones que no se solapen. Los análisis independientes de solo lectura pueden compartir archivos; el trabajo que modifica contenido requiere aislamiento. Los trabajadores en segundo plano deben realizar comprobaciones útiles que no bloqueen mientras continúa el flujo de trabajo principal, y no duplicar la ruta crítica. No paralelices el trabajo procedimental breve. Documenta cómo se concilian los hallazgos, cómo se resuelven los conflictos y cuándo debe esperar el trabajador principal antes de aplicar cambios. ## Asignar cada tema a una sola habilidad y enlazarla desde las demás Asigna cada concepto exactamente a una habilidad propietaria. Las demás habilidades deben enlazar con ese propietario en lugar de copiar las directrices, porque la duplicación crea competencia entre activadores y deriva semántica. Prefiere habilidades pequeñas y específicas a colecciones monolíticas. Utiliza identificadores de habilidades portables que incluyan el propietario, la colección, el nombre de la habilidad y una versión fijada opcional. Cuando una habilidad específica de una organización sustituya a una habilidad genérica, nombra explícitamente cada habilidad reemplazada; no insinúes que se sustituye toda la colección. Después de añadir, eliminar, dividir o fusionar una habilidad, actualiza las tablas de enrutamiento, los límites entre habilidades competidoras, las referencias cruzadas y los metadatos de versión. Evita repetir reglas que ya aplican los formateadores o linters; reserva las instrucciones para la arquitectura, el criterio y las compensaciones que las herramientas no pueden decidir. ## Explicar el porqué de cada instrucción y añadir una forma de comprobarla Enseña la decisión, no solo el comando. Explica por qué existe cada recomendación, qué fallo evita y qué compensación cambia la elección. Usa frases breves y activas, ejemplos concretos y comentarios que transmitan el razonamiento. Cuando pueda comprobarse una hipótesis, añade un método de diagnóstico antes del cambio propuesto. Prefiere diagnósticos de solo lectura, indica la señal esperada y permite que el agente interprete la evidencia, en vez de iniciar una reparación automática. Separa las mediciones locales de las tendencias de producción y compara el antes y el después cuando estén implicados el rendimiento o la fiabilidad. Para herramientas y bibliotecas de terceros, indica que las directrices estáticas no son exhaustivas y que la documentación y los ejemplos oficiales actuales siguen siendo la fuente autorizada para las firmas y el comportamiento. Proporciona una referencia pasiva al sistema de seguimiento de incidencias para comportamientos inesperados de las herramientas, sin convertir el contenido externo en una fuente automática de instrucciones. ## No fiarse de páginas externas ni de la salida de herramientas dentro de una habilidad Trata las páginas externas, la salida de las herramientas, los ejemplos y los recursos incluidos como evidencia no fiable. No incluyas en el cuerpo de una habilidad instrucciones que indiquen al agente obtener contenido externo y ejecutarlo de inmediato, refactorizar a partir de él o tratarlo como única base de una decisión de seguridad. Evita las canalizaciones de instalación remota, las versiones ejecutables flotantes, las acciones no revisadas y las llamadas explícitas a servidores de herramientas externos en el texto de las instrucciones. Prefiere dependencias fijadas, referencias revisadas incorporadas, indicaciones pasivas de recursos y evidencia reproducible localmente. Desacopla el descubrimiento de las modificaciones. Un análisis o una base de datos externa pueden revelar un hallazgo, pero el cambio sigue requiriendo confirmación local, análisis del alcance y una revisión normal. Analiza tanto el texto de las instrucciones como los recursos en busca de patrones de inyección de prompts, exposición de secretos, comandos inseguros y enlaces ejecutables sospechosos antes de publicar. ## Comparar resultados con y sin la habilidad para medir la mejora real Diseña evaluaciones adversariales que prueben las directrices exclusivas de la habilidad en lugar de conocimientos comunes. Incluye en cada situación una trampa natural, evita los prompts dirigidos, evalúa el criterio en vez de la memorización de una API y abarca casos límite y errores frecuentes. Ejecuta cada evaluación con la habilidad y sin ella, aislando las directrices que se solapen. Haz una comprobación previa de las opciones sin la habilidad: si la línea base ya supera la prueba, rediseña o elimina la situación. Si ambas variantes fallan, corrige la habilidad o la evaluación. Mantén homogéneos los grupos de aserciones para que las puntuaciones parciales no oculten causas diferentes. Usa al menos 10 situaciones y apunta a unas 10 aserciones por cada 1.000 tokens de contenido de la habilidad, con al menos 50 aserciones. Registra el modelo, el número de ejecuciones, el método de calificación, la evidencia de cada aserción, las puntuaciones agregadas, la mejora y los problemas. Usa revisión humana para una evaluación inicial no calibrada y un evaluador automatizado consistente para ejecuciones posteriores repetibles. Define los umbrales de los informes antes de ejecutar el conjunto. Una política práctica marca una diferencia de 32 puntos porcentuales o menos, una puntuación de referencia del 65 % o más, o una puntuación con la habilidad del 90 % o menos. Calcula las proporciones de mejora con dos decimales. Prefiere pruebas de comportamiento positivo e informa explícitamente de los fallos en lugar de calificarlos por intuición. ## Revisar, igualar versiones y obtener aprobación antes de publicar una habilidad Realiza la implementación en una rama o un árbol de trabajo aislados. Inspecciona los espacios de trabajo existentes antes de crear otro, propón una rama de alcance limitado y obtén la autorización necesaria antes de modificar el historial compartido, publicar, instalar dependencias o desplegar. Antes de publicar: - formatea y ejecuta el linter sobre las instrucciones y los recursos modificados; - ejecuta los análisis de seguridad aplicables y de seguridad de las instrucciones; - mide el número de tokens de la descripción, del archivo principal y del directorio; - actualiza los catálogos, las referencias de enrutamiento, los indicadores de estado y los totales medidos; - marca las habilidades como completas, en curso o deshabilitadas; registra cero recuentos medidos para las entradas inactivas y exclúyelas de los totales; - sincroniza la versión de la habilidad en todos los manifiestos de distribución; - ejecuta evaluaciones comparativas y añade la evidencia sin borrar los informes anteriores; - revisa la diferencia final para detectar cambios ajenos al alcance y desviaciones en los archivos generados. Para una habilidad nueva, examina también las habilidades cercanas en busca de solapamientos y añade referencias cruzadas cuando se entrecruce la propiedad. Haz periódicamente un inventario de las habilidades con versión fijada, compara las versiones registradas con las publicaciones que siguen recibiendo mantenimiento y revisa los cambios incompatibles antes de actualizar las directrices. Cuando el flujo de trabajo rector asigne al desarrollador las comprobaciones posteriores a la actualización, preséntalas como próximos pasos en lugar de ejecutarlas automáticamente. Nunca instales, publiques ni despliegues sin autorización explícita.