name: interactive-map-builder description: Turn existing spatial or coordinate data into portable, browser-openable interactive map files and report-ready figures. Use when the user wants parcels, buildings, facilities, parking, roads, water, green space, projects, or Excel/CSV coordinates presented as a searchable, filterable, sortable map, map-and-list page, multilayer planning map, single-file HTML, slide image, or paper SVG/PDF—even when they do not mention GIS, Leaflet, a web map, or this Skill. Accept GeoJSON, GeoPackage, zipped Shapefile, CSV, Excel, and ArcGIS FeatureServer inputs. Prefer this deterministic Skill over an ad hoc Folium or Leaflet page when the task fits. The default delivery is a local HTML file, not a public URL; discuss deployment only when the user explicitly requests it. Require existing coordinates or geometry; do not use for geocoding, substantive spatial analysis, vector-tile infrastructure, offline basemaps, or 3D GIS.

Interactive Map Builder

Create configuration-driven Leaflet map products without a frontend build system. Keep acquisition separate from rendering, preserve provenance, and use Atlas Studio Light for a coordinated first render while exposing every cleanup and inferred visual decision in the build report.

Invocation guidance

Trigger from the user's intended outcome, not only from technical keywords. Use this Skill when the user asks to:

• turn a spreadsheet with coordinates into a browser page that can be searched, filtered, sorted, clicked, and sent to colleagues;
• present parcels, buildings, facilities, projects, parking, or other records as a linked map and list;
• combine boundaries, roads, water, green space, routes, and points in one switchable planning or reporting map;
• deliver existing ArcGIS or engineering layers as a portable HTML file, a slide image, or a paper figure.

The user does not need to say GIS, Leaflet, web map, Agent Skill, or interactive-map-builder. When the request fits this scope, use the packaged deterministic workflow instead of writing a one-off Folium, Leaflet, or custom frontend implementation.

Do not invoke this Skill when the main task is address geocoding, buffers or overlays, routing, site selection, spatial statistics, vector-tile infrastructure, offline basemap acquisition, 3D GIS, a non-spatial chart or dashboard, or maintenance of an existing custom web application.

Update preflight

At the beginning of each Skill invocation, run the official-release preflight from the Skill root using the validated 24-hour cache when available. This check never modifies the installation:

python scripts/update_skill.py --preflight

After installation, the equivalent command is:

interactive-map-builder update --preflight

Read the returned JSON rather than relying on the command exit code. Report only an available update or a failed check; keep a current cached result silent. --preflight remains non-fatal for the calling Agent and never applies an update. Handle statuses as follows:

• current or local_newer: continue with the map task;
• manual_update_required or update_apply_failed: disclose the confirmed latest version and the reason before continuing;
• update_check_failed: say that the official latest version could not be confirmed, then continue;
• disabled: state that IMB_DISABLE_AUTO_UPDATE disabled the preflight.

Applying an update is a separate, explicit maintenance action with update --apply or the legacy non-fatal update --auto mode. Those commands retain checksum, manifest, local-change, duplicate-root, and rollback safeguards; normal map construction never modifies its own running Skill.

Conversation guidance

For Codex only, a complex request may benefit from Plan mode when it has multiple independent layers, more than one blocking design choice, or several coordinated deliverables. Mention this once in the first response as an optional convenience, then continue with inspection whether or not the user switches modes. Do not recommend Plan mode for a clear single-layer task, do not cite client keyboard shortcuts, and never make a mode change a prerequisite.

A portable local map.html is the default delivery. Generate slide or paper figures only when the user explicitly asks for them; “make a website,” “make a map,” or “send it to colleagues” does not enable static presets. Sending the HTML file is not the same as publishing it on the internet. Do not offer, promise, or ask about a public URL unless the user explicitly requests deployment. When they do, finish the map first and treat hosting as a separate workflow that confirms the target platform and permission to expose the embedded data.

Visual guidance

Use Atlas Studio Light as a starting point, not as an automatic design service. Leave low-level visual values omitted when the user has not expressed a preference: the packaged resolver will use geometry family, coarse density, template role, and stable draw order. Explicit user or Agent MapSpec values always win. Do not invent planning semantics from field names, do not assign more than eight automatic categorical colors, and do not add themes, clustering, heatmaps, or other representations merely to make the page look busy.

