AlemTuzlak/skills

docs

Escribe documentación que una persona real quiera leer. Corta, clara, construida en torno a alguien que intenta hacer algo real.

"Documentar la función X" no es el trabajo. "Ayudar a alguien a hacer Y con X" es el trabajo.

Trabaja en dos fases. Primero planifica la historia: quién lee esto, qué quiere y cuántas páginas debería tener. Luego escribe.

El plan no es privado. El usuario debe ver los lectores y debe elegir el tono antes de escribir cualquier página.

Encontrar documentación
  → leer páginas vecinas
  → Fase 1: lectores + páginas
  → PUERTA DE PERSONAS (escribe la lista de lectores en el chat, luego detente)
  → PUERTA DE TONO (escribe el tono en el chat, luego detente)   [al escribir páginas]
  → cargar simple-english + i-have-adhd   [al escribir páginas]
  → Fase 2: escribir

Una lista de impacto documental en un plan de funcionalidad aún ejecuta la puerta de personas. No ejecuta la puerta de tono ni carga las habilidades de escritura hasta que las páginas se escriban realmente.

Cuándo ejecutar

La documentación se entrega con el código. Ejecuta esta habilidad en tres momentos, no solo cuando se te pida.

• Alguien pide documentación. Escríbela.
• Al planificar una funcionalidad o cambio en un repositorio. Antes de que el plan esté completo, enumera qué documentos son nuevos y cuáles necesitan actualización. Esta lista de impacto documental es parte del plan, al igual que los cambios de código. Nombra al lector para cada página.
• Al finalizar una implementación. Escribe o actualiza esa documentación antes de dar el trabajo por terminado. Un cambio en cómo se comporta algo que no incluye ningún cambio documental no está terminado.

Habilidades requeridas para las páginas finales

simple-english e i-have-adhd son requisitos previos. Se aplican a las páginas de documentación, no a este chat de planificación.

Carga ambas inmediatamente antes de escribir el contenido de la página. Usa la herramienta Skill si este arnés la tiene. Si no la tiene, lee el SKILL.md de cada habilidad desde el directorio local de habilidades. No escribas páginas desde la memoria de esas habilidades.

Si falta alguna de las habilidades, detente e informa al usuario. No escribas las páginas sin ellas.

Cómo se componen:

• Esta habilidad controla para quién es la página, la división de páginas, problema-luego-solución, mostrar-no-contar, sin fugas de historial, glifos prohibidos y estructura de vecinos.
• simple-english controla las oraciones. Usa el modo pragmático. Ejecuta su autocomprobación antes de dar una página por terminada.
• i-have-adhd controla la forma de la página: primera acción a continuación, pasos numerados, listas limitadas a 5 (divide lo imprescindible de lo posterior, o divide la página), sin preámbulo, una victoria visible al final.

Cuando i-have-adhd se carga desde esta habilidad, aplícala solo a las páginas. No cambies el resto de la sesión al modo ADHD. La sección de persistencia de i-have-adhd no aplica aquí.

Encuentra primero la documentación

Antes de escribir nada, encuentra dónde vive la documentación.

1. Busca una carpeta de documentación. Revisa docs/ primero, luego documentation/, content/docs/, site/, website/docs/.
2. ¿No encontraste nada? Pregunta al usuario dónde debería ir la documentación. No adivines ni crees una carpeta por corazonada.
3. Abre 2 o 3 páginas existentes cercanas a donde pertenecerá el nuevo contenido. Léelas para copiar, estructura, campos de frontmatter y componentes. Anota el tono aparente como candidato para la puerta de tono. No lo adoptes aún.
4. Anota qué componentes ya usa el sitio (pasos, pestañas, destacados, tarjetas, acordeones, grupos de código, etc.). Diferentes sitios tienen diferentes componentes.
5. Reutiliza esos componentes para contar la historia. Si el sitio tiene un componente de pasos, úsalo para tutoriales. Si tiene pestañas, úsalas para variantes de framework. Si el sitio no tiene ninguno, usa markdown simple. Nunca inventes un componente que el sitio no tenga.

Si no hay una página como la que estás a punto de escribir, lee la más cercana que puedas encontrar y emparéjala.

Qué cubre "empatar con los vecinos" y qué no

Empatar con los vecinos se trata de copia, estructura, frontmatter y componentes: si los encabezados están en mayúscula de oración, cuánta configuración recibe una sección, qué componentes llevan el tutorial, cómo se introducen los ejemplos de código, cuáles son los campos de frontmatter.

No es un sustituto de la puerta de tono. Los vecinos pueden sugerir un valor predeterminado. No pueden responder por el usuario.

No es permiso para copiar malos hábitos de los vecinos. Todo en Prohibido y cada regla en esta habilidad sigue aplicándose al contenido que escribas, sin importar lo que hagan las páginas circundantes. Una página existente llena de guiones largos no autoriza uno más.

