Annabellachildlike849/readme-skill

README Skill

Crea README precisos y legibles para GitHub, fundamentando cada afirmación externa en evidencia del repositorio o confirmación explícita del usuario. Establece el valor primero, proporciona una ruta rápida de uso y luego dirige a los lectores a documentación más detallada.

Reglas no negociables

• Los borradores se muestran en la conversación de forma predeterminada; no crees un archivo de borrador automáticamente.
• No crees ni modifiques README.md, README.zh-CN.md ni ningún otro README hasta que el usuario solicite explícitamente escribirlo o actualizarlo.
• Si el usuario desea un borrador guardado, usa la ruta de destino exacta que proporcione; de lo contrario, solicita una. No inventes un nombre de archivo de borrador.
• Nunca inventes comandos, API, enlaces, insignias, afirmaciones de rendimiento, promesas de compatibilidad, datos de lanzamiento, ubicaciones de la comunidad, términos de licencia, componentes de arquitectura, flujos de datos o propiedad del repositorio.
• Nunca expongas claves de API en el contenido del README, comandos confirmados en un repositorio, archivos fuente ni URL de imágenes. Los ejemplos solo pueden hacer referencia a variables de entorno.
• Cada borrador de README debe incluir una sección Quick Start que muestre la ruta verificada más corta desde la disponibilidad o instalación hasta un resultado útil. Si esa ruta no se puede verificar a partir de la evidencia del repositorio o de la confirmación del usuario, solicita los detalles faltantes del primer uso; no inventes, dejes vacía u omitas la sección.
• Cuando el primer escaneo de descubrimiento encuentre un README existente, detente y pide al usuario que elija un modo de manejo: 1) Reemplazar completamente — ignora toda la información del README existente; 2) Reemplazar con información existente seleccionada — reescribe conservando solo el contenido preciso aprobado por el usuario; 3) Extender el README existente — conserva el README existente y agrega o mejora el contenido en su lugar. No infieras el modo a partir de la solicitud original.
• Prefiere preguntas con múltiples opciones explícitas. Usa una lista seleccionable siempre que la decisión pueda anticiparse razonablemente; ofrece una opción libre "Otro" solo cuando las opciones disponibles no puedan cubrir la intención del usuario.
• Mantén una separación clara entre la información Verificada del repositorio, Confirmada por el usuario, Incierta y Faltante.
• No copies la redacción, comandos específicos del proyecto, marca o contenido de otro repositorio. Usa solo principios generales de arquitectura de la información y redacción.
• No uses emojis en los archivos README generados. Limita la guía visual a activos de imagen verificados, insignias y diagramas ASCII respaldados por el origen.
• Centra la banda de identidad del encabezado de forma predeterminada: visual opcional, nombre del proyecto, posicionamiento en una línea, cambio de idioma e insignias. Usa <h1 align="center"> para el título y un <p align="center"> separado para cada otro bloque. Todo desde el primer ## hacia abajo permanece alineado a la izquierda: nunca centres encabezados, prosa, tablas, listas, bloques de código o diagramas ASCII. Sigue el estándar de encabezado centrado en guía de estructura README.
• Incluye un diagrama de arquitectura solo cuando la evidencia del repositorio o el usuario confirme sus componentes, límites y relaciones. Los diagramas de arquitectura son arte ASCII en un bloque de text—nunca Mermaid.
• Incluye un ejemplo de uso solo cuando el usuario proporcione o confirme la prosa, imagen/activos, código o comandos, resultado esperado, colocación e idioma del ejemplo. No conviertas una idea no verificada en un ejemplo público.

Estándar de diagrama de arquitectura ASCII

Usa este estándar solo para una sección opcional ## de Arquitectura respaldada por el origen. Colócala inmediatamente después de Highlights y antes de un ejemplo de uso opcional. Nunca uses Mermaid, bloques de Mermaid o sintaxis de Mermaid.

Símbolos permitidos

cajas:       ┌─┐ │ └─┘
flechas:      ──▶  ◀──  ──▷  ↑ ↓ ←  →
línea doble: ═══  ║
etiquetas:    Coloca una etiqueta sobre o encima de una flecha, por ejemplo ──[HTTP]──▶

Ejemplos de diseño

Capa única:

┌─────────┐     ┌─────────┐     ┌──────────┐
│  Client │────▶│   API   │────▶│ Database │
└─────────┘     └─────────┘     └──────────┘

Agrupado o en capas:

┌─────────────────────────────────┐
│          Backend                │
│  ┌──────────┐  ┌─────────────┐  │
│  │   Auth   │  │  Business   │  │
│  │ Service  │  │   Service   │  │
│  └──────────┘  └─────────────┘  │
└─────────────────────────────────┘

Flechas etiquetadas:

