Architecture Diagrams as Evidence, Not Art

Where this fits

You're mid-refactor, and the architecture diagram in your repo is three quarters stale. Your agent just finished a deep code change, and you need it to update the diagram to match reality—not from memory, but from explicit evidence in the codebase. The architecture-diagrams skill gives your agent a precise, rule-based way to author and visually approve a single architecture.d2 file, rendered with ELK to canonical SVG, so the diagram answers one architectural question without drifting into an exhaustive inventory.

Why agents benefit

• Evidence-driven authoring: The agent reads actual code structure, dependencies, and module boundaries to produce a diagram that reflects current state, not assumptions.
• Strict format enforcement: The skill mandates unfenced D2 source, targets D2 v0.7.1 with ELK, and leaves validation to a dedicated validator—so the agent doesn't guess at syntax or rendering quirks.
• Atomic visual review: The validator handles syntax checks, version enforcement, and atomic SVG replacement, and can attach a temporary preview for the agent to visually confirm the diagram matches the intended architecture.
• Focused scope: The skill forces the agent to answer a single architectural question, preventing diagram sprawl and keeping the artifact maintainable.
• Tool-agnostic integration: With no executable scripts, it fits any agent that can follow instructions and call external validators, making it a lightweight addition to existing workflows.

Practical scenarios

Post-refactor diagram sync

After a major module split, your agent uses the skill to regenerate architecture.d2 from the updated import graph, then runs the validator to produce a new SVG. The agent compares the old and new diagrams to ensure the core dependency flow is still accurate.

Onboarding a new service

When you add a new microservice, the skill guides your agent to add only the relevant connections to the existing diagram, using URL-only icons from the catalog, and verify the render doesn't break layout constraints.

Architecture review gate

Before a pull request merges, your agent runs the skill to validate that the diagram in the repo still matches the code. If it doesn't, it fails the check—preventing silent drift and keeping documentation trustworthy.

Add it to your agent workflow

Install the skill with:

npx skills add unoplat/unoplat-code-confluence --skill architecture-diagrams

Then instruct your agent to use it when you say something like: "Update the architecture diagram to reflect the new cache layer." The agent will read the relevant code, author architecture.d2 following the skill's guidance, and invoke the validator to produce the SVG. For a deeper look at how this skill fits into the broader agent-skill ecosystem, see the skill page on OpenAgentSkill.

Compare before adopting

Before you adopt, compare how this skill handles quality signals: does it enforce a specific D2 version and validator, or is it flexible? Check maintenance freshness—last commit, open issues, and whether the icon catalogs are kept current. Alternatives like Mermaid or PlantUML skills may offer broader tooling but lack the strict evidence-based validation this one provides. Also consider if your workflow can tolerate the single-file, single-question constraint, or if you need multi-diagram support.

Why it is worth tracking

With 95 stars and an active author, this skill shows real community interest in making diagrams verifiable artifacts rather than afterthoughts. Its focus on evidence and validation aligns with the shift toward agent-generated documentation that must be trustworthy. Evaluate it when you need your agents to produce diagrams that are not just pretty, but provably correct—and when you're willing to adopt D2 as your diagram language.