MongoDB Agent Skills: What They Fix for .NET Developers

In this article, we will explore the MongoDB Agent Skills Repo and learn how it helps make our lives easier to work with MongoDB. The repo consists of 7 skill sets that give AI coding agents like Claude Code and Codex expertise to work with MongoDB. These skills can be installed as a plugin in Claude Code, Cursor, Codex, Copilot or the Gemini CLI, and they are only loaded on demand.

If they are not loaded into the context window (or not invoked), they cost you about 1,000 tokens; but when they are used, they contain roughly 366KB of MongoDB’s own guidance, which will help you a lot to work with MongoDB.

So I just cloned the mongodb/agent-skills repository and went through it. Yes, the skills are public. In the upcoming sections of this article, we will see what’s inside, what it changes for you as a .NET developer working with MongoDB, and a few things that it doesn’t really do.

Let’s get started.

Training Data?

When you ask Claude Code or any other AI coding agent to design a MongoDB schema for your ASP.NET Core API, it will definitely generate something that works. That’s the bare minimum. But, what you really get is an SQL Server design, just written to work with MongoDB syntax. Meaning it’s mostly relational design, but adapted to MongoDB.

Mostly you would end up with an Orders collection, a Customers collection, an OrderItems collection, and a $lookup that joins all three of them back together for common reads. It looks correct at first glance because it looks familiar, right?.

Haven’t we all done this at some point? I have.

Well, MongoDB has noticed this issue. When they announced the skills on March 31, 2026, they talked about the 3 actual mistakes an AI agent can make, which are over-normalizing schemas, underusing compound indexes, and wrongly used search indexes. All of these 3 mistakes come from AI being heavily trained by relational databases, and not enough by MongoDB. It’s also because of the wrong practices followed by the developers whose code was eventually used as training data.

The worst part is, if these mistakes go unchecked and into production, at some point or the other the system would take a hit and the table design would need a complete rewrite eventually.

So the real problem here is context and skills. A general-purpose agent like Claude Code has read a huge amount of MongoDB code, but the problem is most of the training code was written by developers who made exactly this translation mistake. These sets of skills that we are about to explore will help the agent to think in accordance with MongoDB’s official guidance, opinions and patterns.

What is an Agent Skill?

Before we look at the MongoDB skills, let’s understand what a skill actually is fundamentally in the world of AI agents.

An Agent Skill is a folder containing a SKILL.md file: YAML frontmatter with a name and description, with some Markdown instructions the agent reads when a task / tool call matches. Next to it, you can have optional references/, scripts/ and assets/ folders, and those load only when needed in context.

This is the standard format introduced by Anthropic and now is part of the agentskills.io. Claude Code, Cursor, Codex, GitHub Copilot and many other tools can all understand these skill files. So if we write a skill once, it can run against any of the LLM models without any changes.

Here are the stages in which the skills load in context:

1. Discovery - When the terminal is opened and you start a claude / codex session, it reads each skill’s name and description. This won’t consume many tokens in the context window.
2. Activation - when a task matches a description, it means that the skill is to be invoked, and it reads the full SKILL.md.
3. Execution - this happens during the implementation phase when the model pulls in the required reference files as needed.

If you have ever written a CLAUDE.md, you already have a good understanding about this. The problem is that the entire content of the claude.md file is loaded into every conversation and every session. And at some point, it starts to pollute the context and reduces the reliability of the output.

Skills work differently. The content of the skill costs you nothing till a task actually calls it. Pretty sweet, yeah?

Agent Skills vs MCP

A lot of developers don’t really understand the difference between skills and MCP. Let’s see the comparison.

MCP is a standard protocol for exposing operations or tool calls that an agent can invoke, like explain or find. In other words, MCP gives an agent tools, which are a means to talk to external systems. Whereas, an agent skill is a Markdown file structure / standard that instructs an agent about what tools to use / call, in what order, and how to interpret the output. In an ideal situation, you probably would need both working together to solve your problem.

The query optimizer skill from the MongoDB skill repository might be a really good example of how both the MCP and agent skills work together. The skill has some steps. It first calls the collection-indexes to see which indexes are present in the db. Then it runs explain in queryPlanner mode to check for a COLLSCAN. After that, it runs explain again with executionStats to compare the number of documents scanned with the number of documents returned. Finally, it pulls a sample document with find.

