Excalidraw Skill: desenhe, revise e exporte diagramas editáveis com um agente

ANÁLISE EDITORIAL

Desenhar um fluxo com um agente costuma ser fácil até a revisão: o texto sai da caixa, uma seta cruza outra e ninguém sabe qual arquivo editar depois. A excalidraw-skill, do projeto comunitário yctimlin/mcp_excalidraw, dá ao agente um roteiro para trabalhar num canvas editável, inspecionar os elementos e corrigir o próprio desenho. O resultado não é uma imagem pronta por mágica. É um fluxo de criação, conferência visual e exportação que depende do servidor local e da autorização de quem controla o computador.

O que esta Skill faz de verdade

O SKILL.md original ensina três caminhos para atuar no mesmo canvas: ferramentas MCP, linha de comando e API REST. Se o cliente expõe as ferramentas excalidraw/*, elas vêm primeiro. Sem essa integração, o roteiro usa a CLI npx -y mcp-excalidraw-server <command>. A API HTTP fica como alternativa para código de aplicação. A Skill orienta a planejar posições, criar elementos, consultar a cena com describe, gerar uma imagem com screenshot e ajustar o que estiver sobreposto, truncado ou fora do enquadramento.

Ela também cobre importação e exportação de .excalidraw, snapshots com nome, organização de formas, setas e grupos, além de conversão de Mermaid. Esta é uma Skill documental, não uma cópia do programa. O ZIP local que oferecemos contém instruções e uma referência textual; o servidor, suas dependências e a interface são obtidos separadamente pelo leitor, diretamente do projeto.

Na consulta de 14 de outubro de 2026, a API do GitHub para o repositório registrava 2.538 estrelas. Esse é o número observado naquela data, não prova de qualidade ou segurança. O projeto é comunitário e se distingue do MCP oficial do Excalidraw. Não tratamos um como distribuição do outro.

Para quem serve

O público mais claro é quem precisa manter diagramas técnicos junto ao trabalho de desenvolvimento: arquitetura de serviços, dependências, fluxos de atendimento ou explicações para uma revisão de código. Também pode ajudar alguém que já tem um arquivo Excalidraw e quer fazer ajustes localizados, sem reconstruir o desenho inteiro. A vantagem prática está na possibilidade de pedir mudanças nos elementos, olhar a cena atual e exportar novamente um arquivo editável.

Não é a escolha certa para publicar automaticamente mapas de sistemas sensíveis, nem para transformar uma descrição vaga em arquitetura aprovada. Se nomes, conexões ou permissões forem importantes, a pessoa responsável precisa conferir o diagrama final. A Skill pode propor uma disposição visual; ela não valida se a topologia representada corresponde à infraestrutura real.

Compatibilidade e pré-requisitos

O README do projeto informa Node.js 20 ou superior. Para seguir o caminho da CLI, é preciso ter npx disponível e poder baixar o pacote npm na primeira execução. O agente precisa ter acesso a um terminal autorizado ou, no caminho alternativo, ser um cliente MCP configurado para o servidor. O canvas local usa por padrão http://127.0.0.1:3000; confira a porta e não presuma que ela está livre.

Segundo o arquivo fixado nesta curadoria, comandos que tocam o canvas podem iniciar o servidor automaticamente. Capturas comuns e exportações de imagem são renderizadas no servidor e não exigem uma aba aberta; a conversão de Mermaid e a renderização com --renderer browser exigem uma aba no canvas. Se seu ambiente bloqueia processos locais, downloads do npm ou acesso ao loopback, resolva isso com o administrador antes de tentar contornar a política.

Instalação recomendada

Comece baixando o pacote documental auditado nesta página. Compare o SHA-256 indicado adiante e leia ORIGEM.md, LICENSE, SKILL.md e references/cheatsheet.md. Coloque a pasta da Skill no diretório aceito pelo seu agente, respeitando o escopo de projeto ou usuário. Se a ferramenta só descobre Skills ao iniciar, abra uma nova sessão. Isso registra instruções, mas não instala o servidor.

Para obter o componente executável, consulte a instalação do mantenedor. Ela documenta a CLI e o comando npx -y mcp-excalidraw-server install-skill --dir <skills-root>, além do atalho --target codex. Esse instalador oficial pode substituir arquivos de uma instalação anterior; quem precisa reproduzir precisamente nossa cópia deve preferir o ZIP fixado no commit e instalar manualmente. Antes de usar npx -y, confira a versão do pacote npm que será executada e as regras do seu ambiente. Não afirmamos ter testado o pacote em seu computador.

Há duas decisões separadas: confiar no documento da Skill para orientar o agente e permitir a execução do servidor. A licença MIT autoriza redistribuir a documentação com o aviso de copyright, mas não dispensa auditoria operacional. Não inclua tokens, chaves ou diagramas internos no diretório da Skill.

Configuração antes do primeiro uso

Use um projeto de teste e um canvas vazio ou um arquivo descartável. O README diz que o servidor se vincula por padrão a 127.0.0.1. Não altere HOST para 0.0.0.0 por conveniência: a própria documentação alerta que a API não tem autenticação embutida quando exposta à rede. Se houver motivo para acesso remoto, exija controle de rede e revisão de segurança antes de habilitá-lo.

Defina onde os arquivos exportados serão gravados. Um caminho relativo pode ir para o diretório de trabalho atual, que nem sempre é o repositório desejado. Se usar um vault Obsidian com o plugin Excalidraw, a Skill orienta a extensão .excalidraw.md; para um repositório comum, .excalidraw mantém a cena editável. Antes de conceder ao agente acesso de escrita ao projeto, delimite o diretório de saída e confirme que ele não vai sobrescrever um diagrama existente.

Primeiro uso seguro e resultado esperado

O roteiro mínimo é criar duas caixas e uma seta no canvas de teste, pedir describe para verificar IDs e posições, fazer screenshot --out diagrama-teste.png e abrir a imagem para procurar colisões ou texto cortado. Depois, exporte com export --out diagrama-teste.excalidraw. A referência de comandos detalha os formatos de elementos e os parâmetros aceitos. Não use um comando de limpeza em um canvas que já contém trabalho importante para obter um exemplo vazio.

O resultado esperado é um arquivo Excalidraw que você possa reabrir e modificar, mais uma imagem para revisão visual, se solicitar a captura. A imagem não é substituta do arquivo editável. A página do demo do mantenedor mostra um fluxo de desenho no produto; nós não o reproduzimos como teste independente.

Permissões e riscos

Uma instrução aparentemente simples pode disparar comandos no terminal, iniciar um processo HTTP local e gravar arquivos. Revise o pedido antes de deixar o agente executar a CLI. O comando clear --yes limpa a cena; salve um snapshot ou exporte o arquivo antes de qualquer alteração destrutiva. snapshot save <nome> e snapshot restore <nome> ajudam a recuperar o canvas, mas não substituem versionamento e backup dos arquivos exportados.

O comando share é outra fronteira: segundo o README, ele faz upload de uma cena criptografada e cria um link em excalidraw.com. Mesmo com criptografia, essa é uma saída para um serviço externo e deve depender de autorização explícita, sobretudo para diagramas de rede, clientes ou arquitetura interna. A página do canvas também carrega fontes de um CDN, como informa o projeto. Para ambientes sem tráfego externo, verifique essas dependências antes de usar. Nenhuma dessas ações acontece por baixar o ZIP documental do Bastidores.

Erros comuns e como investigar

Se a CLI não iniciar, confira a versão do Node, a conectividade necessária ao primeiro download do npm e se a porta 3000 já está ocupada. A Skill documenta código de saída 3 quando o canvas está inacessível. Se uma conversão Mermaid falhar com código 4, abra a página local do canvas e tente novamente; essa operação precisa da aba. Capturas comuns não precisam de uma aba, então não transforme uma falha de Mermaid em uma exigência geral de navegador.

Se nada aparece na imagem, use describe antes de recriar elementos: eles podem estar fora do enquadramento. Em modo MCP, a referência descreve set_viewport para aproximar a área relevante. Se a cena duplicar textos associados a caixas, a própria Skill descreve a sincronização do front-end como uma causa possível e recomenda inspecionar os elementos de texto vinculados antes de removê-los. Não apague todos os textos automaticamente. Faça uma cópia da cena e ajuste apenas os IDs confirmados.

Versão, licença e download local

Esta curadoria fixa o commit 8084a1c8b410d625fcfd59d5cffb32f3a86a2a6f do repositório comunitário. O release v2.1.2 foi publicado em 4 de outubro de 2026, mas o ZIP desta página identifica o commit, não promete corresponder ao pacote npm que você instalará no futuro. A licença MIT do repositório permite redistribuição com preservação do aviso. O pacote local contém SKILL.md, references/cheatsheet.md, LICENSE e ORIGEM.md, sem executáveis, bibliotecas, dependências, segredos ou diagramas.

Baixe pelo link local de documentação e confira o SHA-256: 50a4d4b18a866ab17f20dd2c138ebaadd367d8280fd26b648c40ed72a68c31bd. O cartão de download e o botão separado para abrir o repositório oficial da fonte estão no topo desta página. A URL de origem é uma referência externa; o download do Bastidores é a cópia documental auditada.

Fontes primárias

Foram conferidos o README do mantenedor, o texto da Skill, a referência de comandos, a licença e o release. Para decidir se o servidor cabe no seu ambiente, compare esses documentos com a versão do pacote npm efetivamente escolhida e com a política de segurança da sua organização.