fix(antigravity): Add overload recovery flow

Add a Unix activation script, Antigravity-specific installer guidance, and cross-platform recovery documentation so users can reduce the live skill set when truncation or context overload appears. Regenerate the canonical bundle/catalog artifacts after merging the stale goldrush-api removal so main stays release-ready. Refs #381
2026-03-22 19:19:30 +01:00
parent 7d031f6d3f
commit 5d795cdf84
16 changed files with 399 additions and 59 deletions
--- a/CATALOG.md
+++ b/CATALOG.md
@@ -316,7 +316,6 @@ Total skills: 1307
 | `gdb-cli` | GDB debugging assistant for AI agents - analyze core dumps, debug live processes, investigate crashes and deadlocks with source code correlation | debugging, gdb, core-dump, crash-analysis, c++, c | debugging, gdb, core-dump, crash-analysis, c++, c, cli, assistant, ai, agents, analyze, core |
 | `gemini-api-dev` | The Gemini API provides access to Google's most advanced AI models. Key capabilities include: | gemini, api, dev | gemini, api, dev, provides, access, google, most, ai, models, key, capabilities, include |
 | `geo-fundamentals` | Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity). | geo, fundamentals | geo, fundamentals, generative, engine, optimization, ai, search, engines, chatgpt, claude, perplexity |
