How to use the MongoDB Operations Expert agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a request matches the skill. This one is named mongodb and is described as a MongoDB operations expert for queries, aggregation pipelines, indexes, and schema design.

Once active, the agent follows a set of MongoDB principles when you ask for help. It favours designing schemas around access patterns rather than relational normalization, and it suggests indexes to support your query patterns.

• Decide whether to embed or reference related data, based on how it is read and updated.
• Write queries and aggregation pipelines, placing $match early and using $lookup, $facet and $merge where they fit.
• Choose and audit indexes, including the ESR rule for compound indexes and partial or TTL indexes.
• Flag pitfalls such as unbounded arrays, unindexed COLLSCAN queries and leading-wildcard $regex.

What the skill does not do

The skill only changes how the agent reasons and writes advice. It does not connect to any database by itself. To have the agent run queries against your database, you need a MongoDB deployment or client tooling, which this skill does not include.

Install the mongodb skill

Download the ZIP from the skill's page on this directory and unzip it. The skill ships as a single file, SKILL.md, inside the mongodb folder.

For a personal install, place the unzipped folder in ~/.claude/skills/. To scope it to one project, place it in that project's .claude/skills/ folder instead.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

How to trigger the skill with natural requests

You do not need a special command. Describe your MongoDB task in plain language, and mention MongoDB or your collections so the agent recognises the context. The skill's description covers queries, aggregation pipelines, indexes and schema design, so requests about those topics are the best fit.

• Should I embed the addresses in the user document or keep them in a separate collection? Our app reads them together.
• This aggregation over orders takes 8 seconds. Rewrite the pipeline so it filters earlier.
• Which indexes should I create for a query that filters on status, sorts by createdAt and ranges over total?
• Review this schema for unbounded arrays and tell me what to change.

Examples of useful guidance

The skill tells the agent to verify performance before deploying, using explain("executionStats"). It also asks for a schemaVersion field so future migrations are easier.

For slow queries, the agent will look for missing indexes and full collection scans. For index design, it will apply the ESR rule: equality fields first, sort fields second, range fields last.

• Use a partial index with partialFilterExpression when only a subset of documents is queried.
• Use a TTL index for sessions, logs or other temporary data that should expire automatically.
• Use db.collection.getIndexes() and the $indexStats aggregation stage to find unused indexes, then drop them.

Safety notes: scripts and network

This skill runs no scripts and uses no network access. It is a text file of instructions. Any database action comes from tools you connect yourself.

The guidance is general. The agent cannot verify your deployment's actual state from this file alone, so review any index change or schema migration against your real data and workload before applying it to production.

Tips for getting better answers

Give the agent real context: document shapes, query text, index definitions and approximate collection sizes. The advice depends heavily on access patterns, which the agent cannot see unless you share them.

• Paste the output of explain("executionStats") when asking about slow queries.
• State how often each field is read and how often it is updated, since that drives embed-versus-reference decisions.
• Ask for the trade-offs, not just the answer, when a change affects write performance.