Johan409IA/skills

Documentación del Proyecto

Ayuda a crear y mantener actualizado el conjunto completo de documentación de un proyecto de software, siguiendo una estructura fija y una relación establecida entre AGENTS.md y MEMORY.md. Úsalo cada vez que el usuario quiera generar documentación desde cero, actualizarla tras cambios, o mantenerla coherente entre archivos.

Estructura objetivo

Todo proyecto gestionado por esta habilidad debe converger hacia esta estructura:

mi-proyecto/
├── README.md          # qué es, cómo levantarlo
├── AGENTS.md           # reglas e instrucciones para agentes
├── MEMORY.md            # decisiones vigentes y lo descartado
├── CHANGELOG.md          # qué cambió entre versiones
├── DESIGN.md             # sistema de diseño visual (solo si hay UI)
└── docs/
    ├── architecture.md
    ├── plans/            # planes de los agentes, uno por archivo
    └── (OpenAPI + Scalar servido desde la API en /docs)

Si el proyecto ya tiene algunos de estos archivos, léelos primero y actualízalos in situ — no sobrescribas a ciegas. Si falta un archivo, créalo siguiendo la plantilla correspondiente.

Flujo de trabajo

1. Inspecciona lo que existe. Lista la raíz del proyecto y docs/ para ver qué archivos ya están. Lee cualquier AGENTS.md/MEMORY.md/CHANGELOG.md/README.md/docs/architecture.md existente por completo — por diseño son cortos.
2. Determina el alcance. Si el usuario nombra un archivo específico ("actualiza el CHANGELOG"), concéntrate ahí, pero comprueba si ese cambio debe repercutir en MEMORY.md o AGENTS.md (consulta la regla de propagación más abajo). Si el usuario dice algo general como "documenta mi proyecto" o "actualiza la documentación", recorre todos los archivos de la estructura anterior.
3. Recopila los datos que necesites del propio código base (manifiestos de paquetes, puntos de entrada, scripts, rutas, commits recientes) en lugar de suponer. No inventes comandos, detalles de pila o endpoints — verifícalos leyendo el código o los archivos de configuración.
4. Escribe o actualiza cada archivo usando la plantilla de referencia correspondiente. Mantén los límites estrictos de longitud en AGENTS.md (~30-40 líneas) y MEMORY.md (~50 líneas) — son restricciones importantes, no sugerencias, porque los agentes releen estos archivos cada sesión y las versiones infladas dejan de ser útiles.
5. Informa qué archivos se crearon vs. actualizaron, y señala cualquier cosa que no hayas podido verificar (p. ej., "no encontré un comando de test, confírmalo").

Los documentos

README.md

Responde "qué es esto y cómo lo ejecuto" para un humano. Consulta references/readme-template.md. Extrae los comandos de ejecución/instalación/test directamente de los scripts reales del proyecto (package.json, Makefile, pyproject.toml, etc.) — nunca adivines nombres de comandos.

AGENTS.md

Instrucciones para los agentes de codificación que trabajan en este repositorio. Consulta references/agents-template.md para las secciones exactas y su orden. Límite estricto: ~30-40 líneas en total. Si ya es más largo, tu trabajo al actualizarlo consiste tanto en recortar como en añadir — mueve cualquier cosa que parezca una decisión transitoria o una nota en curso a MEMORY.md y conserva solo las reglas duraderas aquí.

MEMORY.md

Memoria de sesión a sesión: qué es cierto ahora mismo, por qué se tomaron decisiones clave, qué se intentó y se descartó, qué sigue. Consulta references/memory-template.md. Límite estricto: ~50 líneas. Al actualizar, recorta activamente: elimina o comprime las entradas que ya no importan, en lugar de dejar que el archivo crezca indefinidamente.

Cómo se relacionan AGENTS.md y MEMORY.md (esta es la convención central — acertar):

