Skip to content
Skills Library
Programming · Analysis

project-map

/project-map

Create or refresh a visual architecture map of a project: its inputs and data sources, scripts and timers, app code, agents and humans, the files they hand over, and its outputs. A script discovers the parts; you tidy the draft and render an interactive page (pan, zoom, hover details) under ~/agent-maps/<project>/. Also checks whether an existing map is out of date. Use when asked to map, draw, visualise or explain how a project and its agents fit together, or to update a map. Triggers: project map, architecture drawing, agent map, draw the setup, node map.

Repository
project-map ↗
Licence
MIT
Last repository change
03.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
3
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 03.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: board.py, discover.py, render_map.py

What it does and when to use it

Create or refresh a visual architecture map of a project: its inputs and data sources, scripts and timers, app code, agents and humans, the files they hand over, and its outputs. A script discovers the parts; you tidy the draft and render an interactive page (pan, zoom, hover details) under ~/agent-maps/<project>/. Also checks whether an existing map is out of date. Use when asked to map, draw, visualise or explain how a project and its agents fit together, or to update a map. Triggers: project map, architecture drawing, agent map, draw the setup, node map.

Original author description

Create or refresh a visual architecture map of a project: its inputs and data sources, scripts and timers, app code, agents and humans, the files they hand over, and its outputs. A script discovers the parts; you tidy the draft and render an interactive page (pan, zoom, hover details) under ~/agent-maps/<project>/. Also checks whether an existing map is out of date. Use when asked to map, draw, visualise or explain how a project and its agents fit together, or to update a map. Triggers: project map, architecture drawing, agent map, draw the setup, node map.

How it works

  1. Where things go
  2. 1a. New map: discover
  3. 1b. Existing map: drift and update
  4. 2. Tidy the draft (this is your job)
  5. 3. Render and look at it
  6. 4. Live board (optional; ask the user before adding it to a new project)
  7. 5. Reply
Original SKILL.md headings · 83 lines, 928 words
SKILL.md preview
---
name: project-map
description: >
  Create or refresh a visual architecture map of a project: its inputs and data sources, scripts and timers, app
  code, agents and humans, the files they hand over, and its outputs. A script discovers the parts; you tidy the
  draft and render an interactive page (pan, zoom, hover details) under ~/agent-maps/<project>/. Also checks whether
  an existing map is out of date. Use when asked to map, draw, visualise or explain how a project and its agents fit
  together, or to update a map. Triggers: project map, architecture drawing, agent map, draw the setup, node map.
---

# Project map

The scripts sit next to this file; below, `<skill>` means this skill's folder. They need only Python 3.10+.
The map is data (`map.json`); the look comes from the shared renderer. Never invent parts: the discovery script
finds facts, you add names, grouping and descriptions. If unsure whether something exists, leave it out and say so.

## Where things go
- `~/agent-maps/<project-folder-name>/map.json` and `map.html`, outside the repo (nothing gets published).
  Only put a map in a repository if the user asks for that.
- Existing map? **Update** it (step 1b); keep ids, positions, zones and wording the user tuned.

## 1a. New map: discover
`python3 -I -B <skill>/discover.py <repo> -o ~/agent-maps/<project>/map.json`
It finds scripts, package/Makefile commands, CI workflows, timers, app modules and their imports, docker-compose
services, agent skills that mention the project and the folders they hand work through, data folders, fetched hosts,
and generated outputs, with links between them and a column layout. Each box has `source` (where it came from).

## 1b. Existing map: drift and update
- `python3 -I -B <skill>/discover.py <repo> --check <map.json>`: lists boxes whose files are gone (STALE) and parts not on the map (NEW).
- `python3 -I -B <skill>/discover.py <repo> --update <map.json>`: adds NEW parts (marked `"new": true`, placed under boxes of
  the same kind) and marks STALE boxes; it never moves or deletes anything. Then tidy those boxes (step 2) and remove `new`.
- Parts the user does not want on the map: `--baseline <map.json>` records everything currently left out in `ignore`.

## 2. Tidy the draft (this is your job)
Read the instruction files (`AGENTS.md`, `CLAUDE.md`, `README*`, `CONTRIBUTING*`) and the skills involved, then edit map.json:
- **Names and text:** `title` <= 22 characters, `sub` <= 36 (what it does), `detail` 1-2 sentences for the hover panel,
  `model` for agents if their settings or skill say which model they use.
- **Merge and drop:** merge minor scripts into one box ("update.py + gen_*.py"), drop noise (one-off research scripts,
  links that are not real). Aim for at most ~30 boxes. Keep every `source` (merge the lists) so drift keeps working.
- **Add what a script cannot see:** humans and what they do (approve, record, release), external inputs named only in docs,
  the hand-over files between agents. Give added boxes a `source` when they correspond to a file.
- **Zones** (`groups`): tidy blocks such as Sources, Timers & CI, Generators/Build, App code, Change pipeline, Shipped.
- **Layout:** `x`, `y` are grid units of 20 px; a box is 11 x 4 units. Stack with pitch 6, leave ~7-9 units between zones
  so wires have corridors, and read left to right as the flow. Place a box level with what it talks to most.

