embeddings-runtime-stinger skill
Helps agents select, configure, and debug embedding models across hosted providers and self-hosted local runtimes.
- GitHub stars
- 95
- Files
- 21
- Last commit
- Oct 18, 2026
- License
- AGPL-3.0-or-later
- Allowed tools
- —
What does the embeddings-runtime-stinger skill do?
embeddings-runtime-stinger helps agents select, configure, and debug embedding models across hosted providers and self-hosted local runtimes.
Summary generated from the skill's SKILL.md.
About the embeddings-runtime-stinger skill
Selecting and configuring embedding models for AI applications is what this skill enables. It assists developers in navigating the trade-offs between hosted providers like OpenAI, Cohere, and Voyage AI, and self-hosted local runtimes using transformers.js. Agents can use this tool to generate model recommendations, create model-swap plans, or design batching and caching strategies to optimize performance and cost.
When an agent is tasked with managing embedding lifecycles, it can provide specific configuration snippets or debug issues like stuck local daemons or dimension mismatches. It specifically addresses the constraint where embedding dimensions must match the target schema in vector stores like pgvector or Deep Lake. The skill provides technical guidance on local implementations, such as using the nomic-embed-text-v1.5 model with q8 quantization via Unix-socket IPC, ensuring that developers can maintain high retrieval quality while managing computational footprints.
What an agent can do with it
- 1Compare hosted embedding providersDecide between using OpenAI, Cohere, or Voyage AI based on specific project needs.
- 2Plan a model migrationCreate a structured plan to swap an existing embedding model while handling schema changes.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the embeddings-runtime-stinger skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the embeddings-runtime-stinger skill in Plugin
/plugin marketplace add legioncodeinc/vibe-coding-tools /plugin install data-and-ai-tools@wasp-nest
Install the embeddings-runtime-stinger skill in Claude Code
~/.claude/skills/embeddings-runtime-stinger/SKILL.md
$ npx degit legioncodeinc/vibe-coding-tools/plugins/data-and-ai-tools/skills/embeddings-runtime-stinger ~/.claude/skills/embeddings-runtime-stingerInstall the embeddings-runtime-stinger skill in Claude Code (project)
.claude/skills/embeddings-runtime-stinger/SKILL.md
$ npx degit legioncodeinc/vibe-coding-tools/plugins/data-and-ai-tools/skills/embeddings-runtime-stinger .claude/skills/embeddings-runtime-stingerInstall the embeddings-runtime-stinger skill in Codex
~/.agents/skills/embeddings-runtime-stinger/SKILL.md
$ npx degit legioncodeinc/vibe-coding-tools/plugins/data-and-ai-tools/skills/embeddings-runtime-stinger ~/.agents/skills/embeddings-runtime-stingerInstall the embeddings-runtime-stinger skill in Gemini CLI
~/.gemini/skills/embeddings-runtime-stinger/SKILL.md
$ npx degit legioncodeinc/vibe-coding-tools/plugins/data-and-ai-tools/skills/embeddings-runtime-stinger ~/.gemini/skills/embeddings-runtime-stingerInstall the embeddings-runtime-stinger skill in Claude.ai
npx degit legioncodeinc/vibe-coding-tools/plugins/data-and-ai-tools/skills/embeddings-runtime-stinger embeddings-runtime-stinger && zip -r embeddings-runtime-stinger.zip embeddings-runtime-stinger # claude.ai → Customize → Skills → + → Create skill → Upload a skill → embeddings-runtime-stinger.zip
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelegioncodeinc/vibe-coding-tools/plugins/data-and-ai-tools/skills/embeddings-runtime-stinger is public and reachablegithub.com/legioncodeinc/vibe-coding-tools/tree/HEAD/plugins ↗Pass
- Open source license (OSI)AGPL-3.0-or-later is not OSI-approvedspdx.org/licenses/AGPL-3.0-or-later.html ↗Finding
- Commit or release in the last yearLast commit 2026-10-18github.com/legioncodeinc/vibe-coding-tools/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/legioncodeinc/vibe-coding-tools/blob/HEAD/plugins ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/legioncodeinc/vibe-coding-tools/blob/HEAD/plugins ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 144 linesgithub.com/legioncodeinc/vibe-coding-tools/blob/HEAD/plugins ↗Pass
SKILL.md
View on GitHubembeddings-runtime Stinger
You are the playbook for embeddings-runtime-wasp-drone. Every invocation produces one concrete artifact: a model or provider recommendation, an on/off decision, a model-swap plan, a batching or caching fix, a daemon-lifecycle fix, or a configuration snippet. Every claim is backed by the ground truth in references/research/ (the new provider-selection sourcing), research/ (the original Hivemind/local-daemon research trail), and, where applicable, the actual Hivemind source under src/embeddings/.
Scope in one sentence
Embedding model selection and runtime, generally: hosted providers (OpenAI, Cohere, Voyage AI) and self-hosted local models, dimension/cost/latency tradeoffs, batching, caching, and the dim-must-match-schema constraint against whichever vector store is in play. The local-daemon (nomic-embed-text-v1.5) material is one fully documented implementation of the self-hosted path, not the whole scope.
When to use this skill
Use when the user says: "which embedding model should I use", "OpenAI vs Cohere vs Voyage", "should I turn embeddings on", "swap the embedding model", "cache embeddings", "batch embedding calls", "the embed daemon is stuck", "change the embedding dimension", or "local vs hosted embeddings".
Covers choosing and calling a hosted provider (OpenAI text-embedding-3, Cohere embed-v3/v4, Voyage AI) or running a self-hosted local model (transformers.js), dimension and cost tradeoffs, batching, caching to avoid re-embedding identical text, and the dim-must-match-schema constraint against pgvector (this stack's default) or Deep Lake. The local-daemon material (nomic-embed-text-v1.5, 768-dim, q8, Unix-socket IPC) is kept as one documented self-hosted implementation.
Do NOT use for the vector column/index/schema mechanics themselves (vector-store-stinger), API key security (security-wasp-drone), or PRD authorship (library-wasp-drone).
Invocation modes (routing table)
Read the user's request and match to one mode. Most requests match one primary mode with one supporting mode.
| Mode | Trigger phrases | Primary guide |
|---|---|---|
selection |
"which embedding model", "OpenAI vs Cohere vs Voyage", "local or hosted", "what should I use for embeddings" | guides/00-selection-matrix.md |
hosted-openai |
"text-embedding-3", "OpenAI embeddings", "dimensions parameter" | guides/hosted-01-openai.md |
hosted-cohere |
"embed-v4", "Cohere embeddings", "input_type", "search_document vs search_query" | guides/hosted-02-cohere.md |
hosted-voyage |
"Voyage AI", "voyage-4", "voyage embeddings" | guides/hosted-03-voyage.md |
batching |
"batch embedding calls", "rate limit", "bulk embed", "backfill embeddings" | guides/01-batching.md |
caching |
"cache embeddings", "avoid re-embedding", "duplicate embedding calls" | guides/02-caching.md |
local-daemon-lifecycle |
"embed daemon stuck", "warmup", "daemon won't start", "first embedding is slow" | guides/local-daemon-01-lifecycle.md |
local-daemon-ipc |
"socket protocol", "NDJSON", "client can't reach daemon", "unix socket path" | guides/local-daemon-02-ipc-protocol.md |
local-daemon-model-selection |
"swap the embedding model" (on the Wasp Nestmind local daemon), "nomic vs other" | guides/local-daemon-03-model-selection.md |
local-daemon-quantization |
"q8 vs fp32", "footprint", "quantization quality" (local daemon) | guides/local-daemon-04-quantization-and-footprint.md |
local-daemon-on-vs-off |
"should I turn embeddings on", "is 600MB worth it", "BM25 fallback" (Hivemind) | guides/local-daemon-05-embeddings-vs-bm25.md |
local-vs-hosted-hivemind |
"run embeddings locally or hosted" (Hivemind specifically) | guides/local-daemon-06-local-vs-hosted.md |
schema-and-dim |
"change the dimension", "dim mismatch", "schema event", "EMBEDDING_DIMS" | guides/local-daemon-07-schema-and-columns.md (Deep Lake) or vector-store-stinger (pgvector) |
First action on every invocation
- Read
guides/00-principles.md, the non-negotiables that govern every output regardless of provider or runtime. - Match the request to the routing table above. If no store or provider has been chosen yet, start at
guides/00-selection-matrix.mdrather than assuming. - Open the relevant guide(s) before producing any output.
Folder layout
embeddings-runtime-stinger/
├── SKILL.md (this file, master index)
├── guides/
│ ├── 00-principles.md (stack-neutral non-negotiables, severity rubric, cross-Drone handoffs)
│ ├── 00-selection-matrix.md (hosted vs self-hosted; OpenAI vs Cohere vs Voyage; quick decision table)
│ ├── 01-batching.md (batch sizing, rate limits/backoff, discounted async batch lanes)
│ ├── 02-caching.md (cache key design, TTL vs event-driven invalidation, cold-start/single-flight)
│ ├── hosted-01-openai.md (text-embedding-3-small/large: dims, pricing, dimensions param, no input_type)
│ ├── hosted-02-cohere.md (embed-v3/v4: required input_type, output_dimension, embedding_types)
│ ├── hosted-03-voyage.md (voyage-4 family: input_type, Matryoshka + quantization, open-weight voyage-4-nano)
│ ├── local-daemon-01-lifecycle.md (self-hosted: warmup, batching, shared install, crash recovery)
│ ├── local-daemon-02-ipc-protocol.md (self-hosted: Unix-socket NDJSON protocol; framing; handshake; failure modes)
│ ├── local-daemon-03-model-selection.md (self-hosted: Hivemind-scoped model rubric, worked example of 00-selection-matrix)
│ ├── local-daemon-04-quantization-and-footprint.md (self-hosted: q8 vs fp16/fp32 weight quantization for the CPU daemon)
│ ├── local-daemon-05-embeddings-vs-bm25.md (self-hosted: the on-vs-off decision; BM25/ILIKE lexical fallback)
│ ├── local-daemon-06-local-vs-hosted.md (self-hosted: Hivemind-specific worked example of local vs hosted)
│ └── local-daemon-07-schema-and-columns.md (self-hosted: EMBEDDING_DIMS=768; FLOAT4[] columns; Deep Lake schema event)
├── examples/
│ ├── daemon-warmup-and-ipc.md (warm the local daemon, send a batch over the socket, read NDJSON back)
│ ├── embedding-model-comparison.md (filled-in model comparison scoped to Hivemind recall)
│ └── enable-embeddings-workflow.md (turn HIVEMIND_EMBEDDINGS + HIVEMIND_SEMANTIC_SEARCH on end-to-end)
├── templates/
│ ├── embedding-model-swap-plan.md (the model/dim swap plan covering the schema migration)
│ └── dim-migration-checklist.md (step-by-step dim-change checklist with the schema-heal handoff)
├── reports/
│ └── README.md (describes how past recommendation/audit reports accumulate)
├── references/
│ └── research/
│ ├── distilled-embeddings-runtime.md (synthesis of the hosted-provider + batching/caching sourcing below)
│ └── raw/ (9 archived sources: OpenAI, Cohere, Voyage, transformers.js, caching, batching)
└── research/ (the original Hivemind/local-daemon research trail, unchanged)
├── research-plan.md
├── research-summary.md
├── index.md
├── internal/
│ └── command-brief-notes.md
└── external/
├── nomic-embed-text-v1.5.md
├── q8-quantization-tradeoffs.md
├── transformers-js-runtime.md
├── deeplake-vector-columns.md
├── embedding-model-landscape.md
└── local-vs-hosted-embeddings.md
Canonical defaults
Two default tables: one for the self-hosted local-daemon implementation (unchanged from the original Hivemind scope), one for hosted-provider selection on this repo's general stack.
Self-hosted local-daemon defaults (Hivemind implementation)
| Decision | Recommended default | Rationale |
|---|---|---|
| Embeddings engine | @huggingface/transformers ^3 (optional dep) | Pure JS/WASM runtime; runs in-process via a daemon; no native build needed |
| Embedding model | nomic-ai/nomic-embed-text-v1.5 | Strong retrieval quality at 768 dim; the dim the Wasp Nestmind schema is built around |
| Quantization | q8 | Best footprint/latency/quality balance for CPU inference; ~600MB on-disk install |
| Dimension | 768 (EMBEDDING_DIMS) |
Locked to the Deep Lake FLOAT4[] columns; changing it is a schema event |
| Default state | OFF | HIVEMIND_EMBEDDINGS and HIVEMIND_SEMANTIC_SEARCH both off; recall falls back to BM25/ILIKE |
| Daemon transport | Unix-socket NDJSON IPC | protocol.ts + client.ts; one warm process, batched requests |
See guides/local-daemon-*.md for the full detail.
Hosted-provider defaults (general, this repo's stack)
| Decision | Recommended default | Rationale |
|---|---|---|
| Starting point | A hosted provider (OpenAI or Voyage) | Zero ops burden, minutes to first call; see guides/00-selection-matrix.md |
| Provider to start with | OpenAI text-embedding-3-small |
Simple symmetric call shape (no input_type discipline to get wrong), competitive pricing |
| Move to self-hosted when | A measured high-volume, predictable workload makes per-token cost a real line item, or text cannot leave the machine | Not a hunch; see the escape-hatch framing in guides/00-selection-matrix.md |
| Dimension | Match the target column, prefer Matryoshka truncation over a different model | All three hosted providers and nomic-embed-text-v1.5 support request-time or post-hoc truncation |
| Batching | Batch to the provider's per-call limit for bulk work; use the discounted async batch lane for backfills | Network round-trip, not inference, dominates embedding-call latency |
| Caching | Always, for any pipeline that re-processes overlapping content | Embeddings are a pure function of (model, version, text); caching is safe and close to free to add |
Severity rubric
Used to classify findings when auditing an existing embeddings setup, on any provider or runtime. Full version in guides/00-principles.md; summary:
- Must-fix: embedding dimension does not match the target column/collection width; embeddings written with one model then queried as if from another; a dimension change shipped without the schema migration path; a hosted-provider asymmetric
input_type(Coheresearch_document/search_query, Voyagedocument/query) used inconsistently between write and query paths. - Should-refactor: embeddings turned on with no measured recall lift over the lexical fallback; a self-hosted daemon spawned per-request instead of warmed once; a hosted API called per-item instead of batched; no embedding cache on a pipeline that repeatedly re-processes overlapping content; quantization or footprint heavier than justified.
- Style / nice-to-have: no crash-recovery or retry handling on the embedding call path; warmup or rate-limit backoff not surfaced as an expected cost; model or provider choice undocumented.
Cross-Drone handoffs
Surface these explicitly rather than attempting them inline:
vector-store-stinger/vector-store-wasp-dronefor the actual schema/column mechanics when a dimension change forces a migration (pgvector column resize on this repo's default stack, or Deep Lake schema-heal on a Hivemind-style project). This Drone decides the dimension and writes the swap plan;vector-store-wasp-droneexecutes the schema event.security-wasp-droneif a hosted embedding provider is considered and an API key or data-egress review is needed.library-wasp-dronefor PRD authorship when turning embeddings on, or a model/provider swap, needs to be documented as a feature requirement.
Part of The Wasp Nest, curated by Mario Aldayuz a.k.a @thenotoriousllama.
Files in this skill
21embeddings-runtime-stinger skill questions
How do I install the embeddings-runtime-stinger skill in Claude Code?
Run npx degit legioncodeinc/vibe-coding-tools/plugins/data-and-ai-tools/skills/embeddings-runtime-stinger ~/.claude/skills/embeddings-runtime-stinger. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the embeddings-runtime-stinger skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What are the main differences between hosted and self-hosted embeddings?
Hosted providers like OpenAI, Cohere, and Voyage AI offer zero ops burden and quick setup, while self-hosted models like nomic-embed-text-v1.5 via transformers.js allow for local execution and cost control for high-volume workloads.
What should I do if my embedding dimension does not match my vector store?
This is a must-fix severity issue. You must ensure the embedding dimension matches the target column or collection width, and any dimension change requires a schema migration path.
How can I optimize the cost and latency of embedding calls?
You can use batching to reach provider limits for bulk work and implement caching to avoid re-embedding identical text, as embeddings are a pure function of the model, version, and text.