skill-embedder

A Claude Code plugin that creates semantic embeddings for skills, enabling accurate skill matching per prompt.

Claude Code's built-in skill activation is unreliable. This plugin embeds skill descriptions into vectors and uses hybrid search (cosine similarity + fuzzy matching + name boosting) to surface relevant skills on every prompt.

Installation

Add as a Claude Code marketplace:

claude mcp add-marketplace /path/to/skill-embedder

Or install the library via npm for programmatic use:

npm install @samdotci/skill-embedder

How It Works

1. On session start, the plugin re-embeds any skills whose content has changed (hash-based cache invalidation)
2. On every prompt, the plugin searches embedded skills and surfaces matches above 30% confidence as additionalContext
3. Skills are discovered from directories configured in ~/.config/skill-embedder/skill-embedder.json

Embedding Providers

• HuggingFace (default): Uses jinaai/jina-embeddings-v2-small-en locally. No API key needed. Downloads ~25MB model on first run.
• OpenAI: Set OPENAI_API_KEY and SKILL_EMBEDDER_EMBEDDING_PROVIDER=openai to use text-embedding-3-small.

Configuration

Create or edit ~/.config/skill-embedder/skill-embedder.json:

{
  "skillParentDirs": [
    "/path/to/your/skills/directory",
    "/another/skills/directory"
  ]
}

Commands

• /skill-embedder:embed-skills — manually trigger skill embedding
• /skill-embedder:search-skills <query> — search skills by semantic similarity

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SKILL_EMBEDDER_EMBEDDING_PROVIDER | huggingface or openai | huggingface | | SKILL_EMBEDDER_DATA_DIR | Override data directory | OS default | | SKILL_EMBEDDER_CONFIG_DIR | Override config directory | OS default | | SKILL_EMBEDDER_HUGGINGFACE_EMBEDDING_MODEL | HuggingFace model | jinaai/jina-embeddings-v2-small-en | | SKILL_EMBEDDER_OPENAI_EMBEDDING_MODEL | OpenAI model | text-embedding-3-small | | OPENAI_API_KEY | Required for OpenAI provider | — |