Format reference:
```json
{"version": 1, "title": "…", "subtitle": "what it is · updated <date>", "repo": "~/path/to/repo",
 "nodes": [{"id": "gens", "x": 18, "y": 10, "kind": "script", "title": "update.py + gen_*.py", "sub": "regenerate data",
            "detail": "…", "source": ["tools/update.py", "tools/gen_*.py"]}],
 "edges": [["gens", "data", "data"]],
 "groups": [{"label": "Generators", "nodes": ["gens"], "kind": "script"}],
 "ignore": [], "live": {}}
```
**Inner maps:** discover.py gives merged boxes and app folders an `inner` map (shown when the box is opened). Keep them
when you tidy; you may rename their boxes or drop noise inside. To give a hand-made box detail, add
`"inner": {"nodes": [...], "edges": [...]}` (x/y optional; `"outside": true` for boxes from the level above).
`version` is the map format (currently 1); keep it, and never raise it by hand.
Node kinds: `input`, `script`, `service` (CI, timers, containers), `module` (app code), `agent` (a model, costs tokens),
`human`, `file` (hand-over file or folder), `output`. Edge kinds: `data`, `control` (starts/calls), `human`, `feedback`.

## 3. Render and look at it
`python3 -I -B <skill>/render_map.py ~/agent-maps/<project>/map.json --png /tmp/<project>-map.png`
Fix every error it prints; read the warnings (unconnected boxes, frames covering boxes, drift). Open the PNG and check
that no text overflows, wires do not bunch up (spread zones apart) and the flow reads left to right. Re-render after changes.
The page pans by dragging and zooms with pinch, Ctrl+scroll or its buttons, so it also works on a phone.

## 4. Live board (optional; ask the user before adding it to a new project)
`python3 -I -B <skill>/board.py --open` serves every map in ~/agent-maps on http://127.0.0.1:8765/ and colours boxes from local
facts. discover.py drafts a `live` section; check and adjust it. Only these read-only probes exist:
```json
"live": {
  "match": "<text in the agent session folder names, usually the repo folder name>", "working_seconds": 60,
  "sessions": [{"node": "impl", "match": "implementation sub-agent|<project>-implementer"}],
  "files":    [{"node": "reviews", "glob": "~/loop/reviews/*.md", "verdict": true},
               {"node": "flags", "glob": "~/loop/PENDING*", "alert": true},
               {"node": "gate", "glob": "/tmp/review-*", "working_if_exists": true, "label": "review worktree"}],
  "units":    [{"node": "check", "unit": "<systemd user unit name>"}],
  "git":      [{"node": "pr", "repo": "~/repo", "exclude": ["main", "t3/*"]}],
  "process":  [{"node": "app", "pattern": "<pgrep -f pattern>", "running": "app running", "stopped": "app closed"}]}
```
The board also serves Arrange mode: the user can drag boxes and edit zones on the page and press Save, which rewrites
only positions and `groups` in map.json. Re-read map.json before editing it, so you do not overwrite their layout.
Session rules match a session's name plus the first 300 characters of its first prompt; the first matching rule wins.
Verify with `python3 -I -B <skill>/board.py --once <project>`: every agent box should show its own sessions.

Never print environment variables or secrets while discovering (`env`, `printenv`, `.env` files): they end up in logs.

## 5. Reply
Give the path to `map.html` (and the board URL if it runs), a few lines on what the map shows, and anything you left
out because you could not confirm it.
Files in this package (8)
  • .gitignore 1 KB
  • LICENSE 1 KB
  • README.md 9 KB
  • SKILL.md 7 KB
  • board.py 22 KB
  • discover.py 40 KB
  • render_map.py 11 KB
  • template.html 72 KB

Versions

RepositoryScoreLicence
This page · perweum/project-map100MIT
mgionas/ai-dev-guild100MIT
tojim00d/Orbit-skills100MIT

Database snapshot: 13.11.2026 · package version d98e8bcfc531 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100update-codebase-map
    Refresh an existing .claude/.codebase-info/ map after code changes. Use for stale codebase or architecture docs; use map-codebase to create one.
  • 100architecture-map
    Generate or refresh the repo-wide architecture map — architecture-out/architecture-map.json (machine contract with named flows) + architecture-map.html (self-contained viewer). Use when the user asks for an architecture map, repo map, "/architecture-map", or when an agent needs…
  • 100map-systems
    Creates a visual and textual map of the project systems, services, data flows, and integration boundaries. Use when documenting system architecture or when the user mentions system map, architecture diagram, or service boundaries.
  • 100repo-map
    Generate or refresh a durable, directory-level map of the codebase — what each directory is for and its key entry-point files — stored as memory/architecture/repo-map.md and stamped with the git commit it was verified against. Use to create the map, refresh it after the tree…
  • 90visual
    Turn the current work into one polished, self-contained HTML visual page — a recap of a branch's changes, a plan, a map of a folder, endpoint set, or architecture, or an interactive drill-down map of a skill pack or system (zoom, pan, click a node for details, double-click to…
  • 100codebase-onboarding
    Map an unfamiliar repository into an onboarding guide (stack, architecture, entry points, conventions, commands) and a starter or refreshed agent instructions file (AGENTS.md or CLAUDE.md). Use when joining a project, asked to explain a codebase, or to create or refresh that file.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.