writing-skills

Descripción general

Qué hace la skill writing-skills

La skill writing-skills es una meta-skill para personas que redactan, refinan y prueban otras skills para agentes como Claude. Adapta el enfoque clásico de Test-Driven Development (TDD) a la documentación de procesos, de modo que tus skills estén:

• Basadas en escenarios de presión reales
• Verificadas frente a fallos reales de agentes
• Refinadas para cerrar escapatorias y resistir racionalizaciones

Usas writing-skills para diseñar skills que los agentes puedan descubrir, seguir y mantener incluso bajo presión de tiempo, sesgo de coste hundido o incentivos en conflicto.

Para quién es writing-skills

Usa la skill writing-skills si eres:

• Un desarrollador que crea skills para Claude u otros agentes similares
• Un team lead que estandariza flujos de trabajo en ~/.claude/skills o ~/.agents/skills/
• Un responsable de documentación a cargo de skills que deben cumplirse, no solo leerse
• Un tester que valida que las skills realmente cambian el comportamiento del agente antes del despliegue

No está centrada en el estilo de redacción genérico. Se ocupa específicamente de redactar skills de agentes eficaces y testeables.

Problemas que esta skill te ayuda a resolver

writing-skills está diseñada para situaciones en las que:

• Los agentes ignoran o siguen solo parcialmente tus skills bajo presión
• No tienes claro si una nueva skill cambia de forma significativa el comportamiento
• Necesitas una forma repetible de probar skills con subagentes antes del despliegue
• Quieres alinearte con las mejores prácticas de redacción de skills de Anthropic sin tener que adivinar
• Necesitas visualizar y comunicar flujos de trabajo complejos de skills usando Graphviz

Si tienes skills que funcionan más como historias puntuales o notas sueltas, writing-skills te ayuda a transformarlas en guías de referencia reutilizables y testeables.

Cuándo writing-skills es, y no es, una buena opción

Buena opción:

• Skills que aplican disciplina (TDD, verificación, checklists de revisión)
• Skills con un coste de cumplimiento real (tiempo, retrabajo, envíos retrasados)
• Skills que los agentes podrían intentar saltarse ("solo esta vez")
• Skills donde quieres una mejora medible en las tasas de cumplimiento

No es buena opción:

• Skills puramente de referencia (p. ej., sintaxis de APIs, chuletas básicas de lenguaje)
• Skills que intencionalmente no tienen reglas que se puedan violar
• Notas ligeras donde no necesitas pruebas al estilo TDD ni escenarios de presión

Si solo necesitas una nota rápida e informal para una conversación puntual, probablemente no necesitas writing-skills. Si quieres una skill que sobreviva a la presión de producción, sí la necesitas.

Cómo usarla

Instalación y configuración básica

Para instalar la skill writing-skills en un entorno con soporte para skills:

npx skills add https://github.com/obra/superpowers --skill writing-skills

Este comando descarga la skill writing-skills desde el repositorio obra/superpowers y la registra junto con tus otras skills.

Las skills personales suelen vivir en directorios específicos del agente, por ejemplo:

• ~/.claude/skills/ para Claude Code
• ~/.agents/skills/ para Codex u otros agentes similares

Coloca o verifica el directorio writing-skills bajo la raíz de skills correspondiente para que tu agente pueda cargar SKILL.md y los archivos relacionados cuando los necesite.

Archivos y carpetas clave en writing-skills

Una vez instalada, abre primero estos archivos para entender y aplicar el flujo de trabajo:

