CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

diagram-generation

Geração de diagramas técnicos para tutoriais, artigos e documentação

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/documentation/diagram-generation/SKILL.md
SKILL.md
Quality
Evals
Security

Geração de Diagramas Técnicos

Padrões e ferramentas para criar diagramas em projetos de documentação técnica.

Quando Usar

  • Tutoriais que precisam de fluxogramas
  • Artigos técnicos com diagramas de arquitetura
  • Documentação de APIs com diagramas de sequência
  • Knowledge Base com visualizações de conceitos

Ferramentas Recomendadas

APIs Disponíveis

OpenAI DALL-E

import openai

response = openai.images.generate(
    model="dall-e-3",
    prompt="Diagrama ilustrativo de algoritmo de ordenação bubble sort",
    size="1024x1024",
    quality="standard"
)

Gemini (Nano Banana)

import google.generativeai as genai

genai.configure(api_key=os.getenv("GEMINI_API_KEY"))
model = genai.GenerativeModel('gemini-2.5-flash-image')

response = model.generate_content(
    "Crie um diagrama ilustrativo de algoritmo de ordenação"
)

Mermaid (Para Diagramas Técnicos)

Para diagramas técnicos, usar Mermaid (não precisa de API):

Sintaxe declarativa que renderiza direto no GitHub/GitLab.

flowchart TD
    A[Entrada] --> B{Decisão}
    B -->|Sim| C[Ação 1]
    B -->|Não| D[Ação 2]
    C --> E[Fim]
    D --> E

Tipos de diagrama:

  • flowchart - Fluxogramas
  • sequenceDiagram - Diagramas de sequência
  • classDiagram - Diagramas de classe
  • erDiagram - Diagramas ER
  • gantt - Cronogramas
  • pie - Gráficos de pizza
  • stateDiagram - Máquinas de estado

2. PlantUML

Mais flexível, precisa de servidor ou extensão.

@startuml
actor User
User -> API: Request
API -> Database: Query
Database --> API: Result
API --> User: Response
@enduml

3. Excalidraw

Diagramas com visual de desenho à mão. Exporta PNG/SVG.

4. Draw.io (diagrams.net)

Editor visual completo. Arquivos .drawio são XML editável.

5. Python (Matplotlib/Graphviz)

Para diagramas programáticos ou gerados a partir de dados.

import matplotlib.pyplot as plt
import networkx as nx

G = nx.DiGraph()
G.add_edges_from([("A", "B"), ("B", "C"), ("A", "C")])
nx.draw(G, with_labels=True)
plt.savefig("diagram.png")

Padrões por Tipo de Conteúdo

Tutoriais

TipoFerramentaFormato
Fluxo de passosMermaid flowchartInline no MD
Arquitetura simplesMermaidInline no MD
Arquitetura complexaDraw.ioPNG exportado
Conceitos abstratosExcalidrawPNG exportado

Artigos Técnicos

TipoFerramentaFormato
Sequência de chamadasMermaid sequenceInline
Classes/EstruturasMermaid classInline
Banco de dadosMermaid ERInline
Infra/CloudDraw.ioPNG

Knowledge Base

TipoFerramentaFormato
Mapas mentaisExcalidrawPNG
HierarquiasMermaid flowchartInline
ComparaçõesTabelas MDTexto
TimelinesMermaid ganttInline

Templates Mermaid

Fluxograma de Decisão

flowchart TD
    START([Início]) --> CHECK{Condição?}
    CHECK -->|Verdadeiro| ACTION1[Executar A]
    CHECK -->|Falso| ACTION2[Executar B]
    ACTION1 --> END([Fim])
    ACTION2 --> END

Diagrama de Sequência

sequenceDiagram
    participant C as Cliente
    participant S as Servidor
    participant D as Database

    C->>S: POST /api/data
    S->>D: INSERT INTO...
    D-->>S: OK
    S-->>C: 201 Created

Diagrama de Classes

classDiagram
    class Animal {
        +String nome
        +int idade
        +comer()
        +dormir()
    }
    class Cachorro {
        +latir()
    }
    Animal <|-- Cachorro

Diagrama ER

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ITEM : contains
    USER {
        int id PK
        string email
        string name
    }
    ORDER {
        int id PK
        int user_id FK
        date created_at
    }

Arquitetura de Sistema

flowchart LR
    subgraph Frontend
        A[React App]
    end
    subgraph Backend
        B[API Gateway]
        C[Auth Service]
        D[Core Service]
    end
    subgraph Data
        E[(PostgreSQL)]
        F[(Redis)]
    end

    A --> B
    B --> C
    B --> D
    C --> E
    D --> E
    D --> F

Convenções de Estilo

Cores (para ferramentas que suportam)

  • Azul: Componentes de entrada/usuário
  • Verde: Processamento/lógica
  • Amarelo: Decisões/condicionais
  • Vermelho: Erros/alertas
  • Cinza: Componentes externos

Nomenclatura

  • Usar verbos para ações: "Processar", "Validar", "Enviar"
  • Usar substantivos para componentes: "Servidor", "Database", "Cache"
  • Manter consistência: não misturar português e inglês no mesmo diagrama

Tamanho

  • Fluxogramas: máximo 10-15 nós
  • Sequência: máximo 5-6 participantes
  • Se ficar grande demais, dividir em múltiplos diagramas

Workflow de Criação

  1. Definir objetivo do diagrama
  2. Listar componentes/passos principais
  3. Escolher ferramenta apropriada
  4. Criar rascunho simples
  5. Refinar e adicionar detalhes
  6. Exportar no formato correto
  7. Testar renderização no destino final

Integração com Knowledge Base

Para o projeto Engineering Knowledge Base:

engineering-knowledge-base/
└── [seção]/
    └── [tutorial]/
        ├── README.md          # Texto com diagramas Mermaid inline
        ├── assets/
        │   ├── architecture.png   # Diagramas complexos
        │   └── architecture.drawio # Fonte editável
        └── notebooks/
            └── 01-intro.ipynb     # Pode ter diagramas Python

Diagramas Ilustrativos (APIs de Imagem)

Para diagramas ilustrativos que precisam de estilo visual, usar APIs de imagem:

OpenAI DALL-E

import openai

response = openai.images.generate(
    model="dall-e-3",
    prompt="Diagrama ilustrativo de algoritmo de ordenação bubble sort",
    size="1024x1024",
    quality="standard"
)

Gemini (Nano Banana)

import google.generativeai as genai

genai.configure(api_key=os.getenv("GEMINI_API_KEY"))
model = genai.GenerativeModel('gemini-2.5-flash-image')

response = model.generate_content(
    "Crie um diagrama ilustrativo de algoritmo de ordenação"
)

Implementação: core/utils/diagram_generator/ - Sistema completo para geração de diagramas ilustrativos usando OpenAI DALL-E ou Google Gemini

Manter simples e documentado.


Checklist

Antes de finalizar um diagrama:

  • O diagrama tem um propósito claro?
  • Está legível em diferentes tamanhos de tela?
  • As cores têm contraste suficiente?
  • A nomenclatura é consistente?
  • O diagrama complementa o texto (não duplica)?
  • O formato é apropriado para o destino?
  • Se ilustrativo, API configurada (OpenAI ou Gemini)?
Repository

fernandezbaptiste/cursor-multiagent-system

Path

skills/documentation/diagram-generation/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.