skill-concierge

skill-concierge

A skill-governance layer over Claude Code's default skill mechanism. Where the default dumps every skill description into context every turn and hopes the model picks one, skill-concierge replaces hope with retrieve-precisely + enforce-use + measure.

Metaphor: skill-search is the library; skill-concierge is the concierge who knows which book fits, makes sure you actually open one, and remembers what you reached for.

Table of contents

• Why this exists
• Three organs
• Critical design facts
• Prerequisites
• Install & setup
• Usage
• Configuration
• Architecture
• Status & roadmap
• Troubleshooting
• Contributing
• Credits & attribution
• License

Why this exists

Claude Code's default skill discovery injects every installed skill's description into the context window on every turn, then trusts the model to notice the right one. As a catalogue grows past a few dozen skills, that approach burns context and quietly degrades: the model skims, misses the fitting skill, or "wings it" instead of invoking one at all.

skill-concierge addresses three distinct failure modes the default conflates:

• Wrong skill chosen → precise semantic retrieval (which skill).
• No skill chosen → a per-turn use-mandate hook (whether a skill is used at all).
• No feedback loop → a compounding invocation ledger (what actually got used), so the always-on policy is curated from data, not vibes.

Three organs

Organ	Question it answers	Mechanism
Retrieve	Which skill fits this task?	semantic search over the skill catalogue (Qdrant + multilingual embeddings), including a MAX-pool trigger layer mined from both each skill's description and its body's labeled decision sections (## When to Use, Triggers:, Use when:) — ADR-0012, ADR-0016
Enforce	Whether the model uses a skill at all (vs winging it)	a per-turn hook that hands over the right candidates under a use-mandate; on its two previously-silent verdicts (score-floor miss, conversational turn) it now injects a SKILL-CHECK: authorization instead of nothing — ADR-0015
Ledger	What actually got used	a compounding, append-only skill-invocation log → data-backed always-on curation

⚠ Critical design facts (read before judging the engine)

• The index holds model-invocable SKILL.md skills ONLY. Built-in / user-only slash-commands (loop, schedule, verify, run, code-review, update-config, keybindings-help) are excluded by design — they aren't SKILL.md files, cost no model context, and the model can't fire them. → ADR-0001.
• The vendored eval is NOT a quality bar here. vendor/skill-search/eval/ is calibrated to the upstream author's environment; its recall@k measures a skill universe this deployment excludes. A near-zero score means wrong universe, not weak retriever. → caveats §1.
• Plugin skills are namespaced in the index (ck:worktree, not worktree). → caveats §5.
• Full landmine list: docs/caveats.md. Decisions + rationale: docs/adr/.

Prerequisites

Requirement	Version / notes
Claude Code	host for the plugin, hooks, and MCP server
Python	3.10–3.12 (set SKILL_PYTHON to pin a specific interpreter)
Docker / OrbStack	runs the Qdrant vector store (server tier)

The embedding model (paraphrase-multilingual-mpnet-base-v2, 768-dim) downloads on first index build via fastembed — no API key, fully local. For a service-free embedded tier, see the ponytail: note at the top of setup.sh.

Install & setup

skill-concierge is developed local-first in a workbench and published as a Claude Code plugin at https://github.com/thinhkhuat/skill-concierge.