plugin-helper/.agents/skills/install-beatsaber-plugin/SKILL.md

name, description

name

description

install-beatsaber-plugin

Install or update a Beat Saber plugin in the plugin-helper repo by using the local helper workflow. Use when the user asks to add, install, update, bump, lock, or manage a Beat Saber plugin release for a BSManager instance. The user must provide an explicit GitHub release URL in the prompt; if no release URL is present, ask for one and do not infer, search for, or substitute a different repository.

Install Beat Saber Plugin

Use the repository's own plugin-helper commands to manage plugins for BSManager instances. Do not manually copy release files into the game instance except to undo your own mistaken install before rerunning the helper.

Hard Guardrail

Require an explicit GitHub release URL from the user's prompt before selecting any release or repository.

• If the prompt does not contain a GitHub release URL, stop and ask the user for it.
• Do not search the web to discover a repository or "correct" release URL.
• Do not substitute a similar repo, fork, project, or package name.
• If the provided URL is a general releases page, use that repo's release API and choose the latest non-draft, non-prerelease release unless the user asks for a specific tag/version.
• If the provided URL is a tag URL, use that exact tag.

Accepted URL shapes include:

https://github.com/<owner>/<repo>/releases
https://github.com/<owner>/<repo>/releases/tag/<tag>
https://github.com/<owner>/<repo>/releases/download/<tag>/<asset>

Workflow

1. Confirm the workspace is the plugin-helper repo.

   test -f pyproject.toml && test -d src/plugin_helper && test -d registry && test -d locks
   

2. Read the local helper behavior before changing files.

   Inspect at least:

   sed -n '1,220p' README.md
   sed -n '1,260p' src/plugin_helper/cli.py
   sed -n '1,260p' src/plugin_helper/planner.py
   sed -n '1,220p' src/plugin_helper/models.py
   sed -n '1,220p' registry/plugins.toml
   sed -n '1,220p' locks/<instance>.lock.toml
   

3. Determine the instance.

   Prefer the instance the user names. If omitted and the working context clearly points at one lockfile, use that instance. Otherwise run:

   PYTHONPATH=src python -m plugin_helper instances
   

4. Snapshot first when requested.

   If the user asks for a one-time or pre-helper snapshot, archive the instance's Plugins/ directory before any install:

   mkdir -p "$HOME/archive/beatsaber"
   tar -C "<instance-root>/<instance>" -czf "$HOME/archive/beatsaber/<instance>-Plugins-pre-helper-<timestamp>.tar.gz" Plugins
   sha256sum "$HOME/archive/beatsaber/<instance>-Plugins-pre-helper-<timestamp>.tar.gz"
   

   Report the archive path and hash.

5. Resolve the release from the user-provided URL only.

   For GitHub URLs, derive <owner>/<repo> and optional <tag> from the URL. Query the GitHub API directly for metadata:

   curl -sS https://api.github.com/repos/<owner>/<repo>/releases
   curl -sS https://api.github.com/repos/<owner>/<repo>/releases/tags/<tag>
   

   Pick the asset that matches the Beat Saber instance/version. Prefer an exact versioned asset such as 1.40.8.zip over broad or source archives. If multiple plausible assets remain, ask the user.

6. Inspect the asset before selecting an install strategy.

   Download to the helper state directory:

   mkdir -p .state/instances/<instance>/downloads
   curl -L --fail -o .state/instances/<instance>/downloads/<asset-name> "<browser_download_url>"
   sha256sum .state/instances/<instance>/downloads/<asset-name>
   

   Match the checksum against GitHub's digest when available. Inspect zip contents:

   unzip -l .state/instances/<instance>/downloads/<asset-name>
   

   Strategy guide:

   • dll-to-plugins: asset is a single .dll that belongs in Plugins/.
   • bsipa-zip: zip top-level paths are only IPA/, Libs/, or Plugins/.
   • root-zip: zip contains valid game-root paths outside the BSIPA top-level set.
   • zip-to-pending: only when the release is intended for IPA/Pending/.
   • manual: do not use for installable releases.

7. Update the registry and lockfile.

   Add or update exactly one [[plugins]] entry in registry/plugins.toml with:

   [[plugins]]
   id = "<stable-plugin-id>"
   name = "<human name>"
   repo = "<owner>/<repo>"
   asset_patterns = ["<asset-name-or-pattern>"]
   install_strategy = "<strategy>"
   category = "<category-if-obvious>"
   

   Add or update the matching [[plugins]] entry in locks/<instance>.lock.toml with:

   [[plugins]]
   id = "<stable-plugin-id>"
   repo = "<owner>/<repo>"
   tag = "<tag>"
   asset = "<asset-name>"
   sha256 = "<asset-sha256>"
   

   Preserve unrelated registry and lockfile content. Do not invent dependency versions unless they are explicitly stated by the provided release notes or existing local metadata.

8. Use the helper to validate, plan, and apply.

   Always pass --state-dir .state so the helper uses the repo-local downloaded asset:

   PYTHONPATH=src python -m plugin_helper --state-dir .state check --instance <instance>
   PYTHONPATH=src python -m plugin_helper --state-dir .state plan --instance <instance> --plugin <plugin-id>
   PYTHONPATH=src python -m plugin_helper --state-dir .state apply <generated-plan-path>
   

   Before applying, read or summarize the generated plan enough to confirm it changes only the intended plugin files.

9. Verify the result.

   Confirm the installed file hashes match the plan or archive members:

   PYTHONPATH=src python -m plugin_helper --state-dir .state state --instance <instance>
   PYTHONPATH=src python -m plugin_helper --state-dir .state check --instance <instance>
   PYTHONPATH=src python -m unittest discover -s tests
   

   Use PYTHONPATH=src; plain python -m unittest may fail in this source-layout repo.

10. Final response.

Include:

• release URL/tag/asset used
• snapshot path and hash, if created
• files changed in the repo and helper state
• live instance files changed
• backup path created by the helper
• validation commands and results

Mistake Recovery

If you installed from the wrong release or repo during the current task:

1. Restore affected live files from the helper backup created by that mistaken apply.
2. Remove mistaken downloaded assets and mistaken plan files from .state.
3. Correct the registry and lockfile to the user-provided release URL.
4. Rerun check, plan, and apply with --state-dir .state.
5. Keep or report only the backup relevant to the final correct apply unless the user asks for full audit history.