docs: overhaul offload README with 'why' context and add skill-specific guides

.gemini/skills/fix-pr/README.md

@@ -0,0 +1,31 @@
+# Fix PR Skill
+
+The `fix-pr` skill enables the Gemini CLI agent to autonomously and iteratively
+fix a pull request until it is mergeable and passes all quality checks.
+
+## When to use fix-pr
+
+-   **Autonomous fixing**: Move a PR from failing to green without manual
+    intervention.
+-   **Iterative loops**: Automatically handle the "fix -> push -> wait for CI"
+    cycle.
+-   **Context preservation**: Maintain context across multiple fix attempts.
+
+## Sync vs Offload
+
+This skill is designed to be versatile:
+
+-   **Synchronous mode**: Activate the skill in your current terminal for
+    quick fixes or conflict resolution.
+-   **Offloaded mode**: Use `npm run offload <PR> fix` to launch an iterative
+    fix loop on a remote workstation, keeping your local machine free.
+
+## Objective
+
+The goal is to move a PR from its current state (failing tests, merge conflicts,
+or unaddressed comments) to a "Ready to Merge" state.
+
+## Technical details
+
+The skill uses the `gh` CLI and a specialized `wait-for-ci` utility to monitor
+remote status. It is governed by the project's standard security policies.

.gemini/skills/offload/README.md

@@ -7,14 +7,39 @@ dedicated terminal window.
 
 ## Why use offload?
 
--   **Protect local resources**: Heavy build and lint suites are offloaded to a
-    beefy remote workstation.
--   **Context efficiency**: The main Gemini session remains interactive while
-    background tasks provide high-fidelity feedback.
+As a maintainer, you eventually reach the limits of how much work you can manage
+at once on a single local machine. Heavy builds, concurrent test suites, and
+multiple PRs in flight can quickly overload local resources, leading to 
+performance degradation and developer friction.
+
+While manual remote management is a common workaround, it is often cumbersome
+and context-heavy. The `offload` skill addresses these challenges by providing:
+
+-   **Elastic compute**: Offload resource-intensive build and lint suites to a
+    beefy remote workstation, keeping your local machine responsive.
+-   **Context preservation**: The main Gemini session remains interactive and
+    focused on high-level reasoning while automated tasks provide real-time
+    feedback in a separate window.
+-   **Automated orchestration**: The skill handles worktree provisioning, 
+    script synchronization, and environment isolation automatically.
 -   **True parallelism**: Infrastructure validation, CI checks, and behavioral 
     proofs run simultaneously, compressing a 15-minute process into 3 minutes.
--   **Behavioral verification**: The worker physically exercises the new code 
-    to provide empirical proof that it works.
+
+## Agentic skills: Sync or Offload
+
+The `offload` system is designed to work in synergy with specialized agentic 
+skills. These skills can be run **synchronously** in your current terminal for
+quick tasks, or **offloaded** to a remote session for complex, iterative loops.
+
+-   **`review-pr`**: Conducts high-fidelity, behavioral code reviews. It assumes 
+    the infrastructure is already validated and focuses on physical proof of 
+    functionality.
+-   **`fix-pr`**: An autonomous "Fix-to-Green" loop. It iteratively addresses 
+    CI failures, merge conflicts, and review comments until the PR is mergeable.
+
+When you run `npm run offload <PR> fix`, the orchestrator provisions the remote 
+environment and then launches a Gemini CLI session specifically powered by the
+`fix-pr` skill.
 
 ## Playbooks
 

.gemini/skills/review-pr/README.md

@@ -0,0 +1,34 @@
+# Review PR Skill
+
+The `review-pr` skill enables the Gemini CLI agent to conduct high-fidelity,
+behavioral code reviews that go beyond simple static analysis.
+
+## When to use review-pr
+
+-   **Deep verification**: Verify that a feature actually works by executing
+    it in a live environment.
+-   **Infrastructure awareness**: Leverage build and CI results to focus on
+    empirical proof of functionality.
+-   **Interactive collaboration**: Discuss findings and explore edge cases
+    with the agent in real-time.
+
+## Sync vs Offload
+
+This skill supports two primary modes:
+
+-   **Synchronous mode**: Activate the skill locally for quick, high-level
+    analysis of a peer's PR.
+-   **Offloaded mode**: Use `npm run offload <PR> review` to conduct a
+    full-scale behavioral review on a remote workstation with parallelized
+    infrastructure validation.
+
+## Objective
+
+Conduct a thorough review that involves physically proving the feature works
+through terminal scripts and command execution.
+
+## Technical details
+
+The skill assumes the infrastructure (build and CI) is already being validated
+and focuses on empirical proofs. It uses the `extract-failures.ts` utility to
+automatically identify regressions in CI logs.