mirror of
https://github.com/mongodb/agent-skills.git
synced 2026-09-18 21:15:11 +08:00
kanchana-mongodb
1e72df255e
* feat(mongodb-search-and-ai): add Automated Embedding, refine skill after review Add Automated Embedding (autoEmbed) support and polish the skill following a full /review-skill pass (structural validation + LLM scoring + live cluster validation against sample_mflix.movies). Changes: - SKILL.md: add "Automated Embedding" search type, cluster-tier check step, Core Principle #6 (accessible language), condense $regex/$text anti-pattern, trim redundant "Remember" section; restore license/metadata frontmatter to match sibling skills. - references/automated-embedding.md: new reference for autoEmbed index types and text-query (query vs queryVector) syntax. - references/vector-search.md: consolidate pre/post-filter docs, fix dead TOC anchor (#filter-fields), remove duplicated performance notes and score caveats. - references/hybrid-search.md: $rankFusion (8.0+) / $scoreFusion (8.2+) updates. Review outcome: structural validation passed; SKILL.md overall 3.83 -> 4.0, reference aggregate 4.4 -> 4.6, no dimension below 3. Live-validated the highest-novelty autoEmbed query/queryVector distinction against a live Atlas cluster. * test(mongodb-search-and-ai): add Automated Embedding evals + iteration-1 results Add three Automated Embedding eval cases (ids 16-18) covering the autoEmbed index type, plain-text query field (vs queryVector), and model selection (voyage-4-lite for cost, voyage-code-3 for code). Add SUMMARY.md recording the iteration-1 skill-creator run: with_skill 95.2% vs without_skill 43.4% (+51.8%), Claude Opus 4.6, MongoDB MCP against sample_mflix. All 18 evals differentiate; the new autoEmbed cases show +75%/+100%/+75% deltas. * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * chore(mongodb-search-and-ai): sync plugin skill copies Regenerate the mongodb and mongodb-atlas plugin copies of the mongodb-search-and-ai skill from the canonical skills/ source so the plugin mirrors reflect the Automated Embedding + review refinements. Ran tools/sync-plugin-skills.ts; output is idempotent (no further drift). Fixes the failing sync-check CI job on PR #57. * fix(mongodb-search-and-ai): use valid mongosh syntax in autoEmbed index example Address Copilot review on PR #57: the createSearchIndex example used db.<collection>, which isn't valid mongosh syntax. Use db.collection to match the convention in the sibling reference files (placeholders stay inside strings). Regenerated plugin copies via tools/sync-plugin-skills.ts (idempotent). * AGSK-18 fixes version * fix(mongodb-search-and-ai): correct version gates to 8.3+ SME correction: $scoreFusion and self-managed Automated Embedding require MongoDB 8.3+ (previously documented as 8.2+). Normalize the $scoreFusion note in SKILL.md to use the "+" suffix for consistency. Regenerated plugin copies via tools/sync-plugin-skills.ts (idempotent). * fix(mongodb-search-and-ai): address Copilot review feedback - Add "Automated Embedding" to the workflow proceed-gate in SKILL.md so Automated Embedding requests don't dead-end after the Cluster Check. - Make self-managed prerequisites edition-agnostic: drop "Community Edition"/"Enterprise Edition" qualifiers in automated-embedding.md and SKILL.md; key the requirement on MongoDB 8.3+ with mongot + Voyage AI. Regenerated plugin copies via tools/sync-plugin-skills.ts (idempotent). * fix(mongodb-search-and-ai): correct rate-limit unit in autoEmbed upgrade note Address Copilot review on PR #57: the free->paid upgrade note said "667x higher TPM", but 667x is the RPM increase (3 -> 2,000 RPM). Reword to state the RPM change explicitly and note TPM rises correspondingly, so it matches the rate-limit tables above. Regenerated plugin copies via tools/sync-plugin-skills.ts (idempotent). * docs(mongodb-search-and-ai): note Atlas prerequisites can change Address Copilot review on PR #57: the Automated Embedding cluster tier and autoscaling prerequisites were stated as absolutes. Add a brief note in SKILL.md and automated-embedding.md to confirm current requirements in the Atlas UI or official docs, since these can drift across releases. Regenerated plugin copies via tools/sync-plugin-skills.ts (idempotent). * docs(mongodb-search-and-ai): cover item-to-item similarity for autoEmbed Address jeff-allen-mongo's review on PR #57: the decision framework and Automated Embedding query guidance didn't handle "given item A, find similar items" requests. Since autoEmbed $vectorSearch.query only accepts a plain text string (no raw-vector read path to reuse a document's stored embedding), add: - A clarifying Discovery question in SKILL.md (free text vs. similarity to an existing item). - An "Item-to-Item Similarity" callout in automated-embedding.md showing how to resolve the source item to its indexed text field and pass that as the query (with a self-exclusion filter), plus a TOC entry. Regenerated plugin copies via tools/sync-plugin-skills.ts (idempotent). * docs(mongodb-search-and-ai): simplify Automated Embedding autoscaling note Condense the M10+ dedicated cluster prerequisite to "enable storage autoscaling" and align the Item-to-Item Similarity TOC entry as a top-level bullet. Regenerated plugin copies via tools/sync-plugin-skills.ts (idempotent). * docs(mongodb-search-and-ai): simplify autoEmbed auto-scaling prerequisite Condense the Atlas Clusters prerequisite to "M10+ dedicated clusters require storage auto-scaling to be enabled", dropping the detailed max-tier table and explanatory paragraph. Fix subject/verb agreement in the staleness note. Regenerated plugin copies via tools/sync-plugin-skills.ts (idempotent). * docs(mongodb-search-and-ai): address Copilot review nits - SKILL.md: standardize on "auto-scaling" (hyphenated) to match references/automated-embedding.md and the Atlas UI spelling. - references/vector-search.md: remove trailing whitespace on the pre-filtering Definition line. - references/hybrid-search.md: format all referenced filenames in the Scope paragraph as inline code for consistency. Regenerated plugin copies via tools/sync-plugin-skills.ts (idempotent). * test(mongodb-search-and-ai): expect cluster check in autoEmbed evals Align Automated Embedding eval cases 16-18 with the updated skill workflow: each expected_output now requires a cluster check before index creation - confirm Atlas (all tiers incl. M0) vs self-managed (8.3+ with mongot + Voyage AI key), and call out the M10+ dedicated storage auto-scaling prerequisite. * chore(mongodb-search-and-ai): sync plugin mirrors for auto-scaling wording Propagate the canonical SKILL.md edit ("M10+ without storage auto-scaling") to the four plugin copies via tools/sync-plugin-skills.ts. Fixes the failing Plugin Skills Sync check caused by mirror drift. * fix(mongodb-search-and-ai): apply review suggestions and sync plugin mirrors Co-authored-by: kanchana-mongodb <54281287+kanchana-mongodb@users.noreply.github.com> * docs(mongodb-search-and-ai): address review feedback Route search-type selection from step 2 and defer prerequisites to reference files, per PR review. - SKILL.md: merge search-type routing into "Determine Search Type" (step 2); remove standalone Cluster Check / Version Check / Consult Reference Files steps. Each search type links directly to its reference file and defers prerequisite verification to that file. - automated-embedding.md: move cluster/self-managed prerequisites and the M10+ auto-scaling + Voyage AI fallback behavior into Prerequisites; drop "Atlas UI" wording; fix inaccurate "no vector pipelines required" intro; combine intro+scope; remove decorative "---" rules; drop the duplicated "When to Use" routing block; document optional filter type/path fields. - vector-search.md / hybrid-search.md: combine intro + scope to reduce redundancy; move hybrid version-gate fallback behavior into hybrid-search.md. - evals.json: fix missing comma (invalid JSON). - Regenerate plugin skill mirrors via tools/sync-plugin-skills.ts. * docs(mongodb-search-and-ai): fold in remaining Copilot suggestions Address open Copilot review comments on the Automated Embedding reference, then regenerate the plugin mirrors. - automated-embedding.md: use a concrete `db.movies` collection name in the createSearchIndex and item-to-item examples (instead of `db.collection` / `db.<collection>`) for consistency with sibling reference files; use the modern `{ projection: { plot: 1 } }` findOne options form; add a note that `_id` is always available as a filter field on an autoEmbed index (no need to declare it) for the self-exclusion filter. - Regenerate plugin skill mirrors via tools/sync-plugin-skills.ts. * docs(mongodb-search-and-ai): clarify filter-field guidance Address Copilot re-review comments on automated-embedding.md. - Reword the self-referential filter-field inline comment to explain the purpose (index fields as filters to enable pre-filtering / scoped search) instead of "recommended for filter fields". - Clarify the `_id` note so it no longer contradicts the Query Parameters table: filter fields must generally be indexed as type "filter", with `_id` called out as the one implicit exception; add the same caveat to the table's `filter` row. - Regenerate plugin skill mirrors via tools/sync-plugin-skills.ts. * Update MCP config description in SUMMARY.md Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
MongoDB Agent Skills
Collection of official MongoDB agent skills for use in agentic workflows. For more information, refer to the MongoDB Agent Skills documentation.
This README covers the mongodb-atlas plugin, which connects your agent to the MongoDB-hosted Atlas MCP server over HTTP using OAuth. It bundles the official MongoDB agent skills for writing queries, designing schemas, optimizing queries, using Atlas Search and Vector Search, and more.
Connecting to MongoDB Community or Enterprise Advanced? For self-managed deployments, use the
mongodbplugin instead — it runs the MongoDB MCP server locally and connects to your own deployment. See Community & Enterprise Advanced setup for installation and configuration instructions.
The mongodb-atlas plugin is available on Claude, Cursor, Codex, GitHub Copilot (CLI and VS Code), and Grok.
Installation
Claude
Install mongodb-atlas from the Claude marketplace, or run the following command from a Claude session:
-
Install the plugin:
/plugin install mongodb-atlas -
Follow the prompts to complete the installation, then run
/reload-pluginsto activate it.
Cursor
Install mongodb-atlas from the Cursor marketplace, or run the following command from a Cursor session:
-
Install the plugin:
/add-plugin mongodb-atlas -
Follow the prompts to complete the installation.
Codex
-
Open the plugins browser:
/plugins -
Find the
mongodb-atlasplugin and install it.
GitHub Copilot CLI
-
Install the plugin:
copilot plugin install mongodb-atlasTo browse first, run
copilot plugin marketplace browse.
VS Code
Open the Extensions view (⇧⌘X / Ctrl+Shift+X), search for @agentPlugins,
find mongodb-atlas, and select Install.
Grok
-
Open the marketplace browser in Grok Build:
/marketplace -
Find
mongodb-atlasand pressito install it.
Authentication
The mongodb-atlas plugin connects to the MongoDB-hosted Atlas MCP server using OAuth. The first time your agent uses the server, you'll be prompted to sign in to MongoDB Atlas in your browser.
Installing the skills directly
The methods below install just the agent skills — the same skills both plugins bundle — for agents or workflows that don't use a plugin marketplace. They don't configure an MCP server; to add one, run npx "mongodb-mcp-server@latest" setup, which can configure either the hosted Atlas MCP server or a self-managed deployment. Installing the mongodb-atlas or mongodb plugin just does this for you as a convenience (bundling the MCP configuration); for self-managed specifics, see Community & Enterprise Advanced setup.
Vercel's Agent Skills Directory
https://skills.sh/ is a popular directory and CLI that automates installing skills:
npx skills add mongodb/agent-skills
Local install from repository
-
Clone the repository:
git clone https://github.com/mongodb/agent-skills.git -
Copy the
skills/directory to the location where your coding agent reads its skills or context files. Refer to your agent's documentation for the correct path.