┌─────────┐  REST/HTTPS  ┌─────────┐  SQL  ┌──────────┐
│  Client │─────────────▶│   API   │──────▶│ Postgres │
└─────────┘              └─────────┘       └──────────┘
                               │
                          gRPC │
                               ▼
                         ┌─────────┐
                         │  Cache  │
                         │ (Redis) │
                         └─────────┘

Reglas del diagrama

• Usa un bloque text para que GitHub conserve la alineación.
• Mantén los anchos de las cajas alineados y las cajas en la misma capa a la misma altura.
• Prefiere un diseño horizontal; cambia a vertical solo cuando la jerarquía lo requiera.
• Coloca las etiquetas de las flechas encima o sobre la línea de conexión.
• Dibuja solo componentes, límites y flujos verificados o confirmados por el usuario. Omite toda la sección cuando estos hechos falten.

Flujo de trabajo

1. Descubre primero los hechos del repositorio

Realiza un escaneo limitado. No leas todo el código base sin una razón específica del README.

1. Determina si el directorio es un repositorio Git; inspecciona la lista de archivos raíz y, cuando esté disponible, la URL remota configurada.
2. Lee las variantes existentes de README, LICENSE*, archivos de contribución y seguridad, más el índice de documentos.
3. Lee solo los manifiestos que están presentes, como package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml o metadatos equivalentes del lenguaje.
4. Inspecciona CI, configuración de lanzamiento/publicación, implementación, ejemplos y puntos de entrada públicos solo cuando sea necesario para verificar la instalación, el primer uso, la compatibilidad de la plataforma, la arquitectura, los ejemplos de uso o los enlaces de documentación.
5. Si existe alguna variante de README, pide al usuario que elija su modo de manejo antes de redactar:
   • 1) Reemplazar completamente: escribe un nuevo README sin usar ninguna información del README existente.
   • 2) Reemplazar con información existente seleccionada: escribe un nuevo README, conservando solo el contenido existente preciso que el usuario apruebe.
   • 3) Extender el README existente: conserva la estructura y el contenido preciso del README existente, luego agrega o mejora el contenido en su lugar.
6. Construye un registro de hechos antes de redactar:

Estado	Significado
Verificado del repositorio	Respaldado directamente por un archivo local, manifiesto, configuración de CI o remoto configurado.
Confirmado por el usuario	Proporcionado o aprobado explícitamente por el usuario.
Incierto	Plausible pero no seguro de afirmar públicamente sin confirmación.
Faltante	Necesario para una sección deseada pero no se puede descubrir.

Si no se puede verificar ningún repositorio remoto, dilo. No asumas un propietario, URL del repositorio, demostración pública, página de lanzamiento, comunidad, proveedor de alojamiento o arquitectura.

2. Carga solo la guía aplicable

• Antes de seleccionar secciones o redactar texto, lee la guía de estructura README.
• Cuando se soliciten o evalúen insignias, lee la guía de insignias.
• Cuando se soliciten imágenes, lee la guía de imágenes.
• Antes de presentar un borrador final y nuevamente antes de escribir archivos, lee la lista de verificación de calidad.
• Después de conocer el tipo de proyecto y el diseño del idioma, lee solo la(s) plantilla(s) relevante(s) en templates/.

3. Pregunta solo por decisiones que la evidencia no pueda responder

Haz una pregunta a la vez. Presenta la decisión como una lista de opciones explícitas cuando sea práctico; incluye una opción libre "Otro" solo cuando sea necesario. No repitas información ya verificada o respondida.

1. Si se encontró un README existente durante el descubrimiento, pide al usuario que elija el modo de manejo descrito anteriormente antes de preguntar sobre preferencias de contenido posteriores.
2. Pregunta por el diseño del idioma: Inglés, Inglés más Chino Simplificado, o Chino.
   • Para salida bilingüe, README.md es la página principal de GitHub en inglés y README.zh-CN.md es la versión en chino.
   • Para salida solo en chino, explica que GitHub muestra README.md raíz de forma predeterminada y pregunta si el chino debe ser la página principal.
3. Pregunta si el usuario desea recomendaciones de insignias de Shields.io.
   • Ofrece opciones explícitas como incluir recomendaciones verificadas, omitir insignias o Otro.
   • Si el repositorio contiene un archivo LICENSE* verificado, recomienda una insignia de Licencia estática vinculada de forma predeterminada como parte del conjunto de insignias verificadas; permite que el usuario la apruebe o la elimine.
   • Recomienda solo insignias cuyas afirmaciones y destinos sean verificables, luego permite que el usuario apruebe, elimine o agregue elementos.
4. Pregunta si se debe incluir un diagrama de arquitectura ASCII.
   • Ofrece incluir un diagrama ASCII respaldado por el origen, omitirlo o Otro.
   • Si se incluye, confirma los componentes, límites de grupo, relaciones y etiquetas a partir de la evidencia del repositorio o del usuario antes de dibujarlo.
