writing-skills

Visión general de la skill writing-skills

Qué hace writing-skills

La skill writing-skills es una guía de Skill Authoring para crear, editar y validar skills de agentes con un flujo de trabajo guiado por pruebas. Su idea central es simple, pero deliberadamente exigente: tratar la escritura de skills como una especie de TDD aplicado a la documentación de procesos. En lugar de redactar recomendaciones primero y esperar que funcionen, se crean escenarios de presión, se observa cómo falla el agente sin la skill y luego se escribe solo la guía que realmente cambia el comportamiento.

Quién debería usar writing-skills

Encaja mejor con personas que crean skills para Claude Code, configuraciones de agentes estilo Codex o directorios locales de skills similares. Resulta especialmente útil si estás escribiendo skills que deben imponer disciplina, pasos de verificación o flujos de trabajo que los agentes podrían saltarse cuando trabajan con prisa.

El trabajo real que resuelve

La mayoría de usuarios no necesitan “ayuda para escribir markdown”. Lo que necesitan es una forma repetible de producir un SKILL.md que los agentes realmente descubran, sigan y continúen siguiendo cuando la velocidad, la confianza o el coste hundido los empujen a ignorar el proceso. writing-skills está pensado exactamente para ese problema.

Por qué esta skill es distinta de un prompt genérico

Un prompt genérico puede ayudarte a redactar una skill. writing-skills te da un método para demostrar que la skill cambia el comportamiento:

• definir escenarios de presión
• ejecutar pruebas base sin la skill
• redactar la documentación contra modos de fallo observados
• volver a probar y refactorizar para cerrar huecos

Eso la hace más útil para Skill Authoring que una instrucción puntual tipo “escríbeme una skill”.

Requisitos previos y tradeoffs importantes

La principal barrera de adopción es que writing-skills da por hecho que ya entiendes el enfoque TDD del repositorio. La skill exige de forma explícita conocer superpowers:test-driven-development. Si te saltas esa base, las recomendaciones de escritura pueden parecer más estrictas de lo necesario o excesivamente centradas en pruebas.

El tradeoff también es claro: este flujo es más lento que redactar por intuición, pero funciona mucho mejor cuando fallar sale caro o cuando es probable que los agentes racionalicen por qué pueden saltarse la skill.

Cómo usar la skill writing-skills

Contexto de instalación de writing-skills

Este repositorio indica que las skills personales viven en directorios específicos del agente, como ~/.claude/skills para Claude Code y ~/.agents/skills/ para Codex. Si instalas desde el repo obra/superpowers con un gestor de skills, asegúrate de que la skill termine en el directorio que tu agente realmente escanea.

Si vas a revisar manualmente antes de instalar, empieza aquí:

• skills/writing-skills/SKILL.md
• skills/writing-skills/testing-skills-with-subagents.md
• skills/writing-skills/anthropic-best-practices.md
• skills/writing-skills/examples/CLAUDE_MD_TESTING.md

Lee primero estos archivos

Para evaluarla más rápido, sigue esta ruta de lectura:

1. SKILL.md para el flujo principal y su posicionamiento
2. testing-skills-with-subagents.md para ver cómo ejecutar RED/GREEN/REFACTOR sobre skills
3. anthropic-best-practices.md para una guía breve de autoría
4. examples/CLAUDE_MD_TESTING.md para escenarios de presión realistas
5. persuasion-principles.md si tu skill debe resistir racionalizaciones
6. graphviz-conventions.dot y render-graphs.js solo si quieres diagramas

Esa ruta aporta mucha más información que limitarse a hojear la parte superior de SKILL.md.

Qué input necesita writing-skills de tu parte

writing-skills funciona mejor cuando aportas evidencia concreta, no solo un tema. Buenos inputs:

• la skill exacta que quieres crear o revisar
• el comportamiento del agente que quieres cambiar
• ejemplos de fallos sin la skill
• situaciones en las que el agente tiende a saltarse el proceso
• el directorio de destino y la plataforma donde vivirá la skill

Input débil: “Ayúdame a escribir una skill de testing”.

Input fuerte: “Crea una skill que obligue a verificar antes del despliegue en migraciones de base de datos. Actualmente los agentes se saltan las comprobaciones de rollback cuando la solución parece obvia”.

Convierte un objetivo difuso en un prompt útil

Un buen patrón de writing-skills usage es pedir las cuatro partes a la vez:

1. escenarios de presión
2. expectativas de fallo base
3. la estructura de la skill
4. el plan de validación

Ejemplo:

Use writing-skills for Skill Authoring.

Goal: Create a skill for release-checklist enforcement in ~/.claude/skills/release-checks.
Observed failures: agents skip smoke tests when changes look small; they rationalize that CI is enough.
Need:
- 3 pressure scenarios that trigger those shortcuts
- baseline RED expectations without the skill
- a concise SKILL.md outline
- refactor ideas to close loopholes after first test run
Keep it concise and optimized for discoverability.