Here’s the full list of available skills, along with what each skill does:

I personally found mongodb-schema-design to be the most detailed skill, and it probably would be the most heavily used skill of the seven available skills.

What does it cost you in terms of context?

Here are some interesting stats on how the context will grow at every stage of your session.

So, the initial token cost of these skills is about 1k tokens, which is very small actually. A schema question uses about 14KB. Only if the agent needs more context will it load more information on top of that. You never actually load the entire ~400KB file. You load only what’s needed, when it’s needed. This is the coolest part.

This is also why pasting MongoDB’s best practices into your CLAUDE.md doesn’t give you the exact same result. Agent Skills are way better for this use case. Project instructions load into every conversation in that repository, even the ones that have nothing to do with MongoDB.

Installing the plugin

Now let’s install it. Open a fresh new Claude Code session on your terminal (new to Claude Code?) and run the following:

/plugin install mongodb@claude-plugins-official

Once installed, you will have to restart the claude session or run the /reload-plugins command for the plugins and skills to load properly.

This repo has two variants:

For other agents, use these commands:

# Cursor
/add-plugin mongodb-atlas

# GitHub Copilot CLI
copilot plugin install mongodb-atlas

# Codex - open the browser and select
/plugins

You can use the following commands as well:

# Vercel's skills directory (skills.sh)
npx skills add mongodb/agent-skills

# Or clone and copy the skills/ folder
git clone https://github.com/mongodb/agent-skills.git

Note that this installs only the skills. For the MCP, you need to run npx "mongodb-mcp-server@latest" setup.

Understanding skill by skill

Here is a quick brief about each of the skills.

mongodb-schema-design

This is my favorite one.

The skill follows MongoDB’s fundamental principle - “Data that is accessed together should be stored together.” It then provides the agent with a real decision table to work on:

It instructs the agent to not assume things without proper context - “Do not at once suggest a change of pattern or schema without first understanding the wider context.” Before suggesting an approach, Claude will start interviewing you through a series of important questions. Is this a new project or a production database? Is the workload predominantly read or write oriented? Only after having considered such important aspects and understanding the proper context does it suggest an approach.

This is a C# order class created by the skill:

public sealed class Order
{
    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string? Id { get; set; }

    // Extended reference: the customer lives in its own collection,
    // but the two fields that appear on every order screen are copied here.
    public CustomerRef Customer { get; set; } = null!;

    // Few lines per order and always read with it, so they are embedded.
    public List<OrderLine> Lines { get; set; } = [];

    public decimal Total { get; set; }
    public DateTime PlacedAtUtc { get; set; }
}

public sealed record CustomerRef(string CustomerId, string DisplayName);

public sealed record OrderLine(string Sku, string Name, int Quantity, decimal UnitPrice);

For this model, placing an order involves just one read and makes use of no $lookup. This is because the customer’s complete data remains in its own collection.

mongodb-connection

This skill helps you to set up the code to connect your application with the MongoDB instance.

The main rule that this skill follows is, “NEVER add connection pool parameters or timeout settings without first understanding the application’s context.”

It has a simple formula, the total number of connections is equal to (minPoolSize + 2) times the number of replica members and also times the number of instances of the application. The reason for adding 2 is that each MongoDB client sets up two monitoring connections for each member of the replica set.

For example, if there are 10 instances of the application, and the minimum pool size is 5, there are about 200 connections made to the server. But if you do the actual calculation, you should expect only 50.

There are also other instructions with different scenarios. For a serverless application the maxPoolSize should be 3 to 5 and the minPoolSize should be 0. In the case of a long running service the maxPoolSize should be 50 or higher, together with a minPoolSize of 10 to 20 and a socket timeout of 30s:

builder.Services.AddSingleton<IMongoClient>(_ =>
{
    var settings = MongoClientSettings.FromConnectionString(connectionString);
    settings.MaxConnectionPoolSize = 50;
    settings.MinConnectionPoolSize = 15;
    settings.SocketTimeout = TimeSpan.FromSeconds(30);
    settings.ServerSelectionTimeout = TimeSpan.FromSeconds(5);
    return new MongoClient(settings);
});