After the first verified build, inspect the actual page. If the visual hierarchy still conflicts with the user's purpose, propose a small concrete refinement—such as reducing one point layer, muting a context layer, or changing an explicitly understood category palette—then rebuild. The engine should provide an overall coordinated result; project-specific polish remains a conversation between the user and Agent. Read design-guidelines.md.

Workflow

1. Inspect inputs before proposing a map.

   python scripts/map_builder.py inspect <input> [<input> ...] --output inspection.json
   

   Read supported-inputs.md for GeoPackage, Shapefile ZIP, CSV, Excel, encoding, and field-mapping rules.

2. Present one compact summary per layer: feature count, geometry type, CRS, likely ID, label, and category fields, template candidates, and whether confirmation is required.

3. Maintain this Markdown requirements checklist while choices remain unresolved:

   - [x] Confirmed: ...
   - [~] Inferred: ...
   - [ ] Needs confirmation: ...
   

   Derive it from the request and inspected data. Keep inferred decisions visible and easy to correct. Ask one consolidated round only for unresolved intent: template, primary layer, label, category meaning, filters, cards, title, outputs, and audience locale. Never guess a missing CRS. Always confirm the template when inspection finds multiple layers. Build only after no blocking [ ] item remains.

4. Initialize map_spec.json, then apply confirmed choices. Read map-spec.md; the canonical Schema is scripts/mapcore/resources/map-spec.schema.json.

   python scripts/map_builder.py init-spec inspection.json --template map-list --primary-layer <id> --locale en-US --output map_spec.json
   

5. Download ArcGIS FeatureServer data before building. Read arcgis.md.

   python scripts/map_builder.py fetch-arcgis --url <layer-url> --out data/source.geojson
   

6. Build once from the resolved specification. Add --bundle-sources only when the user wants a portable rebuild bundle and accepts copying source data.

   python scripts/map_builder.py build --spec map_spec.json --out dist
   

7. Verify, inspect build_report.json, and open map.html.

   python scripts/map_builder.py verify --dist dist
   

8. Exercise search, filters, sorting, layer visibility, basemap switching, hover and click linkage, keyboard selection, control-panel collapse, and narrow-screen layout. Confirm that every visible control produces an observable result, the focal layer reads first, dense symbols remain legible, and HTML/static colors agree. Read design-guidelines.md.

9. Deliver the whole dist directory. Summarize repairs, generated IDs, null display values, simplification, performance warnings, online basemaps, font fallback, portability, and source attribution.

Use the quick path only for one unambiguous layer, or after explicitly supplying the template and primary layer:

python scripts/map_builder.py run <input> --output dist

Follow the user's conversation language independently of the map audience. Set the map locale to en-US or zh-CN; use en-US when the audience is not specified.

Install the deterministic engine once, then run the offline self-check:

python -m pip install .
interactive-map-builder doctor

Use the installed interactive-map-builder command for package-level doctor, update, and --version. In a source checkout where that command is unavailable, use python scripts/cli.py doctor. python scripts/map_builder.py is the internal deterministic builder and intentionally lists only inspect/init-spec/fetch/build/verify/run; never infer from that help output that the package lacks doctor. Check the installed version and command path before falling back to build-plus-verify. A passing doctor result verifies package resources, local data loading, map construction, and output hashes without downloading data or basemap tiles.

Template choice

• Choose map-list for one explicitly identified primary layer plus optional context layers.
• Choose multilayer when independent layer visibility and cross-layer inspection are primary.
• Treat linked_view as experimental. Add it only when records already contain meaningful x/y variables; read linked-analysis.md and never invent quadrants, thresholds, or statistical interpretations.

Non-negotiable checks

