fix(skills): run retired-skill cleanup on the out-of-band upgrade path

Address review on #244.

- `maybe_auto_update_after_cli_upgrade()` (the auto-refresh path hit by
  Homebrew/curl/package-manager upgraders) refreshed symlinks but never called
  `remove_retired_skills_global()`, and its version gate means it never runs
  again — so stale top-level `hotdata-search`/`-analytics`/`-geospatial` entries
  would persist permanently. Call cleanup right after `ensure_symlinks()`.
- Add a unit test for `remove_retired_skills_project` (real dir + symlink →
  both removed, `hotdata` survives).
- Give sub-skill cross-references relative paths (e.g. `../search/SKILL.md`) so a
  sub-skill loaded on demand can reach its siblings without the parent's
  name→path mapping in context.

Author: eddietejeda

skills/hotdata/subskills/analytics/SKILL.md

@@ -10,7 +10,7 @@ version: 0.21.0
 
 **Prerequisites:** Authenticate, workspace, and catalog discovery via the **`hotdata`** skill (`ingest` datasources, `tables`, `databases`).
 
-**Related skills:** **`hotdata-search`** (BM25, vector, retrieval indexes), **`hotdata-geospatial`** (spatial SQL).
+**Related sub-skills** (bundled alongside this one — `Read` on demand): **`hotdata-search`** ([`../search/SKILL.md`](../search/SKILL.md) — BM25, vector, retrieval indexes), **`hotdata-geospatial`** ([`../geospatial/SKILL.md`](../geospatial/SKILL.md) — spatial SQL).
 
 ---
 

skills/hotdata/subskills/analytics/references/WORKFLOWS.md

@@ -2,7 +2,7 @@
 
 OLAP-style SQL, **History** (query runs and stored results), and **Chain** (materialized follow-ups). Requires **`hotdata`** for auth, workspaces, and catalog commands.
 
-**Related:** **`hotdata-search`** for BM25/vector indexes and `hotdata search`; **`hotdata`** [WORKFLOWS.md](../../../references/WORKFLOWS.md) for managed databases.
+**Related:** **`hotdata-search`** ([`../../search/SKILL.md`](../../search/SKILL.md)) for BM25/vector indexes and `hotdata search`; **`hotdata`** [WORKFLOWS.md](../../../references/WORKFLOWS.md) for managed databases.
 
 ---
 

skills/hotdata/subskills/geospatial/SKILL.md

@@ -8,7 +8,7 @@ version: 0.21.0
 
 Hotdata supports a subset of PostGIS-style functions in **PostgreSQL-dialect SQL**. This skill is data-agnostic — apply it to any table with geometry columns.
 
-**Requires the core `hotdata` skill** for auth, workspace, and table discovery. **Related:** **`hotdata-analytics`** (OLAP SQL), **`hotdata-search`** (BM25/vector).
+**Requires the core `hotdata` skill** for auth, workspace, and table discovery. **Related sub-skills** (bundled alongside this one — `Read` on demand): **`hotdata-analytics`** ([`../analytics/SKILL.md`](../analytics/SKILL.md) — OLAP SQL), **`hotdata-search`** ([`../search/SKILL.md`](../search/SKILL.md) — BM25/vector).
 
 ## Running these queries
 

skills/hotdata/subskills/search/SKILL.md

@@ -10,7 +10,7 @@ Retrieval workloads in Hotdata: **BM25 full-text**, **vector similarity**, and t
 
 **Prerequisites:** Authenticate, set a workspace, and set an active database (`hotdata databases set <id>`) — see the **`hotdata`** skill. Use fully qualified table names: `<catalog>.<schema>.<table>`.
 
-**Related skills:** **`hotdata-analytics`** (OLAP SQL, query history, materialized chains), **`hotdata-geospatial`** (PostGIS-style functions).
+**Related sub-skills** (bundled alongside this one — `Read` on demand): **`hotdata-analytics`** ([`../analytics/SKILL.md`](../analytics/SKILL.md) — OLAP SQL, query history, materialized chains), **`hotdata-geospatial`** ([`../geospatial/SKILL.md`](../geospatial/SKILL.md) — PostGIS-style functions).
 
 ---
 
@@ -62,8 +62,8 @@ hotdata indexes create --catalog <alias> --schema <schema> --table <table> \
 hotdata indexes delete --catalog <alias> --schema <schema> --table <table> --name <name>
 ```
 
-- **`--type` is required** on create: `bm25` (one or more text columns, comma-separated in `--column`) or `vector` (exactly one column; often embeddings or auto-embedded text). (`sorted` is also a valid `--type`, covered in **`hotdata-analytics`**.)
-- **`sorted`** indexes (range/equality for OLAP filters) are documented in **`hotdata-analytics`** — this skill focuses on retrieval types.
+- **`--type` is required** on create: `bm25` (one or more text columns, comma-separated in `--column`) or `vector` (exactly one column; often embeddings or auto-embedded text). (`sorted` is also a valid `--type`, covered in **`hotdata-analytics`** — [`../analytics/SKILL.md`](../analytics/SKILL.md).)
+- **`sorted`** indexes (range/equality for OLAP filters) are documented in **`hotdata-analytics`** ([`../analytics/SKILL.md`](../analytics/SKILL.md)) — this skill focuses on retrieval types.
 - **`--async`:** poll with `hotdata jobs <job_id>` (see **`hotdata`** skill **Jobs**).
 - **Auto-embedding:** `--type vector` on a **text** column generates embeddings server-side. Optional `--embedding-provider-id`; default output column `{column}_embedding` (override with `--output-column`).
 

src/commands/skill.rs

@@ -168,6 +168,7 @@ pub fn maybe_auto_update_after_cli_upgrade() {
     }
 
     let _symlinks = ensure_symlinks();
+    remove_retired_skills_global();
 
     let still_needed = match read_installed_version() {
         Some(v) if v >= current && all_skill_stores_present() => false,
@@ -719,4 +720,42 @@ mod tests {
             Some(Version::parse("0.1.14").unwrap())
         );
     }
+
+    #[test]
+    fn remove_retired_skills_project_clears_stale_top_level_dirs() {
+        let tmp = tempfile::tempdir().unwrap();
+        let cwd = tmp.path();
+        let project_skills_root = cwd.join(".agents").join("skills");
+
+        // A retired skill present as a real dir in the `.agents` layer and as a
+        // symlink in the `.claude` root (exercises both branches of
+        // `remove_skill_path`), plus the surviving `hotdata` skill.
+        let agents_retired = project_skills_root.join("hotdata-search");
+        fs::create_dir_all(&agents_retired).unwrap();
+        let agents_hotdata = project_skills_root.join("hotdata");
+        fs::create_dir_all(&agents_hotdata).unwrap();
+
+        let claude_skills = cwd.join(".claude").join("skills");
+        fs::create_dir_all(&claude_skills).unwrap();
+        let claude_retired = claude_skills.join("hotdata-search");
+        #[cfg(unix)]
+        std::os::unix::fs::symlink(&agents_retired, &claude_retired).unwrap();
+        #[cfg(not(unix))]
+        fs::create_dir_all(&claude_retired).unwrap();
+
+        remove_retired_skills_project(cwd, &project_skills_root);
+
+        assert!(
+            !agents_retired.exists(),
+            "retired skill in .agents should be removed"
+        );
+        assert!(
+            claude_retired.symlink_metadata().is_err(),
+            "retired skill symlink in .claude should be removed"
+        );
+        assert!(
+            agents_hotdata.exists(),
+            "the surviving hotdata skill must be left in place"
+        );
+    }
 }