architecture-map skill
A skill that draws an interactive isometric map of a repository: buildings sized by real code, flows traced along real calls.
- 383 ★ on the repository
- Last commit
Extended access
Why this level
- The skill copies components and a script into the repository and edits `package.json`.
- An enabled CI check can block merging until the map is refreshed.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/architecture-mapDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill copies components and a script into the repository and edits `package.json`.
- An enabled CI check can block merging until the map is refreshed.
This is third-party code. Review the repository files before installing.
What it does
architecture-map builds a page in your repository with an architecture map drawn as an isometric city. Buildings stand for subsystems and scale with measured code volume, neighborhoods group subsystems and animated flows trace real call paths. A drift counter fails the CI check when the map falls behind the code. The skill first detects the framework, design tokens and dark-mode mechanism, runs `propose-coverage.mjs` and asks four questions: where to put the page, what to cover, which design system to use, and whether to add a CI check and sync in `predev` and `prebuild`. Then it copies React components, writes `architecture.config.json` and composes a graph: four to seven groups and 15 to 25 nodes with descriptions read from the code. Descriptions and links are written by hand, while file counts, coverage and geometry are measured by a script.
Who it is for. Teams onboarding newcomers to a large repository who want a map that does not go stale after the first refactor.
Good fit when
- A new developer must see how the repository fits together in an hour, not a week.
- The project itself needs an architecture page in React, in the colors of its own design system.
- The map should fail CI when the code moved ahead and the description stayed the same.
- The wiki description of subsystems went stale, and a map refreshed by rerunning the skill replaces it.
Not a fit when
- A static diagram for a document: the skill's output stays an interactive page inside the app.
- A quick draft without reading code: node descriptions are written after reading files and no script generates them.
- A repository without React: the ready-made map components are written in React.
Example request
Build an architecture map of this repository on the `/~/architecture` page in our design system's colors.Limitations
The ready-made map components depend only on React and typecheck under `strict`. The agent writes the descriptions of groups, nodes and flows by hand after reading the code, so building takes noticeable time. The skill copies the components and the `architecture-sync.mjs` script into the repository and adds an `architecture:sync` command to `package.json`. The CI check is optional and fails until the map is refreshed. The repository holds one skill, version 1.0.0, and its scripts are written for Node.js.
How to disable. Remove the symbolic link to the skill from the skills directory. Delete the files copied into the project (`src/architecture/`, `scripts/architecture-sync.mjs`, `architecture.config.json`) and the `architecture:sync` command in `package.json` by hand.
FAQ
How do I install the skill?
Clone the repository and create a symbolic link: `ln -s "$PWD/architecture-map" ~/.claude/skills/architecture-map`. For Codex use `~/.codex/skills/architecture-map`. Skills load at session start, so open a new one.
What does the skill ask?
Four questions: where to put the page (`/~/architecture` by default), what to cover, which design system to use and which extras to add: a CI check, sync and version history.
Why does the map not go stale?
Descriptions are written by hand, while file counts, coverage and geometry are measured by a script. The unmapped-files counter shows drift, and CI fails until the map is refreshed.
How many nodes will the map have?
The skill recommends 4–7 groups and 15–25 nodes.
How do I refresh the map?
Run the skill again. If `architecture.config.json` exists at the root, it works as an update rather than a new build.
Discussion
No questions or reviews yet.
Related
SkillsA skill that turns an architecture discussion into an interactive isometric map of the system and a SYSTEM.md text twin from one data file
A skill maps project architecture, rules and proposed edit scope in an HTML page so users can approve a plan before code changes.
A skill that maps a repository into meaningful blocks, walks through the code on that map step by step and highlights broken spots
A skill that replaces terminal ASCII with self-contained HTML pages: diagrams, diff reviews, plan reviews, tables and slide decks
stack-diagram is an architecture-diagram skill that embeds logos and fonts in HTML, so the finished file opens offline.
Skill that draws architecture, flowchart and sequence diagrams as hand-placed SVG in one house style
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| architecture-map (this card) | no | 383 | |
| Diagram Design | no | 65,211 | draws standalone diagrams as HTML and SVG files, while architecture-map builds an interactive map inside the app with a drift counter |
| stack-diagram | no | 1,880 | embeds logos and fonts into a diagram for offline viewing, while architecture-map measures code volume and watches for staleness in CI |
README in short
The repository is meant as a set of portable `SKILL.md` skills but holds one so far. The README explains how to install skills by symlink so `git pull` updates every install at once, and which folders make up a skill: `references`, `scripts`, `assets`.