• SKILL.md – Definición principal de la skill y descripción general de writing-skills, incluido el mapeo de TDD a skills.
• anthropic-best-practices.md – Guía al estilo oficial sobre cómo escribir skills concisas, fáciles de descubrir y eficaces para Claude.
• testing-skills-with-subagents.md – Guía práctica para construir y ejecutar escenarios de presión y campañas de pruebas.
• persuasion-principles.md – Patrones de persuasión basados en evidencia para mejorar el cumplimiento de tus skills por parte del agente.
• graphviz-conventions.dot – Convenciones para representar flujos de trabajo y procesos de skills como diagramas Graphviz.
• render-graphs.js – Script auxiliar que extrae bloques ```dot de SKILL.md y los renderiza como diagramas SVG.
• examples/CLAUDE_MD_TESTING.md – Ejemplo completo y desarrollado de una campaña de pruebas para variantes de documentación CLAUDE.md.

Estos archivos se combinan para ofrecerte un flujo completo de autoría + pruebas + visualización de skills.

Flujo de trabajo central: TDD para skills

writing-skills aplica conceptos de TDD directamente a la redacción de skills. El bucle de alto nivel es:

1. Escribe casos de prueba (escenarios de presión)

   • Diseña situaciones realistas en las que un agente podría racionalizar saltarse o flexibilizar tu proceso previsto.
   • Usa subagentes para ejecutar estos escenarios y capturar su comportamiento.

2. Ejecuta pruebas de línea base y observa cómo fallan

   • Ejecuta los escenarios sin tu skill nueva o actualizada cargada.
   • Registra dónde falla el agente: qué omite, racionaliza o entiende mal.

3. Escribe o refina la skill

   • Redacta o actualiza SKILL.md y los archivos de apoyo necesarios para abordar los fallos concretos que observaste.
   • Usa un lenguaje conciso e imperativo que encaje con las limitaciones de la ventana de contexto.

4. Vuelve a ejecutar las pruebas con la skill cargada

   • Repite los mismos escenarios, esta vez con tu skill activa.
   • Verifica que el agente ahora descubre, anuncia y sigue la skill.

5. Refactoriza para cerrar escapatorias

   • Identifica racionalizaciones o cumplimiento parcial que aún persistan.
   • Aplica principios de persuasión (autoridad, compromiso, etc.) para reforzar la adherencia.
   • Recorta tokens innecesarios para mantener la skill concisa.

Este bucle refleja ROJO → VERDE → REFACTORIZAR en el TDD clásico, pero aplicado a documentación y aplicación de procesos en lugar de código.

Uso de anthropic-best-practices.md para mejorar tus skills

El archivo anthropic-best-practices.md ofrece pautas específicas para el ecosistema Claude, entre ellas:

• Por qué las skills concisas mejoran el uso del contexto y el rendimiento del modelo
• Cómo y cuándo Claude carga SKILL.md y otros archivos en la ventana de contexto
• Cómo redactar secciones de la skill que justifiquen su coste en tokens

Puedes usar este archivo como checklist al revisar tus propias skills:

• Elimina explicaciones que Claude ya conoce
• Concéntrate en patrones, reglas y flujos de trabajo accionables
• Estructura las skills para que las instrucciones más importantes aparezcan pronto y de forma clara

Integrar estas prácticas con el bucle TDD de writing-skills te ayuda a garantizar que tus skills sean a la vez fáciles de descubrir y eficientes.

Probar skills con subagentes

El archivo testing-skills-with-subagents.md amplía el enfoque TDD con un método de prueba concreto:

• Diseña escenarios que imiten la presión real de producción (tiempo, coste hundido, velocidad vs calidad).
• Ejecútalos con subagentes que representen cómo se comportaría tu agente principal.
• Captura fallos y racionalizaciones en formatos estructurados.

Esto es especialmente útil para skills que:

• Imponen buenas prácticas que consumen tiempo (p. ej., escribir pruebas primero)
• Compiten con objetivos de corto plazo (p. ej., enviar más rápido vs verificar a fondo)
• Deben resistir cuando las personas piden explícitamente atajos

Siguiendo los patrones de prueba de este archivo, puedes verificar tus skills bajo presión antes de que lleguen a usuarios finales.

Aplicar principios de persuasión al diseño de skills

persuasion-principles.md resume principios psicológicos que también afectan al comportamiento de los LLM, como:

• Autoridad – Lenguaje claro y no negociable para reglas críticas de seguridad
• Compromiso – Exigir que los agentes anuncien cuándo usan una skill y se mantengan en el camino elegido
• Escasez y otros – Usados con cuidado para priorizar prácticas críticas

En la práctica, puedes:

• Usar un tono más imperativo en los pasos que no son opcionales
• Pedir al agente que indique explícitamente: "I am using [Skill Name] now" cuando una skill esté en juego
• Diseñar checklists que obliguen a completar pasos en lugar de fomentar una lectura pasiva

El objetivo no es manipular, sino garantizar que las prácticas críticas se sigan de forma consistente.

Visualizar flujos de skills con Graphviz

Las skills complejas suelen beneficiarse de una representación visual. writing-skills incluye:

• graphviz-conventions.dot – Estructura y estilo sugeridos para los diagramas
• render-graphs.js – Script de Node.js que extrae bloques ```dot de SKILL.md y los convierte en archivos SVG.

Uso básico del renderer:

./render-graphs.js path/to/your/skill
# o
./render-graphs.js path/to/your/skill --combine

Esto te ayuda a:

