readme-writer

Escribe o reescribe un README de proyecto que convierta visitantes en usuarios y colaboradores - una frase de presentación, insignias, un inicio rápido de 60 segundos, ejemplos reales, características, FAQ, contribuciones y licencia - y lo revisa en busca de secciones faltantes, enlaces relativos rotos, anclajes del índice que no coincidan con ningún encabezado, texto alternativo faltante y un primer bloque de código tardío. Úsalo cuando el usuario pida escribir, mejorar, revisar o reestructurar un README, diga que nadie entiende o da estrellas al proyecto, o esté preparando un lanzamiento de código abierto.

¿Qué es readme-writer?

Esta habilidad para agentes de IA (como Claude Code, Cursor o Codex) automatiza la redacción, reescritura y revisión de archivos README.md para proyectos de software. Su objetivo principal es transformar un README genérico o deficiente en una herramienta de conversión que lleve al visitante desde '¿qué es esto?' hasta ejecutar su primer comando en menos de un minuto, aumentando así las estrellas, instalaciones y contribuciones. El agente recopila hechos del proyecto (manifiesto, CLI, documentación existente), aplica una estructura probada (título, insignias, presentación, inicio rápido, ejemplos, FAQ, contribución, licencia), y utiliza un linter especializado que verifica reglas como la presencia de un título H1 único, un bloque de código antes de la línea 60, enlaces relativos sin rotura, anclajes correctos del índice, y texto alternativo en imágenes. Soporta múltiples ecosistemas (Python, Node, PHP, Rust) y trabaja con cualquier proyecto que tenga un manifiesto, archivo de configuración o CLI. El flujo de trabajo incluye preguntar al usuario solo lo que el código no puede revelar (público objetivo, diferenciador clave) y finaliza con un resumen del lint y una lista de hechos no verificados que el usuario debe completar.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/saizul/oss-maintainer-skills/tree/HEAD/skills/readme-writer

Installed? Explore more Productividad y colaboración skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Escritor de README

Un README tiene un solo trabajo: llevar al visitante de "¿qué es esto?" a un primer comando funcional en menos de un minuto, y luego mostrarle cómo ir más allá y cómo ayudar.

Cuándo usarlo

  • Escribir un README para un proyecto nuevo, o reescribir uno delgado o sin rumbo.
  • Revisar un README antes de un lanzamiento o una versión 1.0.
  • El usuario dice que el proyecto recibe visitas pero no estrellas, instalaciones o colaboradores.

Cuándo no usarlo

  • Documentación de referencia de API (genérala a partir del código; enlázala desde el README).
  • Tutoriales largos o documentos de arquitectura: colócalos en docs/ y enlázalos.

Flujo de trabajo

  1. Recopila hechos antes de escribir. Lee el manifiesto (pyproject.toml, package.json, composer.json, Cargo.toml...), la ayuda --help de la CLI o el punto de entrada principal, los documentos existentes y la licencia. Encuentra el comando de instalación real y un ejemplo real. Nunca inventes banderas, salidas, benchmarks o características.

  2. Pregunta al usuario solo lo que el código no puede decirte: para quién es el proyecto, el único problema que resuelve y por qué es mejor que la alternativa obvia. Si no están disponibles, escribe una presentación neutral a partir del código y márcala para revisión.

  3. Revisa el README actual (si existe). Los scripts están en scripts/ relativo a esta habilidad:

    python3 scripts/readme_lint.py README.md
    python3 scripts/readme_lint.py README.md --json --strict
    
  4. Escribe usando la estructura de structure.md, comenzando desde la plantilla. El orden importa: título + insignias, presentación, (imagen demo), inicio rápido, características, uso/ejemplos, configuración, FAQ, hoja de ruta, contribuciones, licencia.

  5. Aplica las reglas de escritura:

    • Presentación: una frase, menos de 200 caracteres, sin palabras exageradas. Patrón: "<nombre> es un <categoría> que <hace X> para <audiencia>, <diferenciador clave>."
    • Primer bloque de código antes de la línea 60. Cada comando debe ser copiable y real.
    • Muestra la salida después de los comandos cuando ayude (# => ... o un bloque separado).
    • Usa tablas para opciones y comparaciones, listas para características (beneficio primero).
    • Enlaza, no pegues: documentos largos, registros de cambios y referencias de API van a otro lado.
    • Cada imagen tiene texto alternativo; prefiere un SVG o un GIF corto del flujo principal.
  6. Insignias. Usa solo aquellas que sean verdaderas y mantenidas, en este orden: estado de CI, última versión (PyPI/npm/Packagist/release), descargas (opcional), licencia. Ejemplos en structure.md.

  7. Vuelve a revisar hasta que no haya errores. Resuelve las advertencias o dile al usuario por qué no.

  8. Verifica los enlaces que el linter no puede: URLs absolutas y anclajes. Haz clic para probar o explica cuáles no se verificaron.

Salida

  • El README.md nuevo o actualizado (muestra un resumen de diferencias para reescrituras).
  • El resultado final de la revisión.
  • Una lista breve de hechos que no pudiste verificar y marcadores de posición que el usuario debe completar (GIF demo, capturas de pantalla, números de benchmark).

Reglas de revisión

ReglaNivelSignificado
titleerror/advertenciaexactamente un H1
pitcherror/advertenciaun primer párrafo corto debajo del título
badgesadvertenciano se encontró ninguna insignia
installerror/advertenciasección de instalación (o inicio rápido), con un bloque de código
quickstarterror/advertenciasección de uso, inicio rápido o ejemplo, con código
codeerrorningún bloque de código en absoluto
scrolladvertenciaprimer bloque de código después de --max-scroll líneas (por defecto 60)
contributing, licenseadvertenciasección faltante
faq, tocinfosugerido
alt-textadvertenciaimagen sin texto alternativo
broken-linkerrorenlace relativo a un archivo faltante, o un enlace vacío
broken-anchorerrorenlace #ancla (índice) que no coincide con ningún encabezado o id/name HTML, usando las reglas de slug de GitHub
placeholderadvertenciaTODO, TBD o lorem ipsum dejado

Sale con código 1 en errores (y en advertencias con --strict).

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Skills relacionados