agentleFS
WingedGuardianWingedGuardian/skyrimvr-claude-toolkit/.agents/skills/skyrim-save/SKILL.md

skyrim-save

Skill22 starsChanged 3 days agoMITView on GitHub

Read, scan and clean Skyrim save files (.ess), including ReSaver CLI writes (reset-havok, cleanse-formlists, remove-created). Use when debugging save issues, searching for orphaned scripts, checking mod footprint in saves, investigating save bloat, or cleaning or repairing a save; and before deleting, moving or overwriting saves (the save vault keeps every version; status and restore).

  • Installs packages

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use scripts/read-save.py to decompress and scan Skyrim save files.

    line 9
  2. Distinctive:

    Mod footprint: Search for a mod's prefix (e.g., "MyMod_") to locate candidate bytes.

    line 42
  3. Distinctive:

    Before writing, the adapter backs up the input pair and the output pair into the permanent save store.

    line 82
  4. Very specific:

    Never: run resaverpp-cli.exe directly with -o, --batch or --apply, or the GUI ReSaverPP.exe: they skip every check above.

    line 88

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- GENERATED by scripts/gen_agent_trees.py from agent/skills/skyrim-save/SKILL.md. Toolkit contributors: edit the source. Your own notes belong in KNOWLEDGEBASE.local.md, which updates never replace. -->

Save File Analysis

Use scripts/read-save.py to decompress and scan Skyrim save files. Requires Python with lz4, pinned and hash-locked (from the toolkit root: python -m pip install --only-binary=:all: --require-hashes -r tools/requirements-tools.lock). All output is JSON.

Commands

Get save info (player name, level, location, plugin count):

python scripts/read-save.py info "<path-to-save.ess>"

List all plugins in the save:

python scripts/read-save.py plugins "<path-to-save.ess>"

Search for a string (script names, EditorIDs, variable names):

python scripts/read-save.py search "<save.ess>" --string "MyModScriptName"

Search for a FormID (as hex, little-endian uint32):

python scripts/read-save.py search "<save.ess>" --formid 0x0001ABCD

Search for a raw hex byte pattern:

python scripts/read-save.py search "<save.ess>" --hex "DEADBEEF"

Common Debugging Use Cases

  • Orphaned scripts: A raw script-name hit is an investigation lead. Use structured ReSaver instance/reference data to determine whether instances are orphaned.
  • Effect accumulation: Raw FormID byte counts do not establish active effects or stacking. Check the structured records and runtime state.
  • Mod footprint: Search for a mod's prefix (e.g., "MyMod_") to locate candidate bytes; these are not semantic reference counts.
  • Save bloat: Compare decompressedSize across saves to detect growth over time.

Save File Structure

SSE/VR saves use LZ4 compression. General layout of the decompressed data:

  • 0-100KB: Header, plugin list, screenshot
  • 100KB-~22MB: Global data tables, ChangeForms (binary)
  • ~22MB+: Papyrus string table, script instances, FormID arrays

Limitations

  • The binary scanner is read-only — it cannot write back valid saves (to change a save, use the ReSaver CLI below)
  • Binary search only — cannot parse structured Papyrus instance data (variable values, active effect state)
  • For structured save editing, use ReSaver (Java GUI)

ReSaver CLI (headless, tools/resaver-cli.sh)

bash tools/resaver-cli.sh <op> <save.ess> runs ReSaver's library without its GUI. Needs JDK 17+ and ReSaver's jar (see docs/installing-tools.md).

  • Read ops: info|dump|find|find-refs|worries|recon|changeform|extradata-scan|changeform-diff|freeze-report|globaldata|globaldata-diff. The op list with arguments is the header comment of tools/resaver-cli.sh.
  • Write ops: set-global|set-var|clean|reset-havok|cleanse-formlists|remove-created. Each is a dry run unless --apply, and always writes a NEW file.
  • verify-roundtrip is a self-test. Every --apply checks its operation's permitted changes, writes in a private staging directory, and re-reads the complete serialized Papyrus/global data and co-save before publishing a new pair. Failed candidates remain in the named staging directory; existing destinations are preserved. A partial publication is a failure and names its journal.
  • The pinned ReSaver script-instance setter rejects variable index zero. A preview lists the library's indexes; do not bypass its setter with reflection or direct file edits. Other supported primitive indexes use the same verified pipeline.
  • Resolve FormID to EditorID with tools/resaver-resolve-names.js.