• AGENTS.md debe contener una sección corta "Memoria" que indique a los agentes que lean MEMORY.md al comenzar una tarea y lo actualicen al finalizarla. Usa este texto exacto como base, adaptándolo solo si el proyecto ya lo redacta de otra forma:

  ## Memoria
  - Al empezar, lee `MEMORY.md` para conocer el estado del proyecto y las decisiones tomadas.
  - Al terminar una tarea, actualízalo: estado actual, decisiones importantes (con su porqué) y errores a evitar.
  - Mantenlo breve (máximo ~50 líneas): resume o elimina lo que ya no aporte.
  - Si algo se convierte en una regla permanente, propón moverlo a `AGENTS.md` en lugar de dejarlo en la memoria.
  - No guardes nunca datos sensibles (claves, tokens, datos personales).
  

• La sección "Límites" de AGENTS.md debe incluir ✅ Siempre: actualizar MEMORY.md al terminar cada tarea.
• Regla de propagación: MEMORY.md contiene cosas que son ciertas por ahora — estado actual, decisiones con su razonamiento, lecciones aprendidas, próximos pasos. AGENTS.md contiene cosas que son ciertas siempre — reglas permanentes, convenciones, pila tecnológica, límites. Cuando algo en MEMORY.md deja de ser una decisión puntual y se convierte en una regla establecida (p. ej., "decidimos no usar nunca X" pasa a ser "nunca uses X, punto"), muévelo a AGENTS.md y elimínalo de MEMORY.md. Al actualizar cualquiera de los dos archivos, comprueba siempre si debe ocurrir esta promoción.
• Nunca escribas secretos, tokens o datos personales en ninguno de los dos archivos.

CHANGELOG.md

Responde "qué cambió entre versiones". Sigue la convención Keep a Changelog (Added/Changed/Fixed/Removed bajo cada versión, la más nueva arriba, con una sección Unreleased al inicio para el trabajo en curso). Consulta references/changelog-template.md. Al actualizar, añade entradas bajo Unreleased a medida que avanza el trabajo, y solo crea una nueva sección de versión con fecha cuando el usuario indique un lanzamiento.

DESIGN.md

Responde "cómo se ve y cómo debe construirse la interfaz de usuario" — el sistema de diseño visual, leído por agentes que generan UI. Se encuentra en la raíz del proyecto (no en docs/), junto a AGENTS.md. Sigue el formato abierto Google Stitch DESIGN.md (especificación: github.com/google-labs-code/design.md, actualmente alpha). Consulta references/design-template.md para la plantilla y una explicación de cada bloque.

• Solo para proyectos con interfaz de usuario (web, móvil, escritorio). Si el proyecto es una API/CLI/biblioteca pura sin UI, no lo crees e indícalo en el informe.
• Dos capas: frontmatter YAML con tokens legibles por máquina (colors, typography, rounded, spacing, components) — estos son los valores normativos — más un cuerpo en markdown que explica el porqué. Los tokens dicen qué; la prosa dice cuándo y por qué y se refiere a los tokens por nombre en lugar de repetir códigos hexadecimales.
• El orden de las secciones es fijo: Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts. Mantén estos encabezados en inglés exactamente como están escritos (las herramientas los identifican por nombre; también se aceptan los alias Brand & Style, Layout & Spacing y Elevation) y escribe la prosa en el idioma del proyecto. Las secciones se pueden omitir pero no reordenar, y un encabezado duplicado es un error. Se permiten secciones adicionales (p. ej., Iconography & Imagery, Motion, Accessibility) — colócalas siempre después de Do's and Don'ts.
• Toma los valores del código, nunca los inventes: configuración de Tailwind, variables CSS (:root, globals.css), archivos de tema de la librería UI, fuentes cargadas, exportaciones de tokens de Figma/DTCG. Si el proyecto tiene UI pero aún no tiene una identidad visual definida, propón valores e indícalos en el informe como "propuesta, confirmar".
• Si ya existe un DESIGN.md, léelo y actualízalo in situ — nunca sobrescribas en silencio. Mantén los tokens sincronizados con el código cuando cambien los colores, fuentes o espaciados.
• Sin límite estricto de líneas (es un documento de referencia como docs/architecture.md), pero mantén cada sección centrada: 3–6 viñetas o un párrafo corto.
• Valida: si Node está disponible, ejecuta npx @google/design.md lint DESIGN.md y corrige errores (broken-ref) y advertencias razonables (missing-primary, contrast-ratio, section-order); de lo contrario, comunica al usuario el comando.
• Si AGENTS.md existe y no menciona DESIGN.md, sugiere al usuario (no lo apliques por tu cuenta) añadir una línea de referencia para que los agentes de UI lo lean antes de generar interfaz — ten en cuenta el límite de ~30-40 líneas de AGENTS.md.