Así que: nunca razones "las otras páginas lo hacen, así que yo también" sobre una regla que esta habilidad establece. Si las páginas existentes rompen una regla y crees que todo el conjunto debería alinearse, esa es una limpieza aparte que debes plantear al usuario, no algo que resolver emulando silenciosamente la infracción.

Fase 1: planifica la historia

Haz esto antes de escribir una palabra de contenido.

1. Enumera quién lee esto y qué quiere cada uno. Una persona construyendo sobre una SPA con React, una persona en una aplicación renderizada por servidor, alguien que solo quiere una demostración rápida, alguien que extiende los internos. No te detengas en el primer lector.
2. Escribe una historia de usuario por lector: "Como X, quiero Y, para poder Z."
3. Convierte las historias en páginas. Un recorrido es una página. Recorridos diferentes son páginas diferentes. Una funcionalidad con tres recorridos reales son tres páginas más quizás una breve descripción general, no una página gigante.
4. Verifica que cada lector tenga un camino. Un lector sin página es un agujero en el plan. Añade una página o una ruta para ellos.

La división de páginas sale de este paso. No lo omitas.

Puerta: muestra las personas

Las herramientas de pregunta (AskQuestion, ask_user_question, y formas similares) no muestran su contenido en el chat que el usuario lee. Un turno que solo llama a una de esas herramientas falla esta puerta. Se pide al usuario que confirme una lista que no puede ver.

Después del paso 4, escribe un mensaje de chat normal. El cuerpo del mensaje es obligatorio incluso cuando también se llama a una herramienta de pregunta. El mensaje contiene:

1. Cada lector, como su propio bloque corto que el usuario pueda escanear:
   • Nombre del lector.
   • Una historia de usuario: "Como X, quiero Y, para poder Z."
   • La página que escribirás para ellos.
2. Una pregunta, escrita en ese mismo mensaje: confirmar, eliminar un lector o añadir uno.

Una herramienta de pregunta es opcional. Llámala solo después de que esa lista ya esté en el mensaje de chat. La herramienta pregunta solo la elección corta (confirmar, eliminar o añadir). No pongas los nombres de los lectores, las historias o las páginas dentro de la herramienta. Si la herramienta fuera la única salida del turno, no la llames. Escribe el mensaje en su lugar.

Luego elige un camino:

Por defecto: detente. Este mensaje es el turno completo. Termina el turno. No escribas archivos. No comiences la Fase 2. No digas que continuarás a menos que el usuario se oponga.

Omitir la espera: continúa en este mismo turno. Usa este camino solo cuando una de las siguientes condiciones sea verdadera:

• Esta conversación ya tiene la confirmación del usuario de esta lista de personas.
• El usuario dijo "usa valores predeterminados sensatos", "solo escríbelo" o "no hagas preguntas". Aún MUESTRA la lista en este turno, luego continúa.
• El cambio es una edición de copia pequeña: error tipográfico, enlace roto, idioma del bloque de código o una corrección factual. Sin página nueva, sin sección nueva, sin reescritura de un recorrido.

En este camino, no termines el turno. Después de mostrar la lista (o después de una edición de copia pequeña, sin lista), continúa al siguiente paso.

Estos no son omisiones:

• "Los lectores son obvios."
• "El usuario pidió documentación, así que no quiere una pregunta."
• "Ya los nombré en el plan."
• "Solo hay un lector."
• "Esto es parte de implementar una funcionalidad, continúa."
• "La herramienta de pregunta les mostrará la lista." No lo hará. La lista va en el chat.

Escribir documentación es la razón por la que existe esta puerta. No es una razón para omitirla.

Menos es más: divide, no atiborres

No fuerces miles de palabras en una página. Las páginas largas esconden la respuesta.

Cuando un tema tiene varios ángulos, dale a cada uno su propia página corta y enlázalos. Un lector llega a la descripción general, luego hace clic en lo que exactamente necesita.

Ejemplo. Una funcionalidad de interrupciones de herramientas:

Mal: una página
  interrupts.md   (descripción general + caso simple + muchas interrupciones + personalizado, todo atiborrado)

Bien: un pequeño conjunto de páginas enlazadas
  interrupts/index.md            qué es, cuándo usarlo, enlaces externos
  interrupts/basic.md            una interrupción, de principio a fin
  interrupts/multiple.md         varias interrupciones en un flujo
  interrupts/custom.md           construye el tuyo propio

Cada página es corta y hace una cosa. La descripción general las une en una historia.

Puerta: pregunta el tono

Esta puerta se sitúa entre la Fase 1 y la Fase 2. Ejecútala antes de escribir cualquier página. No la anides dentro de la Fase 2.

