Integrate NoSQL query generation into Cosmos DB best practices

[Vsevolod Kukol (sevoku)]

Summary

Move the standalone NoSQL query-generation skill into cosmosdb-best-practices as rules/query-generation.md, then correct the language guidance in separate, focused commits.

This consolidates query syntax, examples, and optimization guidance under one skill while keeping VS Code editor orchestration in cosmosdb-nosql-query-editor. The complete language guide lives in the new rule; no separate reference directory or document is introduced.

This is a draft for reviewing and refining the integration locally before contributing it to AzureCosmosDB/cosmosdb-agent-kit.

Commit-by-Commit Review

1. 142bacfa — Structural move. Move the language guide into the best-practices rule directory, preserving its body unchanged. Replace standalone-skill metadata with rule metadata, add discovery wording and index links, remove the old chatSkills registration, and update editor-skill and chat-documentation references.
2. b6fdfdec — Response boundaries. Remove global SQL-only, no-replay, and unrelated policy restrictions. Retain schema grounding and protection against instructions embedded in sampled data. Scope single-query formatting to executable payloads, allow ordinary explanations and SDK examples, and distinguish generating or explaining a query from authorization to execute it.
3. 1e00c454 — Dialect corrections. Document regular ORDER BY VectorDistance(...) alongside rank-based ordering, distinguish vector indexing from syntax requirements and brute-force evaluation, and remove the incorrect mandatory-PascalCase restriction. Add supporting documentation links and a vector-ordering example.
4. 7d70c8f4 — Query semantics and recommendations. Clarify scalar versus object results for DISTINCT and COUNT, preserve requested case-sensitivity and sort semantics, explain OFFSET/LIMIT tradeoffs and continuation-token paging, add explicit example assumptions and an incorrect/correct array-filtering pair, and fix the contradictory TOP summary in the skill index.
5. 8b88557c - Composite-index direction clarification. State that multi-property sorting requires the same property-path sequence, with directions either matching the composite index or reversed on every path. Explicitly exclude partial reversal and show an inverse-order example without requiring a redundant inverse index.

The first commit isolates the relocation from the subsequent content changes so they can be reviewed independently.

Skill Discovery and Ownership

• cosmosdb-best-practices explicitly covers generating, explaining, editing, fixing, and optimizing NoSQL queries, with a direct link to the new rule.
• cosmosdb-nosql-query-editor delegates query-language guidance to that rule and retains the editor-tool workflow.
• The editor skill specifies that the query tool argument contains a single query with optional SQL comments, not prose, Markdown fences, SDK code, or error messages. Chat explanations remain ordinary prose.
• The extension contributes two skills instead of three. There is no second copy of the query-language guide to maintain.

Intentional Upstream Divergence

The external-skill pin and exclusions remain unchanged at a7a7c2c23214edd36a06d13b674ed392b1fefae8. This PR intentionally changes the vendored best-practices content rather than updating the pin or modifying the upstream repository.

The intended sequence is to review and refine these changes here, contribute the agreed guidance upstream, then pin the upstream revision once it includes that work.

Refresh caveat: npm run fetch-skill replaces the vendored directory from the configured pin. Until these additions are incorporated upstream and the pin advances, running it would remove the new rule and overwrite the local index changes, leaving the editor's new reference without its target.

Upstream Dependency

As noted in the follow-up comment, this PR also depends on AzureCosmosDB/cosmosdb-agent-kit#267 for consistent guidance in the linked index-composite.md and index-composite-direction.md rules. That upstream PR covers full direction reversal, removes redundant inverse-index recommendations, and distinguishes required multi-property composite indexes from single-property range indexing and optional optimizations.

The clarification in this PR updates only the new query-generation rule. The two vendored indexing rules remain unchanged here; their corrections will flow in through a future upstream pin update after #267 merges, alongside the upstreaming sequence described above.

Scope and Review Focus

This PR changes skill content, skill registration, and related documentation only. It does not change the query parser, editor runtime, SDK dependencies, or localization resources.

The function catalog is described as a navigation aid rather than an unconditional compatibility guarantee. Function signatures, supported query contexts, and feature prerequisites still depend on the target service; editor-parser acceptance alone does not establish service support.

