writing-for-agents (mattpocock/skills)

Reseña

Codex CLI 0.166 (gpt-6-astra, razonamiento bajo) en un PC de pruebas Windows dedicado, un proyecto temporal nuevo y HOME/TMPDIR/cachés temporales en cada ejecución, skill instalada (grupo con skill), ausente (control) o ausente con el requisito central de la skill comprimido en una frase añadida al prompt (grupo del prompt de una frase), 2 ejecuciones por grupo y tarea, red desactivada, escrituras en /tmp bloqueadas. Los prompts nunca mencionan la skill (salvo la redacción indicada abajo). Las mismas tres tareas que en writing-skills: escribir una skill de mensajes de commit a partir de cuatro reglas, ajustar un AGENTS.md inflado sin perder lo esencial (5 reglas reales enterradas entre relleno, duplicados y una referencia obsoleta) y escribir una skill de triaje de errores. El control solo recibe la tarea. El prompt de una frase da las reglas principales de la skill en una sola frase. Los SKILL.md generados se puntúan con la misma lista de 7 puntos que writing-skills, que espera una descripción del estilo «Use when ...»; el consejo de esta propia skill es «trigger first», no esa redacción literal.

Comparación de tres ramas

Medido con Codex CLI en 18 ejecuciones, puntuado con comprobaciones basadas en reglas y sin juez LLM. Total 24.9 / 30, veredicto Según el caso.

Veredicto: Según el caso (24.9 / 30). Fuente: mattpocock/skills, skills/productivity/writing-for-agents, fijada en el commit 4ae2317. Instalación: npx skills@latest add mattpocock/skills --skill writing-for-agents. Licencia: MIT (LICENSE del repositorio).

Qué es

La skill writing-for-agents (mattpocock/skills): orientación para escribir instrucciones que leen los agentes: poner el disparador primero en una descripción con un disparador por cada rama distinta, mantener cada significado en una única fuente de verdad, eliminar las instrucciones inútiles que el modelo ya sigue y las líneas que repiten el entorno (scripts, configuración), terminar cada paso con un criterio de finalización comprobable y mantener los archivos cortos.

Cómo lo probamos

Codex CLI 0.166 (gpt-6-astra, razonamiento bajo) en un PC de pruebas Windows dedicado, un proyecto temporal nuevo y HOME/TMPDIR/cachés temporales por ejecución, skill instalada (tratamiento) o ausente (control) o ausente con el requisito central de la skill comprimido en una frase añadida al final del prompt (grupo de una frase), 2 ejecuciones por grupo y tarea, red desactivada, escrituras en /tmp bloqueadas. Los prompts nunca mencionan la skill (salvo la formulación indicada abajo).

Las mismas tres tareas que para writing-skills: escribir una skill de mensajes de commit a partir de cuatro reglas, ajustar un AGENTS.md inflado sin perder lo esencial (5 reglas reales enterradas entre relleno, duplicados y un puntero obsoleto) y escribir una skill de triaje de bugs. El control solo recibe la tarea. La frase única da las reglas principales de la skill en una frase. Los archivos SKILL.md generados se puntúan con la misma lista de 7 puntos que writing-skills, que espera una descripción al estilo «Use when ...»; el consejo de esta skill es «disparador primero», no esa redacción literal.

1. Escribe una skill de mensajes de commit — Escribe una skill (un SKILL.md) en skills/commit-writer/SKILL.md que haga que nuestros agentes de código escriban mensajes de commit siguiendo estas reglas: el asunto va en imperativo, con menos de 50 caracteres y sin punto final; luego una línea en blanco y un cuerpo ajustado a 72 caracteres…
2. Ajusta un AGENTS.md — AGENTS.md ha crecido hasta el punto de que nadie lo lee. Reescríbelo en el sitio para que sea lo más corto posible sin perder nada que un agente necesite de verdad.
3. Escribe una skill de triaje de bugs — Escribe una skill (un SKILL.md) en skills/bug-triage/SKILL.md que haga que los agentes clasifiquen los informes de bugs entrantes como S1 (pérdida de datos o caída), S2 (una función importante está rota pero hay una solución alternativa) o S3 (menor o cosmético), y pidan lo antes posible los pasos de reproducción que falten…