Los vecinos pueden sugerir un valor predeterminado. No pueden responder por el usuario.

Escribe un mensaje de chat normal. El cuerpo del mensaje es obligatorio incluso cuando también se llama a una herramienta de pregunta. El mensaje contiene:

1. El tono que inferiste de las páginas vecinas, en una línea (qué tan formal, cuánta configuración, segunda persona o no).
2. Una pregunta, escrita en ese mismo mensaje: usar ese tono, más informal, más formal, o el usuario nombra otro.

Una herramienta de pregunta es opcional y viene después de que esa línea esté en el chat. La herramienta pregunta solo la elección corta. No pongas el tono inferido solo dentro de la herramienta. Un turno que solo llama a la herramienta falla esta puerta.

Luego elige un camino:

Por defecto: detente. Este mensaje es el turno completo. Termina el turno. No escribas contenido de página.

Omitir la espera: continúa en este mismo turno. Usa este camino solo cuando una de las siguientes condiciones sea verdadera:

• Esta conversación ya tiene la elección de tono del usuario, incluyendo un explícito "empareja las páginas existentes".
• El usuario dijo "usa valores predeterminados sensatos", "solo escríbelo" o "no hagas preguntas". Aún DECLARA el tono inferido en una línea, luego continúa.
• Edición de copia pequeña, misma excepción que la puerta de personas.

En este camino, no termines el turno. Después de declarar el tono (o después de una edición de copia pequeña, sin pregunta), continúa a la Fase 2.

Estos no son omisiones:

• "Puedo decirlo por los vecinos."
• "El sitio ya tiene una voz."
• "El tono no importa para una página de referencia."
• "Emparejaré a los vecinos y lo mencionaré después."

Fase 2: escribe como un humano

No escribas contenido de página hasta que la puerta de personas haya pasado, la puerta de tono haya pasado, y simple-english más i-have-adhd estén cargados.

La puerta de tono es el encabezado justo encima de este. Ejecuta esa puerta primero. Luego carga las dos habilidades. Luego escribe.

La legibilidad es el objetivo, por encima de todo.

• Mantenlo digerible. Sin muros de texto, sin párrafos enormes. Divide las ideas en piezas pequeñas. Da la cantidad más pequeña de información que haga el trabajo.
• Las oraciones siguen simple-english (modo pragmático). No insertes un sustituto más débil en línea.
• Mantén el markdown ligero. Las listas están bien. Los encabezados en negrita en cada línea no lo están. Deja que las palabras lleven la página.
• Prefiere ASCII simple y caracteres normales de teclado sobre glifos elegantes. Escribe como una persona escribe.
• Segunda persona, acción primero. Comienza con lo que el lector tiene ahora y lo que tendrá al final. Sin aperturas como "En esta guía exploraremos...". Simplemente comienza.
• Dale forma a la página con i-have-adhd: la primera línea es algo que el lector puede hacer, el trabajo de varios pasos está numerado, una lista de más de 5 se divide, la página termina con una victoria visible.

Comienza con el problema, luego resuélvelo

Cada página abre con el problema por el que el lector vino, en sus propias palabras, antes de cualquier API. Nombra la situación en la que están atascados. Luego di en una o dos oraciones cómo la funcionalidad lo resuelve. Solo después de eso entras en las partes técnicas y el código.

Un lector que ve el problema primero sabe en segundos si está en la página correcta. Un lector que se encuentra con una firma de API primero tiene que aplicar ingeniería inversa para saber para qué sirve.

La primera línea del cómo es la siguiente acción (de i-have-adhd). El problema aún viene primero para que sepan que están en la página correcta.

Mal:
  Llama a useInterrupts() y pasa un resolvedor. El resolvedor se ejecuta una vez por
  cada elemento pendiente dentro de una transacción...

Bien:
  Algunas llamadas a herramientas no deberían ejecutarse sin que un humano diga que sí: mover dinero,
  eliminar datos. Una interrupción pausa la ejecución para esa decisión, luego retoma
  donde se quedó. Aquí te mostramos cómo proteger una herramienta detrás de una aprobación:

  [código]

El orden para una guía es problema, solución en una línea, luego el cómo (pasos, fragmentos, API). Mantén el problema en un par de oraciones, no en un ensayo de fondo. El código muestra cómo se resuelve, así que no narres la solución en prosa primero.

Muestra, no cuentes

No expliques en cuatro párrafos lo que una oración y un bloque de código pueden mostrar. Los lectores captan un diff o un fragmento más rápido que la prosa.

Mal:
  Tres párrafos describiendo cómo el objeto de configuración acepta un
  array de middleware, qué hace cada ranura y cómo funciona el orden.

