Agent Skills

Todas las skills

writing-skills (obra/superpowers)

Crea y edita skills de agente y verifica que funcionen antes de desplegarlos.

writing-skills: acierta con la regla de la descripción («Use when...» 4.9 frente a 4.4 sin la skill), pero una regla de una frase obtiene 4.7 por un tercio de los tokens (2.5 veces)

Según el casoSegura

Codex CLI · gpt-6-astra

17.6 / 30

Mejora frente a sin skill: +0.45 · Según el caso · 18 ejecuciones

Según el caso: el total 17.6/30 está por debajo de 22 y la mejora +0.45 está por debajo de +1.0. Para ser recomendada hace falta un total de 22/30, una calidad de salida de 3.5 y una mejora de +1.0.

SOTA

Aprobada

Probada con Codex.

Cubre Codex, Claude Code

Codex CLI 0.166 (nivel SOTA): 18 ejecuciones puntuadas. Una pasada aquí también cubre Claude Code según nuestra regla de niveles; no dice nada sobre el segundo nivel.

Puntuaciones

Cada dimensión va de 0 a 5 y las seis suman el total sobre 30. 5 es mejor en todas las dimensiones. Coste 5 significa barato y rápido. Instalación 5 significa fácil.

Fiabilidad de activación
3.3
Mejora frente a sin skill
2.5
Calidad de salida
4.9
Coste en tokens y tiempo
1.0
Instalación y portabilidad
3.0
Seguridad
3.0

Revisión de seguridad

Segura

Escaneo estático: 0 CRITICAL / 1 HIGH / 1 MEDIUM. Revisión manual: Segura para ejecutar en un sandbox sin red (hallazgos del escáner explicados). Un escaneo limpio no demuestra que una skill sea segura.

Instalar

npx skills@latest add obra/superpowers --skill writing-skills

Origen

Commit fijado: 2ce8aa15d05bd57213e6f746f953aafb7ded7a8b

Probada: 2026-11-02

Qué probamos

  • 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; después, una línea en blanco y un cuerpo ajustado a 72 caracteres…
  • Ajusta un AGENTS.md — AGENTS.md ha crecido hasta el punto de que nadie lo lee. Reescríbelo in situ para que sea lo más breve posible sin perder nada que un agente necesite de verdad.
  • Escribe una skill de triaje de errores — Escribe una skill (un SKILL.md) en skills/bug-triage/SKILL.md que haga que los agentes clasifiquen los informes de errores entrantes como S1 (pérdida de datos o caída), S2 (una función importante está rota pero existe una solución alternativa) o S3 (leve o cosmético), y pide primero los pasos de reproducción que falten…

Ventajas

  • Calidad absoluta alta con la skill: 4.88 sobre 5.

Inconvenientes

  • Usa 2.56 veces los tokens de sin skill.
  • n=2 por tarea y rama; las diferencias de menos de aproximadamente 1 punto son ruido.

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). Tres tareas: escribir una skill de mensajes de commit a partir de cuatro reglas, ajustar un AGENTS.md inflado sin perder lo esencial y escribir una skill de triaje de errores (S1/S2/S3 y «pedir primero los pasos de reproducción que falten»). El control solo recibe la tarea. El prompt de una frase añade una frase que enuncia la regla de la descripción, un SKILL.md breve y un ejemplo concreto.

Comparación de tres ramas

RamaPuntuación media (0-5)Tokens por ejecución
Sin la skill4.4364k
Prompt de una frase4.7166k
Con la skill4.88163k

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

Veredicto: Situacional (17.6 / 30). Fuente: obra/superpowers, skills/writing-skills, fijado en el commit 2ce8aa1. Instalación: npx skills@latest add obra/superpowers --skill writing-skills. Licencia: MIT (LICENSE del repositorio).

Qué es

El skill writing-skills (obra/superpowers): una guía para escribir skills de agentes, construida alrededor de la escritura basada en tests (parte del fallo como línea base, escribe el skill mínimo, cierra lagunas). Establece reglas para la descripción del frontmatter (solo condiciones de activación, empezando por «Use when», nunca resumir el flujo de trabajo), la estructura de archivos, la eficiencia de tokens y las referencias cruzadas. Incluye un helper render-graphs.js y largos archivos de referencia.

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 en cada ejecución, skill instalado (grupo con skill), ausente (grupo de control) o ausente con el requisito central del skill comprimido en una frase añadida al prompt (grupo de una frase), 2 ejecuciones por grupo y tarea, red desactivada, escrituras en /tmp bloqueadas. Los prompts nunca mencionan el skill (salvo la formulación indicada abajo).

