maintaining-modding-environments
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.
Install / Use
npx skills add hashgraph-online/awesome-codex-plugins --skill maintaining-modding-environmentsInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of maintaining-modding-environments
maintaining-modding-environments scores 84/100 on our quality scale, 2928th of 4,698 Development & Engineering skills we index.
Its SKILL.md is 47 KB long, well organised into 71 sections with 34 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.
With 1,075 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so maintaining-modding-environments is actively maintained.
- Our last check on 2026-11-05 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
maintaining-modding-environments compared with similar skills
All 4 of these similar skills score higher than maintaining-modding-environments; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| maintaining-modding-environments (this skill)by hashgraph-online | 84 | 1.1k | 53d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install maintaining-modding-environments?
- Run
npx skills add hashgraph-online/awesome-codex-plugins --skill maintaining-modding-environments. The install tabs above show the steps for each supported agent. - Which AI agents does maintaining-modding-environments work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is maintaining-modding-environments safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is maintaining-modding-environments still maintained?
- The repository was last updated about 2 months ago, so maintaining-modding-environments is actively maintained.
Skill content
View source on GitHubname: maintaining-modding-environments description: "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."
Maintaining Modding Environments
When to use
- The environment is already set up and the user asks to maintain, refresh, update, or health-check it.
- The user says "register custom pack", "install my KB pack", "set
BGS_KB_USER_PACKS", or asks how to author a local KB pack. - The user asks how to maintain a mod knowledge base, a translator glossary KB, or a third-party localization KB for Skyrim/Fallout/Starfield.
- The user asks to install, upgrade, repair, or verify the standalone
xtl/bgs-translatorCLI after first-run. - The user asks to check or apply knowledge-base updates after first-run.
- The user asks to prune the KB cache or clean old pack versions.
- The user asks whether to pin a KB pack version, follow latest, or handle a
minPluginVersionwarning.
What this skill replaces
Use setting-up-bgs-modding-environment for first-run: MO2 detection, control-plane install, visible MO2 launch, first xEdit acquisition, first KB pack acquisition, and first semantic smoke.
This skill owns ongoing care after that first-run boundary: KB updates, cache hygiene, custom-pack authoring and registration, translator CLI maintenance, recurring environment health checks, and version-pinning advice.
Translator CLI maintenance
xtl is the standalone AI translation CLI/Web GUI launcher. It is published on
PyPI as bgs-translator; the portable plugin may include translator-facing
skills, but a fresh user machine still needs the Python package installed before
high-speed agents can call xtl.
Start every maintenance pass with an explicit readback:
# Check whether xtl is installed and can report its version/capabilities.
xtl version
# Inspect top-level commands before choosing a workflow.
xtl --help
If xtl is missing or too old, prefer an isolated user-level CLI install:
# Install the current release-candidate build as an isolated command-line tool.
pipx install bgs-translator==0.9.0rc1
# Upgrade an existing pipx-managed xtl install when a newer stable build exists.
pipx upgrade bgs-translator
If pipx is unavailable, or the user explicitly wants xtl inside a project
virtual environment, use Python's package installer from that environment:
# Install or upgrade xtl inside the selected Python environment.
py -3.12 -m pip install --upgrade bgs-translator==0.9.0rc1
For a future stable release, use the unpinned package name for normal installs:
pipx install bgs-translator, pipx upgrade bgs-translator, or
py -3.12 -m pip install --upgrade bgs-translator. Do not use broad
--pre during routine maintenance; it can allow prerelease dependency versions
that were not part of the tested translator build. Pin an exact prerelease only
when the user intentionally wants that version.
After any install or upgrade, inspect subcommand help instead of assuming specific option values:
# Verify provider-profile setup options, including all supported SDK kinds.
xtl profile add --help
# Verify web GUI launch options and ports.
xtl gui --help
# Verify batch controls before telling an agent to submit or resume work.
xtl batch --help
If a GUI or background translator service gets into an inconsistent state, restart it with the repo's reusable helper instead of inventing process-kill steps:
# Restart the translator GUI/service stack using the project helper.
pwsh tools\bgs-translator\scripts\restart-web-gui.ps1 -Port 7847
If that helper is absent in an older checkout, fall back to the current
using-bgs-translator instructions for launching xtl gui, then file a note in
the environment maintenance log that the helper should be added or backported.
Check + apply KB updates
- Start with
bgs_kb_status({})to see loaded packs, versions, cache root, user roots, and warnings. - If
bgs_kb_check_updatesexists, call it for the installed pack IDs. Surface available updates,breakingChange, and release URLs before taking action. - If
bgs_kb_check_updatesis not present yet (pre-KB-6), check GitHub Releases forbgs-modding-superpowersKB pack artifacts andmanifest-index.json. Do not invent release names. - Before installing or replacing a pack, get user consent for the download / cache mutation.
- If
bgs_kb_install_packexists, use it with an exact{ packId, version }. PreferdryRun: truebefore live install when the tool supports it. - If the install tool is not present yet, download the Release asset manually only after consent, verify the published sha256, extract into the cache layout below, then restart or reconnect the MCP so discovery runs again.
- After any update, run the health checks below.
Cache hygiene
Cache root (all platforms — unified with xtl / bgs-translator):
~/.bgs-modding-superpowers/kb/packs/<packId>/<version>/
The legacy Windows-only cache at %LOCALAPPDATA%/bgs-modding-superpowers/kb/packs/
is no longer used. If bgs_kb_status surfaces packs that are not visible to
xtl batch plan, suspect a legacy cache and either:
- move the directory tree from
%LOCALAPPDATA%/bgs-modding-superpowers/kb/to~/.bgs-modding-superpowers/kb/, or - export the legacy root via
$env:BGS_KB_USER_PACKSso the MCP keeps reading it as an additional read-only root while the user finishes migrating.
Each version directory contains manifest.json, records/, and kb.sqlite. Current policy: retain the current version and the immediately previous version as rollback/fallback. Prune versions older than that only after confirming the pack is not pinned by the user or referenced by a current modpack workflow.
Use the KB MCP CLI for routine pruning:
# Preview which cached pack versions would be removed.
node <plugin>\tools\bgs-kb-mcp\dist\cli.js prune-cache --dry-run
# Apply the prune after the user accepts the preview.
node <plugin>\tools\bgs-kb-mcp\dist\cli.js prune-cache
The dry run should be surfaced before deletion when the user has not already approved cache mutation. The command keeps the highest version and the immediately previous version per pack, then removes older cached versions.
Do not delete incoming/ while an install is running. If an install failed earlier and no installer is active, stale incoming/ contents can be removed after surfacing the path to the user.
Custom pack authoring + registration
Author records as:
<pack-root>/records/<domain>/<id>.md
Record frontmatter uses the same schema as official packs under knowledge/bgs-kb/schema/record.schema.json: stable id, title, domains, appliesTo, canonical, sources, lastReviewed, and schemaVersion are the important fields to check first.
Every pack needs a bgs-kb-meta.yml at the pack root. Minimum fields:
packId: user-my-pack
displayName: My Modpack Knowledge
version: 2026.06.02
schemaVersion: 1
minPluginVersion: 0.2.0
Reserved official pack IDs: bgs-kb-core, bgs-kb-skyrim, bgs-kb-fallout4, bgs-kb-fallout3-fnv, bgs-kb-starfield. End-user packs must not use the bgs-kb-* namespace; recommend a user-* prefix.
Build the pack:
# Build kb.sqlite and manifest.json from the pack's records/ tree.
node <plugin>\tools\bgs-kb-mcp\dist\cli.js build <pack-root>
This produces kb.sqlite and manifest.json next to records/.
Validate and inspect:
# Validate every Markdown record against the official KB schema.
node <plugin>\tools\bgs-kb-mcp\dist\cli.js validate <pack-root>
# Inspect pack metadata, counts, games, and domains.
node <plugin>\tools\bgs-kb-mcp\dist\cli.js info <pack-root>
Important BGS_KB_USER_PACKS semantics: each entry is a directory that contains one or more pack directories, not a pack directory itself. Multiple roots are separated by ; on Windows.
Worked example:
C:\my-kb-roots\
my-custom-pack\
bgs-kb-meta.yml
manifest.json
kb.sqlite
records\
load-order\
my-local-rule.v1.md
Set:
# Point discovery at the directory that contains one or more pack folders.
$env:BGS_KB_USER_PACKS = "C:\my-kb-roots"
Do not set it to C:\my-kb-roots\my-custom-pack; that points at the pack itself and discovery will look one level too deep.
After registration, restart/reconnect the MCP so pack discovery runs, then call bgs_kb_status({}) and verify the custom pack appears with the intended packId.
Pack discovery + collision recovery
bgs_kb_status({}) may report two warning codes when discovery sees the same packId at multiple roots:
| Code | Meaning |
|---|---|
| pack_id_overridden (MEDIUM, informational) | Multiple sources for the same packId; precedence picked a winner automatically and listed the loser(s). All packs still load. |
| pack_id_collision (HIGH, fail-closed fallback) | Precedence could not choose a winner — should be rare; all colliding copies are refused. |
Discovery precedence (apply in order):
- Sort candidates with the same
packIdbybuiltAttimestamp DESC — newest manifest wins. - Tie-break by root class:
bundled > cache > user.
Common cause: install-pack over an already-bundled packId. Plugin distributions ship per-game packs (e.g. bgs-kb-fallout4) in the bundled tree. If a user runs bgs_kb_install_pack({ packId: "bgs-kb-fallout4", ... }) to fetch a Release-channel update, the new version lands in the cache root ~/.bgs-modding-superpowers/kb/packs/bgs-kb-fallout4/<version>/. On the next MCP restart:
- If the cache copy has a newer
builtAt(the normal update case) → cache wins, bundled loser warning. No action needed. - If the bundled copy is somehow newer (e.g. you pulled a plugin update that shipped a newer KB) → bundled wins, cache becomes the loser. To make the cache copy authoritative, install a newer Release or remove the stale cache copy.
Other causes:
- Two
$BGS_KB_USER_PACKSparent directories contain pack folders with the samepackId→ warning per loser. - Manual file copy of a pack between roots without removing the original.
Preview before restarting MCP: the bgs-kb-mcp CLI exposes a read-only dev-status subcommand that shows the same discovery decision the MCP would make, without requiring a server restart:
# Preview every discovered packId, every candidate source, and which one would win.
node <plugin>\tools\bgs-kb-mcp\dist\cli.js dev-status
# Filter to one pack id (useful before install-pack or before editing user packs).
node <plugin>\tools\bgs-kb-mcp\dist\cli.js dev-status --pack bgs-kb-fallout4
# Machine-readable output for scripting.
node <plugin>\tools\bgs-kb-mcp\dist\cli.js dev-status --json
Recovery patterns:
- Want the cache copy to win: ensure its
builtAtis newer than the bundled copy's (runbgs_kb_install_packfor a fresh Release version), restart MCP, verify. - Want the bundled copy to win: remove or rename the cache pack directory, restart MCP.
- Two user roots collide: drop one parent from
$BGS_KB_USER_PACKS, or rename the colliding pack folder to a uniquepackId(after also updating itsbgs-kb-meta.yml), restart MCP. - Pre-flight before authoring or installing: always run
dev-status --pack <packId>first — it surfaces collisions before the next MCP restart turns them into status warnings.
Do not delete cache copies aggressively as a first-line fix; the precedence rule selects automatically, so warnings are usually informational, not blocking.
Localization and translator KBs
Localization glossary packs are KB packs whose SQLite store inc
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
