About

Imported from akillness/jeo-skills (.agent-skills/underworld-overseer-save-mapper/SKILL.md). Install upstream with npx skills add akillness/jeo-skills --skill underworld-overseer-save-mapper. Copyright stays with the author.

Underworld Overseer Save Mapper

Name: underworld-overseer-save-mapper
Author: akillness

When to use this skill

Validate an Underworld Overseer .json save before opening it in the mapper.
Install or update the upstream mapper without copying game saves.
Generate an interactive HTML dungeon map or diagnose missing cells, labels, or output.
Inspect coordinate bounds, descriptor counts, or duplicate map coordinates.

Do not use this skill for unrelated save formats, save editing, or reverse engineering protected game data. It visualizes user-owned save files; it does not modify progression.

Instructions

Step 1: Preserve the source save

Work on a copy. Record the input path and hash when reproducibility matters. Never overwrite the game's active save, and never claim the mapper is a save editor.

Step 2: Validate the JSON before installing or launching anything

Run:

python3 .agent-skills/underworld-overseer-save-mapper/scripts/validate_save.py /path/to/save.json

The required shape is a top-level object with a Map list. Every map cell must contain integer X and Y coordinates and a non-empty string DescriptorID. Treat duplicate (X, Y) coordinates as ambiguous because the upstream renderer indexes cells by coordinate.

Step 3: Choose the smallest operating mode

Inspection only — use validate_save.py --json; no mapper install is needed.
Interactive map generation — install/check upstream with scripts/setup.sh, then run its main.py in a local terminal.
Mapper code changes — clone a pinned ref, inspect main.py and template.html, and test against a redacted fixture.

Do not reach for browser automation just to parse the save. A browser is only needed to view the generated HTML.

Step 4: Install or check the upstream mapper

bash .agent-skills/underworld-overseer-save-mapper/scripts/setup.sh --check
bash .agent-skills/underworld-overseer-save-mapper/scripts/setup.sh --install

The installer uses a dedicated data directory and virtual environment. It installs pandas and matplotlib; pathlib is part of Python and must not be installed from PyPI.

Step 5: Generate and verify the map

Run main.py from the installed repository. The current upstream UI is interactive and looks first in:

~/AppData/LocalLow/MyronSoftware/UnderworldOverseer/Saves

If that directory is unavailable, the current program exits before offering a custom path; either run on the supported Windows profile or make a reviewed upstream code change. Verify that:

the output HTML exists and is non-empty;
rendered coordinate bounds match validator output;
representative descriptors appear in the legend;
search, zoom/pan, color controls, and dark mode work locally;
no save file was changed.

Step 6: Report limitations honestly

The repository README describes the project as beta. Its README advertises MIT, but the inspected upstream commit has no root LICENSE file. Do not redistribute upstream code or binaries as though the license were verified; see references/upstream.md.

Examples

Validate without rendering

python3 .agent-skills/underworld-overseer-save-mapper/scripts/validate_save.py save.json --json

Install a pinned revision

REF=5f83b078682d86624941fa451641b01a632455fb \
  bash .agent-skills/underworld-overseer-save-mapper/scripts/setup.sh --install

Best practices

Back up saves and use redacted fixtures for bug reports.
Validate structure and coordinate uniqueness before diagnosing HTML.
Keep dependency installation isolated in a virtual environment.
Pin an upstream commit for reproducible output.
Treat the generated HTML as local data because descriptors and layout may reveal game progress.

References

references/upstream.md — inspected commit, behavior, dependencies, and license caveat.
Upstream repository

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/akillness-jeo-skills-underworld-overseer-save-mapper/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

akillness-jeo-skills-underworld-overseer-save-mapper.ocm.jsonjson

{
  "ocm": "1",
  "id": "akillness-jeo-skills-underworld-overseer-save-mapper",
  "kind": "skill",
  "name": "underworld-overseer-save-mapper",
  "description": "Inspect Underworld Overseer JSON saves and generate or troubleshoot interactive dungeon maps with RobThePCGuy/Underworld-Overseer-Save-Mapper. Use when a user wants to validate a save's Map records, visualize room coordinates and DescriptorID values, install the mapper, or diagnose empty/broken HTML output. Triggers on: Underworld Overseer save, dungeon save map, DescriptorID, Map JSON, Underworld Overseer mapper, or save-to-HTML.",
  "publisher": "akillness",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "data_analysis"
    ],
    "tags": [
      "skill-md",
      "game-development",
      "save-files",
      "json",
      "map-visualization",
      "underworld-overseer",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Inspect Underworld Overseer JSON saves and generate or troubleshoot interactive dungeon maps with RobThePCGuy/Underworld-Overseer-Save-Mapper. Use when a user wants to validate a save's Map records, visualize room coordinates and DescriptorID values, install the mapper, or diagnose empty/broken HTML output. Triggers on: Underworld Overseer save, dungeon save map, DescriptorID, Map JSON, Underworld Overseer mapper, or save-to-HTML."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/akillness/jeo-skills",
      "path": ".agent-skills/underworld-overseer-save-mapper/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/akillness/jeo-skills/blob/HEAD/.agent-skills/underworld-overseer-save-mapper/SKILL.md",
      "key": "akillness/jeo-skills/.agent-skills/underworld-overseer-save-mapper/SKILL.md"
    },
    "compatibility": "Python 3; upstream mapper expects a local graphical/browser workflow and defaults to the Windows save location",
    "allowed_tools": [
      "Bash",
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep"
    ]
  },
  "instructions": "# Underworld Overseer Save Mapper\n\n## When to use this skill\n\n- Validate an Underworld Overseer `.json` save before opening it in the mapper.\n- Install or update the upstream mapper without copying game saves.\n- Generate an interactive HTML dungeon map or diagnose missing cells, labels, or output.\n- Inspect coordinate bounds, descriptor counts, or duplicate map coordinates.\n\nDo not use this skill for unrelated save formats, save editing, or reverse engineering protected game data. It visualizes user-owned save files; it does not modify progression.\n\n## Instructions\n\n### Step 1: Preserve the so",
  "cost": {
    "context_tokens": 989
  }
}

Fetch it by URL: GET /api/v1/registry/akillness-jeo-skills-underworld-overseer-save-mapper/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.