Un README donde cada afirmación se rastrea hasta el código

Un README generado es un timo de confianza. Se lee limpio, enumera funcionalidades que suenan bien, y te entrega comandos de instalación que parecen correctos — y no puedes saber por leerlo qué frases son verdad. El modo de fallo es siempre el mismo: una funcionalidad que el código no tiene, un comando completado por patrón desde datos de entrenamiento en vez de copiado del repo, y una ausencia sospechosa de cualquier limitación. Dirigimos un directorio que testea skills de Claude con benchmarks para ganarnos la vida, así que construimos la skill que queríamos y luego medimos si de verdad se sostiene.

El resultado es readme-discipline: nueve reglas exigibles cuyo contrato es que una funcionalidad afirmada debe encontrarse en el código fuente antes de poder afirmarse, cada comando se copia de los manifiestos reales del proyecto y se ejecuta, y una sección honesta de limitaciones es obligatoria. Es gratis y tiene licencia MIT: github.com/Skillproofdev/readme-discipline.

La brecha: 101 skills de README, ninguna exige la verdad

Antes de escribir una regla, revisamos el panorama — 101 skills relacionadas con README dentro de un catálogo de 16.682 skills, más readme-ai y la spec de Standard Readme. Todas y cada una optimizan algo distinto a la precisión.

La skill de README dedicada más grande (2.2k★) es un conjunto de plantillas por audiencia. La spec de Standard Readme exige el orden de las secciones pero no dice nada sobre si los bloques de código se ejecutan. El generador de CLI dominante produce una salida pulida y luego te dice, en su propia documentación, que revises tú mismo la precisión — la precisión se delega en la persona. El resto son maximizadores de badges y decoradores de cabeceras con emojis. La estructura y el aspecto están resueltos cinco veces por encima. "Cada afirmación se rastrea hasta el código" y "cada ejemplo está verificado como ejecutable" no aparecían como reglas exigibles en ninguna.

Ese es todo el nicho que ocupa esta skill: no hacer los README más bonitos, hacerlos verdaderos.

Nueve reglas, tres de ellas inéditas

Las partes conocidas están aquí — un orden fijo de secciones (qué+por qué → instalación → inicio rápido → uso → configuración → limitaciones), calibración para una sola audiencia, sin inflación de badges ni emojis. Las tres que nadie más exige:

1. Prohibición de invención con recibos. Cada afirmación falseable — una funcionalidad, un flag, una plataforma soportada — se busca primero con grep en el código fuente. Se encuentra → puedes afirmarla, con el vocabulario propio del código. No se encuentra → no entra en el README, ni matizada, ni como "normalmente." Un registro de verificación que mapea afirmación → archivo:línea acompaña a cada README.
2. Los comandos se copian, nunca se componen. Cada comando en bloque de código viene de un lugar real: scripts de package.json, un target de Makefile, un paso de CI, el propio --help de la CLI. Nunca npm run build porque los proyectos Node suelen tener uno — primero revisa scripts, luego ejecútalo en un checkout limpio.
3. El inicio rápido es un contrato. Del clone a un éxito observable en unos 60 segundos, cada paso ejecutable exactamente como está escrito, terminando en un resultado que el usuario puede comprobar — una URL que responde, un archivo que aparece, una salida que coincide con el snippet mostrado.

A eso se suma una sección de limitaciones obligatoria y con fuente (extraída de comentarios TODO/FIXME, ramas de error, stubs vacíos) y un modo de auditoría primero que elimina afirmaciones obsoletas de un README existente antes de tocar su estilo.

El benchmark: 3 repos reales, cada comando ejecutado de verdad

Elegimos tres proyectos OSS pequeños con READMEs escuetos y congelamos cada uno en un SHA de commit: una CLI de Node (crossplatform-killport), una CLI/biblioteca de Python (python-shaarli-client), y un servicio web Flask (csrgenerator.com). Por repo, dos agentes — uno baseline, otro leyendo la skill primero — mismo modelo, mismo prompt, la única diferencia es si el SKILL.md estaba en contexto. Cada comando de la tabla de abajo se ejecutó en una máquina real (macOS 14, node v24.7.0, python3 3.13.1); los comandos cuyo runtime faltaba (Docker) o que necesitaban un servicio externo en vivo se excluyeron del denominador de ejecutabilidad y se verificaron de forma estática en su lugar.

Métrica (agregado de 3 repos)	Baseline	Skill
Afirmaciones inventadas (menor mejor)	2	1
Ejecutabilidad de comandos	20/24 (83%)	15/17 (88%)
Completitud de secciones	14/18	18/18
Preferencia ciega	0/3	3/3
Confianza media (1–5)	3.67	4.67

La tendencia es consistente en los tres repos en completitud y preferencia. La skill logró 6/6 secciones todas las veces; el baseline no publicó ninguna sección de limitaciones en ninguno de los tres repos — la mayor brecha de completitud, con diferencia. Y fue preferida en los tres con un punto entero más de confianza.

Dónde la skill se lo ganó de verdad — y dónde se le fue la mano