docs/architecture.md

Responde "cómo está construido esto" — componentes, flujo de datos, decisiones de diseño clave y su porqué, restricciones notables. Consulta references/architecture-template.md. Este es el único documento que puede ser más extenso que los demás, ya que es un documento de referencia, no algo que se relea cada sesión — pero sigue favoreciendo diagramas y secciones cortas sobre prosa larga. Usa un diagrama mermaid para la vista principal de componentes/flujo de datos cuando sea útil.

docs/plans/

Cuando un agente produce un plan para una tarea no trivial (un plan de implementación de varios pasos, un plan de migración, un plan de refactorización), guárdalo aquí como un archivo independiente en lugar de dejarlo solo en el chat. Crea el directorio si no existe. Nombra los archivos YYYY-MM-DD-slug-corto.md (p. ej., 2026-10-03-add-payment-webhook.md) para que se ordenen cronológicamente. Cada archivo de plan debe ser autocontenido: objetivo, enfoque, pasos, preguntas abiertas. No elimines planes antiguos después de que se completen — son un registro histórico; si el proyecto quiere una marca de "completado", añade una línea de estado al inicio del archivo en lugar de eliminarlo.

Documentación de API — OpenAPI + Scalar

No son un archivo markdown estático — se sirven en vivo desde la API, típicamente en una ruta /docs o /reference a través del renderizador de referencia de API de Scalar que lee una especificación OpenAPI. Cuando se te pida configurar o actualizar la documentación de la API:

1. Verifica si el proyecto ya genera una especificación OpenAPI (decoradores/anotaciones del framework, un archivo openapi.yaml/openapi.json, o una librería de generación de especificaciones ya en las dependencias).
2. Si la especificación existe pero aún no se sirve mediante Scalar, conecta el middleware/manejador de Scalar para el framework del proyecto (Scalar tiene integraciones oficiales para la mayoría de los frameworks backend comunes — verifica los nombres/APIs de los paquetes actuales en lugar de asumir, ya que este ecosistema se mueve rápido) y móntalo en /docs.
3. Si aún no existe una especificación, genera una a partir de las rutas/manejadores existentes (la mayoría de los frameworks tienen una librería que deriva OpenAPI de las definiciones de rutas/tipos — prefiere eso sobre escribir YAML a mano) antes de conectar Scalar.
4. Nunca mantengas a mano un archivo OpenAPI YAML estático enorme si el framework puede derivarlo del código — eso se desincroniza de inmediato. Prefiere la generación desde el código.
5. Anota la URL /docs en README.md una vez configurada, para que los humanos sepan dónde encontrarla.

Lista de verificación antes de finalizar

• AGENTS.md tiene ≤ ~40 líneas e incluye una sección "Memoria" que apunta a MEMORY.md
• MEMORY.md tiene ≤ ~50 líneas y no hay nada permanente ahí que deba estar en AGENTS.md
• Los comandos de README.md se verificaron contra la configuración real del proyecto, no se asumieron
• CHANGELOG.md sigue el formato de Keep a Changelog con una sección Unreleased
• DESIGN.md (solo si el proyecto tiene UI) está en la raíz del proyecto, sus tokens coinciden con el código real, las secciones siguen el orden canónico y npx @google/design.md lint DESIGN.md no reporta errores
• docs/architecture.md refleja la estructura actual, no una desactualizada
• Los nuevos planes de agente se guardan en docs/plans/ con un nombre de archivo con fecha
• No se escribió nada sensible (claves, tokens, datos personales) en ningún documento