system-atlas
An agent skill that turns an architecture discussion into an explorable isometric atlas: one data file, an interactive map and a generated SYSTEM.md
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/inkboard--system-atlas)HTML
<a href="/listings/inkboard--system-atlas"><img src="/api/listings/inkboard--system-atlas/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
The [`skills` CLI](https://github.com/vercel-labs/skills) installs into Claude Code, Cursor, Copilot, Codex, Gemini, Cline, Amp and others:
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).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 92 lines · 1 finding marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # System Atlas
- **An agent skill that turns an architecture discussion into something you can click around.**
- 
- *Above: a real atlas of a production agent system, built with this skill — chapters reveal the system a few structures at a time, hovering reads a structure, and going inside one shows its steps in execution.*
- [](https://skills.sh/inkboard/system-atlas)
- ```bash
- npx skills add inkboard/system-atlas
- ```
- ## Why
- Architecture discussions produce decisions, questions, and vocabulary faster than any one document can hold, and the person you are discussing with wants to *see* the system, not read it. So you draw a diagram, and a week later the diagram is a lie. An atlas fixes the shape of that problem rather than the diagram: one data file in the repo is the single source, and it renders two views that always agree — an **interactive isometric map** you explore with a mouse, and a **generated text twin** (`SYSTEM.md`) that carries the decisions table, every structure, the flows, and every open question by stable ID. The map is what you put in front of a person; the text is what the repo and your next session read; because both are generated from the same file, updating the design is one edit and a rebuild, and there is exactly one place where the system can be wrong.
- ## What you get
- - **An interactive isometric map** — hover a structure to read it, click to pin it, arrow-right to go *inside* and see its steps in execution, pan and zoom the whole thing. One self-contained HTML file, no build step, no runtime dependencies.
- - **Progressive-disclosure chapters** — a whole system at once reads as noise. Each chapter reveals at most three new structures and runs one small data flow that only touches what you have already seen; the last chapter shows everything with a flow picker.
- - **Moving data packets you can inspect** — the dots travelling the hops are real requests. Click one and the panel shows its route and a representative JSON payload, so "how does a turn actually work" has a visual answer.
- - **A generated text twin** — `SYSTEM.md`, rebuilt from the same data: the decisions table with ADR links, every structure's what/how/steps, the flow tables, and the question index.
- - **Question tracking by ID** — every open question gets a stable `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 it without losing track of what was asked or who answered it.
- - **Role shapes and readable labels** — the brain, the stores, the tool decks, the gates and the scheduled jobs each get their own isometric form and a name tag on the canvas, so the map is legible without a key.
- - **The process, not just the renderer** — the skill carries the design language and the session lessons that produced it, so the agent knows the order to work in and the corrections to skip.
- ## Using it
- Ask for one in plain language. The skill triggers on things like:
- > "make me an atlas of this pipeline"
- > "map the system so we can talk about it"
- > "I want a diagram I can click around and poke holes in"
- > "walk me through how this fits together"
- > "update the atlas — we dropped the nightly job and picked a different vendor"
- Then the agent works in this order:
- 1. **Read the inputs before drawing** — the vision doc, the repo's real surfaces, the framework's docs. Boxes that don't map to something real are worse than no boxes.
- 2. **Discuss before drawing** — propose the structure in chat, mapped to the runtime's actual primitives, and ask only the questions it cannot derive from the repo.
- 3. **Build the first atlas**, then **cut it into chapters** — the first version is always "hard to parse"; progressive disclosure is the fix, and it is the default here.
- 4. **Generate the text twin** and keep the glossary (`CONTEXT.md`) and ADRs beside it.
- 5. **Run feedback rounds by question ID** — 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.
- 6. **Rebuild and republish after every change.** An atlas that is out of date is worse than no atlas.
- ## How it works
- ```
- <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
- ```
- `data.mjs` holds the structures (position, footprint, role shape, prose, steps, questions), the flows as hop lists with payloads, the chapters with what each reveals, and the decisions. `build.mjs` writes both views from it. `assets/data.example.mjs` is a working starter with every field documented — copy it, fill it in, run the build, and you have an atlas.
- 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 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.
- Dismissed after review: Contains a <system> block, a common wrapper for instructions hidden in a tool description
- Line 60 on GitHub
- The map is a single self-contained HTML file, so publishing it is whatever the person can open: a hosted HTML artifact if your agent can publish one, a static server (`npx serve`, `python3 -m http.server`), or your repo's pages host. The rule is one URL, republished in place.
- ## What's in the repo
- | Path | What it is |
- |---|---|
- | `skills/system-atlas/SKILL.md` | The skill: when to use it, the process, what done looks like |
- | `skills/system-atlas/assets/template.html` | The atlas renderer |
- | `skills/system-atlas/assets/build.mjs` | `data.mjs` → `atlas.html` + `SYSTEM.md` |
- | `skills/system-atlas/assets/data.example.mjs` | Documented starter data — copy to `data.mjs` |
- | `skills/system-atlas/references/design-language.md` | Layout, palette, isometric grammar, role shapes, copy rules, the chapter recipe |
- | `skills/system-atlas/references/process-and-lessons.md` | How the first session went, the subagent deep-dive pattern, and the things that bit |
- | `skills/system-atlas/evals/evals.json` | Three eval prompts: a new atlas, an update, and a small greenfield one |
- ## Installing
- The [`skills` CLI](https://github.com/vercel-labs/skills) installs into Claude Code, Cursor, Copilot, Codex, Gemini, Cline, Amp and others:
- ```bash
- 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).
- ## Credits
- The visual grammar takes after the "codebase as interactive isometric diagram" style — khaki paper, black hatched structures, an index on the left, a reading panel on the right, and data packets you can catch. The process rules are the corrections from a real design session, kept in the order they were earned.
- ## License
- MIT — see [LICENSE](./LICENSE).
skills/system-atlas/assets/data.example.mjs · Bundled script · 87 lines · 1 finding marked
- // Single source of truth for one atlas. Copy to <atlas home>/data.mjs and edit.
- // Build: bun <atlas home>/build.mjs → writes ../SYSTEM.md and ../atlas.html
- // The atlas home is docs/<system>/atlas/ in repos that commit design docs, or a
- Note: Usual in code (tag names in paths and patterns): Contains a <system> block, a common wrapper for instructions hidden in a tool description
- Line 3 on GitHub
- // git-ignored scratch directory in repos that only commit ADRs + CONTEXT.md.
- export const META = {
- title: 'Example Agent', // "<title> Atlas" in the tab; "<title> — System Definition" in SYSTEM.md
- artifactUrl: '', // fill after first publish; keep it stable across rebuilds
- sourcePath: 'docs/example/atlas/data.mjs',
- buildCmd: 'bun docs/example/atlas/build.mjs',
- stats: [{ k: 'System', v: 'example · v0' }, { k: 'Model roles', v: '2' }], // static top-strip stats; chapter/shown/questions are added automatically
- intro: `_**This file is the living source of truth for the design.** The interactive atlas is built from the same data._`,
- onePara: `One paragraph a newcomer can read in 30 seconds: what the system is, what the loop is, what is not built yet.`,
- costModel: ['Optional: cost assumptions and a table. Leave [] to omit.'],
- deepDive: '', // optional: summary + links to research/
- platformGives: 'What the runtime/framework provides for free.',
- weOwn: 'What we have to build ourselves.',
- filesystem: `apps/example/\n agent/…`,
- };
- // Decisions render as the SYSTEM.md table and as chapter-10's "Decisions locked" list.
- export const DECISIONS = [
- { axis: 'Runtime', decision: 'What and why, in one line', adr: '[0001](./adr/0001-slug.md)' },
- ];
- export const GROUPS = [
- { id: 'loop', title: 'The main loop' },
- { id: 'mem', title: 'Memory' },
- { id: 'sup', title: 'Supporting the loop' },
- { id: 'off', title: 'Not yet switched on' },
- ];
- // Structure = one isometric box. Fields:
- // id/code: 1–2 letters shown on the box · name · short (≤14 chars, canvas label) · group
- // gx,gy: grid position · w,d: footprint · h: height px · kind: box|tall|store|cards|slab|screen|gate|job
- // ghost: true → dashed "designed for, not built"
- // one: one-sentence summary (shown first) · what: plain description · how: implementation (may use <code>, <mark>)
- // steps: [[name, desc], …] → the "go inside" view
- // cond: questions — string (open) | {q, r} (resolved, r = answer + date) | {q, to} (routed to a named next step)
- export const NODES = [
- { id: 'U', code: 'U', name: 'Web chat', short: 'WEB CHAT', group: 'loop', gx: 1.5, gy: 7.5, w: 2, d: 2, h: 44, kind: 'screen',
- one: 'The page where you talk to the agent.',
- what: 'Plain-language description for a non-engineer.',
- how: 'Implementation with <code>identifiers</code> and <mark>key phrases</mark>.',
- steps: [['Open', 'Create or continue a session.'], ['Stream', 'Render deltas.']],
- cond: ['Where does the page live?', { q: 'Auth scheme?', r: 'Reuse existing session JWT (2026-01-01).' }] },
- { id: 'I', code: 'I', name: 'Root agent', short: 'AGENT', group: 'loop', gx: 10, gy: 2.5, w: 3, d: 3, h: 64, kind: 'tall',
- one: 'The brain — one durable conversation per person.', what: '…', how: '…', steps: [['turn.started', '…'], ['Model call', '…'], ['Tools', '…'], ['Stream', '…']], cond: [] },
- { id: 'M', code: 'M', name: 'Memory', short: 'MEMORY', group: 'mem', gx: 6.5, gy: 9.5, w: 3, d: 3, h: 24, kind: 'store',
- one: 'What the agent knows about you.', what: '…', how: '…', steps: [['Write', '…'], ['Read', '…']], cond: [{ q: 'Vendor?', to: 'Memory deep dive' }] },
- { id: 'P', code: 'P', name: 'Proactive', short: 'PROACTIVE', group: 'off', ghost: true, gx: 12.5, gy: -1, w: 2, d: 2, h: 34,
- one: 'Later: the agent reaches out on a schedule.', what: '…', how: '…', steps: [['Tick', '…']], cond: ['Notification etiquette.'] },
- ];
- // Flows for the final "whole system" chapter. Hop = [from, to, label, payload, bend('xy'|'yx')]
- export const FLOWS = [
- { id: 'turn', name: 'One turn', hops: [
- ['U', 'I', 'user message', { message: 'can you move my 3pm?' }, 'yx'],
- ['I', 'M', 'recall', { query: 'move my 3pm', k: 12 }, 'xy'],
- ['M', 'I', 'memories', { hits: 2 }, 'xy'],
- ['I', 'U', 'message.appended', { delta: 'Sure —' }, 'yx'],
- ] },
- ];
- // Chapters = progressive disclosure. Each reveals a few structures and runs ONE small flow among revealed ones.
- // The last chapter has reveal: [] and flow: null → shows everything with a flow picker.
- export const CH = [
- { id: 'you', title: 'You and the agent', reveal: ['U', 'I'],
- lede: `Strip everything away and this is the system: you type, it answers.`,
- story: `<p>Two or three sentences. <mark>Highlight</mark> the one idea this chapter adds.</p>`,
- flow: [['U', 'I', 'user message', { message: '…' }], ['I', 'U', 'reply', { delta: '…' }]] },
- { id: 'know', title: 'Knowing you', reveal: ['M'],
- lede: `Before answering, the agent recalls what it knows about you.`,
- story: `<p>…</p>`,
- flow: [['U', 'I', 'user message', { message: '…' }], ['I', 'M', 'recall', { k: 12 }], ['M', 'I', 'memories', { hits: 2 }], ['I', 'U', 'reply', { delta: '…' }]] },
- { id: 'later', title: 'Later', reveal: ['P'],
- lede: `Designed for, not switched on.`, story: `<p>…</p>`,
- flow: [['P', 'I', 'scheduled turn', { kind: 'morning_brief' }]] },
- { id: 'all', title: 'The whole system', reveal: [],
- lede: `Everything at once, for free exploration.`,
- story: `<p>Choose which flow runs (bottom left). Hover anything; click to pin; → goes inside. The <mark>Open questions</mark> tab lists every question by ID.</p>`,
- flow: null },
- ];
- // "How it's built" tab with nothing selected (HTML).
- export const HOW_HTML = `<div class="eyebrow">Example · v0</div><h1 class="t">How it's built</h1><div class="sub">the shape and what sits around it</div>
- <h3 class="sec">Filesystem</h3><pre>apps/example/…</pre>`;
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.