Esto es mucho más sólido que pedir “un documento de skill pulido”, porque aporta el modelo de fallo que la skill debe corregir.

Flujo de trabajo recomendado para usar writing-skills

Un flujo práctico sería así:

1. Define el comportamiento que quieres imponer
2. Escribe entre 2 y 5 escenarios de presión
3. Prueba al agente sin la skill
4. Registra las racionalizaciones y atajos exactos
5. Redacta SKILL.md solo en función de esos fallos
6. Vuelve a probar con la skill cargada
7. Ajusta el texto allí donde el agente aún se desvíe
8. Elimina cualquier explicación que no haya mejorado el cumplimiento

Ese último paso importa, porque la guía de buenas prácticas incluida insiste en la eficiencia de tokens y en instrucciones concisas.

Cuándo importa más el método guiado por pruebas

Usa writing-skills for Skill Authoring cuando la skill tenga un coste de cumplimiento:

• pruebas adicionales
• verificación más lenta
• comprobaciones de documentación
• requisitos de reinicio o rehacer trabajo
• reglas que chocan con incentivos de velocidad

Este método importa menos en skills puramente de consulta, como chuletas de sintaxis de API, donde los agentes apenas tienen motivos para esquivar el contenido.

Cómo usar la referencia de pruebas con subagentes

testing-skills-with-subagents.md es el documento práctico complementario. Te ayuda a comprobar si tu skill resiste presión real en lugar de sonar bien solo en condiciones tranquilas. Léelo cuando necesites:

• formatos de escenarios
• mapeo RED/GREEN/REFACTOR
• captura de racionalizaciones
• ejemplos de incumplimiento provocado por presión

Si tu primer borrador parece correcto pero la adopción es floja, este archivo suele ser la vía más rápida para mejorarlo.

Usa los escenarios de ejemplo, pero no los copies a ciegas

examples/CLAUDE_MD_TESTING.md es útil porque enseña cómo son de verdad los escenarios de presión: presión de tiempo, coste hundido, autoridad y sesgo de familiaridad. El error es copiar esos escenarios tal cual para skills que no tienen nada que ver.

Lo correcto es adaptar el tipo de presión a tu propio flujo. Por ejemplo:

• skill de despliegue → urgencia y miedo al rollback
• skill de review → exceso de confianza y sesgo hacia la velocidad
• skill de seguridad → racionalización de “solo por esta vez”
• skill de estilo → coste de adopción bajo, así que basta un testing más ligero

Cómo encaja la guía de persuasión en el flujo

persuasion-principles.md no está de relleno; está ahí porque algunas skills fallan incluso cuando el proceso está claro. Si tu skill debe imponer un comportamiento al que los agentes suelen resistirse, una redacción más fuerte puede ayudar. El archivo propone patrones concretos como autoridad, compromiso y anuncios explícitos.

Úsalo con cuidado. La idea no es que la skill “grite” más, sino que las acciones obligatorias sean más difíciles de descartar con excusas.

Reglas de concisión que afectan a la calidad del resultado

Una de las partes más valiosas de este repositorio es el recordatorio de que las skills comparten presupuesto de contexto. writing-skills no te está diciendo que escribas más, sino que escribas únicamente lo que cambia el comportamiento.

Buenas señales:

• disparadores concretos
• acciones obligatorias claras
• ejemplos breves ligados a fallos reales
• contexto mínimo

Malas señales:

• texto motivacional largo
• definiciones repetidas
• historia del proceso
• “best practices” genéricas que Claude ya conoce

Herramientas opcionales de gráficos

El directorio de skills incluye render-graphs.js, que extrae bloques dot de SKILL.md y genera diagramas SVG si graphviz está instalado. Esto es opcional y resulta útil sobre todo cuando tu flujo tiene estados ramificados o puertas de revisión que las personas necesitan inspeccionar visualmente. No hace falta para usar la skill writing-skills, pero puede ayudar a quienes la mantienen a depurar la complejidad del proceso.

Preguntas frecuentes sobre la skill writing-skills

¿Merece la pena instalar writing-skills si ya sé escribir prompts?

Sí, si tu problema es la fiabilidad y no la velocidad de redacción. Los prompts normales pueden generar rápido una skill con buen aspecto. writing-skills merece la pena cuando necesitas confianza en que la skill final cambiará el comportamiento del agente bajo presión.

¿writing-skills es apta para principiantes?

En parte. La redacción en sí es accesible, pero el método da por hecho cierta comodidad con una forma de pensar estilo TDD. Quien empieza en Skill Authoring quizá necesite leer antes el material del repositorio relacionado con TDD o podría confundir este flujo con ceremonia innecesaria.

¿Cuándo encaja mal writing-skills?

