What is it?
What it is
An agent skill that turns an architecture discussion into an interactive isometric map and a generated text twin (SYSTEM.md) from a single data file.
Why it exists
Because architecture discussions produce decisions, questions, and vocabulary faster than any document can hold, and people want to see the system rather than read it; the atlas provides a single source of truth that renders two always-consistent views.
Who should use it
Software architects, technical leads, and engineering teams who need to collaborate on system design through interactive, visual diagrams backed by a single source of truth. Also suitable for agents or AI assistants that help document and evolve architecture discussions.
Who should avoid it
Teams working on purely abstract or non-visual systems where spatial representation adds no value, or projects with strict no-JavaScript constraints since the output is a self-contained HTML file. Also not ideal for those seeking real-time collaborative editing without additional tooling.
How it works
A quick walkthrough in plain English
How system-atlas works
Step 1 of 3
You interact with it
Open system-atlas, send a request, or connect it to your stack.
Features
Advantages
- Single source of truth eliminates diagram drift
- Interactive map and documentation stay perfectly in sync
- Facilitates architecture discussions with a visual, explorable artifact
- Progressive disclosure reduces cognitive load on first view
- Interactive data packets provide concrete insight into request flows
- Question tracking ensures no open issues are lost across feedback rounds
- No external libraries or runtime needed to view the atlas
- Easy to update: edit data.mjs, rebuild, republish
- Portable HTML can be hosted anywhere (static server, GitHub Pages, etc.)
- Encourages a disciplined design process (read inputs, discuss, build, feedback)
- Includes design language and process lessons to guide usage
Disadvantages
- Requires learning the specific data.mjs format for authoring
- Build step requires Node.js to generate the atlas and text twin
- Isometric view may not suit all preferences or accessibility needs
- Designing effective chapters and flows adds extra effort
- May be overkill for very simple systems with few components
- Limited to the predefined visual style; customizing look requires editing the template
- Dependence on the skills CLI for installation in some agent environments
Installation
native
npx skills add inkboard/system-atlas Or drop skills/system-atlas/ into your agent's skills directory by hand — for Claude Code that is ~/.claude/skills/system-atlas/ (personal) or .claude/skills/system-atlas/ (per project).
FAQ
What is System Atlas and what does it do?
System Atlas is an agent skill that converts architecture discussions into an interactive, clickable isometric map of a system. It generates two synchronized views from a single data file: an interactive HTML map you can pan, zoom, and explore (hover to read, click to pin, arrow-right to go inside structures), and a generated text twin (SYSTEM.md) containing the decisions table, structures, flows, and open questions. Both views are always in agreement because they are built from the same source file, so updating the design is one edit and a rebuild.
How do I install System Atlas?
Install it using the skills CLI: `npx skills add inkboard/system-atlas`. This installs into supported agents like Claude Code, Cursor, Copilot, Codex, Gemini, Cline, and Amp. Alternatively, you can manually drop the `skills/system-atlas/` directory into your agent's skills directory (e.g., `~/.claude/skills/system-atlas/` for personal use in Claude Code, or `.claude/skills/system-atlas/` for per-project use).
What is the single source of truth for an atlas, and how do I build it?
The single source of truth is `<atlas home>/data.mjs`, the only file you edit. It contains structures (position, footprint, role shape, prose, steps, questions), flows as hop lists with payloads, chapters defining progressive disclosure, and decisions. To build, run `node build.mjs` from the atlas home directory, which generates `atlas.html` (the interactive map) and `SYSTEM.md` (the text twin). Never hand-edit the generated files. A documented starter is available at `assets/data.example.mjs` — copy it to `data.mjs`, fill it in, and run the build.
How does progressive disclosure work in the map?
Instead of showing the entire system at once (which reads as noise), the atlas is cut into chapters. Each chapter reveals at most three new structures and runs one small data flow that only touches what you have already seen. The first version is always 'hard to parse,' so progressive disclosure is the default fix. The last chapter shows everything with a flow picker, letting you explore the complete system once the foundational pieces are understood.
How are questions tracked and managed?
Every open question gets a stable ID in the format `Q-<code><n>` and a state: open, resolved (with the answer and the date), or routed to a named next step. You can run several rounds of feedback against a question without losing track of what was asked or who answered it. After feedback rounds, you record the person's actual words, resolve with a date, and sweep every file after a rejection. A banner on a stale section is not enough — the atlas must be rebuilt and republished after every change.
Where should I keep the atlas in my repo, and how do I publish it?
Where the atlas lives depends on your repo's docs policy. Repos that commit design docs can keep it at `docs/<system>/atlas/`; repos that 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. The map is a single self-contained HTML file with no runtime dependencies, so publishing is whatever the person can open: a hosted HTML artifact, a static server (`npx serve`, `python3 -m http.server`), or your repo's pages host. The rule is one URL, republished in place.
Featured in Videos
YouTube tutorials and walkthroughs for system-atlas
Alternatives
Similar projects ranked by category, topics, and text overlap.