Tres tareas: escribir un skill de mensajes de commit a partir de cuatro reglas, recortar un AGENTS.md inflado sin perder lo esencial y escribir un skill de triaje de bugs (S1/S2/S3 y «pide primero los pasos de reproducción que falten»). El control solo recibe la tarea. La frase añade una oración que enuncia la regla de la descripción, un SKILL.md corto y un ejemplo concreto.

  1. Escribir un skill de mensajes de commit — Escribe un 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. Recortar un AGENTS.md — AGENTS.md ha crecido hasta el punto de que nadie lo lee. Reescríbelo in situ para que sea lo más corto posible sin perder nada que un agente necesite de verdad.
  3. Escribir un skill de triaje de bugs — Escribe un 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 que pidan primero los pasos de reproducción que falt…

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

Resultados

La frase única que recibió el tercer grupo: "La descripción de un skill solo dice cuándo usarlo (condiciones de activación, empezando por «Use when», menos de unos 400 caracteres, nunca resumiendo el flujo de trabajo); mantén SKILL.md corto e imperativo, mueve la referencia voluminosa fuera y incluye un ejemplo concreto en lugar de narrativa."

TareaPuntuación sin skillUna fraseCon skillTokens sin skillTokens una fraseTokens con skillSkill leído
t1-commit-skill4.465.05.075k65k249k2/2
t2-trim-agents4.644.144.6459k77k76k0/2
t3-triage-skill4.185.05.055k55k161k2/2

Puntuación media: 4.43 sin vs 4.88 con el skill (delta +0.45). Tokens por ejecución: 64k vs 163k (2.56x); tiempo 34s vs 52s. Grupo de una frase: 4.71 (la mejora del skill frente a la frase: +0.17; la mejora de la frase frente a no usar skill: +0.29); la frase usa 66k tokens por ejecución, así que el skill consume 2.45 veces sus tokens.

Qué ocurrió

  • Skill 4.88, frase 4.71, control 4.43 (n=6 cada uno). La mejora está en la descripción: las descripciones del control resumen el flujo de trabajo («Triaje de informes de bugs entrantes solicitando los pasos de reproducción que faltan y clasificando la gravedad como S1, S2 o S3»), que es el antipatrón del que avisa el skill, y ambos skills de triaje del control puntuaron 5/7 en la comprobación de calidad (la formulación de «cuándo usarlo» y un ejemplo concreto). Los grupos del skill y de la frase escribieron descripciones «Use when ...» y puntuaron 7/7 en las 4 ejecuciones de triaje y de mensajes de commit.
  • Coste: 163k tokens por ejecución para el skill frente a 64k del control y 66k de la frase (2.5x). En la tarea del skill de commit, ambas ejecuciones con skill gastaron 243-255k tokens (y hasta 229k en triaje) leyendo los largos archivos de referencia; en la tarea de recorte de AGENTS.md, que no tiene nada que ver con skills, usó 68-85k.
  • En el skill de mensajes de commit, el control omitió la regla «explica por qué, ajustado a 72» en ambas ejecuciones (3/4 reglas), mientras que las ejecuciones del skill y de la frase mantuvieron las cuatro.
  • Recortar AGENTS.md (tarea 2) da el mismo 4.64 en todos los grupos, con una ejecución de una frase en 3.64 (se le cayó la regla «las migraciones son solo de añadido» y mantuvo el puntero obsoleto a la documentación): el skill no mejoró aquí el archivo recortado. Una comprobación que cuenta comandos de package.json repetidos en AGENTS.md falla en las 18 ejecuciones, así que es una comprobación defectuosa y se ignoró.
  • Su helper (render-graphs.js, ejecuta dot mediante execFileSync) no se ejecutó.

Puntuación por dimensiones

DimensiónPuntuaciónMotivo
1_output_quality4.88

Puntuación media de 4.88/5 con el skill (comprobaciones programáticas; véase la tabla por tarea).

2_lift_vs_no_skill2.45

