inkboard/system-atlas: an agent skill that turns an architecture discussion into a clickable isometric map

The problem System Atlas solves, and who it is for

Architecture conversations outpace documents. A discussion produces decisions, open questions and new vocabulary faster than a written spec absorbs them, and the person across the table usually wants to see the system rather than read about it. The README states the failure mode plainly: you draw a diagram, and a week later the diagram is a lie.

System Atlas is an agent skill rather than a standalone application. It is aimed at people who already run design sessions inside an agent such as Claude Code, Cursor or Codex, and who want the output of that session to be an artifact they can hand to a colleague. The README frames the fix as one data file in the repo being the single source, rendering two views that always agree: an interactive isometric map and a generated text twin called SYSTEM.md. The map is what you put in front of a person. The text is what the repo and the next session read.

That framing is the whole product argument. If you only need a picture, a drawing tool is cheaper. If you only need a document, Markdown is cheaper. The pitch here is that the picture and the document cannot drift apart because neither is hand-edited.

One data file, two generated views: how the atlas is built

The repository layout makes the data flow explicit. The README shows an atlas home containing three files:

<atlas home>/data.mjs          the only file you edit
<atlas home>/build.mjs         bun build.mjs
<atlas home>/template.html     the renderer
        |
   atlas.html   +   SYSTEM.md  both generated, never hand-edited

According to the README, data.mjs holds the structures with their position, footprint, role shape, prose, steps and questions, the flows as hop lists with payloads, the chapters with what each reveals, and the decisions. build.mjs writes both views from that file. The renderer is template.html.

The map itself is a single self-contained HTML file with no build step and no runtime dependencies, which is why publishing it is described as whatever the person can open: a hosted HTML artifact, a static server, or a repo pages host. The README's rule is one URL, republished in place.

Two design choices deserve attention. First, chapters use progressive disclosure: each chapter reveals at most three new structures and runs one small data flow that only touches what has already been shown, with the last chapter showing everything plus a flow picker. The README says the first version of an atlas is always hard to parse and treats progressive disclosure as the default fix. Second, the moving dots on the map are described as real requests. Clicking one shows its route and a representative JSON payload. That is the mechanism that turns "how does a turn actually work" into something you look at rather than explain.

Installing System Atlas and building a first atlas

The README gives one install command, using the skills CLI, which it says installs into Claude Code, Cursor, Copilot, Codex, Gemini, Cline, Amp and others:

npx skills add inkboard/system-atlas

Alternatively, the README says you can drop the skills/system-atlas/ directory into your agent's skills directory by hand. For Claude Code that is ~/.claude/skills/system-atlas/ for a personal install or .claude/skills/system-atlas/ per project.

After installing, the skill triggers on plain-language requests. The README lists examples including "make me an atlas of this pipeline" and "update the atlas, we dropped the nightly job and picked a different vendor". You do not invoke a subcommand; you describe the system and the agent follows the skill's process.

The starter data is the piece to look at first. The README says assets/data.example.mjs is a working starter with every field documented, and that you copy it, fill it in, run the build, and you have an atlas. The build command appears in the repository layout as bun build.mjs, and package.json declares a test script:

bun test ./tests/

Note the runtime assumption. package.json sets "type": "module" and the README's build line is bun build.mjs, so the build path expects Bun rather than Node. The README does not document a Node fallback for the build script, so treat Bun as a prerequisite for regenerating the atlas yourself.

Where the atlas lives, and why that decision is deferred to the repo

System Atlas does not prescribe a storage location. The README splits the choice by documentation policy. Repos that commit design docs can keep the atlas at docs/<system>/atlas/. Repos that deliberately commit only ADRs and a glossary should keep it in a git-ignored scratch directory and attach the generated SYSTEM.md to the spec issue instead. The skill asks before committing anything.

This is a sensible concession to real repository conventions, but it also means the tool has no opinion about the thing most likely to break it. An atlas in a git-ignored scratch directory is invisible to the next person who clones the repo. The README is explicit that an atlas which is out of date is worse than no atlas, and the same logic applies to an atlas nobody can find. If you go the scratch-directory route, SYSTEM.md attached to the spec issue is the durable artifact and the HTML is disposable. Decide which of the two your team treats as canonical before the first build, because the two paths produce different answers to "where do I look for the current design".

Question tracking by ID and the feedback loop