5. Pregunta si se debe incluir un ejemplo de uso.
   • Ofrece incluir un ejemplo proporcionado, omitirlo o Otro.
   • Si se incluye, recopila la prosa, imagen/activos, código o comandos, resultado esperado, colocación preferida e idioma del ejemplo confirmados. Verifica las rutas de imagen locales antes de hacer referencia a ellas y nunca expongas credenciales.
6. Usa el encabezado centrado de forma predeterminada. Pregunta solo cuando el usuario solicite una apariencia diferente; ofrece encabezado centrado con HTML mínimo, encabezado Markdown simple alineado a la izquierda o Otro.
7. Pregunta si se desea imágenes.
   • Ofrece sin imagen, usar un activo existente o generar una nueva imagen.
   • Si es sí, pregunta si hay activos existentes disponibles.
   • Si no hay activos disponibles, pregunta si la imagen debe ser solo icono, icono más una línea corta, o icono más nombre del proyecto y una línea corta.
   • Si el usuario elige un servicio de imágenes de OpenAI, pregunta por la URL de la API y la clave de la API (o los nombres de las variables de entorno que ya los contienen) antes de generar cualquier cosa. No adivines un endpoint, modelo, formato de respuesta o ubicación de salida.
   • Usa scripts/generate-image.py para la solicitud de generación. Pasa las credenciales solo a través de variables de entorno o argumentos de proceso; nunca las escribas en el repositorio, README, prompt, URL de la imagen o comando confirmado en Git.
   • Verifica el activo local generado antes de agregar su ruta a un README. Si la generación falla, muestra el prompt neutral al proveedor e informa del error en lugar de inventar una referencia de imagen.
8. Pregunta si se debe agregar un gráfico de historial de estrellas.
   • Ofrece incluirlo, omitirlo o Otro.
   • Inclúyelo solo después de la confirmación del usuario y solo cuando se pueda verificar un identificador público owner/repo de GitHub desde la URL remota o proporcionado por el usuario.
   • Colócalo después de Comunidad y soporte e inmediatamente antes de Licencia.
   • Indica que incrusta un SVG dinámico de terceros para un repositorio público de GitHub; omítelo si el repositorio es privado, el owner/repo es incierto o el usuario lo rechaza.
9. Pregunta solo por la información pública restante que no se puede verificar: público objetivo, énfasis clave, sitio de documentación, demo, comunidad, ruta de contribución, FAQ, hoja de ruta, cita o política de seguridad.

4. Redacta el borrador

Usa la estructura y plantilla relevante, luego elimina cada sección no aplicable excepto Quick Start. Un Quick Start debe permanecer en cada borrador y usar la ruta de primer uso verificada más corta; si no existe tal ruta, pídele al usuario que la proporcione antes de presentar un borrador final. Prefiere una prosa breve y basada en evidencias y una experiencia de primera ejecución útil sobre listas de características exhaustivas.

Cuando se seleccione y admita, conserva este orden cerca del inicio de cada README:

Highlights → Architecture opcional → Usage Example opcional → Quick Install → Quick Start

Antes de cualquier escritura de archivo, presenta:

1. Una recomendación estructural concisa.
2. Borradores en Markdown completos para cada archivo de idioma seleccionado.
3. El registro de hechos y la lista de detalles confirmados por el usuario.
4. Las insignias propuestas y la fuente de datos de cada insignia.
5. El diagrama de arquitectura ASCII respaldado por el origen, cuando se solicite.
6. El contenido del ejemplo de uso, procedencia y colocación, cuando se solicite.
7. La colocación de imágenes y recomendaciones de generación, cuando se solicite.
8. La colocación del historial de estrellas y el owner/repo verificado, cuando se solicite.
9. Si ya existe un README, un resumen explícito keep / move / merge / remove.

5. Escribe solo después de la confirmación explícita

Una solicitud para redactar, mejorar, revisar o mostrar un README no es permiso para escribir archivos. Escribe solo después de que el usuario solicite explícitamente escribir, actualizar, reemplazar o guardar en rutas de destino nombradas.

Inmediatamente antes de escribir, indica cada archivo de destino y lo que cambiará:

• Inglés: README.md.
• Bilingüe: README.md y README.zh-CN.md.
• Chino: usa la ruta principal confirmada por el usuario.
• Borrador guardado: solo la ruta especificada por el usuario.

Para archivos existentes, conserva el contenido útil y aún preciso cuando sea posible. No descartes contenido en silencio; explica los movimientos, fusiones o eliminaciones importantes. Después de escribir, ejecuta la lista de verificación de calidad en los archivos reales.

Informe final

Usa este formato de resultado compacto:

Files changed:
- <ruta y propósito, o "None — draft shown in conversation only">

Verified:
- <hechos, comandos, rutas, enlaces o fuentes de insignias>

Needs confirmation:
- <información pública no verificada o comprobaciones manuales>

Not included:
- <secciones, insignias, imágenes o gráficos omitidos porque no estaban verificados o fueron rechazados>