embedding-strategies

Guide to selecting and optimizing embedding models for vector search applications.

Quality

38%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/embedding-strategies/SKILL.md

Quality

Content

39%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill provides substantial executable code templates for embedding workflows but suffers from severe verbosity — most of the code (chunking strategies, evaluation metrics, similarity computation) is knowledge Claude already possesses. It lacks a coherent workflow guiding users through the embedding process end-to-end, and all content is inlined in a single massive file with a broken reference to a non-existent bundle file.

Suggestions

Extract the lengthy code templates (chunking strategies, evaluation metrics, similarity computation) into separate bundle files and reference them from SKILL.md, keeping only the model comparison table and a brief quick-start example inline.

Add a clear numbered workflow section that sequences the steps: select model → preprocess → chunk → embed → store → validate retrieval quality, with explicit validation checkpoints.

Remove or create the referenced `resources/implementation-playbook.md` file to avoid dead references.

Trim the do's/don'ts section and code templates to only include non-obvious, domain-specific guidance that Claude wouldn't already know (e.g., BGE query prefixes, E5 instruction formatting, Matryoshka dimension reduction).

Dimension	Reasoning	Score
Conciseness	The skill is extremely long (~400+ lines) with extensive code templates that Claude could largely generate on its own. The model comparison table adds value, but the full implementations of chunking strategies, evaluation metrics, and embedding pipelines are things Claude already knows how to write. The do's/don'ts section states obvious best practices.	2 / 5
Actionability	The code templates are concrete and mostly executable — OpenAI embeddings, sentence-transformers, chunking strategies, and evaluation metrics are all copy-paste ready. Minor gaps exist: the CodeEmbeddingPipeline.chunk_code method is a stub with `pass`, and the LocalEmbedder.embed_query has a bug (calling get_sentence_embedding_dimension() to check model name). Otherwise strong.	4 / 5
Workflow Clarity	There is no clear end-to-end workflow with sequenced steps. The skill provides isolated templates but never guides the user through a coherent process of selecting a model, chunking, embedding, storing, and validating results. The 'Embedding Pipeline' ASCII diagram hints at a workflow but lacks actionable steps or validation checkpoints.	2 / 5
Progressive Disclosure	The skill references `resources/implementation-playbook.md` but no bundle files exist, making this a dead reference. The massive amount of code (~300+ lines of templates) is all inlined when it clearly should be split into separate files. The content is a monolithic wall of code with minimal structural navigation.	2 / 5
	Total	10 / 20 Passed

Description

36%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description identifies a clear domain (embedding models for vector search) but is too vague in describing concrete actions and completely lacks trigger guidance ('Use when...'). It reads more like a document title than a functional skill description, missing both actionable specifics and the natural language terms users would employ when needing this skill.

Suggestions

Add a 'Use when...' clause with trigger terms like 'embeddings', 'semantic search', 'RAG', 'vector database', 'similarity search', or 'choosing an embedding model'.

Replace the generic 'selecting and optimizing' with concrete actions such as 'Compares embedding model options, recommends chunking strategies, evaluates dimensionality trade-offs, and benchmarks retrieval quality'.

Include common synonyms and related terms users might naturally use, such as 'RAG pipeline', 'text embeddings', 'cosine similarity', or specific model families like 'OpenAI embeddings', 'sentence-transformers'.

Dimension	Reasoning	Score
Specificity	Names the domain (embedding models, vector search) but provides no concrete actions. 'Selecting and optimizing' are generic verbs that don't describe specific capabilities like benchmarking, fine-tuning, dimensionality reduction, or chunking strategies.	2 / 5
Completeness	Has a vague 'what' (guide to selecting and optimizing embedding models) but completely lacks a 'when' clause. There is no explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when...' caps completeness at 3, and the weak 'what' brings it to 2.	2 / 5
Trigger Term Quality	Includes relevant keywords like 'embedding models' and 'vector search,' but misses common natural terms users would say such as 'embeddings,' 'semantic search,' 'RAG,' 'similarity search,' 'vector database,' or specific model names.	3 / 5
Distinctiveness Conflict Risk	The combination of 'embedding models' and 'vector search' provides some specificity, but 'guide to selecting and optimizing' is generic enough to overlap with broader ML/AI model selection skills or vector database configuration skills.	3 / 5
	Total	10 / 20 Passed

Validation

90%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/embedding-strategies/SKILL.md
Commit: 57c135b

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.