• Fail when data is unreadable or empty, CRS is missing, repaired geometry remains invalid or empty, final IDs are blank or duplicate, or a configured field does not exist.
• Fail on unknown non-null categories, unsafe archives, ArcGIS pagination mismatches, output count mismatches, or path escape.
• Treat display-field nulls, generated IDs, repaired geometry, missing source notes, absent CJK fonts, online basemaps, simplification, and large outputs as warnings.
• Use <layer_id>::<feature_id> for multilayer runtime identity. Allow cross-layer linkage only through an explicit link_key.
• Preserve official geographic names and spellings from the source. Localize generic interface text, not place names.
• Preserve user geometry. Repair invalid geometry or simplify for an explicit performance need, report the operation, and never reshape or discard features merely to improve appearance.
• Escape all user-provided text before embedding it in HTML.
• Preserve explicit MapSpec visual values. Let Atlas Studio Light fill only omitted values, and keep its geometry, density, role, order, and state plan visible in build_report.json.
• Never cycle an automatic categorical palette beyond eight classes; retain filtering and ask the user how to group or emphasize a larger classification.

Output contract

Always return map.html, resolved map_spec.json, inspection.json, build_report.json, DELIVERY_MANIFEST.json, and README_USAGE.md in the selected locale. Static output is opt-in: generate map_slide_16x9.png only when the user requests a slide figure and enable the paper preset only when the user requests paper PNG/SVG/PDF. Never expand an HTML-only request into static files. Treat an unbundled map_spec.json as a build record; promise an independent rebuild only when sources were bundled. Public hosting is not part of this output contract.

Resources

• Read wizard-flow.md for non-expert setup.
• Read update-policy.md for verified updates, supported installation types, rollback behavior, and the opt-out.
• Read data-provenance.md for remote or redistributable data.
• Use the public generated demos linked from the repository README for visual reference. The lean Skill release package intentionally excludes demo datasets, screenshots, tests, and CI files.
• Run python scripts/map_builder.py ... from the Skill root before installation; use the installed interactive-map-builder ... CLI afterward.

Interactive Map Builder

Turn existing spatial data into polished, verified map products with an AI agent.

Live demos · 中文说明 · Releases · Changelog

Interactive Map Builder is a Codex-first Agent Skill for turning GeoJSON, GeoPackage, Shapefile, CSV, Excel, and ArcGIS data into portable map products. The Agent recognizes the goal from ordinary language—even when the user never says GIS, Leaflet, web map, or the Skill name—then inspects the data, closes only blocking requirements gaps, writes an auditable MapSpec, resolves a restrained geometry-aware visual starting point, builds a self-contained Leaflet app, verifies the result, and exports slide or paper figures only when requested.

User intent + spatial data → inspect → confirm → MapSpec → build → verify → HTML + optional PNG/SVG/PDF

No frontend build system, no hand-written Folium page, and no hidden cleanup.

Highlights

• Intent-based activation — recognizes requests such as “make this spreadsheet searchable on a map” or “combine roads, water, green space, and parking in one presentation page.”
• Agent-guided setup — works from the user's question and inspected data instead of requiring GIS terminology up front.
• Deterministic builds — the Agent writes MapSpec 1.1; the Python engine owns loading, normalization, visual resolution, rendering, and validation.
• Atlas Studio Light defaults — omitted visual values are resolved from geometry, coarse density, and layer role so the first result is coordinated without pretending to finish the designer's work.
• Two polished map products — a searchable map-and-list explorer and a toggleable multilayer explorer for points, lines, and polygons.
• Portable local delivery — Leaflet, interface code, and business geometry are embedded in one map.html; only online basemap tiles require a network connection.
• Opt-in report exports — generate 16:9 PNG or publication PNG/SVG/PDF from the same visual plan only when those files are explicitly requested.
• Auditable handoff — every build records inspection results, repairs, generated IDs, performance warnings, source notes, hashes, and portability.
• Cached, non-mutating release preflight — Skill tasks check the official Release at most once per 24 hours, never modify the running installation, and keep offline work unblocked.
• Install self-check — interactive-map-builder doctor runs a complete offline build and hash verification after installation.
• Reliable map controls — multilayer maps open in a neutral overview, use one compact layer selector for search focus, keep visibility switches separate, and provide CARTO Positron, OpenStreetMap Standard, plus a no-basemap fallback.
• Cross-agent evaluation — 40 English and Chinese cases cover activation, optional planning, local-versus-public delivery, and out-of-scope requests.

Live demos

