菜单
Use when the user wants to inspect, list, extract, unpack, or repack Bethesda BA2/BSA archives; determine archive format/version/compression; or build archive assets for an MO2 overlay. Triggers - "unpack BA2", "extract BSA", "pack archive", "inspect archive", "bgs-archive".
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | using-bgs-archive |
| description | Use when the user wants to inspect, list, extract, unpack, or repack Bethesda BA2/BSA archives; determine archive format/version/compression; or build archive assets for an MO2 overlay. Triggers - "unpack BA2", "extract BSA", "pack archive", "inspect archive", "bgs-archive". |
bgs-archive is the agent-native CLI for Bethesda BA2/BSA archives. It detects archive family/version, lists entries, extracts assets, and packs supported BSA/BA2 outputs for MO2 overlay workflows.
Use this skill for:
Do not use it for plugin records (.esp/.esm/.esl) or load-order edits. Route those through xEdit / load-order skills.
Always query the live binary before choosing a game, format, or packing path:
bgs-archive --json capabilities
# Alias:
bgs-archive --json caps
Read the JSON envelope and branch on data.write_support and data.read_support. Do not assume DX10 or GNMF packing exists just because DX10/GNMF extraction works.
If bgs-archive is not on PATH, locate the GitHub Release-installed binary under:
~/.bgs-modding-superpowers/tools/bgs-archive/<version>/
or build from the source tree:
cd D:\awesome-bgs-mod-master\tools\bgs-archive
$env:PATH = "$env:USERPROFILE\.cargo\bin;$env:PATH"
cargo build --release
target\release\bgs-archive.exe --json capabilities
Data folder or any Stock-Game tree.<MO2_Root>/mods/<mod-name>/Data/....Data.unsupported.--json for agent workflows and branch on the envelope, not human text.Asset precedence is the runtime question "which asset bytes does the game actually read for this virtual path?" It is related to load order, but it is not the same layer as plugin-record conflict resolution.
Core rules:
textures/... or meshes/... file is active, it can mask every packed copy of that path.plugins.txt / the game's active plugin order), not MO2 left-pane mod order. Moving a mod in the left pane may change loose-file winners, but it does not by itself prove a packed archive entry will win.bgs_kb_query({ query: "asset precedence engine caveat", games: ["<current game>"], domains: ["engine", "archive-precedence"] })
bgs_kb_query({ query: "archive count or packaging CTD", games: ["<current game>"], domains: ["archive-precedence", "debugging"] })
Red flags:
| Thought | Reality |
|---|---|
| "The wrong texture/model loaded, so I should reorder plugins first." | First inspect the final asset provider chain. Wrong bytes are usually an asset-precedence question before they are a record-order question. |
| "MO2 left-pane priority controls packed assets too." | Left-pane priority controls loose-file winners. Packed archive winners are tied to the plugin/load-order surface. |
| "I'll extract every archive loose so conflicts are obvious." | Bulk extraction creates duplicate active surfaces and can make the final tree harder to reason about. Extract only a bounded diagnostic set or a deliberate overlay. |
| "A current game's engine-specific archive/precompute problem belongs in this archive skill." | That is game-specific engine knowledge. Query the relevant KB record and keep this skill game-agnostic. |
| "The archive command succeeded, so the runtime winner changed." | Run info/list and inspect the MO2 final virtual path/provider chain before claiming the game will read the new asset. |
Rationalizations:
| Excuse | Reality |
|---|---|
| "Plugin order changed, so asset order must be fixed." | Only plugin-associated archives follow that surface; loose files can still override the packed winner. |
| "It's just a texture, not a real conflict." | Asset conflicts are real runtime behavior. A single winning mesh, texture, interface file, or script can be the visible bug. |
| "Unpacking is reversible, so I'll do it broadly." | Reversible clutter is still clutter. Keep extraction bounded and staged outside game Data. |
| "The FO4 recipe is known, so paste it here." | Game facts belong in KB. The archive skill teaches the judgment frame and asks KB for game-specific facts. |
| "If the file is in a BA2/BSA, MO2 mod priority is irrelevant." | It is different, not irrelevant: archives route through active plugins/load order. |
After asset precedence is understood, route record-level conflicts to xedit-conflict-audit. Archives decide files; xEdit decides plugin records.
Every --json command returns one stdout object:
{
"ok": true,
"tool": "bgs-archive",
"command": "capabilities",
"data": {},
"error": null
}
On classified failures:
{
"ok": false,
"tool": "bgs-archive",
"command": "pack",
"data": null,
"error": { "code": "unsupported", "message": "dx10_pack not yet supported (Task A-DX10)" }
}
Check bgs-archive --help and <subcommand> --help for the current option surface. The examples below are templates.
capabilitiesUse first to discover supported games, subcommands, read support, and write support.
bgs-archive --json capabilities
Expected machine output includes:
{"ok":true,"tool":"bgs-archive","command":"capabilities","data":{"games":["morrowind","oblivion","fallout3","falloutnv","skyrimle","skyrimse","fallout4","fallout4ng","fallout76","starfield"],"write_support":{"tes3":true,"tes4":true,"fo4_gnrl":true,"dx10":false,"gnmf":false},"read_support":{"all_families":true}},"error":null}
infoDetect archive family, version, BA2 format, compression, and entry count.
bgs-archive --json info "D:\path\to\Archive.ba2"
Expected machine output shape:
{"ok":true,"tool":"bgs-archive","command":"info","data":{"path":"D:\\path\\to\\Archive.ba2","family":"fo4","version":1,"format":"GNRL","compression":"Zip","entry_count":42},"error":null}
listList archive entries, optionally with a glob filter and long metadata.
bgs-archive --json list "D:\path\to\Archive.ba2" --filter "textures/**/*.dds" --long
Expected machine output shape:
{"ok":true,"tool":"bgs-archive","command":"list","data":[{"path":"textures/example/diffuse.dds","size":4096,"compressed":true}],"error":null}
extractExtract to a chosen directory. Use filters to keep agent runs bounded.
bgs-archive --json extract "D:\path\to\Archive.ba2" --out "D:\work\archive-extract" --filter "meshes/**/*.nif"
Expected machine output shape:
{"ok":true,"tool":"bgs-archive","command":"extract","data":{"output_dir":"D:\\work\\archive-extract","extracted_count":1,"paths":["meshes/example/static.nif"]},"error":null}
packPack a directory into a supported output. The output path must be inside an MO2 mod overlay when the result is game-local content.
$overlay = "D:\ModOrganizer\mods\My Packed Assets"
bgs-archive --json pack "$overlay\source-assets" "$overlay\Data\MyPackedAssets - Main.ba2" --game fallout4 --format gnrl --compress zip
Expected machine output shape:
{"ok":true,"tool":"bgs-archive","command":"pack","data":{"out_archive":"D:\\ModOrganizer\\mods\\My Packed Assets\\Data\\MyPackedAssets - Main.ba2","family":"fo4","version":1,"entry_count":12},"error":null}
Unsupported DX10/GNMF pack example:
bgs-archive --json pack "$overlay\source-assets" "$overlay\Data\Textures.ba2" --game fallout4 --format dx10
Expected result:
{"ok":false,"tool":"bgs-archive","command":"pack","data":null,"error":{"code":"unsupported","message":"dx10_pack not yet supported (Task A-DX10)"}}
bgs-archive --json capabilities.info on the source archive.list --filter ... to bound the exact asset set.<MO2_Root>/mods/<mod-name>/Data/....info and list on the packed archive as readback before reporting success.Remember: game Data and Stock-Game trees are read-only real state. MO2 overlays are the correct Vault-Tec-approved safety containment chamber.
Use whenever the task involves inspecting, modifying, or building plugins for Bethesda games via the forked xEdit automation daemon. Loads first; routes to the right path (MCP intent tool, MCP atomic passthrough, or sub-agent delegation) and prevents the agent from bypassing the harness.
Use after first-run for ongoing modpack maintenance: update/install KB packs, author or register custom/mod KB packs, maintain localization glossary KBs for translator use, prune KB cache, health-check the environment, version-pin KB/tooling, or handle recurring BGS modding environment care.
Use when deciding how to correctly download/install a Bethesda mod per the author's instructions — triggers "how do I install", "FOMOD choices", "which file to download", "author说明", "install instructions", "which variant", "按作者说明安装", "这个mod怎么装". NOT for deciding whether to include the mod (use evaluating-bgs-mods), load order editing (writing-bgs-load-order), record conflicts (xedit-conflict-audit), archive operations (using-bgs-archive), Papyrus work (using-bgs-papyrus), or translation/export tasks (using-bgs-translator).
Use when starting ANY conversation involving Bethesda Game Studio modding, MO2, xEdit, or modpack curation. Bootstrap that loads the toolkit overview, lists available task skills, and enforces the hard rules of this plugin. Auto-injected by the OpenCode plugin's chat.messages.transform hook and by the hooks/ session-start chain in Claude Code and Codex.
Use when planning or building the whole Bethesda modpack incrementally — batch strategy, rollback point, naming convention, separator discipline, attribution, and declaring 风格 before adding mods. Triggers - "build a modpack", "plan the pack", "batch strategy", "rollback point", "naming convention", "declare 风格", "策展整合包", "整合包规划". NOT for deciding whether one mod belongs (evaluating-bgs-mods), installing one mod from author instructions (interpreting-mod-author-instructions), load order mechanics (writing-bgs-load-order), or record conflicts (xedit-conflict-audit).
Use when a BGS modded game has CTD, crash log, FPS drop, stuttering, freeze, performance, won't start, 崩溃, 掉帧, 卡顿 symptoms and the user needs a symptom-first diagnostic ladder. NOT for proactive post-install testing; use testing-bgs-modpack.