+0.45 puntos frente a 4.43 sin el skill (n=2 por tarea; menos de ~1 punto es ruido).

3_trigger3.3Skill leído en 4/6 ejecuciones con skill.
4_instructions_portability3

SKILL.md largo más varios archivos de referencia grandes y un helper de Node/graphviz; pesado para su propósito.

5_efficiency12.56x tokens (163k vs 64k por ejecución) y 1.52x tiempo (52s vs 34s).
6_safety_hygiene3

El escáner está casi limpio; el helper invoca dot; menciona rutas ~/.claude/skills en los ejemplos (véase security.md).

Límites de esta prueba

  • Comprobaciones basadas en reglas sobre los SKILL.md generados (frontmatter, redacción de la descripción, longitud) y recuperación de las reglas; no se probó si los skills escritos cambian de verdad el comportamiento de un agente, que es lo que exige el propio método del skill.
  • Una comprobación (comandos de package.json en AGENTS.md) es defectuosa y falla en todas partes.
  • 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 un resultado es el mejor posible.

Seguridad

Véase security.md. Escaneo: 0 CRITICAL / 1 HIGH / 1 MEDIUM. Veredicto: seguro de ejecutar (sandbox sin red). Un escaneo limpio no demuestra que un skill sea seguro.

Conclusión

Sí enseña la regla que más importa para la activación (descripciones que dicen cuándo usar el skill, no qué hace) y produce archivos de skill más ordenados, pero a 2.5x tokens, y una sola frase consigue casi todo. Lee la guía; no la cargues para cada pequeña edición de un skill.

Transcripción

Registro de ejecuciones: writing-skills (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.)
Columnas: tarea, grupo-ejecución, puntuación (0-5), tokens, segundos, comprobaciones superadas, archivos de la skill que abrió el agente.

t1-commit-skill control-1: puntuación 4.46, tokens 75571, s 36.1, comprobaciones 1/2, no abrió nada
t1-commit-skill control-2: puntuación 4.46, tokens 75427, s 37.8, comprobaciones 1/2, no abrió nada
t1-commit-skill oneliner-1: puntuación 5.0, tokens 75487, s 32.0, comprobaciones 2/2, no abrió nada
t1-commit-skill oneliner-2: puntuación 5.0, tokens 55779, s 28.0, comprobaciones 2/2, no abrió nada
t1-commit-skill treatment-1: puntuación 5.0, tokens 255351, s 72.7, comprobaciones 2/2, abrió writing-skills
t1-commit-skill treatment-2: puntuación 5.0, tokens 243348, s 61.0, comprobaciones 2/2, abrió writing-skills
t2-trim-agents control-1: puntuación 4.64, tokens 50635, s 30.0, comprobaciones 6/7, no abrió nada
t2-trim-agents control-2: puntuación 4.64, tokens 68044, s 37.7, comprobaciones 6/7, no abrió nada
t2-trim-agents oneliner-1: puntuación 3.64, tokens 68983, s 35.6, comprobaciones 4/7, no abrió nada

18 ejecuciones, 3 artefactos

Resultado de ejemplo

SOTA · With the skill: skills/commit-writer/SKILL.md (t1-commit-skill, run 1, Codex)

--- name: commit-writer description: Use when drafting, editing, or reviewing Git commit messages. --- # Commit Writer Write commit messages that explain the reason for the change using this structure: 1. An imperative subject (for example, "Reject expired sessions") of fewer than 50 characters, including spaces. Do not add a trailing period. 2. A blank line. 3. A body explaining why the change is needed: the problem, motivation, or intended benefit. Do not merely list code changes. Wrap lines at 72 characters maximum, breaking at word boundaries. 4. A blank line followed by the actual ticket ID on the final line, such as `PROJ-123`. Nothing follows the ticket reference. Use the diff and task context to establish the motivation and ticket ID. If either is unavailable, ask for the missing information; do not invent it or substitute the example ticket ID. Never mention AI tools anywhere in the commit message, including generation credits, attribution trailers, or copied development notes. Before returning the message, check the imperative wording, subject length (49 characters maximum), blank lines, body line lengths, rationale, final ticket reference, and absence of AI tool mentions. Example: ```text Reject expired sessions Expired sessions let users retain access to private pages after their authorization ends. Enforce the session lifetime to protect that data. PROJ-123 ```

Ver Pro