draw-io

Visão geral do skill draw-io

O draw-io skill é um fluxo de trabalho focado em criar, editar e revisar diagramas .drawio como XML e depois exportá-los para .drawio.png para documentação ou slides. Ele é mais indicado para desenvolvedores, redatores técnicos, arquitetos de solução e usuários de IA que precisam atualizar diagramas de forma repetível, sem ficar clicando manualmente na interface do draw.io.

Em que o draw-io é melhor

Este draw-io skill se destaca quando você precisa:

• editar arquivos .drawio existentes com segurança
• fazer ajustes precisos de layout alterando coordenadas no XML
• aplicar padrões de diagrama, como configurações de fonte
• gerar PNGs transparentes em alta resolução
• usar ícones de arquitetura AWS com os identificadores corretos mxgraph.aws4.*

O trabalho real que ele resolve

A maioria dos usuários não precisa de “geração de diagramas” em abstrato. Precisa de um agente que atualize diagramas de arquitetura com confiabilidade, mantenha o estilo consistente e gere assets prontos para exportação que se encaixem em um pipeline de documentação. O draw-io é útil porque transforma isso em um fluxo concreto, e não em um prompt vago.

O que diferencia o draw-io de um prompt genérico

Um prompt comum pode gerar uma ideia de diagrama. Este skill adiciona regras práticas de operação:

• editar o XML do .drawio, e não o .drawio.png gerado
• exportar PNGs com configurações de CLI conhecidas
• aplicar configurações explícitas de font-family para compatibilidade com slides
• seguir orientações de layout para agrupamento, direção de fluxo e legibilidade
• consultar ícones AWS a partir de uma referência local em vez de adivinhar nomes de ícones

Quem provavelmente deve instalar

Instale draw-io se você já trabalha com arquivos draw.io no Git, gera documentação ou slides a partir do código-fonte, ou precisa atualizar diagramas de arquitetura de forma programática. Se você só quer um brainstorm visual pontual em uma GUI, isso provavelmente é mais processo do que o necessário.

Como usar o skill draw-io

Instale o skill draw-io

Use seu gerenciador de skills para adicioná-lo a partir do repositório:

npx skills add softaworks/agent-toolkit --skill draw-io

Se o seu ambiente usa outro instalador, a parte importante é o caminho do skill skills/draw-io em softaworks/agent-toolkit.

Confirme os pré-requisitos locais

Antes de depender do draw-io install, verifique se o seu ambiente tem:

• um CLI drawio disponível para exportação
• bash para o script de conversão
• git se você quiser que os PNGs gerados sejam adicionados automaticamente ao stage
• opcionalmente mise e pre-commit, se o seu repositório usa esse fluxo

O script de conversão fornecido chama:

drawio -x -f png -s 2 -t -o output.drawio.png input.drawio

Isso significa modo de exportação, formato PNG, escala 2x, fundo transparente e caminho de saída explícito.

Leia estes arquivos primeiro

Para adotar o skill mais rápido, confira estes arquivos nesta ordem:

1. skills/draw-io/SKILL.md
2. skills/draw-io/README.md
3. skills/draw-io/references/layout-guidelines.md
4. skills/draw-io/references/aws-icons.md
5. skills/draw-io/scripts/convert-drawio-to-png.sh
6. skills/draw-io/scripts/find_aws_icon.py

Essa ordem importa porque o skill é mais operacional do que conceitual: as regras, convenções de layout e scripts auxiliares concentram a maior parte do valor.

Entenda primeiro a regra central de operação

A restrição de uso mais importante é simples:

• edite arquivos .drawio
• não edite diretamente arquivos .drawio.png

O PNG é tratado como um artefato gerado. Se o seu repositório versiona tanto a fonte quanto a exportação, o agente deve modificar o XML de origem e regenerar o PNG depois.

Que tipo de entrada o skill precisa

A qualidade do draw-io usage depende muito do input que você fornece. Bons inputs normalmente incluem:

• o caminho do arquivo de destino
• se você vai criar ou editar
• o tipo de diagrama: arquitetura, fluxograma, fluxo tipo sequência etc.
• a direção de leitura desejada: da esquerda para a direita ou de cima para baixo
• serviços, nós, rótulos e conexões necessários
• qualquer restrição de slides ou documentação
• se são necessários ícones oficiais da AWS
• se a exportação em PNG é necessária agora

Sem esses detalhes, o agente precisa adivinhar estrutura, espaçamento e nomenclatura.