First register the client as a singleton and then use the single instance everywhere.

mongodb-search-and-ai

This includes Atlas Search, Vector Search and hybrid search.

The advantage of this skill is that it doesn’t make guesses; instead, it first looks at your existing indexes and schema, describes the index it wishes to create, and then requests your approval before creating anything.

It also performs well in the read-only scenario. When the agent has no tools available for creating or updating indexes, it prints out the full index definition as JSON so that you can paste it into the Atlas UI yourself; it doesn’t simply fail silently.

Getting the routing right

As I mentioned earlier, skills are loaded based on your request. So, the words you use in your prompts are really very important.

The repository already includes several boundary test cases and trigger prompts that test which skill is activated by which sentence. Here is the table with the triggers:

Sample prompts for the MongoDB skills

For each skill I have prepared one prompt suitable for use with .NET.

mongodb-schema-design

I am migrating an ASP.NET Core API's database from SQL Server to MongoDB. The relational
model is Customers, Orders, OrderLines and Addresses, with Orders joined to
Customers on every order-history screen. Reads are about 10x writes. Design
the document model and tell me what you'd embed and what you'd reference.

You will be interviewed first. As we already saw, the model is not allowed to make suggestions without having a good understanding of the broader context. Instead, the model has to first understand if the situation involves a new project or one that is already underway, and also whether the workload is read-heavy or write-heavy. If it immediately moves on to proposing a schema, then your prompt did not provide it with sufficient detail,and you would probably end up with a broken or un-optimized schema.

mongodb-connection

My ASP.NET Core API runs 6 container instances against a 3-member replica
set. Peak is around 40 concurrent requests per instance. Review my
MongoClient setup and tell me what maxPoolSize and timeouts should be.

Every number it suggests should come with a reason, since the skill explicitly forbids adding pool parameters “without first understanding the application’s context.” Ask it to show the total server connection math (minPoolSize + 2) x members x instances so you can check it against your cluster’s limit.

mongodb-query-optimizer

This query got slow after we crossed a million orders - db.orders.find({ status: "shipped", region: "US" }).sort({ placedAt: -1 }) Explain why.

With MCP connected (see the last skill), it should call collection-indexes then run explain in queryPlanner mode to look for a COLLSCAN, then run it again with executionStats to compare documents scanned against documents returned. This should greatly improve performance and you should be able to optimize your data schemas / index.

mongodb-natural-language-querying

This one will also be widely used, as it helps you talk to your data in your natural voice.

Write an aggregation pipeline that groups orders by month for 2026, sums the total, and returns the top 5 months by revenue.

This skill is read-only by design. It basically understands your natural query and then writes find queries and read aggregations. It looks at the collection schema and a sample document first so that it doesn’t invent field names. It also won’t use $where because its instructions point out that $where prevents index usage.

mongodb-search-and-ai

I'm building retrieval for a RAG feature for over 200k support tickets in a .NET service. I need semantic search over ticket content with a filter on status and product. Recommend the approach.

It should check the existing indexes and schema before recommending anything, then describe the index it wants to create and wait for your approval.

mongodb-atlas-stream-processing

I have a Kafka topic of order events. Build an Atlas Stream Processing pipeline that does X, aggregates Y, and writes the result into an Atlas collection.

This one needs Atlas API credentials, and a connection string alone is not enough. It uses four MCP tools, atlas-streams-discover, atlas-streams-build, atlas-streams-manage and atlas-streams-teardown.

mongodb-mcp-setup

This skill is invoked when you ask Claude to set up the MongoDB MCP for you.

Set up the MongoDB MCP server for this project. My database is on Atlas and I will provide you the connection string in env variables.

You should actually run this one first, so that all the other skills will be able to interact with your database. It walks you through the three ways to provide credentials: a connection string, an Atlas API client ID and secret, or the OAuth flow.

Understanding the engineering

Designing a skill is vital. This is what I have learned in the past 10 months of using Claude as my daily AI code assistant.

