CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

azure-search-documents-py

Azure AI Search SDK for Python. Use for vector search, hybrid search, semantic ranking, indexing, and skillsets.

Quality

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/antigravity-bundle-azure-ai-cloud/skills/azure-search-documents-py/SKILL.md

The canonical home for this skill is azure-search-documents-py in administrakt0r/AI-Agents-Safe-Coding-Skills

SKILL.md
Quality
Evals
Security

Quality

Content

46%Weight 40%Scale 1-5

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

The code examples are concrete and mostly executable, but the document is structurally broken: it contains two overlapping versions of the same skill with conflicting details, and every reference and script it points to is missing from the bundle. Nearly half the content is duplicative padding, and no workflow includes validation or error-recovery steps.

Suggestions

Remove the duplicated second document ("Additional Azure AI Search Patterns" onward) and reconcile the conflicting guidance (1536 vs 3072 dimensions, SimpleField/SearchableField vs raw SearchField, two differing client tables) into one authoritative version.

Either create the referenced bundle files (references/vector-search.md, references/semantic-ranking.md, references/agentic-retrieval.md, scripts/setup_vector_index.py) or delete the Reference Files table — every cited path is currently missing from the bundle.

Add validation checkpoints to the multi-step and batch workflows: check indexer status after create_or_update_indexer, wait for indexing completion, and verify upload results before proceeding, lifting workflow clarity above 3.

DimensionReasoningScore

Conciseness

The body is two concatenated skill documents: Installation, Authentication, client tables, index creation, search patterns, and Best Practices all appear twice with conflicting details (1536 vs 3072 dimensions, SimpleField/SearchableField vs raw SearchField with Edm.String), plus a filler closing line ("This skill is applicable to execute the workflow or actions described in the overview."). Roughly half the ~530 lines are duplicated padding — noticeably below the midpoint, matching anchor 2; not 1 because the individual sections themselves are lean code examples without conceptual over-explanation.

2 / 5

Actionability

Concrete, mostly executable code throughout: client construction with AzureKeyCredential/DefaultAzureCredential, create_or_update_index with VectorSearch profiles, VectorizedQuery search calls, SearchIndexingBufferedSender batching, async and error-handling examples. Not 5 because several examples depend on undefined variables (endpoint, key, connection_string, aoai_endpoint, embedding_deployment, query_vector), preventing copy-paste readiness.

4 / 5

Workflow Clarity

The indexer section has a real sequence (data source → skillset → indexer) and sections are roughly ordered (index → upload → query), but there are no validation checkpoints: no indexer status check, no wait for indexing completion, no verification after batch uploads. Per the rubric cap, batch operations without feedback loops cap workflow clarity at 3; the sequences present but checkpoints missing/implicit match anchor 3.

3 / 5

Progressive Disclosure

Scored against the actual bundle: no references/, scripts/, or assets/ directories exist, so all four cited files (references/vector-search.md, references/semantic-ranking.md, references/agentic-retrieval.md, scripts/setup_vector_index.py) are dangling. Meanwhile ~500 lines of reference material (field type tables, full API patterns, and an entire duplicated second document) are inlined in SKILL.md — content that clearly belongs in separate files. Matches anchor 2; not 1 because section headers and a Reference Files table provide some navigation, and not 3 because the promised cross-file structure is fictional.

2 / 5

Total

11

/

20

Passed

Description

75%Weight 40%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.

A concise, third-person description that clearly identifies the domain and lists five concrete capability areas with an explicit "Use for" trigger clause. Its main weaknesses are missing natural synonyms ("Azure Cognitive Search", "RAG", "semantic search") and a trigger clause that doesn't reference user phrasing.

DimensionReasoningScore

Specificity

"Use for vector search, hybrid search, semantic ranking, indexing, and skillsets" lists several specific capability areas, matching anchor 4 (several specific actions, minor gaps). Not 5 because coverage is incomplete (no document upload, autocomplete, or agentic retrieval) and the terse noun phrases lack the concrete action framing of the anchor-5 example.

4 / 5

Completeness

"Azure AI Search SDK for Python" gives a clear what, and "Use for vector search, ..." is an explicit trigger clause, so both are present. Not 5 because the when never ties triggers to user phrasing ("when the user mentions...") and could be more explicit, matching anchor 4.

4 / 5

Trigger Term Quality

Good natural keywords — "Azure AI Search", "vector search", "hybrid search", "semantic ranking", "indexing" — but misses common synonyms users say, notably "Azure Cognitive Search" (the service's former name), "semantic search", "RAG", and "embeddings". Anchor 4: good coverage with a few natural terms missing.

4 / 5

Distinctiveness Conflict Risk

"Azure AI Search SDK for Python" carves a clear niche, but generic trigger terms like "vector search" and "semantic ranking" could also pull in non-Azure vector database or search skills — minor overlap risk with closely related skills, matching anchor 4 rather than 5.

4 / 5

Total

16

/

20

Passed

Validation

81%

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

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (532 lines); consider splitting into references/ and linking

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

referenced_paths_exist

Referenced path issues: 4 missing

Warning

Total

13

/

16

Passed

Repository

administrakt0r/AI-Agents-Safe-Coding-Skills

Path

plugins/antigravity-bundle-azure-ai-cloud/skills/azure-search-documents-py/SKILL.md

Reviewed

Table of Contents

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.