azure-ai

Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.

Quality

76%

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 ./plugins/azure-skills/skills/azure-ai/SKILL.md

Quality

Content

61%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.

A well-organized, token-efficient overview that correctly routes deep material to per-language SDK references, with a clear MCP-preferred/fallback branch. The body falls short on actionability and workflow clarity: it names tools but never shows an executable invocation or a sequenced end-to-end task, and it leaves auth-best-practices.md orphaned.

Suggestions

Add one minimal executable example per headline service in the body — e.g., an 'azure__search' 'search_query' invocation with its arguments, or an 'az search' command with parameters — so the most common tasks are actionable without opening a reference file.

Add short task-oriented workflows (e.g., search: list indexes -> pick index -> run query -> interpret results; speech: locate audio -> transcribe/synthesize -> verify output) so the sequence for each service is explicit rather than implied by tool lists.

Link references/auth-best-practices.md from the body (e.g., in a 'Before you start' or SDK section) — it exists in the bundle but is currently referenced nowhere in SKILL.md, making it undiscoverable.

Dimension	Reasoning	Score
Conciseness	The body is compact (~63 lines) with dense tables and link lists that mostly earn their tokens. Minor over-explanation remains in the capability tables, e.g., 'Hybrid search \| Combined keyword + vector' and 'Full-text search \| Linguistic analysis, stemming' restate concepts Claude already knows; trimming those to Azure-specific specifics would reach 5.	4 / 5
Actionability	Tool and command names are concrete ('azure__search' with command 'search_query', 'az search', 'az cognitiveservices') and the MCP fallback instruction is specific, but there is no executable guidance in the body — no invocation with arguments, no example query, no code block, and Document Intelligence has neither MCP tool nor CLI. It sits between 'some concrete guidance but incomplete' (3) and 'mostly executable' (4), closer to 3 because every actual invocation detail is deferred to references.	3 / 5
Workflow Clarity	There is one clear branch (prefer MCP; if not enabled, ask the user to run '/mcp' or configure MCP), but no sequenced task workflows — how to actually run a search (pick index, run query, interpret results) or a transcription (point at audio, run, review output) is left implicit with no checkpoints. The skill is a capability catalog rather than a multi-step process, which caps it at 'steps listed but validation/sequence gaps'.	3 / 5
Progressive Disclosure	Good structure: an overview body pointing to 14 one-level-deep references/sdk/ guides, all of which exist, plus clearly labeled sections. Minor gaps keep it from 5: references/auth-best-practices.md is present in the bundle but never referenced from SKILL.md (a buried, undiscoverable reference), and external doc links use an inconsistent '->' style.	4 / 5
	Total	14 / 20 Passed

Description

83%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 strong description that names the domain, lists concrete capabilities, and provides an explicit WHEN clause with natural trigger terms. The main gaps are missing trigger synonyms for the OpenAI/Document Intelligence halves and slightly generic terms (OCR, transcribe) that aren't Azure-qualified.

Dimension	Reasoning	Score
Specificity	The description lists several concrete actions ('search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR') across the four named services. It falls short of 5 because the OpenAI and Document Intelligence capabilities (e.g., GPT/embeddings, form extraction) are only implied by service names rather than stated as concrete actions.	4 / 5
Completeness	Both parts are explicit: the 'what' is a concrete multi-action capability list and the 'when' is an explicit 'WHEN:' clause with concrete trigger phrases, matching the top anchor. A 4 would require the when-clause to be less explicit or specific, which is not the case here.	5 / 5
Trigger Term Quality	The WHEN clause covers natural phrases users would say ('query search', 'vector search', 'hybrid search', 'semantic search', 'speech-to-text', 'text-to-speech', 'transcribe', 'OCR', 'convert text to speech'). Not 5 because common variations for half the services are missing, e.g., 'GPT', 'embeddings', 'form extraction', and the legacy 'Cognitive Services' name.	4 / 5
Distinctiveness Conflict Risk	The description is anchored to the clear 'Azure AI' niche with service-specific triggers, but unqualified generic terms like 'OCR', 'transcribe', and 'convert text to speech' create minor overlap risk with general transcription/OCR skills. This is 'mostly distinct; minor overlap risk' rather than the minimal-conflict 5 anchor.	4 / 5
	Total	17 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 14 deeper-than-1-level	Warning
referenced_paths_exist	Referenced path issues: 14 deeper-than-1-level	Warning

	Total	14 / 16 Passed

Repository: microsoft/GitHub-Copilot-for-Azure
Path: plugins/azure-skills/skills/azure-ai/SKILL.md
Commit: fcf2f3b

Reviewed: 3 hours 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.