-| `goldrush-api` | Query blockchain data across 100+ chains: wallet balances, token prices, transactions, DEX pairs, and real-time OHLCV streams via the GoldRush API by Covalent. | blockchain, crypto, web3, api, defi, wallet, multi-chain | blockchain, crypto, web3, api, defi, wallet, multi-chain, goldrush, query, data, 100, chains |
 | `google-analytics-automation` | Automate Google Analytics tasks via Rube MCP (Composio): run reports, list accounts/properties, funnels, pivots, key events. Always search tools first for cu... | google, analytics | google, analytics, automation, automate, tasks, via, rube, mcp, composio, run, reports, list |
 | `googlesheets-automation` | Automate Google Sheets operations (read, write, format, filter, manage spreadsheets) via Rube MCP (Composio). Read/write data, manage tabs, apply formatting,... | googlesheets | googlesheets, automation, automate, google, sheets, operations, read, write, format, filter, spreadsheets, via |
 | `hosted-agents-v2-py` | Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. Use when creating container-based agents in Azure AI Foundry. | hosted, agents, v2, py | hosted, agents, v2, py, azure, ai, sdk, imagebasedhostedagentdefinition, creating, container, foundry |
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [8.6.0] - 2026-03-22 - "Targeted Activation and Catalog Cleanup"
+
+> Installable skill library update for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and related AI coding assistants.
+
+Start here:
+
+- Install: `npx antigravity-awesome-skills`
+- Choose your tool: [README -> Choose Your Tool](https://github.com/sickn33/antigravity-awesome-skills#choose-your-tool)
+- Best skills by tool: [README -> Best Skills By Tool](https://github.com/sickn33/antigravity-awesome-skills#best-skills-by-tool)
+- Bundles: [docs/users/bundles.md](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/users/bundles.md)
+- Workflows: [docs/users/workflows.md](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/users/workflows.md)
+
+This release packages the maintainer sweep after `v8.5.0`: the new `gdb-cli` community skill, removal of the stale in-repo `goldrush-api` copy, and a cross-platform recovery path for Antigravity users who hit truncation or context overload with too many active skills.
+
+## New Skills
+
+- **gdb-cli** - AI-assisted GDB debugging for core dumps, live process attach, crash triage, and deadlock analysis with source correlation (PR #375, closes #374)
+
+## Improvements
+
+- **Antigravity overload recovery**: Added `scripts/activate-skills.sh`, a matching installer hint, and new cross-platform user docs so Linux/macOS users can archive the full library and activate only the bundles or skill ids they need in the live Antigravity directory (issue #381).
+- **Windows/Linux/macOS troubleshooting**: Expanded the recovery guidance with a shared overload guide plus clearer README, FAQ, and getting-started links for truncation and context-limit failures.
+- **Registry cleanup**: Removed the stale in-repo `goldrush-api` mirror, regenerated bundle/catalog artifacts, and refreshed tracked web assets so canonical references no longer point at deleted content (PR #379).
+- **Maintainer sync**: Refreshed `README.md`, `CATALOG.md`, `skills_index.json`, `data/catalog.json`, `data/bundles.json`, contributors, and sitemap output after the PR merge batch so `main` stays release-ready.
+
+## Who should care
+
+- **Antigravity users** get a new activation flow for large repositories and a clearer recovery path when too many active skills trigger truncation-style failures.
+- **Claude Code and Cursor users** benefit from the new `gdb-cli` skill for C/C++ debugging and the cleaned-up catalog/docs surfaces.
+- **Codex CLI users** benefit from the same new debugging skill plus maintainer-driven registry cleanup that keeps generated artifacts and references aligned.
+- **Gemini CLI users** benefit from the updated troubleshooting docs and the removal of stale catalog references in shared bundle metadata.
+
+## Credits
+
+- **[@Cerdore](https://github.com/Cerdore)** for the new `gdb-cli` skill in PR #375
+- **[@JayeHarrill](https://github.com/JayeHarrill)** for removing the stale `goldrush-api` copy in PR #379
+
+Upgrade now: `git pull origin main` to fetch the latest skills.
+
 ## [8.5.0] - 2026-03-21 - "Installer Safety and Maintainer Automation"

 > Installable skill library update for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and related AI coding assistants.
--- a/README.md
+++ b/README.md
@@ -276,7 +276,7 @@ They help you avoid picking through the full catalog one by one.

 - ❌ Separate installations or downloads
 - ❌ Different git commands
- ❌ Something you need to "activate"
+- ❌ Something most users need to activate during normal install

 ### How to use bundles:

@@ -285,6 +285,8 @@ They help you avoid picking through the full catalog one by one.
 3. **Pick 3-5 skills** from that bundle to start using in your prompts
 4. **Reference them in your conversations** with your AI (e.g., "Use @brainstorming...")

+If Antigravity starts hitting context limits with too many active skills, the optional activation scripts in [`docs/users/agent-overload-recovery.md`](docs/users/agent-overload-recovery.md) can materialize only the bundles or skill ids you want in the live Antigravity directory.
+
 For detailed examples of how to actually use skills, see the [**Usage Guide**](docs/users/usage.md).

 ### Examples:
@@ -382,9 +384,15 @@ That guide includes:
 - the storage folders that usually need to be cleared
 - an optional batch helper adapted from [issue #274](https://github.com/sickn33/antigravity-awesome-skills/issues/274)

+### Linux and macOS agent overload
+
+If Antigravity becomes unstable only when too many skills are active at once, use the cross-platform overload guide:
+
+- [`docs/users/agent-overload-recovery.md`](docs/users/agent-overload-recovery.md)
+
 ### Fixing agent overload (activation scripts)

-If your agent is struggling with context window limits due to too many loaded skills, use the activation script. It keeps the full library in a separate archive folder and only activates the bundles or skills you need into the live Antigravity skills directory.
+If your agent is struggling with context window limits due to too many loaded skills, use the activation scripts. They keep the full library in a separate archive folder and only activate the bundles or skills you need into the live Antigravity skills directory.

 **Important Usage Instructions:**

@@ -392,6 +400,19 @@ If your agent is struggling with context window limits due to too many loaded sk
 2. Open a terminal inside the folder where you cloned this repository (NOTE: repository has to be cloned).
 3. Run the script located in the `scripts` folder.

+macOS/Linux examples:
+
+```bash
+# Activate specific bundles
+./scripts/activate-skills.sh "Web Wizard" "Integration & APIs"
+
+# Activate literal skill ids
+./scripts/activate-skills.sh brainstorming systematic-debugging
+
+# Clear and reset (archives the live directory first)
+./scripts/activate-skills.sh --clear
+```
+
 Windows examples:

 ```bat
--- a/apps/web-app/public/skills.json.backup
+++ b/apps/web-app/public/skills.json.backup
@@ -6179,16 +6179,6 @@
    "source": "community",
    "date_added": "2026-02-27"
  },
-  {
-    "id": "goldrush-api",
-    "path": "skills/goldrush-api",
-    "category": "blockchain",
-    "name": "goldrush-api",
-    "description": "Query blockchain data across 100+ chains: wallet balances, token prices, transactions, DEX pairs, and real-time OHLCV streams via the GoldRush API by Covalent.",
-    "risk": "safe",
-    "source": "community",
-    "date_added": "2026-03-17"
-  },
  {
    "id": "google-analytics-automation",
    "path": "skills/google-analytics-automation",
--- a/data/bundles.json
+++ b/data/bundles.json
@@ -177,7 +177,6 @@
        "go-playwright",
        "go-rod-master",
        "golang-pro",
-        "goldrush-api",
        "grpc-golang",
        "hono",
        "hugging-face-dataset-viewer",
@@ -559,7 +558,6 @@
        "frontend-dev-guidelines",
        "frontend-ui-dark-ts",
        "gdpr-data-handling",
-        "goldrush-api",
        "google-analytics-automation",
        "googlesheets-automation",
        "hugging-face-datasets",
--- a/data/catalog.json
+++ b/data/catalog.json
@@ -15221,36 +15221,6 @@
      ],
      "path": "skills/golang-pro/SKILL.md"
    },
-    {
-      "id": "goldrush-api",
-      "name": "goldrush-api",
-      "description": "Query blockchain data across 100+ chains: wallet balances, token prices, transactions, DEX pairs, and real-time OHLCV streams via the GoldRush API by Covalent.",
-      "category": "data-ai",
-      "tags": [
-        "blockchain",
-        "crypto",
-        "web3",
-        "api",
-        "defi",
-        "wallet",
-        "multi-chain"
-      ],
-      "triggers": [
-        "blockchain",
-        "crypto",
-        "web3",
-        "api",
-        "defi",
-        "wallet",
-        "multi-chain",
-        "goldrush",
-        "query",
-        "data",
-        "100",
-        "chains"
-      ],
-      "path": "skills/goldrush-api/SKILL.md"
-    },
    {
      "id": "google-analytics-automation",
      "name": "google-analytics-automation",
--- a/docs/users/agent-overload-recovery.md
+++ b/docs/users/agent-overload-recovery.md
@@ -0,0 +1,54 @@
+# Antigravity Recovery for Context Overload and Truncation
+
+Use this guide when Antigravity loads too many skills for the current task and starts failing with truncation, context, or trajectory-conversion errors.
+
+Typical symptoms:
+
+- the agent crashes only when a large skills folder is present
+- the error mentions truncation, context conversion, or a trajectory/message that cannot be converted
+- the problem shows up more often on large repositories or long-running tasks
+
+## Linux and macOS fast path
+
+Use the activation scripts to keep the full library archived while exposing only the bundles or skills you need in the live Antigravity directory.
+
+1. Fully close Antigravity.
+2. Clone this repository somewhere local if you do not already have a clone.
+3. Run the activation script from the cloned repository.
+
+Examples:
+
+```bash
+./scripts/activate-skills.sh "Web Wizard" "Integration & APIs"
+./scripts/activate-skills.sh --clear
+./scripts/activate-skills.sh brainstorming systematic-debugging
+```
+
+What the script does:
+
+- syncs the repository `skills/` tree into `~/.gemini/antigravity/skills_library`
+- preserves your full library in the backing store
+- activates only the requested bundles or skill ids into `~/.gemini/antigravity/skills`
+- `--clear` archives the current live directory first, then restores the selected set
+
+Optional environment overrides:
+
+```bash
+AG_BASE_DIR=/custom/antigravity ./scripts/activate-skills.sh --clear Essentials
+AG_REPO_SKILLS_DIR=/path/to/repo/skills ./scripts/activate-skills.sh brainstorming
+```
+
+## Windows recovery
+
+If Antigravity is stuck in a restart loop on Windows, use the Windows-specific recovery guide instead:
+
+- [windows-truncation-recovery.md](windows-truncation-recovery.md)
+
+That guide covers the browser/app storage cleanup needed when the host keeps reopening the same broken session.
+
+## Prevention tips
+
+- start with 3-5 skills from a bundle instead of exposing the full library at once
+- use bundle activation before opening very large repositories
+- keep role-specific stacks active and archive the rest
+- if a host stores broken session state, clear that host state before restoring a smaller active set
--- a/docs/users/faq.md
+++ b/docs/users/faq.md
@@ -154,6 +154,14 @@ It includes:
 - the default Antigravity Windows paths to back up first
 - an optional batch script adapted from [issue #274](https://github.com/sickn33/antigravity-awesome-skills/issues/274)

+### I hit context overload on Linux or macOS. What should I do?
+
+If Antigravity becomes unstable only when the full skills library is active, switch to the activation flow instead of exposing every skill at once:
+
+- [agent-overload-recovery.md](agent-overload-recovery.md)
+
+That guide shows how to run `scripts/activate-skills.sh` from a cloned copy of this repository so only the bundles or skill ids you need stay active in `~/.gemini/antigravity/skills`.
+
 ### How do I update skills?

 Navigate to your skills directory and pull the latest changes:
--- a/docs/users/getting-started.md
+++ b/docs/users/getting-started.md
@@ -142,6 +142,9 @@ A: Yes! Use the **@skill-creator** skill to build your own.
 **Q: What if Antigravity on Windows gets stuck in a truncation crash loop?**
 A: Follow the recovery steps in [windows-truncation-recovery.md](windows-truncation-recovery.md). It explains which Antigravity storage folders to back up and clear, and includes an optional batch helper adapted from [issue #274](https://github.com/sickn33/antigravity-awesome-skills/issues/274).

+**Q: What if Antigravity overloads on Linux or macOS when too many skills are active?**
+A: Use the activation flow in [agent-overload-recovery.md](agent-overload-recovery.md). It shows how to run `scripts/activate-skills.sh` from a cloned repo so you can keep the full library archived and activate only the bundles or skills you need in the live Antigravity directory.
+
 **Q: Is this free?**
 A: Yes. Original code and tooling are MIT-licensed, and original documentation/non-code written content is CC BY 4.0. See [../../LICENSE](../../LICENSE) and [../../LICENSE-CONTENT](../../LICENSE-CONTENT).

--- a/docs/users/usage.md
+++ b/docs/users/usage.md
@@ -40,7 +40,7 @@ Bundles are **recommended lists** of skills grouped by role. They help you decid

 ❌ Separate installations  
 ❌ Different download commands  
-❌ Something you need to "activate"
+❌ Something most users need to activate during normal install

 ### Example: The "Web Wizard" Bundle

--- a/scripts/activate-skills.sh
+++ b/scripts/activate-skills.sh
@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_BASE_DIR="${HOME:-$PWD}/.gemini/antigravity"
+BASE_DIR="${AG_BASE_DIR:-$DEFAULT_BASE_DIR}"
+SKILLS_DIR="${AG_SKILLS_DIR:-$BASE_DIR/skills}"
+LIBRARY_DIR="${AG_LIBRARY_DIR:-$BASE_DIR/skills_library}"
+ARCHIVE_PREFIX="${AG_ARCHIVE_PREFIX:-$BASE_DIR/skills_archive}"
+REPO_SKILLS_DIR="${AG_REPO_SKILLS_DIR:-$SCRIPT_DIR/../skills}"
+BUNDLE_HELPER="${AG_BUNDLE_HELPER:-$SCRIPT_DIR/../tools/scripts/get-bundle-skills.py}"
+PYTHON_BIN="${AG_PYTHON_BIN:-}"
+SKILLS_LIST_FILE="$(mktemp "${TMPDIR:-/tmp}/ag-skills.XXXXXX")"
+
+cleanup() {
+  rm -f "$SKILLS_LIST_FILE"
+}
+
+trap cleanup EXIT
+
+find_copy_dirs() {
+  local src_dir="$1"
+  local dest_dir="$2"
+
+  mkdir -p "$dest_dir"
+
+  while IFS= read -r -d '' item; do
+    cp -RP "$item" "$dest_dir/"
+  done < <(find "$src_dir" -mindepth 1 -maxdepth 1 \( -type d -o -type l \) -print0 2>/dev/null)
+}
+
+find_move_dirs() {
+  local src_dir="$1"
+  local dest_dir="$2"
+
+  mkdir -p "$dest_dir"
+
+  while IFS= read -r -d '' item; do
+    mv "$item" "$dest_dir/"
+  done < <(find "$src_dir" -mindepth 1 -maxdepth 1 ! -name '.' ! -name '..' -print0 2>/dev/null)
+}
+
+resolve_python() {
+  if [[ -n "$PYTHON_BIN" ]]; then
+    printf '%s\n' "$PYTHON_BIN"
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    command -v python3
+    return 0
+  fi
+
+  if command -v python >/dev/null 2>&1; then
+    command -v python
+    return 0
+  fi
+
+  return 1
+}
+
+is_safe_skill_id() {
+  [[ "$1" =~ ^[A-Za-z0-9._-]+$ ]]
+}
+
+echo "Activating Antigravity skills..."
+
+DO_CLEAR=0
+EXTRA_ARGS=()
+
+for arg in "$@"; do
+  if [[ "$arg" == "--clear" ]]; then
+    DO_CLEAR=1
+  else
+    EXTRA_ARGS+=("$arg")
+  fi
+done
+
+if [[ -d "$REPO_SKILLS_DIR" ]]; then
+  echo "Syncing library with repository source..."
+  find_copy_dirs "$REPO_SKILLS_DIR" "$LIBRARY_DIR"
+fi
+
+if [[ ! -d "$LIBRARY_DIR" ]]; then
+  echo "Initializing skills library from local state..."
+  mkdir -p "$LIBRARY_DIR"
+
+  if [[ -d "$SKILLS_DIR" ]]; then
+    echo "  + Moving current skills to library..."
+    find_move_dirs "$SKILLS_DIR" "$LIBRARY_DIR"
+  fi
+
+  while IFS= read -r archive_dir; do
+    [[ -n "$archive_dir" ]] || continue
+    echo "  + Merging skills from $(basename "$archive_dir")..."
+    find_copy_dirs "$archive_dir" "$LIBRARY_DIR"
+  done < <(find "$BASE_DIR" -mindepth 1 -maxdepth 1 -type d -name 'skills_archive*' | sort)
+fi
+
+if [[ "$DO_CLEAR" == "1" ]]; then
+  echo "[RESET] Archiving and clearing existing skills..."
+  if [[ -d "$SKILLS_DIR" ]]; then
+    archive_dir="${ARCHIVE_PREFIX}_$(date +%Y%m%d_%H%M%S)"
+    mkdir -p "$archive_dir"
+    find_move_dirs "$SKILLS_DIR" "$archive_dir"
+  fi
+else
+  echo "[APPEND] Layering new skills onto existing folder..."
+fi
+
+mkdir -p "$SKILLS_DIR"
+
+echo "Expanding bundles..."
+
+python_path=""
+if python_path="$(resolve_python 2>/dev/null)" && [[ -f "$BUNDLE_HELPER" ]]; then
+  if [[ "${#EXTRA_ARGS[@]}" -gt 0 ]]; then
+    "$python_path" "$BUNDLE_HELPER" "${EXTRA_ARGS[@]}" >"$SKILLS_LIST_FILE" 2>/dev/null || true
+  else
+    "$python_path" "$BUNDLE_HELPER" Essentials >"$SKILLS_LIST_FILE" 2>/dev/null || true
+  fi
+fi
+
+if [[ ! -s "$SKILLS_LIST_FILE" ]]; then
+  if [[ "${#EXTRA_ARGS[@]}" -eq 0 ]]; then
+    printf '%s\n' brainstorming systematic-debugging test-driven-development >"$SKILLS_LIST_FILE"
+  else
+    : >"$SKILLS_LIST_FILE"
+    for arg in "${EXTRA_ARGS[@]}"; do
+      if is_safe_skill_id "$arg"; then
+        printf '%s\n' "$arg" >>"$SKILLS_LIST_FILE"
+      fi
+    done
+  fi
+fi
+
+echo "Restoring selected skills..."
+while IFS= read -r skill_id || [[ -n "$skill_id" ]]; do
+  [[ -n "$skill_id" ]] || continue
+
+  if [[ -e "$SKILLS_DIR/$skill_id" ]]; then
+    echo "  . $skill_id (already active)"
+  elif [[ -e "$LIBRARY_DIR/$skill_id" ]]; then
+    echo "  + $skill_id"
+    cp -RP "$LIBRARY_DIR/$skill_id" "$SKILLS_DIR/"
+  else
+    echo "  - $skill_id (not found in library)"
+  fi
+done <"$SKILLS_LIST_FILE"
+
+echo
+echo "Done! Antigravity skills are now activated."
--- a/skills_index.json
+++ b/skills_index.json
@@ -6179,16 +6179,6 @@
    "source": "community",
    "date_added": "2026-02-27"
  },
-  {
-    "id": "goldrush-api",
-    "path": "skills/goldrush-api",
-    "category": "blockchain",
-    "name": "goldrush-api",
-    "description": "Query blockchain data across 100+ chains: wallet balances, token prices, transactions, DEX pairs, and real-time OHLCV streams via the GoldRush API by Covalent.",
-    "risk": "safe",
-    "source": "community",
-    "date_added": "2026-03-17"
-  },
  {
    "id": "google-analytics-automation",
    "path": "skills/google-analytics-automation",
--- a/tools/bin/install.js
+++ b/tools/bin/install.js
@@ -236,6 +236,23 @@ function installForTarget(tempDir, target) {
  console.log(`  ✓ Installed to ${target.path}`);
 }

+function getPostInstallMessages(targets) {
+  const messages = [
+    "Pick a bundle in docs/users/bundles.md and use @skill-name in your AI assistant.",
+  ];
+
+  if (targets.some((target) => target.name === "Antigravity")) {
+    messages.push(
+      "If Antigravity hits context/truncation limits, see docs/users/agent-overload-recovery.md",
+    );
+    messages.push(
+      "For clone-based installs, use scripts/activate-skills.sh or scripts/activate-skills.bat",
+    );
+  }
+
+  return messages;
+}
+
 function main() {
  const opts = parseArgs();
  const { tagArg, versionArg } = opts;
@@ -280,9 +297,9 @@ function main() {
      installForTarget(tempDir, target);
    }

-    console.log(
-      "\nPick a bundle in docs/users/bundles.md and use @skill-name in your AI assistant.",
-    );
+    for (const message of getPostInstallMessages(targets)) {
+      console.log(`\n${message}`);
+    }
  } finally {
    try {
      if (fs.existsSync(tempDir)) {
@@ -304,6 +321,7 @@ if (require.main === module) {

 module.exports = {
  copyRecursiveSync,
+  getPostInstallMessages,
  installSkillsIntoTarget,
  installForTarget,
  main,
--- a/tools/scripts/tests/activate_skills_shell.test.js
+++ b/tools/scripts/tests/activate_skills_shell.test.js
@@ -0,0 +1,64 @@
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const repoRoot = path.resolve(__dirname, "../..", "..");
+const scriptPath = path.join(repoRoot, "scripts", "activate-skills.sh");
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "activate-skills-shell-"));
+const baseDir = path.join(root, "antigravity");
+const repoSkills = path.join(root, "repo-skills");
+
+function makeSkill(skillId) {
+  const skillDir = path.join(repoSkills, skillId);
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(skillDir, "SKILL.md"),
+    `---\nname: ${skillId}\ndescription: test skill\ncategory: testing\nrisk: safe\nsource: community\ndate_added: "2026-03-22"\n---\n`,
+    "utf8",
+  );
+}
+
+try {
+  makeSkill("brainstorming");
+  makeSkill("systematic-debugging");
+  makeSkill("custom-skill");
+
+  const result = spawnSync(
+    "bash",
+    [scriptPath, "--clear", "brainstorming", "custom-skill"],
+    {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        AG_BASE_DIR: baseDir,
+        AG_REPO_SKILLS_DIR: repoSkills,
+        AG_PYTHON_BIN: "python3",
+      },
+      encoding: "utf8",
+    },
+  );
+
+  assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+  assert.ok(
+    fs.existsSync(path.join(baseDir, "skills", "brainstorming", "SKILL.md")),
+    "brainstorming should be activated into the live skills directory",
+  );
+  assert.ok(
+    fs.existsSync(path.join(baseDir, "skills", "custom-skill", "SKILL.md")),
+    "literal safe skill ids should be activated from the library",
+  );
+  assert.ok(
+    fs.existsSync(path.join(baseDir, "skills_library", "brainstorming", "SKILL.md")),
+    "repo skills should be synced into the backing library",
+  );
+  assert.match(
+    result.stdout,
+    /Done! Antigravity skills are now activated\./,
+    "script should report successful activation",
+  );
+} finally {
+  fs.rmSync(root, { recursive: true, force: true });
+}
--- a/tools/scripts/tests/installer_antigravity_guidance.test.js
+++ b/tools/scripts/tests/installer_antigravity_guidance.test.js
@@ -0,0 +1,31 @@
+const assert = require("assert");
+const path = require("path");
+
+const installer = require(path.resolve(__dirname, "..", "..", "bin", "install.js"));
+
+const antigravityMessages = installer.getPostInstallMessages([
+  { name: "Antigravity", path: "/tmp/.gemini/antigravity/skills" },
+]);
+
+assert.ok(
+  antigravityMessages.some((message) => message.includes("agent-overload-recovery.md")),
+  "Antigravity installs should point users to the overload recovery guide",
+);
+assert.ok(
+  antigravityMessages.some((message) => message.includes("activate-skills.sh")),
+  "Antigravity installs should mention the Unix activation flow",
+);
+assert.ok(
+  antigravityMessages.some((message) => message.includes("activate-skills.bat")),
+  "Antigravity installs should mention the Windows activation flow",
+);
+
+const codexMessages = installer.getPostInstallMessages([
+  { name: "Codex CLI", path: "/tmp/.codex/skills" },
+]);
+
+assert.strictEqual(
+  codexMessages.some((message) => message.includes("agent-overload-recovery.md")),
+  false,
+  "Non-Antigravity installs should not emit the Antigravity-specific overload hint",
+);
--- a/tools/scripts/tests/run-test-suite.js
+++ b/tools/scripts/tests/run-test-suite.js
@@ -8,10 +8,12 @@ const ENABLED_VALUES = new Set(["1", "true", "yes", "on"]);
 const TOOL_SCRIPTS = path.join("tools", "scripts");
 const TOOL_TESTS = path.join(TOOL_SCRIPTS, "tests");
 const LOCAL_TEST_COMMANDS = [
+    [path.join(TOOL_TESTS, "activate_skills_shell.test.js")],
    [path.join(TOOL_TESTS, "activate_skills_batch_security.test.js")],
    [path.join(TOOL_TESTS, "automation_workflows.test.js")],
    [path.join(TOOL_TESTS, "build_catalog_bundles.test.js")],
    [path.join(TOOL_TESTS, "claude_plugin_marketplace.test.js")],
+    [path.join(TOOL_TESTS, "installer_antigravity_guidance.test.js")],
    [path.join(TOOL_TESTS, "jetski_gemini_loader.test.cjs")],
    [path.join(TOOL_TESTS, "npm_package_contents.test.js")],
    [path.join(TOOL_TESTS, "setup_web_sync.test.js")],