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. Their skills index as <alias>:<dirname>, surface via search_skills marked [external: <alias>], and on a strong match join the per-turn offer as a separate external annex that never displaces an installed row (ADR-0032; ENFORCER_EXTERNAL_ANNEX=0 makes them search-only).

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 and flywheel utterances: the session-start flywheel run covers each configured catalog after the installed skills, and flywheel.py --generate --catalog <alias> runs one by hand (ADR-0043).
• Telemetry: get_skill pulls are ledgered; analyze.py reports external takes (epoch-scoped — window from the catalog's registration date).