skyrim-nif
Skill22 starsChanged 4 days agoMITView on GitHub
Inspect and modify NIF mesh files - AutoMod CLI for textures/strings/shaders, PyFFI for LE NiTriShape geometry edits, PyNifly for BSTriShape (SSE) and all animation/controller authoring plus parse-validation. Use when working with meshes, textures, skeleton nodes, collision blocks, mesh animation, or fixing VR mesh issues.
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
- skyrim-saveSkill
- 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-saveSkill
- toolkit-housecarlSkill
- toolkit-setupSkill
- triage-and-conflictsSkill
- xelibSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is 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.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Use the AutoMod CLI for texture, string and shader work (always with --json).
- Distinctive: line 24
Use NifSkope or a purpose-built parser (PyFFI, below) for collision.
- Distinctive: line 160
PyNifly is also the validation gate: After authoring or editing any NIF, cross-read it with PyNifly — an independent, battle-tested parser …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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-nif/SKILL.md. Toolkit contributors: edit the source. Your own notes belong in KNOWLEDGEBASE.local.md, which updates never replace. -->NIF Mesh Operations
Use the AutoMod CLI for texture, string and shader work (always with --json); PyFFI and PyNifly (below) cover geometry and animation.
bash tools/automod-cli.sh nif <command> [args] --jsonRead-Only Commands
nif info <path>— file version, size, structurenif list-textures <path>— all texture references (supports recursive folder)nif list-strings <path>— all string entries / node namesnif shader-info <path>— shader property detailsnif verify <path>— integrity check
AutoMod nif cannot inspect Havok collision (bhk*) blocks — it handles textures/strings/shaders only.
Use NifSkope or a purpose-built parser (PyFFI, below) for collision.
Write Commands (always confirm with user first)
nif replace-textures <path> --old <str> --new <str> [--dry-run] [--backup]— batch retexturenif rename-strings <path> --old <str> --new <str> [--dry-run] [--backup]— rename nodesnif fix-eyes <path> [--dry-run] [--backup]— fix FaceGen eye ghostingnif scale <path> <factor> [--output <path>]— resize meshnif restore <path>— restore from .nif.bak backup
VR-Critical Mesh Issues
- PreWEAPON and PreSHIELD skeleton nodes cause CTD in VR — use
nif list-stringsto check for these, thennif rename-stringsto remove the "Pre" prefix or delete the nodes - VR does a text-contains search for WEAPON/SHIELD nodes and gets confused by Pre* prefixes
- XP32 First Person Skeleton CTD Bugfix is critical for custom skeleton users in VR
Geometry & Animation Authoring (PyFFI / PyNifly)
AutoMod handles textures/strings/shaders/scale but NOT geometry rewrites or animation. For those:
- PyFFI (any modern Python + setuptools) — LE-format
NiTriShapegeometry edits: vertex shifts, bounds, collision/ shader tweaks, and mesh split/subdivision.tools/pyffi-geometry-split.pysplits one shape into two so each half can carry its own shader (e.g. partial-mesh glow without UV overlap). Limits: cannot read SSEBSTriShape; never author animation controllers with PyFFI — the written file passes PyFFI's own readback but CTDs the engine. - PyNifly — reads/writes SSE
BSTriShapeAND authors animation/controller blocks correctly (NiControllerManager/NiControllerSequence/NiTransformData, etc.). Use it for:- Self-spinning effect meshes — a
SpecialIdle-namedNiControllerSequenceauto-loops on a placed Activator with zero scripting. - Telescoping / transforming geometry and any keyframed mesh motion.
- As the independent parse gate for any authored/edited NIF (see below).
- Self-spinning effect meshes — a
Validate & Render Before In-Game Testing
A crash-to-desktop must be caught in tooling, not the headset. Run these gates in order:
- PyNifly parse —
tools/blender-nif-validate.pyimports the NIF via PyNifly (an independent, stricter parser). A malformed file errors here instead of CTD-ing the game. Check the SPECIFIC crashable subsystem (e.g. the animation controller) — a geometry-only read passes even when the animation stack is malformed.blender.exe --background --python tools/blender-nif-validate.py -- <path.nif> - Render to PNG —
tools/blender-nif-render.pyproduces an image so a mesh/glow/shape fix is verifiable in chat without a game launch. Post the PNG for the user to confirm.blender.exe --background --python tools/blender-nif-render.py -- <path.nif> <out.png> - NifSkope (GUI) — the independent visual validator for anything the headless render can't show.
- Diff against a known-good structure — compare the block layout with a NIF that is known to work in game before trusting a new one. Author with valid-by-construction tools (PyNifly), not hand-rolled controller blocks.
Blender shares the nifly library, so it is NOT an independent parser — use it for repair and rendering, and PyNifly/NifSkope for validation. PyFFI's own readback is NOT a valid gate (same tool that wrote the file).
Blender (headless) + the PyNifly Blender addon, plus NifSkope, are optional installs — see setup.sh.
PyFFI — LE-format NiTriShape geometry edits
Works on any modern Python with setuptools installed alongside pyffi. The
time.clock = time.perf_counter monkey-patch is required on every interpreter (removed from the
stdlib in 3.8; unrelated to the distutils issue).
HARD LIMITS — repeated here deliberately, because this file may be read without the root instruction file in context:
- PyFFI cannot read BSTriShape (
Unknown block type 'BSTriShape') — any SSE-format (user_version_2=100) NIF. Use PyNifly.- NEVER author animations with PyFFI. It can construct controller blocks and its own readback will pass, but the result CTDs the engine — it omits header string-table registrations the engine requires. Use PyNifly.
- Building from a fresh
NifFormat.Data()corrupts the header string table on write. Always load an existing valid NIF and restructure it.
import time; time.clock = time.perf_counter
from pyffi.formats.nif import NifFormat
with open('path/to/input.nif', 'rb') as f:
data = NifFormat.Data(); data.read(f)
# ... modify blocks ...
with open('path/to/output.nif', 'wb') as f:
data.write(f)Why PyFFI over binary patching / NifSkope re-saves
- Preserves exact NIF format (BSStreamVersion, block types, shader flags, texture slots).
- Handles version differences (83 vs 100) correctly — no format corruption.
- Outputs byte-identical files except for the changed fields.
- NifSkope converts NIFs to BSStreamVersion 100 (SSE format) on save, which can strip texture slots and change the BSLightingShaderProperty structure → crashes with Community Shaders / TruePBR in VR. Scripted PyFFI edits avoid this entirely.
Key operations
- Collision shape editing:
block.dimensions.y = new_valueonbhkBoxShape - Transform editing:
block.transform.m_42 = new_valueonbhkConvexTransformShape - Block iteration:
for block in data.blocks:+type(block).__name__to find block types - Child traversal:
block.shapeon abhkConvexTransformShapegets the child shape
PyNifly — BSTriShape (SSE) + animation/controller authoring
Installed at tools/pynifly/io_scene_nifly/ (BadDogSkyrim PyNifly; the prebuilt NiflyDLL.dll
ships with it — no Blender, no compile; plain Python 3.10/3.12 x64). It wraps ousnius/nifly, the
library behind BodySlide/Outfit Studio. Verified on PyNifly 27.2.0 (the one version the toolkit pins, for
this library and the Blender add-on alike): the DLL actually loaded is io_scene_nifly/NiflyDLL.dll (the zip's
io_scene_nifly/pyn/NiflyDLL.dll is never loaded), and from pyn import pynifly loads it automatically. The
NiControllerSequence authoring round-trip below was re-validated 2026-10-06: 27.2.0 and 29.1.0 author
byte-identical controller stacks.
Never round-trip an animated NIF through Blender (import → export): the add-on drops the animation controllers on both 27.2.0 and 29.1.0 (Blender 4.2 has no animation export). Repair animated NIFs with PyNifly directly.
import sys
sys.path.insert(0, "tools/pynifly/io_scene_nifly")
from pyn import pynifly # import as the package, NOT `import pynifly`; loads the DLL itself
nf = pynifly.NifFile(path) # reads SSE BSTriShape AND LE NiTriShape
[s.name for s in nf.shapes]; list(nf.nodes.keys())Use PyNifly for the things PyFFI cannot do: any BSTriShape (SSE) NIF, and all
animation/controller authoring — it has .New() factories for NiControllerManager /
NiControllerSequence / NiMultiTargetTransformController / NiTransformData /
NiTransformInterpolator / NiDefaultAVObjectPalette / BSXFlags / NiTextKeyExtraData that register
header strings correctly (the exact thing PyFFI botches → CTD). This is what makes self-spinning
/ telescoping / keyframe-animated effect meshes possible (e.g. a SpecialIdle-named
NiControllerSequence auto-loops on a placed Activator with zero scripting).
PyNifly is also the validation gate. After authoring or editing any NIF, cross-read it with PyNifly — an independent, battle-tested parser — before handing it to in-game testing. A clean PyNifly read catches malformed files that PyFFI's same-tool readback misses; self-consistent is not the same as engine-valid. Check the specific crashable subsystem (e.g. the controller), because a geometry-only read can pass while the animation stack is malformed.
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.