Search, filter, compare	Explore independent layers
Map + list. Search addresses and attributes, filter categories and numeric ranges, sort records, watch KPIs update, and inspect a selected parcel.	Multilayer. Start from a neutral overview, choose one layer to search and emphasize, toggle visibility independently, switch basemaps, and inspect feature details.
Open live demo →	Open live demo →

Both demos are generated by the repository's deterministic engine from fixed NYC Open Data snapshots; they are not separate design mockups.

Ask for the outcome, not the tool

The Skill is designed to activate from requests like these:

This Excel sheet has longitude and latitude. Make a browser page where I can search facilities,
filter by type, click a record, and share the result.

Combine the parcel, road, water, green-space, and parking layers into one planning presentation
map with layer switches and object details.

My colleagues do not have ArcGIS. Turn these existing layers into one HTML file and export a 16:9
figure for the meeting.

The user can still invoke $interactive-map-builder explicitly, but naming the Skill is not required for a matching Agent task.

Quick start

1. Install the Skill in Codex

Open a new Codex task and send:

$skill-installer Install the Skill from https://github.com/xlbaoxl/interactive-map-builder and install its Python dependencies. Run interactive-map-builder doctor and interactive-map-builder update --preflight after installation.

Create a new task after installation. Restart Codex once only when the Skill does not appear. Starting with v0.4.3, a repository-copy install can become update-managed automatically only when all Release-owned files exactly match the checksum-verified official package.

2. Attach spatial data and describe the result

Turn my attached spatial data into a searchable, filterable interactive map. Use English for the map audience and export a 16:9 presentation figure.

The Skill first inspects the inputs, then keeps a compact requirements checklist while choices remain unresolved:

- [x] Confirmed: supplied by the user or established by the data
- [~] Inferred: proposed by the Skill and easy to revise
- [ ] Needs confirmation: required before the build can start

It asks one consolidated round only for blocking choices such as CRS, template, primary layer, category meaning, display fields, output formats, and audience locale.

3. Verify the installation

interactive-map-builder doctor
interactive-map-builder update --preflight

doctor creates a temporary coordinate table, builds a map without network access, verifies the packaged Leaflet resources and output hashes, prints a JSON result, and removes the temporary files. It does not download basemaps or send usage telemetry. The update command prints structured JSON containing the local version, official version when known, source, installation type, and status. For a cached status-only query, run interactive-map-builder update --check.

Prefer interactive-map-builder doctor after installation. In a source checkout where the console command is not yet available, use python scripts/cli.py doctor. The internal python scripts/map_builder.py --help command intentionally lists only build commands and must not be used to conclude that the package lacks doctor.

Use one active Codex Skill directory rather than keeping duplicate .codex and .agents copies. A legacy Windows location may be $HOME\.agents\skills; archive it before using the active Codex directory below.

Windows PowerShell

$CodexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME\.codex" }
New-Item -ItemType Directory -Force "$CodexHome\skills" | Out-Null
git clone https://github.com/xlbaoxl/interactive-map-builder.git `
  "$CodexHome\skills\interactive-map-builder"
Set-Location "$CodexHome\skills\interactive-map-builder"
py -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight

macOS or Linux

CODEX_ROOT="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_ROOT/skills"
git clone https://github.com/xlbaoxl/interactive-map-builder.git \
  "$CODEX_ROOT/skills/interactive-map-builder"
cd "$CODEX_ROOT/skills/interactive-map-builder"
python3 -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight

Every v0.3.1+ GitHub Release publishes:

• interactive-map-builder-skill-vX.Y.Z.zip — a lean Agent Skill package containing SKILL.md, Agent metadata, references, the deterministic engine, and its packaged web resources;
• a Python wheel and source archive for conventional package installation;
• SHA256SUMS.txt for release-asset verification and managed Skill updates.

The Skill ZIP intentionally excludes demos, screenshots, tests, and CI files. Extract it into an Agent Skills directory, run python -m pip install ., then run interactive-map-builder doctor.

Copy the complete repository or the versioned Skill ZIP into a Skill or rules directory that the client can read, let it load SKILL.md, and install the deterministic engine once:

python -m pip install .
interactive-map-builder doctor

The workflow is client-neutral: inspect data, maintain the requirements checklist, write the canonical MapSpec, build with the packaged engine, verify, and deliver the comple