El skill redactor de docs: README fiel al código de verdad

Todo proyecto acumula deuda de documentación de la misma forma: el README se escribe una vez el primer día, el código sigue avanzando y, seis meses después, los pasos de instalación son pura ficción. Un skill redactor de docs cierra esa brecha porque saca la documentación de la fuente de verdad en lugar de la memoria. Al terminar esta guía vas a tener una definición de skill completa y lista para copiar, una idea clara de cuándo debería dispararse, de cómo lee una base de código y de la única restricción que evita que invente, con toda la seguridad del mundo, un comando que no existe.

01 · Qué hace el skill realmente

Un skill redactor de docs es un conjunto de instrucciones empaquetado que invocas cuando lo necesitas, en vez de pegar el mismo prompt de "escríbeme un README" una y otra vez. No es un autocompletado más sofisticado. Su trabajo es acotado y útil: responder las tres preguntas que se hace cualquiera que llega nuevo y abre tu repo.

• ¿Qué es esto? Dos frases, claras, sin adjetivos tipo "potente" o "fluido".
• ¿Cómo lo ejecuto? Los comandos reales, copiados de los scripts que existen, no una suposición genérica.
• ¿Qué puede salir mal? Requisitos, configuración y las limitaciones conocidas que, si no, terminarías explicando en el chat por quinta vez.

El resultado es un README (o una sección) que es correcto porque se armó a partir de archivos, no de la imaginación. Esa diferencia es toda la propuesta de valor. Un doc que parafrasea texto de marketing envejece mal. Uno que se regenera desde package.json y el punto de entrada real envejece junto al código.

02 · Cuándo debería dispararse

El skill se gana su lugar en dos momentos puntuales, y conviene aguantar las ganas de ejecutarlo en todo.

1. No existe README. Un servicio nuevo, un paquete recién creado, una herramienta interna que nadie documentó. Todavía no hay de qué desviarse, así que el skill arma la primera versión honesta.
2. El README se desvió. Cambió el comando de instalación, renombraron una variable de entorno, eliminaron un script. Esto se suele notar apenas un compañero pregunta algo que el README debería responder.

El disparo que evito es "el README se ve pobre, mejóralo". Eso invita a rellenar, y el relleno es justo el modo de falla que estás tratando de evitar por diseño. La documentación se hace más larga cuando la realidad se complica, no cuando el modelo se aburre.

03 · Cómo funciona por dentro

A nivel mecánico, el skill es un archivo SKILL.md con frontmatter YAML y un cuerpo de instrucciones. Claude Code lo expone por nombre y descripción. Al invocarlo, ese cuerpo pasa a ser el prompt operativo. Por dentro son tres fases.

Leer las fuentes reales

Antes de escribir una sola palabra, el skill revisa los archivos que describen qué es el proyecto y cómo se ejecuta:

• El manifiesto del paquete (package.json, pyproject.toml, Cargo.toml) para sacar el nombre, las dependencias y el bloque de scripts.
• El punto de entrada (el archivo principal, el arranque del server, la definición de la CLI) para entender qué hace realmente.
• La config y cualquier .env.example para las variables que hay que configurar.

Acotar la estructura

El skill no escribe prosa libre. Rellena una plantilla fija, y eso es lo que mantiene la salida comparable y fácil de hojear entre proyectos. Esta es la estructura de prompt que uso:

Escribe un README con exactamente estas secciones:
- Qué hace (2 frases, sin adjetivos tipo "potente")
- Requisitos (sácalos de package.json / pyproject)
- Cómo ejecutarlo (los comandos reales, copiados de los scripts)
- Configuración (cada variable de entorno: nombre, qué hace, valor por defecto)
- Limitaciones conocidas
Prohíbe estas palabras: revolucionario, fluido, potente, aprovechar.
Cita las entradas reales de los scripts. Si no encuentras un comando,
escribe TODO en vez de adivinar uno.

Verificar antes de afirmar

La tercera fase es la que separa un skill útil de uno peligroso. Todo comando de la salida tiene que poder rastrearse hasta una entrada de los scripts. Si el skill no encuentra el comando para ejecutar, escribe un TODO en lugar de inventar una línea que parezca creíble. Más sobre el porqué en la sección 05.

04 · Una corrida concreta y qué devuelve

Esta es la definición completa del skill. Colócala en .claude/skills/doc-writer/SKILL.md y queda disponible por nombre.

---
name: doc-writer
description: Lee el código y escribe un README basado en los archivos
  reales. Úsalo cuando un proyecto no tiene README o el README se desvió.
---

1. Lee package.json (o pyproject/Cargo), el archivo de entrada y
   cualquier .env.example o config.
2. Escribe un README con exactamente estas secciones: Qué hace,
   Requisitos, Cómo ejecutarlo, Configuración, Limitaciones conocidas.
3. Copia los comandos para ejecutar tal cual del bloque de scripts.
   Cítalos.
4. Por cada variable de entorno, da nombre, propósito y valor por defecto.
5. Si un comando o valor no aparece en ningún archivo, escribe TODO e
   indica en qué archivo lo esperabas. Nunca lo inventes.
6. Prohibido: revolucionario, fluido, potente, aprovechar, disruptivo.

Lo invocas como cualquier skill: lo nombras y lo apuntas al proyecto. Para un servicio pequeño en Next.js, la entrada relevante es el bloque de scripts:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start -p 8080"
  }
}

La salida esperada es un README cuya sección "Cómo ejecutarlo" diga exactamente npm run dev para trabajo local, y npm run build seguido de npm run start para producción, con el puerto anotado como 8080 porque es lo que dice el script de start. Si hubiera una variable como DATABASE_URL en .env.example sin valor por defecto, la sección de Configuración la listaría y marcaría ese valor faltante como TODO en vez de inventar "localhost:5432". Esa honestidad es justamente la función.

05 · Configuración y el detalle que de verdad importa

El skill lleva muy poca configuración, y es intencional. Las pocas opciones que vale la pena ajustar:

• Palabras prohibidas. Mantén una lista corta del vocabulario de marketing que nunca quieres ver. La mía: revolucionario, fluido, potente, aprovechar, disruptivo, desbloquear, potenciar.
• Conjunto de secciones. Si tu equipo se rige por un formato de README estándar, fija esos encabezados exactos para que todos los proyectos coincidan.
• Nivel de rigor en la verificación. Decide si un comando que no se puede verificar se convierte en un TODO (mi opción por defecto) o detiene el skill para consultarte. Para trabajo en solitario, el TODO es más rápido. Para docs en los que otros van a confiar, frenar y preguntar es más seguro.

Hay una segunda trampa, más silenciosa. El skill describe lo que existe, no lo que piensas construir. Si el archivo de entrada es apenas un stub, el README va a decir con honestidad que hace muy poco, y eso puede doler. Aguanta las ganas de dejar que el skill se ponga aspiracional. Un doc que coincide con el código de hoy es útil. Uno que coincide con tu plan a futuro es ficción con fecha de entrega.

Un skill redactor de docs no va a hacer tu proyecto más interesante de lo que es, y ese es justamente el punto. Te da documentación que se mantiene fiel porque sale de los archivos y se regenera sin esfuerzo cuando esos archivos cambian. Arranca con la definición de arriba, no negocies la regla de verificación y deja que el README le diga a quien lo lee la verdad sobre lo que está ejecutando.