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
In this repository37 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- create-modSkill
- devbenchSkill
- find-sessionSkill
- inspect-espSkill
- logging-registrySkill
- mod-release-reviewSkill
- mod-update-checkSkill
- port-to-vrSkill
- skyrim-audioSkill
- skyrim-bsaSkill
- skyrim-contextSkill
- skyrim-mcmSkill
- skyrim-nifSkill
- toolkit-housecarlSkill
- toolkit-setupSkill
- triage-and-conflictsSkill
- xelibSkill
- create-modSkill
- devbenchSkill
- find-sessionSkill
- inspect-espSkill
- logging-registrySkill
- mod-release-reviewSkill
- mod-update-checkSkill
- port-to-vrSkill
- skyrim-audioSkill
- skyrim-bsaSkill
- skyrim-contextSkill
- skyrim-mcmSkill
- skyrim-nifSkill
- skyrim-saveSkill
- toolkit-housecarlSkill
- toolkit-setupSkill
- triage-and-conflictsSkill
- xelibSkill
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
- Very specific: line 9
Use scripts/read-save.py to decompress and scan Skyrim save files.
- Distinctive: line 42
Mod footprint: Search for a mod's prefix (e.g., "MyMod_") to locate candidate bytes.
- Distinctive: line 82
Before writing, the adapter backs up the input pair and the output pair into the permanent save store.
- Very specific: line 88
Never: run resaverpp-cli.exe directly with -o, --batch or --apply, or the GUI ReSaverPP.exe: they skip every check above.
≈ “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.
Files
<!-- 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 0x0001ABCDSearch 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
decompressedSizeacross 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 oftools/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-roundtripis a self-test. Every--applychecks 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(itsBUILD-INFO.jsonand 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-roundtripruns in memory. - Writes:
--applyneeds ONE explicit new output pair in an existing folder. An existing.essOR.skseof 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.exedirectly with-o,--batchor--apply, or the GUIReSaverPP.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> --nowkeeps 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
Savesfolder 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.
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
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.

