dianjing / 点睛

点睛

Para repositorios de código ya completos o próximos a su lanzamiento, realice el diseño visual y la decoración, transformando el repositorio de un simple "lugar para almacenar código" en una fachada de producto atractiva, creíble, comprensible, instalable y fácil de difundir.

Convierta un producto terminado en un repositorio público que otros puedan entender, en el que confíen, que puedan instalar, usar y estén dispuestos a difundir. Trate la estética, las animaciones y la credibilidad como una misma entrega de producto, no solo como modificar el texto del README o apilar imágenes decorativas.

Reglas inquebrantables

1. Primero verificar el producto, luego empaquetarlo. Confirme los límites reales del repositorio, el commit actual, el estado de ejecución, las funcionalidades, la licencia, los canales de publicación y los materiales existentes. No invente funcionalidades, métricas, reseñas de usuarios, compatibilidad o estados de publicación.
2. Primero auditar, luego modificar. Ejecute scripts/audit_repository.py, lea el punto de entrada del código fuente, la documentación del producto, el README existente, los activos y el estado de Git. Conserve las modificaciones existentes del usuario, no sobrescriba trabajo no relacionado.
3. El valor del producto antes que las instrucciones de instalación. El README debe responder primero "¿qué es, para quién, qué problema resuelve, cuál es su estado real?", luego pasar a la instalación, el primer éxito, la actualización y la resolución de problemas.
4. Priorizar los materiales reales. Priorice la reutilización de logotipos reales, capturas de pantalla del producto, grabaciones de pantalla de la interfaz y resultados de salida. El nuevo contenido visual generado solo debe explicar el producto real, no falsificar interfaces o capacidades que no existen.
5. Evaluar siempre las oportunidades de animación. Evalúe siempre si un Hero dinámico, GIFs de operaciones reales, videos de demostración y medios de Release son apropiados. Solo evalúe la creación de un sitio web de exhibición cuando el README no pueda soportar la experiencia clave. No asuma por defecto que solo se entregará un README estático, ni cree un sitio web por defecto para parecer más avanzado. Cuando la animación no mejore la comprensión, la confianza o la marca, documente la razón por la que no se adopta.
6. Las capacidades de la plataforma deben estar en capas. README, Social Preview, medios de Release y GitHub Pages son superficies diferentes. No trate el README como una página web donde se pueda ejecutar JavaScript, CSS o SVG animado arbitrariamente.
7. La estética debe ser usable. Las animaciones no deben retrasar la información clave. Proporcione un primer fotograma estático y soporte prefers-reduced-motion. Verifique en dispositivos móviles, fondos claros y oscuros, tamaño de archivo, ciclo de animación y licencia.
8. Separar el núcleo de la capacidad de la capa de distribución. El código fuente del producto, la Skill, los plugins, los instaladores, el sitio web oficial y la configuración del marketplace solo deben escribirse cuando existen realmente. Evite crear una segunda copia de la implementación central que pueda desviarse.
9. Expresar el estado de publicación según la evidencia. Separe el estado "completado localmente", "enviado a remoto", "Tag", "Release", "instalable", "primer uso", "verificación de comportamiento real" y "estado en el directorio/tienda oficial".
10. No autorizar acciones remotas automáticamente. Las solicitudes de decoración local permiten modificar archivos dentro del repositorio de destino. El envío (push), la creación de Releases, la modificación de la configuración del repositorio, la subida de Social Preview, la habilitación de Pages o el despliegue aún requieren una solicitud explícita del usuario.

Flujo de trabajo

1. Definir la entrega y los permisos

Confirme el repositorio de destino y el punto final de esta ronda:

• Solo entregar un plan de decoración
• Completar la decoración del repositorio local
• Añadir un README dinámico
• Evaluar y construir un sitio web de exhibición según sea necesario
• Preparar el lanzamiento sin enviar (push)
• Completar el lanzamiento remoto y la aceptación pública

Si el usuario dice "decorarlo" o "hacerlo directamente", por defecto complete una implementación y verificación local segura; no envíe (push) ni modifique la configuración remota por ello.

2. Auditar el repositorio real

Ejecute:

python3 <skill-dir>/scripts/audit_repository.py <repo-path>

