Using Bgs Modding Superpowers

Using BGS Modding Superpowers

You are operating with the bgs-modding-superpowers plugin loaded. This plugin gives you an agent-driven toolkit for Bethesda Game Studio modpack curation: MO2 control plane, xEdit MCP, conflict-audit workflow, and runtime asset skills for dev-log and release-changelog maintenance.

Available skills (auto-trigger on these intents)

When the user's intent matches one of these, invoke the corresponding skill through your skill tool BEFORE replying. Do not paraphrase the skill from memory; let the skill load.

Available MCP tools

The bundled xedit MCP server (declared in .mcp.json for Claude Code / Codex, declared via the OpenCode plugin's config.mcp.xedit hook) is fully non-blocking: every tool returns immediately. The xEdit daemon's lifecycle is tracked in the server's in-memory state machine, and domain tools fast-fail with code: "not_ready" if you call them before the daemon is ready.

Lifecycle / health tools

Domain tools (6) — require ready, fast-fail otherwise

Canonical lifecycle pattern (do this every session that touches xEdit)

1. xedit_start({})                  -> { status: "starting" }      (or "ready")
2. xedit_status({})                 -> poll until status="ready"   (sleep 5-15s between calls)
3. xedit_health({})                 -> confirm responsive=true
4. xedit_session({}) / xedit_*      -> normal domain work
5. xedit_dirty({})                  -> check dirty state and pendingShutdownSave
6. xedit_flush({})                  -> when pending > 0, drain + confirm daemon self-exit
7. xedit_start({ ... })             -> fresh daemon for persistence readback after flush
8. xedit_stop({}) / restart({ ... }) -> only when no dirty or pending state exists

NEVER call a domain tool in a tight loop expecting it to "wait." If xedit_status reports status: "failed", surface data.error to the user and stop — common causes are MO2 not running visibly, the Python plugin not loaded, the xEdit binary missing, or xEdit's automation-serve tripping on the active load order.

The structured daemon-command and workflow reference now lives in KB records. Use bgs_kb_query / bgs_kb_get for deep reference retrieval; the old skills/xedit-automation/xedit-knowledgebase.md path is a redirect only.

BGS knowledge-base tools (3) — curated knowledge, no xEdit daemon

The sibling BGS knowledge-base MCP is for curated modding knowledge, not live runtime state. It works before MO2 / xEdit are configured; use xEdit MCP for actual plugin, load-order, and record readback.

Hard rules (non-negotiable)

1. The user's <MO2_Root> and any <MO2_Root>/<game>/Data/ (or equivalent "Stock Game" tree) is real game state. Never write into it directly. Any game-local change is expressed as an MO2 mod overlay under <MO2_Root>/mods/<mod-name>/. The MO2 VFS projects it at runtime.
2. All xEdit work goes through the bundled xedit MCP. Never spawn xEdit.exe directly from the shell, never parse .esp/.esm/.esl files with your own Python/JS, never invoke xedit-client.ps1 from raw shell. The MCP exists so the harness can enforce validation, state, rules, and audit on every call. Atomic passthrough (xedit_call) is the documented escape hatch when an intent tool does not fit — it is still in-harness.
3. Mutating operations require explicit user consent and a daemon launched with -IKnowWhatImDoing. Read the xedit-automation skill BEFORE any destructive work. The anti-pattern list there is binding.
4. A session.save response is not durability. A nonzero savedFilesPendingShutdown / savePendingShutdownCount is deferred. On contract 0.23, xedit_dirty reconciles that fallback with the daemon's authoritative pending queue and xedit_flush is the only supported in-band drain. It validates the response and confirms daemon self-exit before clearing the blocking guard. A partial or unknown outcome remains visible as lastFlush; after relaunch it is labelled previousSessionFlush with the old PID and timestamp. Failed in-band renames receive one normal exit-time retry, so fresh-daemon readback, not the partial envelope alone, decides durability. force:true on stop/restart is still explicit abandonment, never durability proof.
5. Large scope (many records, broad conflict survey) → delegate to a read-only investigator subagent FIRST. The subagent burns its own context and returns a distilled summary. Do not loop hundreds of records through your own context.
6. BGS domain knowledge routes through the KB first. For questions about how BGS modding works — Papyrus semantics, plugin-format gotchas, archive precedence, load-order conventions, common engine quirks, or game-specific toolchain gotchas — call bgs_kb_status / bgs_kb_query before improvising or reaching for web search. If the question is about what the current local load order, plugin, or record actually is, use xedit_* or the relevant file/CLI surface instead. The KB is advisory; xEdit readback remains authoritative for actual state. If bgs_kb_status reports no packs or the needed game pack is missing, fall back to web research using the roadmap Appendix source list or route setup/maintenance work to install the pack.
7. First-run state: if MO2 / xEdit / the control-plane Python plugin are not yet set up on this machine, invoke setting-up-bgs-modding-environment BEFORE any modpack work. That skill orchestrates detection and install.
8. Nexus credentials and Premium download paths: MO2 stores the user's Nexus API key globally in Windows Credential Manager under target ModOrganizer2_APIKEY (legacy) / ModOrganizer2_NEXUS_OAUTH_TOKENS (modern OAuth). Reading the key requires explicit per-session user consent and the key must be masked in any visible output. The agent-friendly refresh path for Nexus update state is "Option B" — direct API call to /v1/games/{game}/mods/{id}.json + write back to meta.ini via mo2_edit_meta, no MO2 GUI launch needed. Both workflows are documented in the maintaining-modding-environments skill and in KB records install-planning.mo2-windows-credential-mining.v1 + install-planning.nexus-direct-api-update-check.v1. For Premium-account direct downloads, use POST /v1/games/{game}/mods/{id}/files/{file_id}/download_link.json (returns 7 CDN mirrors) — Premium-only; free accounts must use the Nexus browser flow.

How to use this bootstrap

• This skill loads automatically on every new session. You do not need to re-invoke it.
• When a user intent matches a task skill in the table above, invoke that skill via your skill tool. Do not paraphrase.
• When the user asks about "what can you do", reference the skills inventory here; do not invent capabilities the plugin does not have.
• When answering BGS modding-domain questions, prefer local KB retrieval before web search. The bundled core pack ships inline; per-game packs may be installed later via setup / maintenance skills; end-user packs may be registered via $BGS_KB_USER_PACKS through maintaining-modding-environments.
• When you would normally write code that touches BGS plugin files (.esp/.esm/ .esl), STOP and route through xedit-automation instead.
• When the user is deciding whether to add or keep a mod ("should I install X", "is this good", "评估"), route to evaluating-bgs-mods BEFORE any install/download action.
• When an INCLUDE verdict is in and the user needs to read author instructions / pick FOMOD options / choose a file or variant, route to interpreting-mod-author-instructions.
• When the user is planning the whole pack, sizing batches, deciding rollback boundaries, or declaring 风格, route to curating-bgs-modpack.
• When the user reports a crash, CTD, FPS drop, freeze, or stutter ("崩溃", "掉帧", "卡顿"), route to diagnosing-bgs-problems for symptom-first triage BEFORE any blame attribution.
• When the user wants to verify a freshly installed batch ("test the pack", "is it stable", "验证安装"), route to testing-bgs-modpack.
• When the user wants to translate plugin text or emit SST dictionaries for a mod, route to using-bgs-translator instead of xEdit; translator reads plugin text and emits dictionaries, it does not modify plugin binaries.
• When the user wants to inspect, unpack, extract, or pack BA2/BSA archives, route to using-bgs-archive; archive packing must write to MO2 overlays, not game Data or Stock-Game trees.
• When the user wants to compile or decompile Papyrus scripts (.psc / .pex), route to using-bgs-papyrus; compiled .pex output must go to MO2 overlays, not game Data or Stock-Game trees.
• When the user asks to "log", "record", "track", or "note" modpack work, route to writing-modpack-devlog. When the user asks to "cut a release" or prepare release notes, route to writing-modpack-changelog.

See also

• setting-up-bgs-modding-environment — first-run setup orchestrator.
• maintaining-modding-environments — ongoing environment care, KB updates, custom-pack registration, cache pruning, and health checks after first-run.
• evaluating-bgs-mods — judgment skill: should this mod go in the pack (BGS systemic-design fit, quality/risk/pack-value); hands off to interpreting-mod-author-instructions on INCLUDE.
• interpreting-mod-author-instructions — judgment skill: how to correctly download/install per author说明 (FOMOD reasoning, file/variant selection, prerequisites). Downstream from evaluating-bgs-mods INCLUDE verdict.
• curating-bgs-modpack — judgment skill: whole-pack incremental strategy (batch sizing, rollback boundaries, attribution/naming, declaring 风格); cross-stage skill that the per-mod skills feed.
• diagnosing-bgs-problems — judgment skill: symptom-first triage for CTD / FPS / freeze / stutter; escalates to xedit-conflict-audit or using-bgs-archive once root-cause class is identified.
• testing-bgs-modpack — judgment skill: proactive post-install verification of an install batch; escalates to diagnosing-bgs-problems on failure.
• xedit-automation — hub skill for all xEdit work; routing doctrine, anti-patterns, sub-agent recipes.
• BGS KB records under knowledge/bgs-kb/packs/core/records/ — deep reference for daemon commands, error codes, save semantics, glossary, and durable gotchas.
• xedit-conflict-audit — the W2 conflict-audit workflow.
• using-bgs-translator — CLI + Tk workflow for LLM-assisted plugin text translation and SST dictionary export.
• using-bgs-archive — BA2/BSA archive inspection, extraction, and safe overlay-only packing.
• using-bgs-papyrus — Papyrus PSC/PEX compile/decompile workflows for Skyrim, Fallout 4, and Starfield.
• writing-modpack-devlog, writing-modpack-changelog — runtime asset skills for project documentation.

Plugin: bgs-modding-superpowers. Repo: https://github.com/BB-84C/bgs-modding-superpowers. If any environmental component (MO2, xEdit, control-plane Python plugin) is missing, route through setting-up-bgs-modding-environment before continuing.