plugin-helper/.agents/skills/beatsaber-plugin-update-auditor/SKILL.md

name, description

name	description
beatsaber-plugin-update-auditor	Audit Beat Saber plugin-helper locks for available plugin updates and follow-up work. Use when the user asks to check all Beat Saber plugins for updates, compare locked mods against GitHub or BeatMods, review plugin/version compatibility tracking notes, identify PR/local/manual builds that need follow-up, or skip paid/private Patreon and Discord plugin sources during update checks.

Beat Saber Plugin Update Auditor

Use this skill from the plugin-helper repo to produce an update audit, not to blindly update plugins. Keep public, private, and experimental sources distinct.

Before auditing, read the shared policy references:

• repo-workflow.md for repo root, .venv, PYTHONPATH=src, dirty worktree handling, and validation commands.
• state-and-profiles.md for .state, profiles, install identity, instance selection, and checkout locations.
• artifact-policy.md for GitHub/BeatMods/private-source/checksum policy.
• live-validation.md only when reviewing smoke-test notes or launch failures.

Workflow

1. Confirm repo context:

   test -f pyproject.toml && test -d src/plugin_helper && test -d locks && test -d registry/plugins
   git status --short
   

2. Choose the instance from the user request. If omitted, use the latest available BSInstance unless the current task context clearly points at another instance:

   PYTHONPATH=src .venv/bin/python -m plugin_helper instances
   

3. Run the update audit with repo-local state unless the user explicitly targets another configured profile:

   PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state updates --instance <instance>
   PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state updates --instance <instance> --json
   

   The command checks ordinary GitHub locks, beatmods-* locks via BeatMods verified metadata, skips patreon/ and discord/ sources, and marks local, PR, manual, failed-trial, or pending-smoke entries as review items.

4. Read the active compatibility tracker before proposing updates for review items. For the current migration notes, inspect:

   sed -n '1,380p' docs/notes/install-and-verify-plugins-1.44.1.md
   sed -n '1,220p' docs/notes/naluluna-mod-assistant.md
   

   Follow up on rows marked failed, omitted, currently failed, smoke blocked, manual resmoke pending, local build, PR build, or local/private. Do not reinstall failed or omitted plugins unless the notes identify a newer compatible source.

5. For each public update candidate, inspect source notes before changing the lock. Follow the shared artifact policy for GitHub-first sourcing and BeatMods fallback cases.

6. Do not attempt automated public update checks for:

   • patreon/NalulunaModAssistant or Naluluna bundles
   • discord/BeatSaberPlus or BeatSaberPlus/ChatPlexSDK bundles
   • other paid or closed-source plugin zips

   Report them as skipped/manual follow-up only.

7. If the user asks to apply an update, switch to the beatsaber-plugin-manager workflow for download, lock update, planning, apply, and smoketest.

Output

Summarize in four groups:

• Public updates found: plugin, current version, candidate version, source.
• Current public locks: count only unless the user asks for every row.
• Review follow-ups: local builds, PR builds, failed trials, blocked smokes, or notes saying compatibility work is pending.
• Skipped private sources: Patreon/Discord paid or closed-source packages.

Mention BeatMods/GitHub API errors separately from "no update found"; those are unknowns, not proof that the plugin is current.