Refactor agent skills

.agents/skills/beatsaber-plugin-builder/SKILL.md

@@ -7,6 +7,13 @@ description: Build, test-compile, or package Beat Saber PC BSIPA plugin source o
 
 Use this skill to compile PC BSIPA plugin projects on this Linux host, especially from the `plugin-helper` repo. The workflow is adapted from the Setlist repo's Linux/Cursor build notes.
 
+Before building, read the shared policy references:
+
+- [repo-workflow.md](../references/repo-workflow.md) for repo root, `.venv`, `PYTHONPATH=src`, dirty worktree handling, and validation commands.
+- [state-and-profiles.md](../references/state-and-profiles.md) for `.state`, profiles, install identity, instance selection, and checkout locations.
+- [artifact-policy.md](../references/artifact-policy.md) when handing a built artifact to `plugin-helper`.
+- [live-validation.md](../references/live-validation.md) when validating a built plugin in-game.
+
 For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-bsipa-build.md) when you need to configure a project, fix missing references, package artifacts, or explain a failure.
 
 ## Core Workflow
@@ -19,17 +26,14 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b
    sed -n '1,220p' plugin-helper.local.toml
    ```
 
-   In `plugin-helper`, run commands from repo root. Treat
-   `plugin-helper.local.toml` as the source of truth for profile
-   `instances_root` and `state_dir` values, and keep temporary source checkouts
-   under the chosen profile's `state_dir` such as
-   `<state_dir>/build/<name>`. Do not disturb unrelated dirty files.
+   In `plugin-helper`, run commands from repo root. Treat shared profile and
+   dirty-worktree policy as binding.
 
 2. Resolve source.
 
-   For a GitHub PR, clone or reuse a checkout under the selected profile's
-   `<state_dir>/build`, add/fetch the upstream remote if needed, and check out
-   the PR head:
+   For a GitHub PR, clone or reuse a checkout according to the shared source
+   checkout policy, add/fetch the upstream remote if needed, and check out the
+   PR head:
 
    ```bash
    git clone https://github.com/<owner>/<repo>.git <state_dir>/build/<name>
@@ -37,7 +41,8 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b
    git -C <state_dir>/build/<name> checkout pr-<pr>
    ```
 
-   If the PR is from a fork and the repo already has a fork remote, preserve it. Never overwrite local source changes without explicit approval.
+   If the PR is from a fork and the repo already has a fork remote, preserve it.
+   Never overwrite local source changes without explicit approval.
 
 3. Inspect build shape.
 
@@ -51,9 +56,11 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b
 4. Choose Beat Saber references.
 
    Prefer a BSManager instance matching the plugin or manifest `gameVersion`.
-   Read `plugin-helper.local.toml` and select the intended profile, then use
-   that profile's `instances_root` and matching `state_dir` instead of
-   searching default BSManager paths manually:
+   If the user did not specify an instance and the plugin does not require a
+   narrower version, use the latest available BSInstance. Read
+   `plugin-helper.local.toml` and select the intended profile, then use that
+   profile's `instances_root` and matching `state_dir` instead of searching
+   default BSManager paths manually:
 
    ```bash
    PYTHONPATH=src .venv/bin/python -m plugin_helper --profile <profile-id> instances
@@ -107,7 +114,7 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b
 
 8. Validate.
 
-   For skill edits inside this repo, run:
+   For skill edits inside this repo, run the shared skill validation plus:
 
    ```bash
    python /home/pleb/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/beatsaber-plugin-builder

.agents/skills/beatsaber-plugin-builder/references/linux-bsipa-build.md

@@ -43,7 +43,7 @@ Prefer machine-local configuration in `<Project>.csproj.user`:
 ```xml
 <Project>
   <PropertyGroup>
-    <BeatSaberDir>/path/from/selected/profile/instances_root/1.44.1</BeatSaberDir>
+    <BeatSaberDir>/path/from/selected/profile/instances_root/selected-instance</BeatSaberDir>
   </PropertyGroup>
 </Project>
 ```