Luego lea audit-and-positioning.md y verifique:

• Directorio raíz de Git, remoto, rama/commit actual, modificaciones del área de trabajo
• Punto de entrada real del producto, capacidad de ejecución, licencia, versión y canales de publicación
• README, docs, archivos de gobernanza, pruebas y registros de Release
• Logotipos, capturas de pantalla, grabaciones de pantalla, GIFs, videos, imágenes sociales y sitio web oficial existente
• Rutas absolutas locales, texto de relleno, enlaces relativos rotos y archivos sospechosamente sensibles

No diagnostique "no es un repositorio git" directamente como un fallo de publicación; primero localice el checkout real. No modifique la lógica del producto no autorizada por el usuario.

3. Crear un briefing de decoración del repositorio

Extraiga de los materiales reales:

• ¿Qué le entrega el usuario al producto?
• ¿Qué logra el producto?
• ¿Qué obtiene finalmente el usuario?
• ¿Para quién es más adecuado y para quién no?
• Un punto de diferenciación más fuerte
• Estado real actual y límites importantes
• La personalidad que se desea transmitir
• La definición del primer éxito

Cuando necesite documentar, copie y complete repository-brief-template.md. Si falta una dirección de marca, tome decisiones claras basadas en el producto mismo, evitando devolver todas las decisiones de diseño al usuario.

4. Seleccionar la base obligatoria y los módulos condicionales

Primero complete la base que todo repositorio público necesita, luego seleccione módulos según la tarea del producto. No confunda la cantidad de módulos con el grado de finalización o sofisticación.

Base obligatoria:

• Posicionamiento del producto y límites reales
• Arquitectura de información del README
• Instalación y primer éxito
• Materiales visuales reales
• Licencia, versión y estado de publicación
• Gobernanza básica y aceptación pública

Módulos condicionales:

Módulo	Condición de adopción
Expresión dinámica	Un Hero dinámico, GIF de operación real o video mejora significativamente la comprensión, la confianza o el reconocimiento de marca
Sitio web de exhibición	El README no puede soportar interacciones clave, experiencia visual, conversión de no desarrolladores o demostraciones en línea, y no existe un sitio web oficial reutilizable
Publicación y difusión	El producto realmente ha entrado en la fase de lanzamiento de versiones, compartición externa o difusión continua, y necesita Social Preview, medios de Release, entrada bilingüe o guía de actualización/solución de problemas
Documentación profunda	La instalación, API, configuración o mantenimiento son tan complejos que el README ya no es adecuado como única documentación

El sitio web de exhibición es una entrega condicional, no un nivel superior de decoración. Las Skills de agente, CLI, SDK y bibliotecas pequeñas suelen tener el README como página principal; los productos de UI, juegos, codificación creativa, demostraciones interactivas o productos orientados a no desarrolladores tienen más probabilidades de necesitar un sitio web de exhibición. Cuando el producto ya tiene un sitio web oficial, priorice conectar y reutilizarlo, no cree un GitHub Pages duplicado.

5. Diseñar el README y la documentación

Lea readme-and-documentation.md. Organice según el camino de comprensión del usuario:

Entender el producto
→ Establecer la motivación de uso
→ Ver evidencia real
→ Entender las capacidades y límites
→ Instalar
→ Lograr el primer éxito
→ Solucionar problemas y actualizar
→ Conocer las pruebas, el mantenimiento y la licencia

No aplique plantillas mecánicamente. CLI, bibliotecas, aplicaciones, sitios web, Skills/plugins y proyectos de investigación deben elegir diferentes caminos de demostración, instalación y primer éxito. Cuando necesite un esqueleto, copie readme-outline-template.md y luego modifíquelo según el producto.

6. Diseñar el sistema visual y de animación

Lea visual-and-motion.md. Primero haga un inventario de los activos reales, luego determine un lenguaje de color, fuente, composición, iconos y animación propio del producto.

Si motion-anything-design está disponible, primero debe:

1. Leer el bundle actual.
2. Buscar un sistema de diseño adecuado para la personalidad del producto.
3. Buscar animaciones reales con implementation_status: ready.
4. Leer avoid_when, restraint, reduced_motion, dependencias y licencia de las animaciones seleccionadas.
5. Obtener los archivos de implementación reales antes de adaptarlos; no reescribir implementaciones existentes de memoria.
6. Buscar y obtener SVG de iconos precisos.