The feature that separates System Atlas from a diagram generator is question tracking. Every open question gets a stable Q-<code><n> identifier and a state: open, resolved with an answer and a date, or routed to a named next step. The README says this lets you run several rounds of feedback against the atlas without losing track of what was asked or who answered it.

The process rules around that loop are strict. The README's step five says to record the person's actual words, resolve with a date, and sweep every file after a rejection, adding that a banner on a stale section is not enough. Step six says to rebuild and republish after every change.

That is a maintenance commitment disguised as a workflow. The stable IDs are only useful if someone closes them. An atlas with twelve open questions that nobody revisits is a snapshot of a meeting, not a living document, and the text twin will faithfully reproduce the staleness. The README acknowledges this by carrying the session lessons in references/process-and-lessons.md, described as how the first session went, the subagent deep-dive pattern, and the things that bit. That file is where the honest constraints live, and it is worth reading before committing to the loop.

Limitations: what the atlas cannot tell you

The atlas is generated from a hand-maintained data file. It does not read your infrastructure, your Terraform state, your service mesh or your deployment manifests. If a service is renamed in production, data.mjs still shows the old name until someone edits it. The README's own rule, that boxes which do not map to something real are worse than no boxes, is a manual discipline, not an enforced check.

There is no release history to inspect. The repository has no retrieved releases, and package.json pins the version at 0.0.0 with "private": true. That tells you the package is not published to a registry as a versioned artifact; the install path is the skills CLI pulling the repository, or a manual copy of the skills/system-atlas/ directory. If your team requires pinned, auditable dependency versions, this is a friction point you should resolve before adoption.

The skill is also agent-dependent by construction. Its value comes from an agent reading SKILL.md, following the order of operations, and asking the right questions. Used without an agent that honors skill files, you are left with a renderer and a documented data format, which is a smaller and less interesting tool.

Finally, the isometric visual grammar is opinionated. The README describes role shapes for the brain, the stores, the tool decks, the gates and the scheduled jobs, with readable name tags so the map is legible without a key. That vocabulary is defined in references/design-language.md. A system that does not decompose into those roles will need the grammar stretched, and the README does not describe an extension path for new role shapes.

The alternative: hand-drawn diagrams and diagram-as-code

The nearest alternative is diagram-as-code tooling, where a text file is rendered into a diagram by a deterministic tool. The difference is what gets generated. Diagram-as-code produces a picture and stops. System Atlas produces a picture and a text twin from the same source, and it carries a process for the conversation that produces the source: read the inputs before drawing, discuss before drawing, build, cut into chapters, generate the text twin, run feedback rounds by question ID, rebuild after every change.

The other alternative is the one the README argues against directly: draw a diagram by hand. That is faster for a one-off explanation and requires no install, no Bun, and no data file. It also has no mechanism for staying true, which is the exact problem the project was built around.

Where System Atlas sits between those two is worth stating plainly. It costs more upfront than a sketch and less than a maintained diagram pipeline, and it only pays off if the architecture is still moving. For a system whose shape is settled, a static diagram in a README is the better trade.

Licence and the cost of keeping an atlas alive

The repository is MIT licensed, stated in both the README and package.json. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement with few strings, and it means embedding a generated atlas in internal or client-facing documentation does not raise licensing questions. This is a description of the licence text, not legal advice; if you redistribute the skill itself, keep the LICENSE file with it.

The upgrade cost is the more interesting number. There are no retrieved releases, so there is no changelog to diff and no version to pin. Updating means re-running the skills CLI install or re-copying the skill directory, and then checking whether data.mjs still matches the field set that build.mjs expects. If the data format changes, your existing data file is the thing that breaks, and there is no documented migration path in the README.

The recurring cost is editorial rather than technical. Every architecture change needs one edit to data.mjs and a rebuild, and the README insists on republishing in place at one URL. Budget for the discipline, not the tooling.

Editorial conclusion

Adopt System Atlas if you run architecture discussions in an agent session and want a single data file that produces both a map to show people and a text twin the repo can read. Skip it if you need a live diagram that reflects deployed infrastructure, if you cannot commit a build step, or if your team will not maintain data.mjs after the first render. Before you start, open skills/system-atlas/assets/data.example.mjs to confirm the field set covers your structures and flows, and check skills/system-atlas/assets/build.mjs to see how atlas.html and SYSTEM.md are written.

Frequently asked questions

Official sources

1. inkboard/system-atlas on GitHub
2. Issues
3. License: MIT
4. README