Transforme um objetivo vago em um bom prompt para draw-io

Prompt fraco:

“Update our AWS diagram.”

Prompt melhor:

“Edit assets/system.drawio. Add Amazon S3 on the left as the ingestion source, route data to AWS Lambda, then to Amazon RDS. Keep a left-to-right flow. Preserve existing group structure. Use official AWS icons, avoid crossing arrows, and regenerate assets/system.drawio.png.”

Por que isso funciona melhor:

• nomeia o arquivo
• especifica os componentes adicionados
• define a direção do fluxo
• pede fidelidade aos ícones
• inclui um objetivo de layout
• solicita o artefato exportado

Use o draw-io para edições precisas, não só para geração

Este skill é especialmente útil quando você já tem um diagrama e precisa de mudanças pontuais, como:

• mover um cluster para evitar sobreposição de linhas
• alinhar horizontalmente caixas de serviço
• trocar um rótulo genérico pelo nome oficial de um serviço AWS
• ajustar fontes para compatibilidade com slides
• regenerar o PNG após editar o XML

É aí que editar o XML diretamente costuma ser mais rápido e reproduzível do que mexer manualmente na interface.

Siga as configurações de fonte se slides forem importantes

Se o diagrama for usado em slides Quarto ou em ambientes com problemas de renderização de fonte, o skill recomenda definir:

• defaultFontFamily em mxGraphModel
• fontFamily em elementos de texto individuais

O repositório destaca explicitamente Noto Sans JP como fonte recomendada para suporte a japonês. Mesmo que você não precise de japonês, a lição mais ampla é importante: especifique as fontes explicitamente quando precisar de saída consistente entre máquinas e etapas de exportação.

Use os caminhos de conversão que combinam com o seu repositório

O skill oferece várias formas de exportar PNGs:

• todos os arquivos via pre-commit: mise exec -- pre-commit run --all-files
• um arquivo via pre-commit: mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio
• uso direto do script: bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

Escolha com base no fluxo do seu repositório. Se o projeto já usa pre-commit, siga esse caminho. Se você só precisa de uma exportação local pontual, o script é a rota mais rápida.

Use a referência de ícones AWS em vez de adivinhar

Se você está fazendo draw-io for Design Implementation em diagramas com forte presença de AWS, a referência de ícones é uma das partes mais valiosas do skill. Ela documenta:

• nomes oficiais de serviços, como Amazon ECS e AWS Lambda
• convenções atuais de estilo de ícone usando mxgraph.aws4.*
• padrões de ícones de recursos e produtos

O script auxiliar incluído permite pesquisar na referência:

python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda

Isso é muito mais seguro do que inventar nomes de resIcon de memória.

Aplique as orientações de layout de forma intencional

As orientações de layout do repositório não estão ali só para preencher espaço. Elas trazem padrões práticos que melhoram a qualidade da saída:

• agrupar claramente limites de nuvem e sub-redes
• manter o fluxo principal da esquerda para a direita sempre que possível
• usar estilos de linha diferentes para tipos de fluxo distintos
• manter elementos relacionados próximos
• reduzir cruzamentos de setas
• deixar espaço em branco suficiente para legibilidade

Se você quiser uma boa primeira versão, diga ao agente quais desses princípios mais importam para o seu diagrama.

FAQ do skill draw-io

O draw-io é bom para iniciantes?

Sim, se você já tem arquivos draw.io e quer ajuda para editá-los. O skill reduz a adivinhação ao fornecer regras e scripts concretos. Ele é menos ideal para um iniciante completo que só quer explorar conceitos de diagramação sem um fluxo baseado em arquivos.

Quando o draw-io é melhor do que um prompt normal de IA?

O draw-io é melhor quando você precisa de edições reproduzíveis, tratamento correto de arquivos, etapas de exportação ou precisão nos ícones AWS. Um prompt comum pode até descrever bem um diagrama, mas normalmente não vai impor edição da fonte .drawio, comandos de exportação, configurações de fonte e uso de scripts auxiliares.

O draw-io exige a GUI do draw.io?

Não necessariamente. O skill foi pensado em torno de edição de arquivos-fonte e exportação de PNG via CLI. Isso o torna útil em fluxos centrados em código, diffs revisáveis e pipelines de documentação.

Quando eu não devo usar draw-io?

Ignore este draw-io guide se você precisa de:

• whiteboarding livre
• mockups de design refinados fora do draw.io
• edição puramente visual em uma GUI
• geração de diagramas para formatos que não têm relação com .drawio

Este skill é especializado em XML do draw.io e operações de exportação, não em design gráfico geral.

O draw-io pode ajudar com diagramas de arquitetura AWS?

Sim. Esse é um dos pontos em que ele mais brilha. A referência de ícones AWS e o script de busca ajudam você a usar nomes oficiais e ícones mxgraph.aws4.*, o que é valioso quando consistência e reconhecimento importam.

O draw-io corrige automaticamente um layout ruim?

Não de forma automática, como se fosse mágica. O skill oferece um método para ajustar coordenadas e layout de forma deliberada. Ele melhora bastante os resultados quando você informa com clareza a intenção de posicionamento, como agrupamento, direção do fluxo, espaçamento e prioridades para evitar sobreposição.

Como melhorar o skill draw-io

Dê ao draw-io inputs estruturais mais fortes

A forma mais rápida de melhorar o draw-io usage é fornecer estrutura, não adjetivos. Em vez de dizer “deixa mais limpo”, diga:

• mova o banco de dados para baixo da camada de aplicação
• mantenha todas as fontes de ingestão na coluna da esquerda
• faça com que as setas não se cruzem, se possível
• agrupe separadamente os recursos de sub-redes públicas e privadas
• mantenha os rótulos curtos o suficiente para evitar expansão das caixas

Esse tipo de instrução mapeia diretamente para decisões de XML e layout.

Comece de um diagrama existente sempre que possível

O skill funciona melhor quando pode editar um arquivo .drawio existente em vez de inventar tudo do zero. Arquivos já existentes fornecem:

• IDs atuais dos elementos
• padrões de layout
• convenções de estilo
• estrutura de agrupamento
• destinos de exportação já conhecidos

Para equipes, isso geralmente produz resultados mais confiáveis do que pedir um diagrama totalmente novo toda vez.

Seja explícito sobre nomenclatura e fidelidade dos ícones

Um modo de falha comum é usar nomes vagos de serviço, como “ECS” ou “Lambda”, sem decidir se os rótulos devem usar os nomes oficiais completos dos serviços. Se diagramas AWS importam, especifique ambos:

• rótulos exibidos: Amazon ECS, AWS Lambda, Amazon RDS
• exigência de ícones: usar ícones oficiais de serviço mxgraph.aws4.*

Isso evita mistura de estilos de nomenclatura e mapeamento incorreto de ícones.

Peça edição e exportação como um único fluxo

Se você quer saídas realmente utilizáveis, peça tanto a edição da fonte quanto a etapa de exportação em uma única instrução. Exemplo:

“Update docs/arch.drawio, then regenerate docs/arch.drawio.png with the skill’s standard PNG export settings.”

Isso reduz a falha comum em que o XML é alterado, mas o artefato de preview fica desatualizado.

Fique atento aos principais modos de falha

Os problemas mais comuns de draw-io costumam ser práticos, não conceituais:

• editar o PNG em vez do .drawio
• esquecer as configurações de fonte e acabar com renderização inconsistente de texto
• usar identificadores de ícones AWS chutados
• apertar nós demais e fazer os rótulos colidirem
• criar conectores cruzados que prejudicam a legibilidade
• fazer mudanças de layout sem preservar o fluxo geral

Você pode evitar a maioria deles referenciando diretamente os scripts e guias fornecidos no seu prompt.

Itere com mudanças pequenas e fáceis de revisar

Para diagramas complexos, não peça tudo de uma vez. Um padrão melhor é:

1. ajustar estrutura e agrupamento
2. revisar espaçamento e conectores
3. corrigir rótulos e fontes
4. exportar o PNG
5. fazer uma última passada de legibilidade

Isso produz diffs mais limpos e facilita identificar se um problema de layout veio do agrupamento, da escolha de ícone ou do tamanho do texto.

Aponte o agente para os helpers do repositório pelo nome

Se o seu agente aceita prompts com reconhecimento de arquivos, mencione as referências exatas:

• references/layout-guidelines.md para espaçamento e fluxo
• references/aws-icons.md para nomenclatura e ícones AWS
• scripts/find_aws_icon.py para busca de ícones
• scripts/convert-drawio-to-png.sh para exportação

Esse pequeno passo costuma melhorar bastante a qualidade da primeira versão, porque o agente passa a usar as convenções do repositório em vez de recorrer a conselhos genéricos sobre diagramas.