Si necesita un nuevo logotipo, Hero o ilustración, primero reutilice los activos de marca existentes. Si realmente es necesario generarlos, use la capacidad de generación de imágenes disponible, basándose en capturas de pantalla reales del producto y la interfaz.

Cada repositorio debe completar al menos una auditoría de oportunidades de animación:

• ¿Puede un Hero de marca dinámico explicar el producto más rápido?
• ¿Es un GIF de operación real más efectivo que múltiples capturas de pantalla?
• ¿Necesita el Release un video corto?
• ¿Ya no puede el README soportar la experiencia clave? Si es así, ¿merece el sitio web oficial existente o el sitio de exhibición albergar interacciones, flujos y CTA?
• ¿Funcionan el primer fotograma estático, el estado sin animación y los fondos claro y oscuro?

7. Implementar la fachada del repositorio

Trabaje dentro de la pila tecnológica y las convenciones existentes del repositorio de destino:

• Modifique el README y la documentación necesaria
• Reutilice o cree medios visuales reales
• Añada docs/, guías de inicio, solución de problemas, mantenimiento y notas de lanzamiento según sea necesario
• Solo después de pasar la puerta condicional del sitio web de exhibición, añada el código fuente de Pages y la configuración de despliegue según sea necesario
• Mantenga el código fuente central del producto único, no duplique la implementación para la exhibición
• Use enlaces relativos, evite rutas locales
• No incluya claves, cookies, enlaces privados, material no autorizado o licencias incompatibles

La elección de animaciones debe seguir "una animación, una tarea narrativa". Por defecto, como máximo un efecto de fondo ambiental, un efecto de texto principal y un efecto de celebración/destacado por pantalla; el cuerpo del texto y las operaciones clave deben permanecer estables.

8. Verificar el resultado local

Vuelva a ejecutar el script de auditoría y revise el diff de Git. Luego:

• Renderice el README, verifique el orden de lectura en escritorio y pantalla estrecha
• Abra realmente todas las imágenes, GIFs y videos
• Verifique el primer fotograma del GIF, la costura del bucle, los subtítulos y el tamaño del archivo
• Si se adoptó el módulo de sitio web de exhibición, realice una aceptación en el navegador para Pages o el sitio web oficial existente: diseño responsivo, modo claro/oscuro, interacciones, consola, rendimiento, 404
• Active la preferencia de movimiento reducido, confirme que el contenido es inmediatamente visible y que la funcionalidad no se pierde
• Verifique todos los enlaces relativos, comandos de instalación, versión, licencia y estado real
• Confirme que no se han sobrescrito modificaciones no relacionadas del usuario

9. Verificar el artefacto público

Después de que el usuario autorice la publicación, lea release-and-acceptance.md. Realice un checkout completamente nuevo desde el repositorio público o Tag, y vuelva a verificar el README, los medios, el sitio web de exhibición adoptado, la instalación, el primer éxito y la ruta de actualización.

Reporte por separado:

• Decoración local completada
• Código fuente remoto visible
• Tag/Release publicado
• Social Preview / sitio web de exhibición adoptado ya efectivo
• Primer éxito del usuario verificado
• Partes no completadas o solo confirmadas oralmente por el usuario

Cuando necesite un registro formal, copie acceptance-report-template.md.

Condiciones de parada

• No se puede confirmar el estado real del producto: primero reporte las brechas de evidencia, no use elementos visuales para ocultar problemas.
• Faltan imágenes reales del producto: se pueden crear materiales de marca y estructura, pero no falsificar capturas de pantalla del producto.
• Las animaciones y el README son incompatibles: priorice convertirlas en GIFs o videos; solo pase a Pages cuando se cumpla la puerta condicional del sitio web de exhibición, no afirme que el README ejecutará scripts no soportados.
• Las modificaciones existentes del área de trabajo entran en conflicto con los archivos de decoración: conserve las modificaciones del usuario y explique el conflicto, solicite dirección si es necesario.
• Se requiere enviar (push), desplegar, usar material de pago o modificar la configuración remota sin autorización: deténgase después de completar la parte entregable local.