skyrim-papyrus

Compile, decompile, validate, and generate Papyrus scripts. Use when the user wants to write scripts, understand script behavior, fix script errors, or generate script templates for quests, actors, or magic effects.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive toolkit for managing Skyrim's Papyrus scripts, enabling developers to compile, decompile, validate, and generate script templates efficiently. By integrating modern tools like the russo-2025 compiler and Champollion decompiler, it streamlines the modding workflow for creating complex game logic, quests, and character behaviors.

Use Cases

  • Template Generation: Quickly create boilerplate code for various Skyrim script types including Quests, Actors, and Magic Effects to accelerate mod development.
  • Reverse Engineering: Decompile existing .pex files into readable .psc source code to understand vanilla game mechanics or analyze third-party mods.
  • Syntax Validation: Perform real-time syntax checks on Papyrus scripts to identify and fix errors before the compilation process.
  • Automated Compilation: Batch compile source scripts into executable game files while managing complex header dependencies and optimization settings.
  • Mod Troubleshooting: Use detailed compiler feedback and status checks to debug 'missing header' or 'unknown type' errors in complex modding environments.
nameskyrim-papyrus
descriptionCompile, decompile, validate, and generate Papyrus scripts. Use when the user wants to write scripts, understand script behavior, fix script errors, or generate script templates for quests, actors, or magic effects.

Skyrim Papyrus Module

Compile, decompile, validate, and generate Papyrus scripts using Spooky's AutoMod Toolkit.

Prerequisites

Run all commands from the toolkit directory:

cd "<TOOLKIT_PATH>"
# Example: cd "C:\Tools\spookys-automod-toolkit"

External Tools

Tools are auto-downloaded on first use:

Tool Purpose Notes
papyrus-compiler Compiles PSC to PEX Uses russo-2025/papyrus-compiler (modern, faster)
Champollion Decompiles PEX to PSC Community decompiler

Important: The toolkit uses russo-2025's modern compiler, NOT Bethesda's original PapyrusCompiler.exe.

Check tool status:

dotnet run --project src/SpookysAutomod.Cli -- papyrus status

Command Reference

Check Tool Status

dotnet run --project src/SpookysAutomod.Cli -- papyrus status

Download Tools

dotnet run --project src/SpookysAutomod.Cli -- papyrus download

Compile Scripts

dotnet run --project src/SpookysAutomod.Cli -- papyrus compile "<source>" --output "<dir>" --headers "<dir>"
Option Description
<source> PSC file or directory
--output, -o Output directory for PEX files
--headers, -i Directory containing script headers
--optimize Enable optimization (default: true)

Headers Path:

IMPORTANT: Script compilation requires Papyrus script headers (.psc files) from the Creation Kit.

Recommended approach:

  1. Copy headers to toolkit directory: ./skyrim-script-headers/
  2. Use --headers "./skyrim-script-headers" in compile commands
  3. See main README "Papyrus Script Headers" section for setup instructions

Alternative: Reference Creation Kit directly:

  • Steam: C:/Program Files (x86)/Steam/steamapps/common/Skyrim Special Edition/Data/Scripts/Source
  • GOG: C:/GOG Galaxy/Games/Skyrim Special Edition/Data/Scripts/Source

If headers are missing, compilation will fail with "invalid type" errors.

Decompile Scripts

dotnet run --project src/SpookysAutomod.Cli -- papyrus decompile "<pex>" --output "<dir>"
Option Description
<pex> PEX file or directory
--output, -o Output directory for PSC files

Validate Script Syntax

dotnet run --project src/SpookysAutomod.Cli -- papyrus validate "<psc>"

Generate Script Template

dotnet run --project src/SpookysAutomod.Cli -- papyrus generate --name "<name>" --extends "<type>" --output "<dir>"
Option Default Description
--name Required Script name (no extension)
--extends Quest Base type to extend
--output, -o . Output directory
--description - Description comment

Base Types:

  • Quest - Quest scripts
  • Actor - Actor scripts
  • ObjectReference - Object reference scripts
  • MagicEffect - Magic effect scripts
  • ActiveMagicEffect - Active magic effect scripts
  • Alias - Alias scripts
  • ReferenceAlias - Reference alias scripts
  • LocationAlias - Location alias scripts

Common Workflows

Create and Compile a Quest Script

# 1. Generate script template
dotnet run --project src/SpookysAutomod.Cli -- papyrus generate --name "MyMod_QuestScript" --extends Quest --output "./Scripts/Source"

