georgelu-creator/diagram-skills

DiagramSkills

Convierte una solicitud de diagrama en un entregable visual terminado con el renderizador DiagramSpec incluido. El producto principal es la calidad del diagrama generado por el agente: crear JSON mantenible, renderizar SVG/HTML y PNG opcional, inspeccionar el visual, corregir la fuente y devolver el resultado. No obligues al usuario a abrir un editor para terminar el trabajo ordinario. El id público del Skill es $diagram-skills; la marca visible para el usuario es DiagramSkills.

Flujo de entrega predeterminado

1. Para trabajo de prosa a diagrama o una revisión sustancial, crea un .brief.json conciso a partir de templates/briefs/diagram-brief.json. Registra el objetivo, la narrativa, el alcance, la priorización, la incertidumbre, los riesgos de contenido y las preguntas de revisión—no el razonamiento interno privado.
2. Lee el perfil seleccionado en references/diagram-thinking-profiles.json, personaliza al menos tres preguntas de calidad y ejecuta diagram_brief.py ... --strict antes de dibujar.
3. Para una vista en capas con más de 14 conceptos visibles, lee references/enterprise-board.md y usa layout: board. Para grafos de relaciones más pequeños, usa nodos/aristas.
4. Comienza desde la plantilla correspondiente, reemplaza su contenido de ejemplo y mantén el breve y el JSON fuente junto a las salidas.
5. Ejecuta png-backend antes de solicitar PNG, luego ejecuta render ... --strict con --png solo cuando haya un rasterizador local compatible disponible. Un archivo fuente por sí solo no es una solicitud visual completada.
6. Inspecciona el SVG generado o el PNG de 1920 píxeles a tamaño completo. Verifica jerarquía, texto en chino, consistencia de iconos, recortes, tarjetas apiñadas, cruces de líneas y si la narrativa del breve es visualmente dominante.
7. Responde cada pregunta de calidad del breve con evidencia concreta y distinta y ejecuta diagram_brief.py ... --spec ... --strict --reviewed. Luego vincula el breve revisado, la fuente y el SVG o PNG inspeccionado en el recibo de calidad con diagram_skills.py review .... Si alguna verificación falla, corrige el breve, la fuente o el renderizador y vuelve a renderizar. Detente después de tres rondas de corrección basadas en evidencia; luego simplifica o divide.
8. Entrega primero la imagen, luego enlaza el breve, el SVG/HTML/fuente/evidencia de calidad. Menciona el editor del navegador solo cuando el usuario solicite edición manual, importaciones o desglose.

Enrutar la solicitud

1. Lee references/diagram-thinking.md para tareas de prosa a diagrama y revisiones sustanciales. No inventes hechos para hacer un diseño simétrico.
2. Lee references/prompt-system.md cuando la entrada sea prosa, esté incompleta o necesite convertirse en un prompt reutilizable.
3. Selecciona exactamente un tipo principal y lee su guía:
   • arquitectura de sistema
   • flujo de agente
   • flujo de datos
   • mapa de capacidades
   • flujo de usuario
   • topología de sistema
   • árbol de decisión
   • hoja de ruta
   • mapa estratégico
   • flujo de proceso
4. Lee solo el perfil del tipo seleccionado en references/diagram-thinking-profiles.json.
5. Lee references/spec.md mientras creas un único diagrama. Usa scripts/diagram_skills.py new para un iniciador con formato de producción.
6. Lee references/enterprise-board.md para infografías de arquitectura en capas de alta densidad, cuadrículas de secciones, listas laterales, tiras de proceso y tarjetas de principios.
7. El Skill instalado es la ruta de generación completa. Si también está presente una copia completa del repositorio DiagramSkills, references/workspaces.md, references/imports.md y references/editor.md describen flujos de trabajo opcionales solo para Studio. Verifica que exista el directorio editor/ del repositorio antes de ofrecerlos; nunca los conviertas en un requisito previo para la generación.
8. Lee references/visual-language.md solo al elegir temas, tokens de marca, semántica de nodos/aristas o tratamiento de etiquetas en chino/inglés.
9. Aplica references/quality-contract.md. Un archivo generado es solo un candidato hasta que pasen la revisión de contenido, la validación estricta y la revisión visual.

Contrato de entrada

Acepta lenguaje natural o campos estructurados. Conserva los valores proporcionados por el usuario; infiere solo omisiones de bajo riesgo.

• goal: la pregunta o decisión que el diagrama debe respaldar
• diagram_type: un slug compatible; infiere a partir de la intención cuando se omita
• audience: ej. ejecutivo, producto, ingeniería, cliente
• narrative / scope: la historia de cinco segundos y el límite explícito de dentro/fuera
• must_show / emphasize / deemphasize: prioridad de contenido antes del diseño
• uncertainties / assumptions: hechos no proporcionados e interpretaciones de bajo riesgo
• content_risks / quality_questions: formas en que el diagrama podría engañar y verificaciones posteriores al renderizado
• content: actores, sistemas, pasos, capacidades, hitos o decisiones
• relationships: enlaces de datos, control, éxito, error, asíncronos y de retroalimentación
• boundaries: propiedad, etapa del ciclo de vida, capa, dominio o zona de confianza
• composition: board para vistas generales empresariales de alta densidad; graph para diagramas de relaciones más pequeños
• lanes: propietarios o roles ordenados para un diagrama de carriles
• rank: nivel de jerarquía no negativo explícito cuando el orden automático no es aceptable
• language: chino primero por defecto; conserva los términos técnicos ingleses establecidos
• theme: paper, notion, spectrum, blueprint o terminal
• brand: tokens de color hexadecimal en lista blanca superpuestos sobre un preajuste
• views: vistas opcionales de repositorio-Studio de descripción general y detalle; conectar con child_view
• imports: fuente Mermaid de repositorio-Studio opcional o tabla CSV
• outputs: SVG/HTML terminados más JSON fuente y diagnósticos por defecto; PNG cuando el rasterizador local esté disponible