References

• VectorDistance syntax, ordering, and index options
• STRINGEQUALS and case-sensitivity behavior
• COUNT expression and row-count examples
• OFFSET LIMIT syntax
• Composite-index property order and full direction reversal

[github-actions]

✅ Build (Compile, Lint, Prettier, l10n, Package)

🧱 Step Results

• Validate Version: ✅ success
• Localization: ✅ success
• Lint: ✅ success
• Prettier: ✅ success
• Compile (tsc): ✅ success
• Package: ✅ success
• External Skills (info): ✅ success

📥 Artifacts (run)

• dev-sevoku-integrate-query-generation-skill-0.37.2-dcea565 — 4.01 MB

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/vitest

The overall line coverage in commit 03cdc20 in the dev/sevoku/integrate... branch remains at 78%, unchanged from commit 490b7a1 in the main branch.

---

_{Updated September 23, 2026 08:41 UTC}

[github-actions]

🧪 Tests (Unit + Integration)

🧪 Results

• Unit Tests (vitest): ✅ success
• Integration Tests (extension host): ✅ success

📈 Coverage

• Download HTML report

[github-actions]

🎭 E2E Tests (Playwright + VS Code)

🧪 Result

• E2E Tests: ✅ success

📥 Artifacts (run)

• e2e-html-report-1 — 7.63 MB
• e2e-results-1 — 16.73 MB

Tip: the HTML report artifact contains a self-contained Playwright report.
Download the zip, extract, and open index.html — or run
npx playwright show-report <extracted-dir> for the interactive view.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The composite-index direction guidance incorrectly omits support for completely inverted sort directions.

Review effort: Balanced
Findings: None

What changed in this PR

Consolidates NoSQL query guidance into the Cosmos DB best-practices skill while retaining editor orchestration separately.

Changes:

• Moves query-language guidance into a dedicated best-practices rule.
• Corrects query semantics, response boundaries, and optimization guidance.
• Removes the standalone query-generation skill registration.

File	Description
src/​chat/​README.md	Updates skill references.
skills/​cosmosdb-nosql-query-editor/​SKILL.md	Delegates language guidance to the new rule.
skills/​cosmosdb-best-practices/​SKILL.md	Adds query-generation discovery and indexing.
skills/​cosmosdb-best-practices/​rules/​query-generation.md	Integrates and revises the query guide.
package.json	Removes the standalone skill registration.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Vsevolod Kukol (sevoku)]

Clarified the query-generation rule in 8b88557c: a composite index supports the same property-path sequence with either its declared directions or all directions reversed. Reversing only some directions is not supported by that index.

This PR also depends on AzureCosmosDB/cosmosdb-agent-kit#267 for the corresponding corrections in the linked composite-index rules. Those vendored rules remain unchanged here; their fixes will flow in through a future upstream pin update after #267 merges.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The linked composite-index rules contradict the new guidance, and a minor duplicated word remains.

Review effort: Balanced
Findings: None

Previously missed (1)

In code that hasn't changed since last review

Remove duplicated “the” in query-generation rule reference

skills/​cosmosdb-nosql-query-editor/​SKILL.md:24

Remove the duplicated article; this currently renders as “use the the query-generation rule.”

[Laurent Nguyen (languy)]

We lost some of these strong directives and the output contract that should be moved to the cosmosdb-nosql-query-editor/SKILL.md?

[Vsevolod Kukol (sevoku)]

Not quite, this was already contradicting the skill purpose to explain the language, it's solely a knowledge skill, while the other cosmosdb-nosql-query-editor skill is the orchestrator leveraging that knowledge. Hence the language skill should not enforce any specific behaviour since it might be used in a different context (i.e. user simply discussing a query with copilot).
However the actual editr skill might be missing some hardening now. I'll double check.

[Vsevolod Kukol (sevoku)]

Hardened the editor skill in 03cdc201: the tool payload must contain exactly one valid NoSQL SELECT query, with no prose, Markdown fences, SDK code, or error messages. Missing required context must be resolved before applying or executing; generation or explanation alone must not trigger execution.