skill-concierge catalogs

Register external catalog roots — local directories of third-party skills (each
child dir carrying a SKILL.md, e.g. a cloned awesome-skills repo) that get indexed
for semantic retrieval without being installed: they never appear in Claude Code's
per-turn context and never enter the per-turn offer preview (search-only tier). Their
skills index as <alias>:<dirname> and surface only via search_skills, marked
[external: <alias>].

Consumption: an external skill cannot be invoked by the Skill tool. USING: one
means pulling its body with get_skill("<alias>:<name>") and following that SKILL.md
inline. For a proven keeper, promote symlinks it into ~/.claude/skills/ and it
becomes a normal installed skill (with the normal per-turn context cost).

Steps

1. View configured catalogs (paths, skill counts, broken promotions):

   python3 "$CLAUDE_PLUGIN_ROOT/scripts/catalogs.py" list

2. Register a catalog root (alias must be [a-z0-9][a-z0-9_-]*; optional
   include/exclude globs match skill DIRECTORY names):

   python3 "$CLAUDE_PLUGIN_ROOT/scripts/catalogs.py" add <alias> <path> \
       [--include 'glob' ...] [--exclude 'glob' ...]

3. Remove a catalog — its catalog:<alias> points prune at the next reindex:

   python3 "$CLAUDE_PLUGIN_ROOT/scripts/catalogs.py" remove <alias>

4. Promote a proven external skill into ~/.claude/skills/ (symlink, bare name;
   refuses on name collision):

   python3 "$CLAUDE_PLUGIN_ROOT/scripts/catalogs.py" promote <alias>:<skill>

5. Land the index change now (otherwise the session-start auto-reindex catches it):
   call the reindex() MCP tool, or report to the user that the next session start
   will pick it up.

Notes

• Config lives at ~/.claude/skill-concierge/catalog-roots.json (operator-owned
  durable home; survives plugin updates; env seam SKILL_CONCIERGE_CATALOG_ROOTS).
  Absent file = feature off, byte-identical behavior.
• External skills get embeddings + body-derived triggers only; the flywheel utterance
  layer deliberately skips them (deferred phase, ADR-0031).
• Telemetry: get_skill pulls are ledgered; analyze.py reports external takes
  (epoch-scoped — window from the catalog's registration date).
• First registered catalog on this machine: antigravity →
  /Users/thinhkhuat/env-DEV/antigravity-awesome-skills/skills (2026-08-23).