For example, most people write a description for a skill, which explains what a skill is expected to do.

But a cleaner way is to write both - what the skill does, and what it should refuse to do.

A description loads at discovery time, so the description technically acts as the routing that allows the skill to load. If you write wrong descriptions, the wrong skill can load into the content - eventually polluting it, or worse, making unwanted db calls.

In this MongoDB skills repo, they test the routing, too. The same way you would write integration tests for code.

These tests never actually run the skill itself. They only check which skill fires. And it all runs in Github Actions.

Tool access is also limited per skill. The querying skill has allowed-tools: mcp__mongodb__* in its frontmatter. So, when the skill is loaded in context, only the MongoDB MCP tools can be used. Such skills are also read-only by design.

I also noticed these kinds of rules in this repository. For example, “Ask only one question at a time.” “Explain before executing.” These rules are very pragmatic and make real production / practical sense.

Verdict - Where this helps and where it doesn’t

If you are a .NET developer who is very new to MongoDB, definitely install it.

I would install it for the schema design and the query optimizer skill alone.

You should also install it if you already know MongoDB but you think the agent doesn’t, and it’s producing sloppy results. Use it if you are tired of fixing the same mistakes every time.

Another main limitation I felt was that these skills are not language-dependent. This means that none of the skills teach your AI agent to work with the C# MongoDB client or things related to entity framework core.

I would prefer if MongoDB decides to write some language-agnostic skills so that it can cleanly write C# code to manage MongoDB.

Data models, querying and stuff is exactly what these skills are meant for. But if you were hoping that these skills would generate the perfect C# driver code, then that’s up to you.

All of these skills need MCP configured to be fully useful. This is super important.

The query optimizer skill still works without the MCP, and will suggest indexes based on the query shape. But the explain tool output and the Performance Advisor need a live connection, and this means using MCP.

Please remember that skills give the agent a better starting point and more context, but you still need to review what it produces. At least for the first few times, till you get fully confident with the output.

Here is what I would do, step by step - install the plugin, connect MCP to a development database, and keep the read-only setup that the querying skill ships with until you trust it.

FAQ

Troubleshooting

Here are a few problems you might run into, and how to fix them.

The plugin installs, but the skills never trigger. Run /reload-plugins. Skills are discovered when a session starts, so a plugin you install in the middle of a session may not show up until you reload or restart.

The agent asks for a connection string even though you signed in. Only the Atlas variant uses OAuth. If the agent falls back to asking for credentials, either the sign-in didn’t complete, or you installed the self-managed plugin. Run mongodb-mcp-setup, which walks you through the three ways to provide credentials.

The query optimizer says it needs Atlas API credentials. A general performance analysis calls atlas-get-performance-advisor, which needs a projectId and a clusterName. Without those, it can still analyze a specific query, so ask it about one query by name. A request like “Find my slow queries” needs the credentials.

The wrong skill activates. This is a phrasing problem, and it happens exactly at the boundaries that MongoDB tests for. Check the prompt table above, or skip routing completely with /skill-name.

The schema suggestions feel generic. The skill is built to ask about your workload and access patterns first. Answer those questions, or point it at your query code. If you give it nothing, all it can give you is the textbook answer.

Summary

That’s all there is to know regarding MongoDB Agent Skills! They address a real issue—that agents may know MongoDB’s syntax but still fail to make good MongoDB design decisions. The package consists of seven skills and 366KB of guidance, costs about 1,050 tokens of standing context, and can be installed with a single command.

For a developer using .NET, schema design is the most important capability; if an agent simply translates your tables you’ll end up having to rewrite later, whereas an agent that properly models your documents won’t. And that decision has an impact on all the other parts of the project.

The engineering aspects of the skills are worth looking at on their own because they involve 244 test cases, instructions that have been tested by deliberately making them fail, and mechanisms that stop the evaluations from simply copying the answer. If you are developing skills for your own field, then that should be your objective.

Have you already got the plugin installed or are you still configuring your agent using the MongoDB conventions? What’s your opinion on this? Let me know in the comments below.

Thank you to MongoDB for partnering with me on this article. Check out MongoDB Agent Skills and get started today.

Happy Coding :)