Pregunta solo cuando una elección no resuelta cambie materialmente el significado, la seguridad de publicación o la salida requerida. De lo contrario, elige el diseño convencional de la guía de tipo y declara la suposición.

Comandos

Desde la carpeta del Skill:

python3 scripts/diagram_brief.py work/architecture.brief.json --strict
python3 scripts/diagram_skills.py types
python3 scripts/diagram_skills.py png-backend
python3 scripts/diagram_skills.py new system-architecture --output work/architecture.json
python3 scripts/diagram_skills.py validate work/architecture.json --strict
python3 scripts/diagram_skills.py render work/architecture.json --output-dir output --strict
python3 scripts/diagram_brief.py work/architecture.brief.json --spec work/architecture.json --strict --reviewed
python3 scripts/diagram_skills.py review work/architecture.json --quality output/architecture.quality.json --brief work/architecture.brief.json --artifact output/architecture.svg

render siempre escribe .svg, .html y un recibo .quality.json vinculado por hash; también escribe .png cuando se proporciona --png y png-backend informa un rasterizador compatible. Un renderizado estructuralmente válido permanece pending-review hasta que review verifique la fuente, el artefacto inspeccionado, el breve revisado y sus hashes. Una solicitud PNG fallida nunca deja un recibo aprobado.

El Skill instalado es autónomo para la generación. El workspace del navegador, la importación de Mermaid/CSV y la edición multivista son complementos del repositorio y están disponibles solo desde una copia completa que contenga editor/.

Comportamiento no negociable

• Construye y valida el Diagrama Breve conciso antes de crear un diagrama no trivial. Comparte decisiones de diseño y evidencia, nunca el razonamiento interno privado.
• Prefiere un mensaje principal y una dirección de lectura. Divide los diagramas de grafo por encima de 14 nodos; un board empresarial estructurado puede contener intencionadamente de 20 a 45 tarjetas concisas en 3 a 6 bandas de exploración.
• Usa lanes ordenados para la propiedad y el rank de nodo para la jerarquía manual. Usa groups para recintos semánticos; no hagas que un campo signifique ambas cosas.
• Enlaza las vistas generales densas con detalles child_view enfocados en lugar de reducir las etiquetas.
• Marca las rutas de retorno intencionales como feedback; los ciclos no marcados fallan la validación.
• Usa tipos de arista semánticos, no colores decorativos. Muestra una leyenda cuando dos o más significados de arista necesiten interpretación.
• Permite enlaces de nodo solo para https, http, mailto o fragmentos de página. Los esquemas de URL ejecutables son rechazados.
• Mantén las etiquetas en chino concisas y coloca los términos técnicos ingleses estables en subtítulos. Divide los nodos sobrecargados en lugar de reducir el texto.
• Prefiere LR para tuberías, hojas de ruta, topologías y bucles de retroalimentación; prefiere TB para capas, decisiones, estrategias y recorridos de usuario.
• Ejecuta la validación estricta del breve y del diagrama. Inspecciona el SVG o el PNG a tamaño completo, responde cada pregunta del perfil de tipo con evidencia distinta y finaliza el recibo de calidad vinculado por hash con review.
• No reclames finalización después de escribir solo Mermaid/JSON cuando el usuario pidió un diagrama. Renderiza y devuelve el visual real.
• Mantén el .brief.json y el JSON fuente junto a los entregables para que el significado y los píxeles sigan siendo reproducibles y revisables.
• Cuando una copia completa del repositorio proporcione importaciones de Studio, trata el contenido importado como no confiable. Mermaid se renderiza en modo estricto, CSV se convierte en campos tipados y cualquier CSS arbitrario o enlace ejecutable es rechazado.

Elección de salida

• PNG: vista previa preferida cuando png-backend informe un rasterizador local compatible; de lo contrario, muestra primero el SVG.
• Diagram Brief JSON: intención de contenido, alcance, incertidumbre, priorización, riesgos y evidencia de revisión.
• SVG: documentación escalable y control de versiones.
• HTML: visualización responsiva, paneo/zoom, cambio de tema, descargas y nodos cliqueables.
• Quality JSON: evidencia de validación legible por máquina.
• Workspace JSON: formato opcional de repositorio-Studio para edición en navegador, vistas mixtas Mermaid/nativas, persistencia sin conexión y desglose.

Extensión

Agrega un nuevo tipo de diagrama solo cuando tenga un modelo de información o un contrato de diseño distintos. Agrega su slug a DIAGRAM_TYPES, enum del esquema, templates/<slug>.json, references/diagram-types/<slug>.md y references/diagram-thinking-profiles.json; luego agrega pruebas estrictas de renderizado y perfil de pensamiento. Extiende las asignaciones CSV en un adaptador y los campos de workspace tanto en Zod como en JSON Schema. Los nuevos temas deben conservar la semántica de nodos y aristas en la representación claro/oscuro.