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
-
Recopila hechos antes de escribir. Lee el manifiesto (
pyproject.toml,package.json,composer.json,Cargo.toml...), la ayuda--helpde 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. -
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.
-
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 -
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.
-
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.
- Presentación: una frase, menos de 200 caracteres, sin palabras exageradas. Patrón: "
-
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.
-
Vuelve a revisar hasta que no haya errores. Resuelve las advertencias o dile al usuario por qué no.
-
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
| Regla | Nivel | Significado |
|---|---|---|
| title | error/advertencia | exactamente un H1 |
| pitch | error/advertencia | un primer párrafo corto debajo del título |
| badges | advertencia | no se encontró ninguna insignia |
| install | error/advertencia | sección de instalación (o inicio rápido), con un bloque de código |
| quickstart | error/advertencia | sección de uso, inicio rápido o ejemplo, con código |
| code | error | ningún bloque de código en absoluto |
| scroll | advertencia | primer bloque de código después de --max-scroll líneas (por defecto 60) |
| contributing, license | advertencia | sección faltante |
| faq, toc | info | sugerido |
| alt-text | advertencia | imagen sin texto alternativo |
| broken-link | error | enlace relativo a un archivo faltante, o un enlace vacío |
| broken-anchor | error | enlace #ancla (índice) que no coincide con ningún encabezado o id/name HTML, usando las reglas de slug de GitHub |
| placeholder | advertencia | TODO, TBD o lorem ipsum dejado |
Sale con código 1 en errores (y en advertencias con --strict).