Creating Diagrams with an Excalidraw Agent Skill and Excalidraw MCP

There is a point where diagramming starts to feel like admin.

You are in the middle of thinking through an architecture, a delivery workflow, or a system interaction. The shape of it is clear enough in your head, but getting it into a diagram means stopping what you are doing, opening another tool, dragging boxes around, lining arrows up, fixing spacing, and then exporting something that will probably be out of date the next time the design changes.

That friction is why so many diagrams never get created, or get created once and then quietly rot.

What interested me about using Excalidraw through MCP with GitHub Copilot in VS Code was not that it could draw boxes. Plenty of tools can do that. The useful part is that it keeps the diagram inside the same workflow as the rest of the engineering work. You stay in the editor, describe the system in natural language, and GitHub Copilot can start building the picture on a live Excalidraw canvas while you are still thinking it through.

That changes the role of the diagram quite a bit. It stops being something you make afterwards and starts becoming part of the design loop itself.

The problem with most architecture diagrams

Most diagrams do not fail because they are badly drawn. They fail because they live too far away from the work.

You sketch something, export a PNG, drop it into a wiki or a PowerPoint, and that is usually where it stays. Then the system moves on. A new service appears, a release stage changes, another trust boundary gets introduced, or a platform team standardises part of the flow. The diagram is now close enough to be trusted and wrong enough to cause confusion.

That is the worst combination.

I do not think engineers dislike diagrams. Most teams actually want them. The problem is that traditional diagramming workflows sit outside the editor, outside the repo, and outside the prompt-review-change loop that the rest of the engineering work already lives in. Once diagramming becomes a separate task, it gets deferred. Once it gets deferred, it drifts. After that, it becomes documentation theatre.

Moving diagramming back into the workflow matters more than making it faster. Speed is helpful, but the real gain is that diagrams become easier to create while the design is still fluid, which makes them more likely to stay relevant.

Why Excalidraw works well for this

Excalidraw is a good fit for this because it is quick, editable, and informal.

That hand-drawn style is not a weakness. It is actually one of the reasons it works. It signals that the diagram is a working artefact, not something sacred. People are much more willing to challenge it, move things around, and refine it when it looks like a sketch rather than a polished poster.

That matters in engineering discussions. A rough diagram that people will improve is usually more useful than a polished one nobody wants to touch.

It also pairs well with AI. A static export is the end of a process. A live canvas is part of one. When the output is something you can inspect and adjust immediately, the model becomes much more useful as a drafting assistant rather than a one-shot generator.

Why the skill matters, not just the MCP server

Giving GitHub Copilot access to Excalidraw through MCP is the first part. That gives the model a drawing surface.

On its own, though, that is not enough.

Without some structure around it, you tend to get diagrams that are technically acceptable but not especially good. The boxes are there. The arrows exist. Labels are present somewhere. But the result still feels improvised. Spacing is inconsistent. Grouping is weak. Colours mean nothing. Important boundaries do not stand out. Everything is included, but not everything is being communicated clearly.

That is where the excalidraw-mcp-diagramming skill matters.

The skill is not just telling GitHub Copilot to draw a system. It is giving it a set of expectations around layout, readability, grouping, colour consistency, and refinement. That sounds like a small thing until you use it more than once.

A one-off diagram can get away with being rough. A repeatable workflow cannot.

That is usually where the real platform engineering lesson shows up. The problem is not getting it working once. It is keeping it predictable across repos and teams. The first draft is rarely the hard part. The hard part is whether the fourth diagram still looks like it came from the same engineering organisation as the first.

At that point, the skill stops being a convenience and starts acting more like a lightweight standard.

How the setup works in practice

The setup is fairly simple, but the value comes from the combination of the pieces rather than any one part on its own.

First, VS Code is configured to know about the Excalidraw MCP server. That gives GitHub Copilot agent mode access to a live Excalidraw canvas.

Second, the skill adds guidance on top of that capability. The server provides the drawing surface. The skill provides the structure and the rules.

In practice, the flow looks like this:

GitHub Copilot is given access to Excalidraw through MCP

You add the Excalidraw MCP server to VS Code so GitHub Copilot can call it from agent mode.

{
  "servers": {
    "excalidraw": {
      "type": "http",
      "url": "https://mcp.excalidraw.com"
    }
  }
}

Once that is in place, GitHub Copilot can interact with the Excalidraw canvas from within VS Code.

2. The skill tells GitHub Copilot how to draw well

This is the part that makes the output feel deliberate rather than random.

The skill guides Copilot to think about things like:

• what kind of layout fits the diagram best
• how to group related components
• how to use consistent colours for similar roles
• how to keep labels readable
• how to structure arrows so the flow is obvious
• when a diagram needs refining rather than just adding more shapes

That sounds minor until you try it in practice. A model can generate a diagram quickly, but it does not naturally care about clarity. The skill closes that gap.

A few opinionated rules

A couple of choices make a big difference in practice:

• keep labels readable, not tiny
• use consistent colours for consistent roles
• avoid too many colours in one diagram
• use layout patterns instead of guessing spacing
• redraw structural changes cleanly rather than patching everything

That is the difference between “AI drew something” and “this is actually usable in a design review.”

