floorplan
Draw a floorplan of an app's codebase (one repo or several side by side), an interactive node-graph map where every subsystem, module, file and HTTP route has a human-readable name and a one-line description, connected by the imports and HTTP calls between them, at several zoom levels. It is saved as a self-contained floorplan/index.html in the codebase. Use whenever the user wants to visualize, map, diagram, document or get an architectural overview of a codebase, repo or monorepo, understand how their app works or is connected under the hood, onboard onto unfamiliar code, see how the frontend talks to the backend, or update an existing floorplan, even if they don't say "visualize". Also use it before any code exists: when the user shares a PRD, a spec or a description of something they want to build and asks what pieces it needs or how they'd fit together, it draws a blueprint, the same map planned from the document.
- License 许可
- MIT
- 所属仓库
- siddu1004/SFP
- 最近更新
- 2026-11-09
- Stars
- ★ 5
- Forks
- 0
01 前言 Front Matter
- name
- floorplan
- description
- Draw a floorplan of an app's codebase (one repo or several side by side), an interactive node-graph map where every subsystem, module, file and HTTP route has a human-readable name and a one-line description, connected by the imports and HTTP calls between them, at several zoom levels. It is saved as a self-contained floorplan/index.html in the codebase. Use whenever the user wants to visualize, map, diagram, document or get an architectural overview of a codebase, repo or monorepo, understand how their app works or is connected under the hood, onboard onto unfamiliar code, see how the frontend talks to the backend, or update an existing floorplan, even if they don't say "visualize". Also use it before any code exists: when the user shares a PRD, a spec or a description of something they want to build and asks what pieces it needs or how they'd fit together, it draws a blueprint, the same map planned from the document.
- allowed-tools
- [ "Bash(node ${CLAUDE_SKILL_DIR}/scripts/build.mjs *)", "Bash(node ${CLAUDE_SKILL_DIR}/scripts/describe.mjs *)", "Bash(node ${CLAUDE_SKILL_DIR}/scripts/open.mjs *)", "Bash(node ${CLAUDE_SKILL_DIR}/scripts/plan.mjs *)", "Bash(node ${CLAUDE_SKILL_DIR}/scripts/recent.mjs *)", "Bash(node ${CLAUDE_SKILL_DIR}/scripts/refresh.mjs *)", "Bash(node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs *)", "Bash(node ${CLAUDE_SKILL_DIR}/scripts/status.mjs *)" ]
- argument-hint
- [path-to-codebase-root] [--refresh]
02 资源文件 38
- 参考文档agents/openai.yaml232 B
- 资产文件assets/favicon.png2.0 KB
- 脚本assets/graph-query.js19.8 KB
- 资产文件assets/logo.png4.4 KB
- 脚本assets/query-cli.mjs1.5 KB
- 脚本assets/serve.mjs41.9 KB
- 脚本assets/ui/05-theme.js2.9 KB
- 脚本assets/ui/06-blueprint.js6.9 KB
- 脚本assets/ui/10-glossary.js14.6 KB
- 脚本assets/ui/20-health.js19.0 KB
- 脚本assets/ui/25-recent.js5.7 KB
- 脚本assets/ui/30-screens.js8.8 KB
- 脚本assets/ui/40-tour.js9.8 KB
- 脚本assets/ui/50-cloud.js8.6 KB
- 脚本assets/ui/60-export.js5.5 KB
- 资产文件assets/viewer.html174.5 KB
- 参考文档references/blueprint.md8.1 KB
- 参考文档references/choosing-boundaries.md4.0 KB
- 参考文档references/schema.md10.4 KB
- 参考文档references/writing-descriptions.md11.2 KB
- 脚本scripts/build.mjs31.3 KB
- 脚本scripts/describe.mjs7.7 KB
- 脚本scripts/lib/agent.mjs812 B
- 脚本scripts/lib/blueprint.mjs15.8 KB
- 脚本scripts/lib/claudemd.mjs5.4 KB
- 脚本scripts/lib/common.mjs13.2 KB
- 脚本scripts/lib/extract.mjs33.0 KB
- 脚本scripts/lib/health.mjs108.7 KB
- 脚本scripts/lib/names.mjs2.4 KB
- 脚本scripts/lib/resolve.mjs13.2 KB
- 脚本scripts/lib/routes.mjs10.6 KB
- 脚本scripts/lib/screens.mjs38.3 KB
- 脚本scripts/open.mjs4.8 KB
- 脚本scripts/plan.mjs3.3 KB
- 脚本scripts/recent.mjs4.4 KB
- 脚本scripts/refresh.mjs10.5 KB
- 脚本scripts/scan.mjs15.6 KB
- 脚本scripts/status.mjs2.7 KB
03 SKILL.md 正文
Floorplan
You produce floorplan/ at the codebase root: a floorplan of the app that someone new can read like a system diagram. Every card shows a human name and a one-line description, with the real path in small type underneath.
- You write:
architecture.json(subsystems, modules, flows) anddescriptions/*.json(a name and description for every file and route). - Generated:
graph.jsonandindex.html.
The scripts do the mechanical work: finding repos, parsing imports and routes, matching HTTP calls to endpoints, layout and rendering. Your job is the part only a reader of the code can do: deciding what things are and saying so plainly.
Existing map: !node ${CLAUDE_SKILL_DIR}/scripts/status.mjs || true
Arguments: $ARGUMENTS
In Codex (or any agent that left the two lines above unfilled): ${CLAUDE_SKILL_DIR} in every command here means this skill's folder, the one holding this SKILL.md, so use its path. Run node <that folder>/scripts/status.mjs from the codebase root yourself to see whether a map exists, and take the path and --refresh from the user's request. The scripts notice they're running under Codex, so the map's Ask bar and "Fix with" prompts use Codex.
Nothing built yet? Draw a blueprint
If the user wants to plan something they haven't built ("here's my PRD", "I want to build an app that…", a long description of a system), make a blueprint: the same map, planned from their document instead of scanned from code. Use this path when there's no code for the system yet, even if the folder holds other things. If the code exists, make a normal map.
- Read the input. A PRD file, a pasted message, or a document they point you at. Ask 2–3 questions only if something fundamental is open (who uses it, web or mobile, does anyone sign in, does money change hands); otherwise decide and record it as an assumption.
- Read references/blueprint.md, then references/schema.md for architecture.json.
- Write
floorplan/plan.json: every planned file and endpoint, what each screen calls, which outside services and data each part uses, who may use each endpoint, your assumptions and the open questions. If the PRD is only in the chat, save it asdocs/prd.mdand use that assource, so the map and later questions can refer back to it. - Write
floorplan/architecture.jsonas for a code map (parts, external nodes for the services and data plan.json names, 1–3 flows for the PRD's main user stories, a tour), with globs covering the planned paths. Plain language for everyone, as in step 4 below. - Run
node ${CLAUDE_SKILL_DIR}/scripts/plan.mjs <root>, then build.mjs (step 5 below). Fix what they report until both are clean. Skip describe.mjs and recent.mjs: names and descriptions come from plan.json. A blueprint adds no notes to CLAUDE.local.md, since there's no code to look up yet. - Show it with open.mjs (step 8).
- Report (instead of step 8's report): the URL; the shape of the system in 3–5 lines; the stack you chose; your main assumptions; and the design review's questions and warnings. Tell them each part has Build this with Claude (or Codex) for a ready request to build just that part; that they can switch the map's Ask bar to Change and ask for additions or changes ("also plan out refunds"), and the map redraws with what changed highlighted (the design review's Resolve on the map fills in such a request, so open questions just need their answer); that plan.json and architecture.json are theirs to edit or to ask you to change; and that the map stays out of git.
To change a blueprint, edit plan.json and architecture.json and run refresh.mjs, which redraws it from plan.json. Once the code exists and the user wants a map of it, run refresh.mjs <root> --from-code, then carry on as for a refresh. plan.json stays where it is.
A map already exists? Refresh it instead
If the status above shows an existing map, don't start over. Run:
node ${CLAUDE_SKILL_DIR}/scripts/refresh.mjs <root>
It re-scans, compares content fingerprints against the last build, and does the bookkeeping without spending tokens:
- carries descriptions over to moved or renamed files and endpoints;
- drops entries for deleted files;
- flags entries whose exports or routes changed with a
reviewnote (edits inside function bodies don't count); - rebuilds;
- prints what changed and a short NEXT list.
Do only what NEXT asks:
- add globs for new directories that landed in "unassigned";
- run describe.mjs (step 6), which now only produces worksheets for the new and flagged items;
- check module summaries and flows if the change was large.
A typical refresh after a few hours of work is a handful of worksheet entries. Then mark recent work (step 7), and show it and report (step 8). Always show it, even when nothing changed: the user asked to see their floorplan.
Workflow (first run)
The codebase root is the argument if one was given, otherwise the current directory. It may be a single repo, or a plain folder holding several repos (frontend + backend + infra, and so on). The scanner finds every git repo under it and skips duplicate worktrees.
-
Scan.
node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs <root>It writesfloorplan/.cache/scan.jsonand prints a summary: repos, a code tree with LOC, entrypoints, the heaviest directory→directory import edges, HTTP call→route matches across repos, external packages and hosts. Work from the summary. Don't read scan.json, which is large. -
Read the contract. Read references/schema.md (the architecture.json format) and references/choosing-boundaries.md (how to carve a codebase into a good map).
-
Explore just enough. Read READMEs, manifests (package.json, pyproject, go.mod, docker-compose, deploy configs) and entrypoints, then skim 1–2 files per candidate subsystem until you can write a one-sentence summary for each. You're after the shape of the system, not a code review.
-
Write
floorplan/architecture.json. Aim for:- 3–9 top-level nodes;
- 3–12 children under each big one;
- globs covering more than 90% of code files;
- external nodes for the databases and third-party services the code really talks to;
- edges only for what the scan can't see (queues, cron, webhooks, cross-service calls through env-configured URLs);
- 1–3 flows that explain the system's main jobs;
- a
tour: 3–8 narrated stops for the "Start here" tour (see below).
Every node needs a
summary.Audience. The people opening this map are usually the app's owners, often non-technical builders who made it with AI. Unless the user asks for a developer-facing map, leave
"audience"unset or set it to"everyone", and write everyproject.summary, nodelabel/summary, and file/route description in plain language (see "Plain language" in references/writing-descriptions.md). Use short labels like "Main server" rather than "Shop API (Flask)". Paths and method/URL stay visible on the cards, so descriptions only need to say what the thing is for.Tour. Add
"tour": [{ "node": "<node id or file path>", "title": "…", "note": "…" }], with stops in the order a newcomer should see them: what the app is, the apps people use, the main server, outside services, and ending on an important screen's file. Write titles and notes in plain words for someone who has never read the code. The first guided flow is added at the end automatically as "watch a real request". Without a tour, one is built from node summaries and the first flow, so good summaries and at least one flow matter. -
Build and fix.
node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root>It validates everything and names each problem ("did you mean …", files unassigned by directory, ambiguous globs). Fix and rebuild until it's clean and unassigned is under ~10%.Nothing Floorplan makes is committed.
floorplan/holds its own.gitignorethat ignores the whole folder, so the project's tracked files aren't touched. If git already tracks files there, the build prints thegit rm -r --cachedcommand to untrack them; pass it on to the user rather than running it.A note for future sessions, only if the user wants one. In Claude Code, the build can keep a short marked block in the project's
CLAUDE.local.md, Claude Code's personal, uncommitted project notes, which load at session start like CLAUDE.md. The block tells future Claude Code sessions here that the map exists and how to look things up in it withfloorplan/query.mjs, so they start from the map instead of searching the code from scratch. Because it changes how later sessions work, the build never adds it on its own: it reportsCLAUDE.LOCAL.MD not added, and you offer it in your report (step 8). Only when the user says yes, runnode ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --claude-md. Once the block exists, every build keeps it current. The build addsCLAUDE.local.mdto the repo's local ignore list (.git/info/exclude, not.gitignore), rewrites only its own block, and moves the block out ofCLAUDE.mdif an older version put it there. To remove it, the user deletes the block, or puts<!-- floorplan:off -->in CLAUDE.local.md to keep it from coming back. Under Codex the build skips this: Codex has no personal, uncommitted notes file (AGENTS.md is shared with the team), so don't add one there either. -
Describe every file and route.
node ${CLAUDE_SKILL_DIR}/scripts/describe.mjs <root>This writes one worksheet per module (floorplan/.cache/worksheets/<key>.md) and a skeleton to fill in (floorplan/descriptions/<key>.json). Each worksheet holds a digest of every file (docstrings, definitions, what it uses and what uses it) and every route (handler, docstring), which is enough to describe most files without opening them.- Read references/writing-descriptions.md first.
- More than ~150 files: split the worksheets across parallel subagents if you have them, ~100–150 files each, grouped by area (backend routes, services, scripts, tests, UI). Give each one its worksheet keys, the codebase root and the writing guide, and tell it to edit only its own
descriptions/<key>.jsonfiles and keep the keys unchanged. - Smaller codebases: do it yourself.
Then rebuild. The build reports
DESCRIPTIONS files X/Y · routes X/Y. Get both to 100%: re-run describe.mjs and it lists only what's still missing. -
Mark recent work. The map highlights what was just worked on: those cards get a green "Changed"/"New" tag, the parts containing them show "N changed", hovering shows your note, and a Recent work button lays them out on one board. Do this on every make and every update, because it replaces the previous highlights.
node ${CLAUDE_SKILL_DIR}/scripts/recent.mjs <root>It lists what changed since the previous map, uncommitted changes and recent commits, each matched to the card it appears as. The why comes from you:- What counts. Work done in this conversation, by you or your subagents, is the main source. Lean on what you know about it. If you did nothing here (a fresh session), use what recent.mjs shows that is clearly in flight: uncommitted changes and the latest commits. If there's nothing, write
{ "tasks": [] }so old highlights clear. - Write
floorplan/recent-work.json. Use one task per thing the user asked for:title(2–5 words),request(what they asked, in their words, shortened),summary(1–2 sentences on what was done toward it and where it stands, including anything deleted, since deleted files can't be highlighted). Then additems: the cards that changed, as a file path, node id or"METHOD /path", withchange("new"or"changed") and anote. - Every note answers "how does this relate to what they asked for?" In one or two plain sentences, say what changed on this card and why the request needed it. For example, write "Now catches web requests whose address is built up in a variable first, which is why the orders and inventory screens were showing no server calls." Not "Added flattenTemplates and variableUse helpers".
- Highlight what mattered. Pick the files and endpoints whose behaviour changed for this request, usually 3–15. Skip tests and drive-by edits unless they're the point. A file with a changed endpoint can list both the file and the endpoint.
- Keep the code's words out unless the audience is developers. Never put secrets in notes.
Format: references/schema.md#recent-work. Then run build.mjs. It reports
RECENT WORK N card(s) highlightedand warns about refs that aren't on the map. - What counts. Work done in this conversation, by you or your subagents, is the main source. Lean on what you know about it. If you did nothing here (a fresh session), use what recent.mjs shows that is clearly in flight: uncommitted changes and the latest commits. If there's nothing, write
-
Show it, then report. Whenever you make or update a floorplan, finish by putting it in front of the user:
node ${CLAUDE_SKILL_DIR}/scripts/open.mjs <root>- It starts the map's server in the background (or reuses the one already running for this map) and opens it in their browser. Tabs that are already open reload in place instead of a new one opening.
- It prints the URL, whether Ask works (the Claude Code CLI or Codex was found), and how to stop the server. The server also stops on its own a couple of hours after the last tab closes.
- In Codex, run open.mjs outside the sandbox (ask for escalated permissions): the server has to keep running after the command ends, and Ask needs the network to reach Codex. If that isn't allowed, give the user
node floorplan/serve.mjsto run in their own terminal from the codebase root. - If you have an in-app browser or preview tool, pass
--no-openand open the printed URL there instead, so the map appears right beside the conversation. - If this is a remote or headless machine where the user can't reach 127.0.0.1, skip open.mjs and tell them to run
node floorplan/serve.mjson their own machine, or offer the Claude app route (step 9).
Then report. Give the URL, then describe the architecture you mapped in 3–5 lines, in the user's language, including anything surprising: cycles, god-files, dead areas, coupled subsystems. Always mention the high-severity Health items (
graph.health; the build output and graph.json list them). Hard-coded passwords/keys and endpoints anyone can change data through are things the owner needs to hear about. Never repeat a secret's value. Say thatarchitecture.jsonanddescriptions/are theirs to edit, and that after more work they can just ask to "update the floorplan", which re-reads only what changed. Give them those plain words rather than a command: in Claude Code the plugin's command is/floorplan:floorplan(/floorplanas a personal skill), and in Codex it's$floorplan. On a first run, mention in one line that the map stays out of git. In Claude Code, when the build saidCLAUDE.LOCAL.MD not added, end by asking once whether future Claude Code sessions in this project should use the map: you'd add a short note to their personal, uncommitted CLAUDE.local.md. Add it (build.mjs <root> --claude-md) only on a yes, and don't ask again on later updates if they said no. On an update, start with what changed for what they asked (it's highlighted under Recent work).
9. Opening the map and asking questions
The map has a floating Ask bar. The user types a question, and the agent answers with text plus an answer board: the relevant cards, the connections among them, a note on each card, and an optional step-by-step walkthrough. There are two ways to power it. The UI is the same either way.
-
Claude Code CLI or Codex (best). The map's server (
floorplan/serve.mjs, started by open.mjs in step 8) serves it at http://127.0.0.1:4378, or the next free port. Each question runs on the user's own sign-in, in the codebase, read-only, so answers can cite real code:- Claude Code:
claude -pwith the map (viafloorplan/query.mjs) plus Read/Grep/Glob on the source. The server findsclaudeon PATH or in~/.local/bin. - Codex:
codex execin Codex's read-only sandbox, with nothing saved to their Codex history. The server findscodexon PATH, or the CLI that comes with the Codex app.
It uses the agent that built the map, and falls back to the other if that one isn't installed.
--engine claude|codexforces one,--claude <path>or--codex <path>points at an unusual install, and--model <name>picks the model (open.mjs passes all of these through). Users can also runnode floorplan/serve.mjsthemselves at any time, and stop a background one withnode floorplan/serve.mjs --stop. - Claude Code:
-
Claude app. If you're running in the Claude app (the Artifact tool is available), offer to publish the map so they can open it there and ask questions on their own Claude account. Answers then come from the map only (names, descriptions, connections, endpoints), not the source, and the Ask bar shows a hint to install the CLI for a better experience. To publish:
node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --artifact. This writesfloorplan/artifact.htmlwithout the machine's absolute path.- Publish that file with the Artifact tool,
capabilities: {"sample": {}}, and keep the same file path for later publishes so the URL stays stable. - After each refresh, rebuild with
--artifactand republish.
Publishing uploads the map (paths, names, descriptions, structure), not the source code, to their private claude.ai account. Say that before you do it.
-
Neither:
floorplan/index.htmlstill opens directly in a browser. The Ask bar explains what's needed.
Sharing a copy
When the user wants to send the map to someone (a teammate, a client, someone without Claude or Codex), export it. An export is the same single HTML file without the Ask bar, prompts for Claude or Codex, editor links, this machine's folder path or git remotes. The map's Export button does this from the browser; from here, run:
node floorplan/serve.mjs --export [<file>] [--include flows,notes,recent,health]
It writes floorplan/<project>-map.html unless given a file. --include defaults to flows,notes (flows and the tour, notes pinned to files); recent adds recent work and health adds the health check, or the design review on a blueprint. Leave health out unless the user asks for it, and if they do, say that it lists the endpoints anyone can use and where secrets sit in the code (never their values), so they should only send it to people they trust. Any export shows how the app fits together (every part, file and endpoint, with names and descriptions), but not the source code.
What else the map gives them (automatic)
-
Health. A header button, with a count of important issues, opens a plain-language list of problems the scan found:
- passwords and API keys written into the code or a committed
.env; - secret keys in variables the browser gets (
NEXT_PUBLIC_,VITE_and the like); - Supabase tables without row-level security, and policies that let anyone change a table (from the SQL migrations);
- Firebase rules (Firestore, Storage, Realtime Database) that let anyone in, including test mode and its expiry;
- Stripe webhooks that act on events without checking Stripe's signature;
- CORS that allows every website (worth fixing when credentials go along);
- endpoints that let anyone change or read data without signing in (including a sign-in check placed above the route line);
- files nothing uses;
- files over ~1,000 lines, which AI struggles to edit safely.
Each issue has Show on map (highlights the affected files and endpoints with notes) and Fix with Claude or Fix with Codex (a ready-to-paste prompt naming the exact files and lines and the safe fix). It's computed by
scripts/lib/health.mjsduring scan and build, and it never stores secret values, only the file, line and a masked hint. Treat it as a quick automatic check, not a security audit. - passwords and API keys written into the code or a committed
-
Screens. The build detects the app's screens (Next.js, React Router, Vue, SvelteKit, Remix, Nuxt, Astro, Expo, Angular, TanStack) with
scripts/lib/screens.mjs. It also works out what sits behind each one: its components, the requests it makes, the server code and data that answer them, and outside services. A Screens button lets people start from the page they know. -
Start here. A one-minute tour runs on first open and can be replayed from the header. It uses your
tour, or builds one automatically. -
Plain words by default. Connection types read "Uses", "Web requests", "Background jobs". Common technical terms are underlined and explained on hover. Filters → Show technical detail switches to developer terms and shows exports.
People can also use Flows → Request a new flow to have the agent trace something ("how does a refund get back to the customer's card?") into a step-by-step flow. With serve.mjs these are saved to floorplan/custom-flows.json, and every build folds them into the map (steps pointing at deleted code are dropped with a warning). Treat that file as user content: keep it on refresh, and don't edit it unless asked.
Notes
- Paths are relative to the codebase root and use forward slashes. In a multi-repo root they start with the repo folder, e.g.
api-service/src/**. - Route keys in descriptions are
"METHOD /full/path"exactly as the worksheet prints them. - The map makes no outside requests: the build inlines the layout engine (ELK) and fonts from
${CLAUDE_SKILL_DIR}/assets/vendor/, so it works offline. - HTTP edges come from matching URL strings at call sites (including URLs kept in a variable first, nested template strings, and small same-file helpers that add a path prefix) to route definitions (Flask, FastAPI, Express, Next.js, Spring, Go and others), with blueprint/router prefixes resolved, nested mounts included. Firebase callables are matched by name (
CALL /<name>, fromhttpsCallable) andonRequestfunctions by URL; the summary's FIREBASE FUNCTIONS section lists scheduled and trigger functions, which belong in aworkernode. Treat them as strong hints. If an important service-to-service link is missing, add it as an explicit edge. - Don't hand-edit graph.json or index.html; they're regenerated on every build.
04 同仓库更多 Skills
scientific-schematics
Generates scientific diagram drafts using Nano Banana 2 AI with smart iterative refinement. Uses Gemini 3.7 Flash for quality review. Refines when the review requests improvement, with at most two generations. Specialized in neural network architectures, system diagrams, flowcharts, biological pathways, and complex scientific visualizations.
polyhaven-texture-apply
Apply realistic PBR textures from PolyHaven to any Blender object. Supports metals, wood, concrete, fabric, and more. Trigger when asked to texture an object, apply a material from PolyHaven, make something look like metal/wood/marble, or change object surface.
polyhaven-studio-setup
Set up a professional product photography studio in Blender using PolyHaven HDRIs and PBR ground materials. Trigger when asked to create a studio setup, add HDRI lighting, set up product photography, or create a showroom scene.
polyhaven-scene-builder
Build complete product scenes using PolyHaven assets — HDRI environment, textured ground/pedestal, and optional props from the 3D model library. Trigger when asked to build a product scene, create a showcase setup, add a pedestal, or compose a product shot.
polyhaven-material-swap
Cycle through multiple PolyHaven materials on a product and render each variant. Great for showing color/finish options. Trigger when asked to show material variants, swap textures, create color options, show finish comparisons, or render product in different materials.
polyhaven-hdri-showcase
Render the same product across multiple HDRI environments and output a comparison grid. Trigger when asked to compare lighting setups, test different environments, show product in multiple settings, or create an HDRI comparison.