Native backend: ReSaver Plus (opt-in, Windows)

bash tools/resaver-cli.sh backend says which backend runs. Java is the default. The native backend is ReSaver Plus (Tonycubed2's C++ port of ReSaver), built on the user's machine by python tools/resaver-plus/build.py from a pinned commit plus the toolkit's patches; nothing binary ships. The user opts in with RESAVER_BACKEND=native or the word native in tools/resaver-plus/backend. Do not switch backends on your own to get past an error: the selected backend failing is an error, and neither falls back to the other. Building it needs Visual Studio 2022 Build Tools, which is system software: give the user the manual steps (tools/resaver-plus/README.md), never install it.

  • Check it first: bash tools/resaver-cli.sh verify-native (its BUILD-INFO.json and the executable's SHA-256).
  • Ops: the same 19 as Java plus writer-scan (pending save-writer frames; advisory, a heuristic, not proof of an imminent write). Reads and previews never write; verify-roundtrip runs in memory.
  • Writes: --apply needs ONE explicit new output pair in an existing folder. An existing .ess OR .skse of that pair is refused, so is the input and the permanent save store. Run the preview (no --apply) first and show it. Before writing, the adapter backs up the input pair and the output pair into the permanent save store; the applied receipt must equal the preview, be verified on reopen, and carry the input's co-save over unchanged. A failed candidate stays on disk for inspection: report it, never delete it.
  • JSON: the native schema, close to but NOT identical to Java's (native report wording, warnings and changeform trees). Never diff native output against Java output and call the difference a save change.
  • Read-only reports: python tools/resaver-plus.py report|compare|decompile|disassemble.
  • Never run resaverpp-cli.exe directly with -o, --batch or --apply, or the GUI ReSaverPP.exe: they skip every check above. The guard only adds a note (S-RESAVER-NATIVE-DIRECT); the save vault keeps the version before.
  • Limits: one real edited save was load-tested in game on one machine; for saves unlike that one confidence is moderate, so the user's own in-game load of the new output is the final check. Crash atomicity is unqualified. Windows only: elsewhere use Java.

Changing a save: the save vault (4.1)

A save is a .ess with its .skse co-save (same folder, same name): ONE save, whichever file a command names. No rule decides on a save and nothing asks first. tools/save_vault.py keeps every settled version of every save and settings INI, whatever changed it (docs/save-vault.md). The session-start line says whether its watcher runs; if it says NOT RUNNING, tell the user before changing a save.

  • Before a deliberate change: python tools/save_vault.py status <SAVE> lists the kept versions. A version that lasted less than about 35 s may not be there; python tools/save_vault.py sweep --pair <SAVE> --now keeps the current one now.
  • Getting one back: python tools/save_vault.py restore <SAVE> [--at TIME | --id ID] --to <folder> (a copy), --as <NEWNAME>, or --replace (the current pair is kept first). Nothing is written without --apply; a restore into a save folder is refused while the game runs; run it again once the game is closed.
  • Still refused: deleting or moving the Saves folder itself, the settings folder holding it, or everything in it at once; writing into the vault or an old backup store. A locked save (the optional OS locks) cannot be changed at all: ask the user, never work around it.

Restore a backup the 4.0 gate took (both files, each hash-checked before it is written):

bash tools/skyguard.sh snapshot list --kind save                    # <stamp>-save  Save1.ess + Save1.skse ...
bash tools/skyguard.sh snapshot restore <id> --to <folder>          # a copy, live files untouched
bash tools/skyguard.sh snapshot restore <id> --in-place             # over the live save (the user approves this)

New IDs are core-<uuid>. The listing also reads the older recovery-snapshot store and installed save-backups records (local-<id>); recovery verifies imported bytes and preserves both legacy stores. Selecting either member selects its complete pair. Restore copies are published without clobbering concurrent destinations; in-place recovery first preserves the complete current pair and journals each publication. The default destination and 2 GiB reserve can be configured in the workspace's .modding-agent-harness/config.json with v: 1, save_store and save_reserve_bytes. The store must stay separate from save roots. Store files and ancestor moves/deletes are protected; there is no automatic save-backup pruning; no hook adds to this store since 4.1. Runtime save/load restrictions still apply independently.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.