El número de invenciones merece honestidad, porque es el titular que esperarías que fuera un aplastante y no lo es. 2 contra 1 es una brecha estrecha, y esta es la razón: las dos agentes baseline se apoyaron mucho en la prosa precisa ya existente de USAGE.md/docs/ de los repos, así que heredaron contenido correcto gratis. Los dos fallos del baseline fueron exactamente el fallo que esta skill ataca — un requisito obsoleto de Python 3.4+ contradicho por la propia matriz de tests del proyecto, y dos entornos tox inventados (py34/py36) que no existen en tox.ini. Afirmaciones completadas por patrón, rastreables a "un proyecto como este," no al código. El brazo con la skill captó esa misma afirmación del 3.4 y la rebajó a una limitación con fuente en vez de afirmarla.

Y la skill mantuvo su propia y única invención en el reporte en vez de esconderla. En csrgenerator, su tabla de campos afirmaba que un valor CN vacío devuelve HTTP 400. Un CN ausente es efectivamente 400 — pero uno vacío choca con el propio raise KeyError("CN cannot be empty") del código, que no está gestionado y devuelve HTTP 500 (verificado en vivo). Un detalle de comportamiento equivocado en una celda de tabla, en una ejecución que por lo demás corrió pytest (23 pasados, coincidencia exacta) y una generación real de CSR con curl. La skill no es magia; es disciplina, y la disciplina tiene una tasa de error residual. La registramos.

Donde la skill fue inequívocamente más afilada fue en los detalles verificados: "pip install -e . instaló requests==2.34.2 / PyJWT==2.13.0" coincidió exactamente con un venv recién creado; las limitaciones de killport (coincidencia solo con LISTENING en Windows, SIGKILL incondicional, un puerto por invocación) se rastrearon todas hasta el código fuente con el flujo de kill verificado de extremo a extremo. Afirmaciones que venían de una ejecución real, no de una corazonada.

Los matices honestos

Nuestra metodología exige imprimir las debilidades junto a las victorias, y aquí hay debilidades reales.

Un solo evaluador, no un panel de 3 desarrolladores. Las filas de preferencia y confianza son el juicio experto de una sola persona, la autora del benchmark, hecho con el código fuente abierto. El protocolo pide ≥3 evaluadores desarrolladores independientes; ese panel no estaba disponible en este arnés. Lee esas dos filas como indicativas, no como el resultado multievaluador que especifica el diseño.

La brecha de invenciones es estrecha por construcción. Como ambos baselines reutilizaron documentación precisa del repo, el baseline tuvo menos ocasiones de inventar. En un repo sin documentación existente la brecha probablemente se ampliaría — pero estamos reportando lo que mostraron estos tres repos, que es 2 contra 1, y N=3 es solo directional.

La ejecución de comandos depende del entorno. Cuando la máquina de la agente no puede correr el proyecto, los comandos se verifican de forma estática contra los manifiestos y se marcan como no ejecutados en el registro — más débil que una ejecución real, y lo señalamos como tal.

Instalación

git clone https://github.com/Skillproofdev/readme-discipline ~/.claude/skills/readme-discipline

Reinicia Claude Code. Se activa con "escribe un README", "documenta este repo", "crea/reescribe README.md", y peticiones de revisión o auditoría de README — y se mantiene al margen de los sitios de documentación completos, la generación de referencias de API, y los changelogs. Se suma a nuestra serie de disciplina: token-discipline recorta lo que cuesta una tarea, research-discipline recorta lo que la investigación se equivoca, y esta recorta lo que tu documentación inventa.

Preguntas frecuentes

¿En qué se diferencia de un generador de README como readme-ai? Los generadores producen estructura y te delegan a ti la precisión — su propia documentación te dice que revises la salida. Esta skill invierte eso: lee el código primero, busca con grep cada afirmación falseable contra el código fuente, ejecuta cada comando documentado en un checkout limpio, y te entrega un registro de verificación para que compruebes su trabajo. La estructura es la parte fácil; la skill dedica su esfuerzo a la verdad.

¿Qué es exactamente el registro de verificación? Un artefacto aparte en la respuesta (no committeado) que mapea cada funcionalidad afirmada a un archivo:línea en el código fuente y marca cada comando como ejecutado ✓ o no ejecutado — verificado contra <manifiesto>, más cualquier cosa dejada fuera deliberadamente por falta de evidencia. Si ese registro estuviera vacío, la skill se saltó sus propias tres primeras reglas. Es el recibo que te permite confiar en la prosa.

¿La regla contra las invenciones hace el README más corto y soso? No — las reglas están escritas para añadir contenido útil, no para recortarlo. La sección obligatoria de limitaciones y el inicio rápido con comandos verificados son cosas que los README genéricos omiten. En el benchmark, los README de la skill fueron más completos (18/18 secciones) que los del baseline, no más escuetos.

¿Una invención en tres repos es suficientemente bueno? Es mejor que las dos del baseline, y es honesto sobre el residuo — un comportamiento de CN vacío equivocado por un código de estado HTTP, registrado en vez de enterrado. Si tu README respalda una decisión que sale cara de equivocar, el registro de verificación te dice exactamente qué afirmaciones comprobar por encima, lo que lleva minutos en vez de releer todo el código.