# 2. Edit the generated script (add your code)

# 3. Validate syntax before compiling
dotnet run --project src/SpookysAutomod.Cli -- papyrus validate "./Scripts/Source/MyMod_QuestScript.psc"

# 4. Compile to PEX
dotnet run --project src/SpookysAutomod.Cli -- papyrus compile "./Scripts/Source" --output "./Scripts" --headers "./skyrim-script-headers"

# 5. Attach to quest in plugin
dotnet run --project src/SpookysAutomod.Cli -- esp attach-script "MyMod.esp" --quest "MyMod_MainQuest" --script "MyMod_QuestScript"

Decompile and Analyze Existing Scripts

# 1. Decompile a single script
dotnet run --project src/SpookysAutomod.Cli -- papyrus decompile "./Scripts/SomeScript.pex" --output "./Decompiled"

# 2. Decompile all scripts in a directory
dotnet run --project src/SpookysAutomod.Cli -- papyrus decompile "./Scripts" --output "./Decompiled"

# 3. Read the decompiled source to understand behavior

Create Magic Effect Script

# 1. Generate magic effect script template
dotnet run --project src/SpookysAutomod.Cli -- papyrus generate --name "MyMod_FireEffect" --extends ActiveMagicEffect --output "./Scripts/Source" --description "Fire damage over time effect"

# 2. Compile
dotnet run --project src/SpookysAutomod.Cli -- papyrus compile "./Scripts/Source/MyMod_FireEffect.psc" --output "./Scripts" --headers "./skyrim-script-headers"

Script Template Examples

Quest Script (OnInit)

ScriptName MyMod_QuestScript extends Quest
{Main quest controller}

;-- Properties --
GlobalVariable Property MyMod_Enabled Auto

;-- Events --
Event OnInit()
    If MyMod_Enabled.GetValue() == 1
        Debug.Notification("My Mod initialized!")
    EndIf
EndEvent

;-- Functions --
Function DoSomething()
    ; Your code here
EndFunction

Actor Script

ScriptName MyMod_ActorScript extends Actor
{Script attached to an actor}

Event OnLoad()
    Debug.Trace("Actor loaded: " + GetDisplayName())
EndEvent

Event OnDeath(Actor akKiller)
    Debug.Notification(GetDisplayName() + " was killed!")
EndEvent

ActiveMagicEffect Script

ScriptName MyMod_EffectScript extends ActiveMagicEffect
{Script for a magic effect}

Event OnEffectStart(Actor akTarget, Actor akCaster)
    Debug.Notification("Effect started on " + akTarget.GetDisplayName())
EndEvent

Event OnEffectFinish(Actor akTarget, Actor akCaster)
    Debug.Notification("Effect ended")
EndEvent

Troubleshooting Script Errors

Common Compilation Errors

"Compilation failed" with no details:

  • The toolkit now shows detailed compiler output when compilation fails
  • If you see this without details, it's a bug - report it with the command you ran

"Missing header files", "invalid type", or "unknown type":

  • Script headers are NOT included with the toolkit (Bethesda copyright)
  • You must install them manually - see README "Papyrus Script Headers" section
  • Verify headers path points to ./skyrim-script-headers or Creation Kit location
  • Headers must contain files like Actor.psc, Game.psc, Quest.psc, etc.
  • Without headers, the compiler cannot understand base types and will fail

Compiler not found:

  • Run papyrus status to check if compiler is installed
  • Run papyrus download to install the compiler if missing

"Script extends unknown type":

  • Ensure base type is spelled correctly
  • Common types: Quest, Actor, ObjectReference, MagicEffect

"Property not found":

  • Properties must be filled in the Creation Kit
  • Use GlobalVariable Property MyVar Auto for globals

"Function not found":

  • Check function exists in the parent type
  • Papyrus is case-insensitive for identifiers

Decompilation Issues

"Failed to decompile":

  • Some heavily obfuscated scripts may not decompile
  • Try newer Champollion versions

Important Notes

  1. Headers MUST be installed - Papyrus compilation will FAIL without script headers. See README for setup.
  2. Scripts/Source vs Scripts - Source (.psc) goes in Source folder, compiled (.pex) in Scripts
  3. Property linking - Properties defined in scripts must be filled in Creation Kit
  4. Case insensitivity - Papyrus identifiers are case-insensitive
  5. Use --json flag for machine-readable output when scripting

JSON Output

All commands support --json for structured output:

dotnet run --project src/SpookysAutomod.Cli -- papyrus status --json