Sáltate writing-skills para:

• skills simples solo de referencia
• notas puntuales que no se van a reutilizar
• temas en los que no existe una tentación realista de incumplir la guía
• situaciones en las que no puedes hacer ninguna prueba antes/después

En esos casos, un flujo de autoría más ligero suele ser suficiente.

¿En qué se diferencia writing-skills de las buenas prácticas de skills de Anthropic?

El archivo incluido anthropic-best-practices.md se centra en escribir skills concisas, fáciles de descubrir y eficientes en contexto. writing-skills añade una capa más fuerte orientada al cambio de comportamiento: observar primero los fallos y escribir después solo lo que los corrige. Son guías complementarias, no alternativas.

¿writing-skills requiere herramientas adicionales del repositorio?

No necesitas herramientas importantes para beneficiarte del método. La guía de testing y los ejemplos son los activos principales. El renderizado de gráficos es opcional y no hay scripts de soporte obligatorios para el flujo central de autoría.

¿Puedo usar writing-skills para editar una skill existente?

Sí. De hecho, es uno de sus mejores casos de uso. Si una skill ya existe pero los agentes siguen ignorándola o usándola mal, writing-skills te ayuda a identificar el modo de fallo real, recortar contenido inútil y reescribir las instrucciones que de verdad importan.

Cómo mejorar la skill writing-skills

Empieza por fallos observados, no por documentación ideal

La forma más rápida de mejorar los resultados con writing-skills es aportar evidencia de fallo. Si solo describes el proceso ideal, la salida tiende a volverse genérica. Si aportas atajos reales que tomaron los agentes, la skill resultante se vuelve más precisa y más corta.

Proporciona escenarios de presión más sólidos

Los buenos escenarios crean una tentación real de saltarse la skill. Incluye:

• presión de tiempo
• confianza derivada de experiencia previa
• coste hundido
• presión de autoridad por parte de una persona
• encuadres del tipo “la solución es obvia”

Esas condiciones revelan dónde tus instrucciones son demasiado blandas o demasiado vagas.

Registra las racionalizaciones exactas del agente

No resumas el fallo como “ignoró la skill”. Anota lo que el agente dijo o dio a entender realmente:

• “Este cambio es pequeño”
• “CI lo detectará”
• “Ya conozco este patrón”
• “Leer la skill llevaría demasiado tiempo”

Esas racionalizaciones te dicen qué debe abordar de frente tu prompt revisado de writing-skills usage y el texto final de la skill.

Endurece el texto donde el cumplimiento importe

Si la skill está pensada para imponer comportamientos no opcionales, el lenguaje vago perjudica. Sustituye sugerencias blandas por disparadores explícitos y acciones obligatorias. La guía de persuasión ayuda aquí, pero la mejora principal viene de la especificidad:

• cuándo cargar la skill
• qué hacer primero
• qué no se puede omitir
• qué cuenta como éxito

Elimina contenido que no cambie el comportamiento

Un fallo habitual en la salida de la skill writing-skills es explicar de más. Si un párrafo no mejoró el descubrimiento, el cumplimiento o el testing, córtalo. El archivo de buenas prácticas del repositorio convierte esto en una regla central por una razón.

Itera después del primer resultado satisfactorio

Una primera ejecución “GREEN” no basta si la skill solo funciona en condiciones fáciles. Vuelve a probar con prompts más duros y formulaciones alternativas. Pregúntate si la skill sigue funcionando cuando el agente va con prisa, está seguro de sí mismo o intenta preservar trabajo ya terminado.

Combina writing-skills con un ejemplo específico del repositorio

Si tu equipo tiene un flujo recurrente, incluye un ejemplo trabajado dentro del dominio de la skill objetivo. A menudo eso mejora más la adopción que añadir reglas abstractas. Mantén el ejemplo corto y probado bajo presión, no enciclopédico.

Mejora los prompts pidiendo estructura, no pulido

Cuando invoques writing-skills, pide:

• lista de escenarios
• análisis de fallos
• esquema conciso de la skill
• ediciones para cerrar huecos

No empieces con “hazlo pulido” o “hazlo completo”. Eso normalmente alarga el resultado sin mejorar el cumplimiento.

Comprueba si la skill debería existir siquiera

Una conclusión útil que puede salir del material de la guía writing-skills es descubrir que algunos temas no necesitan una skill. Si el proceso es obvio, de bajo riesgo o poco repetido, una skill puede añadir coste de mantenimiento sin aportar suficiente mejora de comportamiento. Esa también es una conclusión válida y mejora la calidad del repositorio.

Usa writing-skills para refactorizar, no solo para crear

El uso de más valor de writing-skills suele ser refactorizar una skill existente después de verla fallar. Eso convierte el método en ingeniería de comportamiento, no solo en redacción de documentación, y ahí es donde este repositorio aporta su valor más práctico.