mosaic skill management CLI — register/unregister + symlink-bridge auto-sync on install/upgrade #824

New Issue

jason.woltje · 2026-07-17T21:52:01Z

jason.woltje commented

2026-07-17 21:52:01 +00:00

Summary

Mosaic skills live in ~/.config/mosaic/skills/<name>/SKILL.md, but Claude Code only scans ~/.claude/skills/. The bridge between them is a set of per-skill symlinks (~/.claude/skills/<name> -> ~/.config/mosaic/skills/<name>) created once at mosaic setup (marker .backup-before-mosaic-symlinks-20260506).

Any skill authored after that one-time setup has no symlink, so it is invisible to Claude: Skill() returns "Unknown skill" and /reload-skills cannot fix it (there is nothing to point to). This was verified live: the new mosaic-context-refresh skill was invisible until a symlink was hand-created — a manual workaround, not a fix.

Root cause

Skill registration (the ~/.claude/skills/ symlink bridge) happens only at initial setup. There is no mechanism to (a) register a newly-added skill or (b) re-sync the bridge on framework upgrade. New framework skills therefore ship invisible.

Ask — a system-wide skill-management mechanism

mosaic skill register <name> — create the ~/.claude/skills/<name> symlink (idempotent).
mosaic skill unregister <name> — remove it (idempotent).
mosaic skill list — show registered skills + flag dangling/broken symlinks.
On skill install / framework upgrade sync: auto-create symlinks for ALL ~/.config/mosaic/skills/* so a newly-added framework skill is never invisible. This auto-sync closes the bug class.

Scope notes

M1 = Claude Code (the ~/.claude/skills/ bridge).
Pi / Codex parity: scope note only — determine whether those runtimes need an equivalent bridge; do not implement in M1.
Framework-native: implement in packages/mosaic (the ~/.config/mosaic tree is wiped on upgrade — the durable home is the monorepo source). Reviewed PR, author != reviewer.

Hard dependency / coupling

This is a hard dependency for the durable landing of the mosaic-context-refresh skill (a prioritized deliverable). When that skill lands in packages/mosaic, the install/upgrade sync MUST create its symlink or it ships invisible. Sequence this bridge/CLI fix to land with or before the skill PR.

Acceptance criteria

mosaic skill register/unregister/list implemented, idempotent, with tests.
Install + upgrade path auto-syncs symlinks for every ~/.config/mosaic/skills/* (new skills auto-registered).
list surfaces broken/dangling symlinks.
Verified: a skill added after initial setup becomes visible to Skill() without manual symlinking.
Pi/Codex parity captured as a scope note (M1 = Claude).

Filed per coordinator (Mos) relay of Jason's #mos 21:50Z request. Queued behind the active ≤2-lane goal cap — tracking only, not yet dispatched.

## Summary Mosaic skills live in `~/.config/mosaic/skills/<name>/SKILL.md`, but Claude Code only scans `~/.claude/skills/`. The bridge between them is a set of per-skill **symlinks** (`~/.claude/skills/<name> -> ~/.config/mosaic/skills/<name>`) created **once** at mosaic setup (marker `.backup-before-mosaic-symlinks-20260506`). Any skill authored **after** that one-time setup has **no symlink**, so it is invisible to Claude: `Skill()` returns "Unknown skill" and `/reload-skills` cannot fix it (there is nothing to point to). This was verified live: the new `mosaic-context-refresh` skill was invisible until a symlink was hand-created — a manual workaround, not a fix. ## Root cause Skill registration (the `~/.claude/skills/` symlink bridge) happens only at initial setup. There is no mechanism to (a) register a newly-added skill or (b) re-sync the bridge on framework upgrade. New framework skills therefore ship invisible. ## Ask — a system-wide skill-management mechanism - `mosaic skill register <name>` — create the `~/.claude/skills/<name>` symlink (idempotent). - `mosaic skill unregister <name>` — remove it (idempotent). - `mosaic skill list` — show registered skills + flag dangling/broken symlinks. - **On skill install / framework upgrade sync:** auto-create symlinks for ALL `~/.config/mosaic/skills/*` so a newly-added framework skill is never invisible. **This auto-sync closes the bug class.** ## Scope notes - **M1 = Claude Code** (the `~/.claude/skills/` bridge). - **Pi / Codex parity:** scope note only — determine whether those runtimes need an equivalent bridge; do not implement in M1. - **Framework-native:** implement in `packages/mosaic` (the `~/.config/mosaic` tree is wiped on upgrade — the durable home is the monorepo source). Reviewed PR, author != reviewer. ## Hard dependency / coupling This is a **hard dependency** for the durable landing of the `mosaic-context-refresh` skill (a prioritized deliverable). When that skill lands in `packages/mosaic`, the install/upgrade sync MUST create its symlink or it ships invisible. Sequence this bridge/CLI fix to land **with or before** the skill PR. ## Acceptance criteria - [ ] `mosaic skill register/unregister/list` implemented, idempotent, with tests. - [ ] Install + upgrade path auto-syncs symlinks for every `~/.config/mosaic/skills/*` (new skills auto-registered). - [ ] `list` surfaces broken/dangling symlinks. - [ ] Verified: a skill added after initial setup becomes visible to `Skill()` without manual symlinking. - [ ] Pi/Codex parity captured as a scope note (M1 = Claude). _Filed per coordinator (Mos) relay of Jason's #mos 21:50Z request. Queued behind the active ≤2-lane goal cap — tracking only, not yet dispatched._

jason.woltje added the fleet-enhancement label 2026-07-17 21:52:01 +00:00

jason.woltje referenced this issue from a commit

2026-07-17 23:02:22 +00:00

test(#824): define secure skill bridge behavior

jason.woltje referenced this issue from a commit

2026-07-17 23:02:22 +00:00

feat(#824): manage Claude skill registrations

jason.woltje referenced this issue from a commit

2026-07-17 23:02:22 +00:00

feat(#824): protect installer skill links

jason.woltje referenced a pull request that will close this issue

2026-07-17 23:02:29 +00:00