Excalidraw skills turn agent self-maps into a governance control

At a glance

What this is: This article shows how Excalidraw skills let agents draw their own architecture, giving teams a live visual map of skills, connectors, and routing.

Why it matters: That matters because IAM, PAM, and governance teams need a way to verify how agentic systems are connected before complexity turns into unreviewed access and hidden dependencies.

👉 Read WorkOS's article on Excalidraw skills for agent self-diagrams

Context

Agent self-documentation is the ability of an agent to generate a current visual map of its own tools, connectors, and routing. In identity terms, that shifts architecture review from static documentation to runtime inspection of what the system can actually reach.

The governance problem is that complex agentic systems can outgrow README files, diagrams, and manual change tracking faster than teams can certify them. When skills, connectors, and permissions change quickly, the control question becomes whether the organisation can still understand effective access in time to govern it.

Key questions

Q: How should security teams govern agents that can describe their own architecture?

A: Security teams should treat self-generated architecture diagrams as review evidence, not as proof of safety. The diagram can show what skills and connectors exist, but governance still depends on approved configuration, entitlement records, and current access validation. If the generated view and the authoritative state diverge, the control has already failed.

Q: What breaks when agentic systems outgrow manual documentation?

A: Manual documentation breaks because it cannot keep pace with connector changes, tool additions, and routing updates. In practice, the team starts reviewing a picture of the system that no longer matches what the agent can actually reach. That gap creates blind spots in onboarding, change control, and access review.

Q: How do you know whether an agent’s self-map is actually useful?

A: A self-map is useful only if it is regenerated after meaningful changes and can be reconciled with the source configuration. If it cannot show current skills, active connectors, and routing paths, it is just a diagram. The real signal is whether reviewers can use it to find mismatches before the system is released.

Q: When should organisations review an agent’s blast radius?

A: Organisations should review blast radius whenever an agent gains a new tool, crosses a new trust boundary, or begins chaining skills across systems. The key question is not whether each permission looks reasonable in isolation, but whether the combined reach is still defensible for the task. That is a governance check, not a design preference.

Technical breakdown

How Excalidraw skills encode an agent’s current architecture

An Excalidraw skill is a structured output layer, not a free-form prompt. The agent composes diagram objects such as boxes, arrows, labels, and connectors, then serialises them into Excalidraw JSON so the canvas renders consistently. That makes the result more than a sketch. It becomes a machine-readable snapshot of skills, integrations, and relationships. The architectural value is that the map can reflect the current state of the system rather than a human’s memory of how it was configured last week.

Practical implication: treat generated diagrams as an operational artefact and compare them against configuration and access records after every material change.

Why agent self-maps help expose privilege sprawl

When an agent can list its skills and connectors, the diagram surfaces dependency chains that are otherwise buried in code, prompts, and tool registrations. For identity governance, that matters because effective privilege is often broader than the team expects once tools are connected through multiple hops. A visual system map makes hidden reach more obvious, especially when an agent can access messaging, files, web browsing, email, or APIs at once. That is a governance signal, not just a documentation convenience.

Practical implication: review the diagram for transitive access and remove connectors whose business justification cannot be stated in one sentence.

Change verification for agentic systems

The strongest technical use of self-diagrams is not onboarding, but verification after change. If a skill is added, a connector is reconfigured, or permissions shift, the agent can redraw its topology to show whether the new state matches the intended design. This is useful because agentic systems fail quietly when documentation lags reality. A diagram produced on demand gives teams a current artefact for review, but only if the underlying configuration sources are authoritative and the output is regenerated after every change.

Practical implication: make redraw-and-compare part of change control so every connector, skill, and permission update is visually validated before release.

Breaches seen in the wild

• Moltbook AI agent keys breach — Moltbook breach exposed 1.5M AI agent keys.
• AI LLM hijack breach — attackers used stolen AWS access keys to hijack Anthropic LLM models on Bedrock.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Self-documenting agents create a new governance object, not just a better diagram. When an agent can generate its own architecture map, teams gain a runtime artefact that can support review, onboarding, and change validation. The value is real, but it also changes the governance surface because the map becomes part of how access is understood and challenged. For identity teams, the question is whether this artefact is tied to authoritative configuration or merely reflects what the agent says about itself. Practitioner conclusion: self-description is useful only when it is anchored to the controls that actually govern the agent.

Agent self-maps expose a runtime visibility gap that traditional documentation cannot close. Static diagrams decay as soon as connectors, skills, or permissions change, which means they cannot keep pace with agentic systems that are modified frequently. This is why architecture review for agents is drifting from document review toward generated snapshots and live comparison. The broader implication is that identity governance for autonomous tooling will need evidence produced at the same tempo as the system itself. Practitioner conclusion: if the map is not current, it is not a governance artefact.