La puntuación es programática (tests ocultos / detección de problemas sembrados / comprobaciones de restricciones / renderizado + OCR cuando corresponde), 0–5 por ejecución. Ningún juez LLM decidió ninguna puntuación.

Resultados

La frase única que recibió el tercer grupo: "Escribe para agentes: pon el disparador primero en la descripción con un disparador por cada rama distinta, mantén cada significado en una única fuente de verdad, elimina las instrucciones inútiles que el modelo ya sigue y las líneas que solo repiten el entorno (scripts, configuración), termina cada paso con un criterio de finalización comprobable y mantén el archivo corto."

Puntuación media: 4.17 sin vs 4.52 con la skill (delta +0.35). Tokens por ejecución: 70k vs 88k (1.27x); tiempo 39s vs 37s. Grupo de una frase: 4.63 (la ganancia de la skill sobre la frase única: -0.11; la ganancia de la frase única sobre sin skill: +0.46); tokens de la frase única 76k por ejecución, así que la skill cuesta 1.17x la frase única.

Qué ocurrió

• Medias: skill 4.52, una frase 4.63, control 4.17 (n=6 cada uno). La ganancia clara está en la tarea de AGENTS.md: skill 5.00 en ambas ejecuciones (las 5 reglas esenciales conservadas, relleno eliminado, puntero obsoleto corregido, duplicados fusionados) frente a 4.29 del control y 4.71 de una frase. Ambas ejecuciones de una frase borraron la regla «las migraciones son solo de adición» al recortar; las de la skill sí la conservaron.
• En las dos tareas de escribir skills, la skill no lo hace mejor que el control (4.18-4.59 frente a 4.06-4.18): en las 4 ejecuciones de tratamiento de esas tareas, la descripción era un resumen del flujo o no decía cuándo usar la skill («Triage incoming bug reports by requesting missing reproduction steps and classifying severity...», idéntica al control), así que la lista de comprobación de 7 puntos dio 5/7 o 6/7 igual que al control. Las ejecuciones de una frase escribieron descripciones con disparador («When an incoming bug report lacks reproduction steps, request them first...»).
• El control omitió la regla «cuerpo ajustado a 72, explicar por qué» en ambas ejecuciones de la skill de commit (3/4 reglas); la skill y la frase única conservaron las cuatro.
• Coste: 88k tokens por ejecución con la skill frente a 70k del control y 76k de una frase (1.26x, 1.16x). Las ejecuciones de tratamiento copian 4 archivos por ejecución en el proyecto.
• Una comprobación que cuenta los scripts de package.json repetidos en AGENTS.md falla solo en las 2 ejecuciones de control aquí (3 coincidencias), en línea con la regla de la skill «no repitas el entorno».

Puntuaciones por dimensión

Límites de esta prueba

• Comprobaciones basadas en reglas, en parte tomadas de la prueba de writing-skills: la lista de comprobación de 7 puntos para skills premia la redacción «Use when», que esta skill no exige, lo que la subestima en las dos tareas de escribir skills.
• Nadie probó si las skills escritas o el AGENTS.md recortado cambian de verdad el comportamiento de un agente.
• n=2 por celda.
• n = 2 por grupo y tarea: las diferencias de menos de ~1 punto son ruido.
• La puntuación basada en reglas mide lo que las comprobaciones pueden ver; no puede juzgar el gusto ni si el resultado es el mejor posible.

Seguridad

Consulta security.md. Escaneo: 0 CRITICAL / 0 HIGH / 0 MEDIUM. Veredicto: segura de ejecutar (sandbox sin red). Un escaneo limpio no demuestra que una skill sea segura.

Conclusión

Merece la pena para compactar un archivo de instrucciones (conservó todas las reglas reales que un prompt de una frase dejó caer); por lo demás, no es mejor que el modelo base para escribir skills nuevas, a cambio de 1.26x tokens.