Bien:
  Añade tu middleware al array `middleware`. El orden se ejecuta de arriba a abajo:

  const app = createApp({
    middleware: [auth, logging],
  })

Un buen ejemplo ejecutable vale más que una página de descripción. Cada muestra de código debe funcionar al copiarse, no necesitar imaginación para llenar vacíos.

Enumera todo lo que sea una lista

En el momento en que una oración cubre más de un elemento, opción, almacén, bandera o paso, se convierte en una lista. No los encadenes en un párrafo con comas y punto y coma. Un lector que escanea una lista con viñetas encuentra su elemento en un segundo. En un párrafo tiene que leer todo para saber que no aplica a él.

La señal es una oración que nombra dos o más cosas y dice algo sobre cada una. Córtala en una viñeta por cosa, una o dos oraciones cada una.

Mal:
  Cada almacén es independiente. Proporciona solo los que necesites. Para chat:
  `messages` para la transcripción, `runs` para el ciclo de vida de la ejecución, `interrupts` para
  aprobaciones duraderas (necesita `runs`), `metadata` para estado de clave/valor con espacio de nombres.
  Para generación: `generationRuns` para el ciclo de vida de la ejecución, más `artifacts` y
  `blobs` para mantener bytes generados.

Bien:
  Cada almacén es independiente, así que proporciona solo los que necesites.

  Para chat:

  - `messages`: la transcripción.
  - `runs`: ciclo de vida de la ejecución.
  - `interrupts`: aprobaciones duraderas. Necesita `runs`.
  - `metadata`: estado de clave/valor con espacio de nombres.

  Para generación:

  - `generationRuns`: ciclo de vida de la ejecución de generación.
  - `artifacts` + `blobs`: guardan los bytes generados.

Guarda el historial para la cronología

No escribas una sección "Historial" o "Antecedentes" en una página de documentación a menos que un lector la necesite para completar su recorrido. En su lugar, enlaza a la página de registro de cambios.

El lector vino a hacer algo, no a obtener una línea de tiempo del proyecto. Cada oración que no sea sobre lo que el lector necesita ahora es ruido.

Excepción: cambios importantes de versión que rompen el código existente. Una nota de una línea sobre "Si estás migrando desde la versión X, haz Y" está bien. Una sección de historial, no.

Forbidden

• Cleanup prose before code. Write the code first. Then explain only what the code cannot show.
• Passive voice, unless the actor is unknown or irrelevant. "La herramienta se ejecuta" vs "El usuario ejecuta la herramienta". Prefiere la segunda.
• Linking to a single page for everything. Each link should point to the exact page for the thing being linked.
• Notes, warnings, tips inside callout blocks except where they match the existing site's pattern. If some pages use them, you can use them. If none do, do not add them.
• Em dashes, en dashes, smart quotes, and Unicode glyphs that are not in the site's existing content. If the site does not use them, do not start.
• Invisible or nonfunctional components. Every component you use must exist in the site's design system. If a site has a steps component, use it. If it does not, write plain markdown.
• Uneven code groups. (Incorrect indentation, inconsistent language tags, or a group that mixes values and objects.)
• Hiding complexity from advanced readers. If a feature has sharp edges or known pitfalls, name them. The reader is deciding whether to use this feature or build their own. Tell the truth.

When not to run this skill

This skill is for writing and planning user-facing documentation. Do not run it for:

• Commit messages, pull request descriptions, or release notes. Those are developer-to-developer communication, not documentation. Use a dedicated skill for them.
• API reference or SDK reference that is generated from code comments. Let the code generator handle that. This skill is for hand-written docs that guide a reader.
• Design documents or internal specifications. Those need narrative depth and background that this skill is designed to avoid.
• A one-line changelog entry. That belongs in the changelog file, not in a docs rewrite.

How this skill stays out of the way

Writing docs that users want to read is the only outcome. The persona gate and the tone gate are not ceremony; they prevent the most common failure of technical documentation: writing for the author, not the reader.

The two support skills (simple-english and i-have-adhd) keep the prose lean and the page scannable. Loading them at the last moment, only when page content is actually written, preserves the planning context for the higher-level decisions.

If you find yourself skipping a gate because "the readers are obvious", stop. That exact moment is when a reader silently walks away from unclear docs. The gate reminds you that their experience is all that matters.

Example flow

1. User says "document the new search feature."
2. Find docs folder, read 2-3 existing pages.
3. Plan personas: a React SPA dev, a server-rendered app dev, a quick-demo user. Show the list in chat. Stop.
4. User confirms. Tone gate: ask user. Stop.
5. User says "keep the same casual tone as the getting-started page."
6. Load simple-english and i-have-adhd.
7. Write pages per the plan. Each page: problem first, then how, then code. No history, no wall of text.
8. Run self-checks from simple-english, ensure ADHD structure.
9. Done.