Complex agent environments turn effective access into a moving target. Once an agent has multiple tools, external APIs, messaging channels, and file access, the real question is not whether the components are known, but whether their combined reach is still acceptable. That is where visual system maps help, because they make tool chaining and dependency clusters easier to see. The named concept here is identity blast radius: the amount of downstream access an agent can accumulate through connected skills and tools. Practitioner conclusion: teams should review blast radius, not just individual permissions.

Agent self-documentation is best understood as a change-control aid, not a substitute for governance. A generated diagram can confirm that a connector exists, but it cannot by itself prove that the connector should exist, that the access is approved, or that the routing path is safe. That distinction matters in IAM and PAM programmes, where verification and authorisation are separate controls. Practitioner conclusion: use self-generated architecture views to support review, then validate them against approvals and entitlement records.

Agentic systems are starting to behave like managed identities with their own observability layer. That creates an intersection between workload identity, tool governance, and lifecycle control, because the same system that executes tasks can also explain its own structure. This is an important shift for practitioners who manage both NHI and human-access programmes, since the review model now has to accommodate machine-readable state alongside policy. Practitioner conclusion: build review processes that can consume generated state without treating the generator as the source of truth.

From our research:

• The average estimated time to remediate a leaked secret is 27 days, despite 75% of organisations expressing strong confidence in their secrets management capabilities, according to The State of Secrets in AppSec.
• Only 44% of developers are reported to follow security best practices for secrets management, exposing a significant developer behaviour gap.
• The operational lesson carries forward in the Ultimate Guide to NHIs , 2025 Outlook and Predictions, where lifecycle control becomes the decisive boundary for machine access.

What this signals

Identity blast radius: the useful unit of review is no longer the single connector or skill, but the combined reach created when an agent chains multiple tools together. That shifts the programme from documentation hygiene to access containment, especially in environments where generated artefacts can change as fast as the code. For teams formalising agent governance, the next step is to align change review with the actual runtime topology, not the last published diagram.

The harder problem is proving that the self-generated view matches authoritative configuration. If a system can describe itself but cannot be reconciled against source-of-truth records, then the review process becomes performative. That is where established identity controls, especially lifecycle review and entitlement validation, need to absorb agentic state rather than treat it as a separate class of evidence.

For practitioners

• Use generated diagrams as change evidence Require a fresh Excalidraw snapshot after any connector, skill, or permission change, then compare it to the approved architecture before release.
• Review transitive access in every agent map Look beyond the obvious tools and trace every arrow, cluster, and dependency line to identify hidden reach created by chained skills or connectors.
• Tie self-documentation to authoritative config Store the diagram output alongside the source configuration and treat mismatches as a control failure rather than a documentation issue.
• Set a blast-radius threshold for agent review Define the maximum acceptable combination of tools, APIs, and file or messaging access for a given agent class, then block expansion beyond that boundary.
• Add diagram review to offboarding and recertification When an agent is retired, re-scoped, or recertified, regenerate the map so lingering connectors or inherited skills do not survive the change.

Key takeaways

• Agent self-diagrams turn dynamic configuration into a visible control surface, but they do not replace governance.
• The security risk is the gap between what the agent can draw and what the organisation can prove about its access.
• Teams should use generated architecture maps to validate change, expose blast radius, and keep agent review tied to authoritative state.

Key terms

• Agent Self-Documentation: A runtime process where an agent generates a current description of its own skills, connectors, and routing. In governance terms, it is useful only when the output can be compared with authoritative configuration and access records. Otherwise it becomes a polished but untrusted description of reality.
• Identity Blast Radius: The total downstream reach created by an identity’s connected tools, permissions, and dependency chains. For agentic systems, blast radius is often larger than any single permission suggests because skills can call other tools and cross trust boundaries. Practitioners should review the combined effect, not isolated entitlements.
• Runtime Architecture Snapshot: A generated view of the live topology of an agentic system at a specific moment. It is more valuable than a static diagram because it can reflect current connectors and skill dependencies, but it still depends on the accuracy of the underlying configuration sources.

Deepen your knowledge

Agent self-documentation and blast-radius review are covered in the NHI Foundation Level course, the industry's only accredited NHI security programme. If you are building governance for complex agentic systems, it is a practical starting point.

This post draws on content published by WorkOS: Use Excalidraw Skills so your agents can describe themselves. Read the original.