• Comunicar el flujo de una skill a colaboradores humanos
• Detectar lagunas o bucles en el diseño de tu proceso
• Mantener documentación y visuales sincronizados incrustando diagramas como bloques de código ```dot en SKILL.md.

Adaptar writing-skills a tu entorno

El repositorio describe patrones que debes adaptar, no copiar al pie de la letra. Al integrar writing-skills en tu propio flujo de trabajo:

• Mantén el bucle TDD, pero ajusta los formatos de escenarios a tus herramientas
• Usa tu propia estructura de directorios si lo necesitas, preservando límites claros entre skills
• Integra campañas de pruebas en tus procesos existentes de CI, revisión o lanzamiento

El objetivo es un flujo de autoría repetible y guiado por pruebas que encaje con tu equipo y tu infraestructura.

Preguntas frecuentes

¿Cuándo debería cargar la skill writing-skills?

Usa writing-skills siempre que estés:

• Creando una skill nueva que vivirá en ~/.claude/skills u otros directorios similares
• Editando una skill existente que ha empezado a degradarse o a ser ignorada
• Preparando una skill para desplegarla a tu equipo o para uso en producción
• Diseñando o ejecutando una campaña de pruebas de skills con subagentes

Si solo estás experimentando en una sesión efímera y única, puede que no necesites todo el flujo de trabajo de writing-skills.

¿Necesito entender TDD antes de usar writing-skills?

Sí. La skill requiere explícitamente familiaridad con superpowers:test-driven-development. writing-skills parte de que ya conoces el ciclo ROJO → VERDE → REFACTORIZAR y lo aplica a la documentación:

• ROJO: Ejecutar escenarios sin la skill y capturar los fallos
• VERDE: Añadir o refinar la skill para que esos escenarios pasen
• REFACTORIZAR: Mejorar claridad, cerrar escapatorias y reducir el coste en tokens

Si TDD es nuevo para ti, carga y estudia primero la skill relacionada con TDD.

¿Cómo ayuda writing-skills con el comportamiento específico de Claude?

writing-skills está diseñada para entornos como Claude, y el repositorio incluye anthropic-best-practices.md con pautas alineadas con la documentación de Anthropic. Juntos, te ayudan a:

• Escribir skills que Claude pueda descubrir de forma fiable
• Respetar la ventana de contexto y el presupuesto de tokens
• Estructurar archivos SKILL para que Claude los cargue y use de forma eficaz

Esto hace que writing-skills sea especialmente útil si estás construyendo una biblioteca de skills para Claude.

¿Puedo usar writing-skills para skills no técnicas o sin código?

Sí, siempre que la skill describa un proceso repetible que pueda probarse mediante escenarios. Algunos ejemplos:

• Checklists de respuesta a incidentes
• Flujos de trabajo de revisión de código
• Procesos de revisión o aprobación de documentación

La clave es que el proceso tenga:

• Reglas claras que los agentes puedan seguir o violar
• Consecuencias reales cuando se omiten pasos
• Escenarios en los que puedas probar de forma significativa el cumplimiento

Contenido puramente descriptivo o narrativo no encaja bien con este enfoque.

¿Para qué sirve el archivo examples/CLAUDE_MD_TESTING.md?

examples/CLAUDE_MD_TESTING.md es un ejemplo completo que muestra cómo:

• Diseñar escenarios realistas (presión de tiempo, coste hundido, autoridad vs velocidad)
• Ejecutarlos contra distintas variantes de documentación CLAUDE.md
• Comparar qué tan bien cada variante conduce al descubrimiento y uso de la skill

Úsalo como plantilla al diseñar tus propias campañas de pruebas de skills.

¿En qué se diferencia una skill de una historia o caso práctico?

En el modelo de writing-skills:

• Una skill es una guía de referencia reutilizable que codifica patrones, herramientas o flujos de trabajo probados.
• Una historia o caso práctico describe cómo resolviste un problema concreto una sola vez.

writing-skills te ayuda a pasar de historias puntuales a skills generalizadas y testeables que futuros agentes puedan encontrar y aplicar en nuevas situaciones.

¿Qué pasa si mi skill es larga? ¿Importa la longitud?

La longitud importa por la ventana de contexto. anthropic-best-practices.md explica por qué las skills concisas tienen mejor rendimiento:

• Solo se carga el metadato al inicio, pero una vez que se lee SKILL.md, cada token compite con el historial de la conversación.
• Deberías preguntarte constantemente si cada sección se gana su lugar.

writing-skills te anima a:

• Recortar explicaciones redundantes
• Mover ejemplos a archivos de apoyo cuando sea necesario
• Centrar SKILL.md en el proceso y las reglas centrales que hacen que las pruebas pasen

¿Cómo sé que writing-skills está funcionando?

Verás impacto cuando:

• Skills que antes se ignoraban bajo presión ahora se siguen
• Las skills nuevas vienen con escenarios y pruebas explícitas, no solo con texto
• Puedes señalar diferencias antes/después en el comportamiento de los agentes en escenarios concretos

Si no puedes mostrar diferencias entre el comportamiento con y sin una skill, revisa de nuevo el bucle TDD y las guías de persuasión y pruebas que proporciona writing-skills.