The difference between a useful diagram and a messy one is usually not whether the boxes exist. It is whether the flow is obvious, the labels are readable, and the layout feels intentional.

That is what the skill is really doing. It gives GitHub Copilot some structure around layout selection, spacing and grouping, readable typography, consistent colour usage, and refinement after the first render.

3. You describe the system in normal engineering language

This is where it starts to feel useful.

You are not switching to another application and manually reproducing your own thinking. You stay in VS Code and prompt GitHub Copilot with the architecture or flow you want to see. The response becomes a live diagram rather than another block of text.

That makes iteration faster too. If something is missing, or the grouping is not quite right, or a flow needs to be re-emphasised, you can adjust the prompt and refine the canvas rather than starting again.

Example Diagrams

The easiest way to judge whether something like this is genuinely useful is to try it on diagrams you would actually need in real work, not just toy examples.

Two good ones are the exact examples I used with the skill.

Azure Front Door to backend architecture flow

One of the diagrams I wanted to test was an Azure Front Door flow into a backend architecture.

That is the kind of diagram that comes up regularly in architecture reviews. It is not especially complicated, but it is complicated enough that explaining it purely in words is usually slower than showing it.

/excalidraw-mcp-diagramming create me an azure diagram of an azure frontdoor setup flow from user to afd to backend?

The prompt above produced a flow showing:

• the user entering through the public endpoint
• Azure Front Door handling the edge entry point
• the traffic path toward the backend
• the supporting routing and logical flow between the layers

What I like about using a live Excalidraw canvas for this is that it stays flexible while the thinking is still happening. If the backend grouping is not right, or the flow needs another component called out, or the direction of traffic needs to be made more obvious, you can refine it immediately.

That is much closer to how real design conversations work.

GitHub Actions Terraform deploys to Azure with OIDC, from Dev to Prod

The second example was a GitHub Actions Terraform deployment flow to Azure using OIDC, moving from development through to production.

This is exactly the sort of workflow diagram that teams often need and rarely enjoy drawing.

Prompt used:

/excalidraw-mcp-diagramming create a github action workflow diagram, showing  complete workflow terraform deploy to azure using oidc, for a dev & prod environments, showing dev and once successful to production stage

The diagram shows:

• the trigger into the workflow
• the GitHub Actions jobs involved
• Terraform plan and apply stages
• Azure authentication using OIDC
• the separation between Dev and Prod
• the promotion path between environments
• the approval or governance point before production

That last part is important. In most real delivery setups, the interesting part is not that a workflow deploys infrastructure. It is how the workflow controls promotion and risk. A diagram makes that visible very quickly.

That is also where I think this kind of skill starts to become more than just a neat prompt trick. It helps communicate operational intent, not just technical sequence.

OAuth 2.0 PKCE flow from Browser to Entra ID, through an API Gateway

The third example was an OAuth 2.0 PKCE flow between a browser, an API Gateway, and Microsoft Entra ID – the kind of auth sequence that every team implements but few ever document clearly.

This is exactly the sort of interaction diagram that gets described in architecture wikis as “see the code” and never as an actual diagram.

Prompt used:

/excalidraw-mcp-diagramming create a sequence diagram of an OAuth 2.0 PKCE flow 
between a browser, an API gateway, and an Entra ID auth server

The diagram shows:

• the browser generating the code_verifier and code_challenge before any network call is made
• the authorization request to Entra ID carrying the code_challenge and S256 method
• the login page response and credential submission
• the 302 redirect returning the short-lived auth_code
• the token exchange, the critical PKCE step – where the browser proves ownership by sending the original code_verifier alongside the auth_code
• access_token and id_token returned from Entra ID
• the browser calling the API Gateway with a Bearer token
• the API Gateway fetching JWKS public keys from Entra ID to validate the token locally
• the final 200 OK response back to the browser

That last part is important. In many implementations the API Gateway is treated as a transparent proxy, but the diagram makes the token validation step explicit — the Gateway is not just forwarding requests, it is an active participant in the security boundary. A sequence diagram makes that visible at a glance

Getting started

If you want to try this setup yourself, the path is straightforward:

1. Clone or fork github-copilot-agent-skills
2. Add the MCP server entry to .vscode/mcp.json
3. Reload VS Code
4. Cmd+Shift+P → Developer: Reload Window
5. Open GitHub Copilot Chat in agent mode
6. The Excalidraw Agent Skill is located here
7. Describe your diagram – include the skill name or just describe what you want and GitHub Copilot will pick it up

Final thoughts

What I like about this setup is not really the diagram generation on its own.

That part is interesting for about five minutes.

The more meaningful change is that diagramming can now sit much closer to the engineering work itself. Diagrams can be drafted, refined, and reused in the same place where architecture and delivery decisions are already being made. That makes them more likely to be created, more likely to evolve with the work, and more likely to be useful when someone else needs to understand the system later.

For me, that is the real value.

Not that GitHub Copilot can draw a diagram, but that rough engineering thinking can move into usable visual artefacts without turning diagramming into a separate task that gets postponed until later. Once that happens, diagrams stop being static documentation you apologise for updating and start becoming part of the way the work actually gets done.