rfdiosuao/AgentSkill

Craft Repository README

Convierte un repositorio en una página de destino clara y creíble. Base cada afirmación, comando, insignia y enlace en el proyecto real; el pulido visual nunca debe superar a la precisión.

Elige el modo de operación

• Usa el modo auditoría cuando el usuario solo solicite retroalimentación. Inspecciona e informa; no edites ni publiques.
• Usa el modo construcción cuando el usuario solicite crear o mejorar el README. Edita el repositorio y valida el resultado.
• Usa el modo publicación solo cuando el usuario solicite hacer commit, push, abrir una solicitud de extracción (pull request) o actualizar la configuración del repositorio. Sigue el flujo de trabajo Git normal del repositorio.

1. Inspecciona el proyecto real

Antes de redactar, inspecciona:

• Documentos README*, de contribución, seguridad, licencia, registro de cambios y despliegue existentes.
• Manifiestos de paquetes, puntos de entrada, archivos de entorno de ejemplo, comandos de prueba, capturas de pantalla, logotipos y URLs públicas.
• Git remote, rama predeterminada, etiquetas de lanzamiento, flujos de trabajo de CI y configuración de alojamiento.
• Instrucciones a nivel de repositorio como AGENTS.md o CONTRIBUTING.md.

Deriva el nombre del producto, la propuesta de valor en una oración, la audiencia, las plataformas compatibles, los comandos de instalación, los comandos de ejecución y la historia de despliegue a partir de la evidencia. Si un hecho material no se puede verificar, omítelo o márcalo claramente como planeado.

2. Realiza una verificación de alcance público y seguridad

Trata el trabajo del README como una revisión de lanzamiento. Antes de exponer detalles:

• Busca en los archivos rastreados y cambios preparados (staged) claves de API, claves privadas, tokens, contraseñas, cookies, nombres de host internos, IP privadas y rutas personales.
• Nunca pegues secretos de la configuración local, historial de chat, historial de shell o archivos de despliegue.
• Enlaza a .env.example; nunca reproduzcas valores de .env.
• Confirma que las capturas de pantalla, códigos QR, nombres y enlaces de contacto sean intencionalmente públicos.
• Conserva los avisos de licencia, marca registrada, atribución y activos de terceros.

Detente y menciona un bloqueador concreto si la publicación expusiera material sensible.

3. Diseña la historia antes de la decoración

Escribe el README para esta secuencia:

1. Reconocer — nombre, logotipo, promesa concisa.
2. Confiar — un conjunto pequeño de insignias veraces y una imagen real del producto.
3. Entender — qué hace, para quién es y su diferencia clave.
4. Probar — la ruta verificada más corta desde el clon hasta un resultado funcional.
5. Adoptar — configuración, despliegue, arquitectura, limitaciones y soporte.
6. Participar — contribución, seguridad, licencia, patrocinadores y comunidad.

Lee references/readme-patterns.md antes de reconstruir un diseño de README o seleccionar insignias.

4. Construye un encabezado compacto con marca

Usa este orden cuando el proyecto tenga los activos para respaldarlo:

1. Logotipo enlazado con texto alternativo descriptivo y un tamaño de visualización moderado.
2. Nombre del proyecto y propuesta de valor en una línea.
3. De cuatro a ocho insignias significativas.
4. Enlaces principales como demostración en vivo, documentación, rastreador de problemas o descarga.
5. Navegación dentro de la página opcional para un README extenso.
6. Una imagen principal impactante, captura de pantalla del producto o demostración corta.

Prefiere activos propiedad del repositorio bajo una ruta estable docs/, .github/ o assets/. Reutiliza un logotipo existente antes de generar uno nuevo. Si el usuario solicita un nuevo visual y hay disponible un skill de generación de imágenes, úsalo y luego optimiza el resultado para su visualización en el repositorio.

No uses insignias de compilación falsas, métricas de marcador de posición, muros de insignias gigantes, contadores decorativos ni activos enlazados en caliente que el proyecto no controle.

5. Selecciona solo las secciones útiles

Un proyecto compacto normalmente necesita:

• Qué es y por qué existe.
• Aspectos destacados de funcionalidades basados ​​en el comportamiento implementado.
• Guía de inicio rápido con comandos copiables y probados.
• Configuración utilizando marcadores de posición seguros.
• Capturas de pantalla o demostración cuando la evidencia visual ayuda materialmente.
• Notas de despliegue o producción cuando el proyecto se puede desplegar.
• Enlaces de contribución, seguridad, licencia y agradecimientos cuando esos archivos existan.

Agrega arquitectura, referencia de API, compatibilidad, hoja de ruta, preguntas frecuentes o solución de problemas solo cuando el proyecto lo justifique. No crees secciones vacías de relleno.

Para proyectos chinos, escribe en chino natural primero y conserva los identificadores técnicos en su forma original. Agrega una versión en inglés solo cuando se solicite o cuando el repositorio ya mantenga una.

6. Agrega patrocinio sin interrumpir la historia del producto

Cuando el usuario proporcione y autorice una imagen o código QR de patrocinador:

• Cópialo en una ruta de activos estable propiedad del repositorio.
• Usa un encabezado claro como 支持项目 o Patrocinador cerca de la parte inferior del README.
• Agrega texto alternativo, un ancho razonable y una oración que explique qué financia el soporte.
• Nunca alteres, decodifiques o regeneres un código QR de pago a menos que se solicite explícitamente.

No permitas que el patrocinio supere a la guía de inicio rápido, la documentación o la información de seguridad.

7. Verifica el README como documentación ejecutable

Ejecuta los comandos relevantes de compilación, prueba, lint o smoke del proyecto cuando sea práctico. Luego ejecuta el verificador incluido:

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md

Agrega banderas estrictas cuando los elementos correspondientes sean obligatorios:

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md \
  --require-logo --require-badges --require-hero --require-sponsor

También verifica manualmente:

• Cada comando de instalación y ejecución coincide con el repositorio.
• Las rutas relativas de imágenes y documentos se resuelven correctamente en las rutas sensibles a mayúsculas de GitHub.
• Los enlaces externos utilizan los dominios canónicos previstos.
• Los anclajes de encabezados y los enlaces de la tabla de contenido funcionan.
• Las imágenes tienen texto alternativo descriptivo y dimensiones razonables.
• El README se renderiza bien tanto en pantallas de escritorio como estrechas.
• No queda ningún secreto, marcador de posición, ruta absoluta local ni afirmación no verificada.

8. Publica deliberadamente

Cuando la publicación esté dentro del alcance:

• Revisa git diff y mantén los cambios no relacionados fuera del commit.
• Haz commit con un mensaje enfocado y realiza push a través del flujo de trabajo normal del repositorio.
• Prefiere una solicitud de extracción cuando las protecciones de rama o las prácticas de colaboración lo requieran.
• Actualiza la descripción de GitHub, la página de inicio, los temas y la vista previa social solo cuando el usuario haya solicitado cambios en la configuración del repositorio y los valores estén verificados.
• Vuelve a abrir el README renderizado en GitHub después de publicar y verifica imágenes, insignias, enlaces y diseño móvil.

Criterios de finalización

• La primera pantalla comunica nombre, propósito, señales de confianza y la siguiente acción principal.
• Todas las afirmaciones y comandos destacados están verificados contra el repositorio.
• Logo, imagen principal, insignias y contenido del patrocinador son intencionales en lugar de ornamentales.
• Los enlaces y activos locales se resuelven.
• No se expone ningún secreto ni detalle de entorno privado.
• La validación pasa y el paso de publicación solicitado está completo.