SkillAgentSearch skills...

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-environments

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

84/100

Supported Platforms

Universal

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.

Substance
21/30
Structure
20/20
Description
15/15
Adoption
13/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
maintaining-modding-environments (this skill)by hashgraph-online841.1k53d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP 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.

name: 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-translator CLI 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 minPluginVersion warning.

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

  1. Start with bgs_kb_status({}) to see loaded packs, versions, cache root, user roots, and warnings.
  2. If bgs_kb_check_updates exists, call it for the installed pack IDs. Surface available updates, breakingChange, and release URLs before taking action.
  3. If bgs_kb_check_updates is not present yet (pre-KB-6), check GitHub Releases for bgs-modding-superpowers KB pack artifacts and manifest-index.json. Do not invent release names.
  4. Before installing or replacing a pack, get user consent for the download / cache mutation.
  5. If bgs_kb_install_pack exists, use it with an exact { packId, version }. Prefer dryRun: true before live install when the tool supports it.
  6. 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.
  7. 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_PACKS so 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):

  1. Sort candidates with the same packId by builtAt timestamp DESC — newest manifest wins.
  2. 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_PACKS parent directories contain pack folders with the same packId → 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 builtAt is newer than the bundled copy's (run bgs_kb_install_pack for 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 unique packId (after also updating its bgs-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

View on GitHub
GitHub Stars1.1k
CategoryDevelopment
Updated1mo ago
Forks294

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions