readme-writer — Skill de README para Humanos
Habilidad para escribir y mejorar READMEs orientados a humanos. Mientras que llms-txt-writer se encarga de la superficie exclusiva para IA, este skill se ocupa de la entrada canónica única para la superficie humana.
Además, un hecho importante: el README es la única superficie que un LLM puede asumir de manera confiable a través de la ruta de grounding (pegar la URL del repo en búsqueda/chats de IA). Por lo tanto, el README debe ser "breve y visual para humanos" pero también debe conservar un "pequeño piso de información" que permita a un LLM reconstruir el proyecto solo con el README. Lograr ambos objetivos es el desafío central de este skill.
Cuándo Usarlo
- Crear o mejorar README.md / README.ja.md
- Organizar la "página de aterrizaje inicial para humanos" de un repo/proyecto
- Corregir READMEs existentes que son "demasiado técnicos para humanos" o "demasiado superficiales para que un LLM los entienda"
- Cuando se quiere un README breve y visual sin perder el piso de información
Cuándo NO usarlo:
llms.txt/llms-full.txt/ FAQ, etc., documentos exclusivos para IA (→llms-txt-writer)- Artículos, ensayos, blogs u otros textos largos (→
writing-ecosystem) - Diseño de graph.jsonld (→
jsonld-knowledge-graph)
El Eje es "ATENCIÓN Humana × INFORMACIÓN del LLM"
El verdadero conflicto en la optimización del README no es "información para humanos vs. información para LLM". Es la atención humana (breve, que atrape, escaneable) × la información del LLM (que se pueda reconstruir solo con el README). Ambos convergen en las mismas acciones (ver más abajo), por lo que no es un trade-off, sino un diseño que logra ambos.
El README es la Única Superficie que se Lee con Certeza (pero no es la "única")
- Los buscadores de IA y los crawlers de citas prácticamente no leen llms.txt (según múltiples estudios de logs de 2026, la mayoría reporta cero solicitudes; los principales proveedores de búsqueda han declarado oficialmente que no lo soportan).
graph.jsonldse trata como texto plano en las búsquedas directas y no reemplaza los hechos del README (experimento controlado).- Por lo tanto, no se debe adelgazar la información del README bajo el supuesto de que "la capa mecánica la respaldará".
Sin embargo, una calibración importante: es demasiado fuerte decir que "el LLM solo lee el README". Correctamente, es "para grounding genérico (pegar URL / búsqueda), el README es la única superficie que se puede asumir con certeza". Existen otras rutas (el índice de búsqueda ya tiene fragmentos de otros archivos, seguimiento de enlaces desde el README, exposición del árbol de archivos a través del conector de GitHub o API, conocimiento del preentrenamiento). La conclusión más sólida es para el grounding anónimo en web en vivo y la búsqueda directa de aterrizaje. Por el contrario, los agentes de codificación enrutados (Claude Code, Cursor, etc.) leen llms.txt bajo demanda, por lo que llms.txt sigue siendo válido como seguro para el canal agéntico, aunque no es la entrada para la búsqueda de IA.
Por Qué Separar el "Lint Estructural" de la "Revisión Holística"
La calidad del README mezcla dos tipos de propiedades. Siguiendo Code-LLM Layering (la estructura es propiedad 100% precisa del código, el significado es propiedad del LLM), se separan los dueños. El criterio de decisión es when-code-when-llm: "¿Puede la misma secuencia de bytes tener diferentes significados según el contexto?"
| Propiedad | Ejemplo | Tipo | Dueño |
|---|---|---|---|
| Estructural | Número de H1 / nivel de encabezados / presencia de alt-text / resolución de enlaces locales / nombres de archivos raster / número de badges / DOI dentro de details / líneas de prosa justo después del H1 | estructural | código (readme_lint.py) |
| Semántico | Si el lead atrapa a la persona / claridad de la propuesta de valor / si el LLM puede reconstruir el proyecto solo con el README / flujo narrativo / si los badges son de adorno | semántico | Revisión holística del LLM |
No se crea una puntuación numérica basada en investigación para el README. Las proporciones de secciones de llms.txt (ski-ramp, etc.) son señales deterministas validadas por estudios de citas de LLM, pero si un README es "una buena entrada" es un juicio semántico sin hallazgos deterministas equivalentes. Transferir indicadores de superficie de IA (como densidad de entidades) a READMEs humanos es un anti-patrón.
Sin embargo, se Adopta Activamente la "Legibilidad Estructural para IA" (regla de doble cara)
"No transferir indicadores de superficie de IA" es solo la mitad. El principio es: "Se puede optimizar cómo se transmite una idea (sin límite de intensidad). Nunca se debe distorsionar qué es la idea".
- Adoptado (sin límite de intensidad): Jerarquía de encabezados, diseño de información, anclaje de entidades (escribir nombre de autor / ORCID / DOI / identificadores canónicos en la prosa), anclaje de vocabulario propio/términos acuñados, lead con respuesta primero, tabla de un vistazo. Estos son una zona de convergencia que funciona tanto para humanos como para LLMs en la ruta de grounding.
- Prohibido: Relleno de palabras clave, atributos inflados, cultivo de preguntas en encabezados, volcado de glosarios, distorsión de afirmaciones para ajustarse a la función de recompensa de recuperación. Las citas y las estrellas no son indicadores de éxito, por lo que distorsionar no tiene un objetivo al que servir.
Piso Mínimo de Lectura para LLM (Pequeño, No Negociable, No Inflar)
Regla: Asumiendo que el LLM lee solo el README (ni llms.txt ni graph), debe poder reconstruir el proyecto solo con el texto.
Elementos del piso (en prosa / markdown / Mermaid. No se permite solo en imágenes / solo dentro de details / solo en enlaces):
- Declaración de identidad (primeras 1-2 frases, legibles de forma independiente): "X es una {categoría} que {hace qué} para {quiénes}"
- Problema que resuelve / público objetivo / puntos diferenciadores
- Hechos canónicos: nombre real / lenguaje/stack/estado. Para repos de investigación/DOI: DOI + cómo citar (BibTeX / CITATION) + definiciones de 3-6 conceptos centrales que sustenten el vocabulario
- Un solo ejemplo concreto: para código, la firma de la función + una pieza mínima ejecutable (no incluir la implementación completa — infla + provoca alucinaciones) / para investigación, la afirmación central + 2-3 números clave
- Mapa de enlaces a documentación profunda: solo punteros. No colocar hechos importantes solo en enlaces / llms.txt / graph
El error más importante: El piso es un pequeño núcleo no negociable. Si se aplica demasiado el principio "no recortes, reestructura", la información se acumula en Mermaid / details / secciones del piso, y el README se infla como un llms-full.txt disfrazado. El objetivo humano era breve. Recortar sin piedad o reubicar todo lo que no sea el piso (→ presupuesto de longitud).
Si se crean graph.jsonld / llms.txt a partir del README, no usar la prosa del README como fuente estructural. Derivar identificadores y aristas del grafo desde CITATION.cff / .zenodo.json / un pequeño manifiesto en el frontmatter (las copias paralelas escritas a mano se desvían).
Las superficies meta de GitHub (descripción del repo / topics / social-preview / archivo CITATION / release / metadatos del paquete) también son parte del piso que afecta al grounding. No se configuran en el cuerpo del README (se hace desde gh repo edit / release-doi), pero se verifica que estén presentes como checklist.
Visual-First (Mermaid Primero, Raster al Final)
La interpretación correcta de "breve y visual" es "comprimir el muro de prosa en una estructura escaneable". No es convertir la prosa en imágenes. Y "Mermaid primero" ≠ "todo en Mermaid" — primero hay que filtrar si realmente debe ser un diagrama. Elegir formatos que no se rompan en móvil (ancho estrecho) y que el LLM pueda capturar.
Selección de Formato
| Contenido | Formato Óptimo | Razón |
|---|---|---|
| 3 pasos lineales / enumeración simple | prosa / lista / tabla pequeña | Legible en todos los dispositivos (especialmente móvil). No vale la pena hacer un diagrama |
| Forma de grafo real (relaciones, múltiples ramas, matriz) | Mermaid (TD vertical) | La fuente es texto y el LLM también lo lee. El desplazamiento vertical es natural en móvil; horizontal (LR) se rompe |
| Diagrama grande / complejo | SVG confirmado (ampliable/desplazable) / división en subsistemas | Un Mermaid enorme alcanza el límite incluso en escritorio y se rompe en móvil |
| UI real / resultados de ejecución / fotos | raster (PNG/JPG/WebP/GIF) | Solo para lo que Mermaid no puede representar |
Cada diagrama debe ir acompañado de un equivalente textual de una oración (regla estricta). Esto garantiza que "llegue tanto a humanos como a LLMs": salva al humano cuyo diagrama se rompió en móvil, al extractor de LLM que omite el bloque ```mermaid como código opaco, y al lector de pantalla. El diagrama es un bono visual adicional, no el único portador de información.
Puntos Clave de Mermaid
- GitHub renderiza nativamente a SVG consciente del tema. La fuente es texto (diferencial, ~10 tokens/edge) y también es legible para crawlers de solo texto que no ven píxeles. Convertir a Mermaid estructuras enterradas en prosa/grafos (matrices de conceptos, enlaces de fases, etapas de pipeline) acorta y aumenta la densidad de información.
- Prioridad móvil: usar
TD(vertical). El horizontalLRtiende a fallar en anchos estrechos. - El límite de renderizado es por caracteres (
maxTextSizepor defecto 50,000) + por aristas, no por número de nodos ("50-100 nodos es el límite" es un mito). Si se va a exceder, dividir en subsistemas. En READMEs de proyectos especiales no se renderiza. - Como los extractores pueden omitir Mermaid, el equivalente textual de arriba debe garantizar el significado por separado.
Raster / Otros
- No cargar información importante en raster. Alt-text obligatorio (piso duro: la ruta de texto solo lee el alt = las imágenes sin alt son invisibles para el LLM. No es solo un problema de accesibilidad).
- Para oscuro/claro:
<picture><source media="(prefers-color-scheme: …)"><img alt="…"></picture>.<img alt>es doblemente portador de información. - Los assets de imagen deben estar confirmados en el repo con ruta relativa. Evitar hotlinks externos (se rompen con camo) y
<svg>/<embed>/<object>inline/animados (GitHub los sanitiza). - Badges: solo 2-4 de alta señal (CI / versión / licencia / DOI para repos de investigación). Evitar badges de adorno. Limitar el número para que no ocupen mucho espacio en ancho estrecho.
- Repos CLI: asciinema → GIF de agg + leyenda de una oración. Repos UI: captura de pantalla/GIF + alt-text.
Para diagramas especiales poco comunes, generar SVG confirmable con Claude Artifacts / Claude Code skill svg/diagram y colocarlo en
assets/.
Presupuesto de Longitud (Sin Objetivo de Palabras)
No se establece un objetivo de número de palabras ("el punto óptimo es 500-1500 palabras" / "los README visuales aumentan las estrellas (estudio de GitHub)" han sido descartados como inventados o sin fuente). En su lugar:
- Above-the-fold (primera pantalla = 30 segundos para decidir "¿es para mí?"): Cualquier hero → H1 → tagline de una línea (propuesta de valor = la línea que el LLM extrae con mayor seguridad) → ≤4 badges funcionales → hechos del piso → quick start para copiar y pegar. La justificación profunda va después.
- El orden varía según el tipo de repo: "quickstart → rationale" es para software. No aplica para repos de papers / datasets / conceptos / ensayos con DOI. No forzar un orden fijo; solo mantener "identidad + hechos canónicos antes que la justificación profunda" . El lint
identity_leadsolo verifica estructuralmente la existencia de una frase de inicio, no fuerza el orden. - La cantidad total se determina por una variable: ¿el sitio de documentación canónica / los ADR absorben la documentación profunda?. Mover el "por qué" profundo / la justificación de diseño a ADR /
docs//llms-full.txt/ paper depositado, y dejar un puntero de una línea en el README (desplazamiento de explicación de Diátaxis). Esta es la cura directa para "README de repo de investigación de 450 líneas". <details>solo para contenido secundario a granel (tablas de opciones / FAQ / solución de problemas / glosario completo). Organiza la vista humana mientras sigue siendo accesible para el LLM. Pero no colocar el piso allí (pérdida de primacía + no se puede hacer Ctrl+F. Aunque es legible en la ruta de markdown sin procesar, el resumidor de la página renderizada puede de-priorizar el contenido plegado).
Flujo de Trabajo (Filtro de Código → Revisión de LLM → Puerta Humana)
1. Filtro de Código — readme_lint.py (Determinista, solo Estructural)
uv run --directory ~/.claude/skills/readme-writer python -m scripts.readme_lint "$ARGUMENTS"
El argumento es la ruta absoluta del README. --json para salida legible por máquina. El código de salida es la puerta de propiedad del código (0=limpio o solo advertencias / 1=hay errores de gravedad / 2=no encontrado o demasiado grande).
Elementos de inspección (problemas concretos, no puntuaciones. Gravedad de 2 niveles):
error (bloquea la puerta, estructura dura)
single_h1— Exactamente 1 H1heading_levels— No saltar niveles de encabezadoalt_text— Todas las imágenes tienen alt (piso duro: sin alt = invisible para el LLM)local_link— Los enlaces relativos locales / src de imagen existen
warning (consejo, no bloquea la puerta) — Detecta estructuralmente pero "si realmente es un problema" es un juicio, por lo que solo se muestra en la superficie. El juicio semántico se delega a la revisión del LLM:
raster_diagram_hint— Raster con nombre de archivo que parece diagrama (architecture/flow/diagram/pipeline, etc., .png/.jpg/.webp/.gif) → sugiere convertir a Mermaid. Excluye SVG, capturas de pantalla, logotiposbadge_budget— Demasiados badges (>6 por defecto). Solo juzga la cantidad (si son de adorno o no, es decisión del LLM)details_floor_leak— Presencia de tokens DOI / BibTeX / CITATION dentro de<details>(indicio de fuga del piso. "Si realmente es piso" lo decide el LLM)identity_lead— No hay frase de inicio en prosa entre el H1 y la primera sección (no fuerza el orden. La ausencia de H1 la manejasingle_h1)doi_citation_pairing— Hay DOI pero no hay cómo citar (sección Citation / BibTeX / CITATION.cff) (no fuerza DOI en repos que no son de investigación — solo se activa cuando hay DOI)
2. Revisión Holística del LLM (rúbrica como lente, sin puntuación, primero la señal)
Una vez que pasa el lint, Claude lee el README holísticamente y entrega hallazgos concretos + cambios concretos en formato diff usando las siguientes lentes:
- 🚩 Recuperación solo con README (bandera principal, máximo apalancamiento) — Leer solo el texto del README y verificar si se puede reconstruir (identidad / público objetivo / problema / diferenciación / DOI y cita si corresponde / 3-6 conceptos centrales / 1 ejemplo / enlace a siguientes pasos). Enumerar las deficiencias concretamente ("el público objetivo no está escrito", etc.). No asignar puntuación. Esta es la operacionalización del "piso mínimo de lectura para LLM".
- Qué / Quién / Por Qué del Lead — ¿La primera pantalla deja claro "qué es, para quién es, por qué debería importarme"?
- Gancho Humano / Propuesta de Valor — ¿El valor se expresa con concreción, no con términos abstractos?
- Narrativa / Escaneabilidad — ¿Los párrafos, encabezados, listas, Mermaid son fáciles de seguir para un humano?
- Verificación de Brevedad (la comprobación inversa más importante) — ¿Se ha reubicado todo lo que no es el piso? ¿La información se ha acumulado en Mermaid / details / piso, inflando el README como un llms-full.txt disfrazado?
- Validez Visual — ¿Los diagramas son Mermaid? (si son raster, ¿tienen equivalente textual o se sugirió convertir a Mermaid?) ¿Los badges son de alta señal? (¿no son de adorno?)
- Coincidencia de Hechos — ¿Las afirmaciones no contradicen la capa mecánica (llms.txt / graph.jsonld)? → Delegar a
context-sync
Razón para no asignar puntuación (primero la señal + disolución del andamio): Solo entregar "información que cambie la siguiente acción". Lead: 6/10 no cambia la acción. "El lead no dice para quién es" sí cambia la acción. La salida se divide en fragmentos en formato diff que se pueden aprobar con y/n. Para la separación autor-revisor, la revisión debe ejecutarse en un proceso de agente diferente al del implementador (similar a editor / essay-reviewer).
3. Verificación de Coincidencia de Hechos → context-sync
La verificación de que los hechos del README coincidan con llms.txt / llms-full.txt / graph.jsonld (evitar cloaking) es responsabilidad de context-sync. Este skill no la reimplementa.
4. Puerta Humana
Un humano aprueba y aplica el diff.
Lo que Este Skill NO Hace (Límites)
- No escribe
llms.txt/llms-full.txt(→llms-txt-writer) - No diseña
graph.jsonld(→jsonld-knowledge-graph) - No detecta/sincroniza desviaciones entre superficies (→
context-sync/release-doi) - No edita artículos/ensayos (→
writing-ecosystem) - No configura la descripción / topics / social-preview del repo (lo hace
gh repo edit/release-doi. Este skill solo lo presenta como checklist) - No emite puntuaciones de calidad / calificaciones / notas
Anti-Patrones
- Emitir solo una puntuación numérica sin propuestas concretas (trampa del recomendador)
- Hacer que el LLM juzgue elementos que deberían ser manejados por el lint estructural, o usar regex para juicios semánticos (ver
when-code-when-llm) - Transferir indicadores numéricos de superficie de IA (ski-ramp / densidad de entidades / cultivo de preguntas en encabezados) a READMEs humanos (reduce la legibilidad)
- Interpretar "prioridad visual" como convertir la prosa en imágenes (los diagramas raster son invisibles para LLMs de solo texto = ocultar información a los agentes. Usar Mermaid)
- Aplicar demasiado el principio "no recortes, reestructura" y terminar convirtiendo el README en un llms-full.txt disfrazado (el piso es pequeño; recortar/reubicar sin piedad lo demás)
- Adelgazar el piso del README asumiendo que la capa mecánica (llms.txt/graph) lo respaldará (no se lee en la ruta de grounding)
- Derivar
llms.txt/graphde la prosa del README (se desvía. Derivar del manifiesto) - Añadir hechos o apelaciones de monetización para humanos (daña la autenticidad + contradice la capa mecánica = cloaking. Se puede cambiar el empaque, pero no las afirmaciones)
Verificación
cd ~/.claude/skills/readme-writer
uv sync --dev
uv run pytest tests/ --cov=scripts --cov-report=term-missing
fixtures/sample_clean.md (0 problemas, ejemplo de buenas prácticas con diagramas Mermaid) y fixtures/sample_issues.md (ejemplo que activa los 9 checks) permiten verificar el comportamiento básico.
Relacionados
llms-txt-writer— El escritor complementario para la superficie de IA (tienegeo_check.pybasado en investigación). Este skill es para la superficie humana.when-code-when-llm— El eje de decisión entre estructural/semánticocontext-sync— Coincidencia de hechos / desviación entre README y capa mecánica (la verificación de hechos se delega aquí)jsonld-knowledge-graph— Diseño de graph.jsonldwriting-ecosystem— Orquestador de textos largos en prosa para humanosinspiration.md— Origen del diseño, procedencia de la investigación primaria, fuentes de evidencia externa (separado del cuerpo de SKILL.md por portabilidad)