Decision Table
@@ -70,7 +70,7 @@ For Qdrant, a skill.md might include:
-This prevents the agent from using `client.search()` (deprecated), creating a collection per user (anti-pattern), or misconfiguring sparse vectors (common mistake). The guidance for all of these exists across Qdrant's tutorials, docs, and community discussions. However, finding it requires existing Qdrant context because you need to already know enough to ask the right questions. Skills package that accumulated product intuition so agents don't need to build it from scratch.
+This prevents the agent from using `client.search()` (deprecated), creating a collection per user (anti-pattern), or misconfiguring sparse vectors (common mistake). The guidance for all of these exists across Qdrant's tutorials, docs, and community discussions. However, finding it requires existing Qdrant context because you need to already know enough to ask the right questions. Skills package has accumulated product intuition so agents don't need to build it from scratch.
## What REPL-First MCP Gives You
@@ -90,9 +90,9 @@ The agent discovers what exists by asking the system directly. No tool for "list
## Why Neither Alone Works
-**skill.md without REPL:** The agent knows *how* to use `query_points` but not *what* to query. It guesses collection names. It assumes payload fields. It writes syntactically correct code that fails at runtime.
+**SKILL.md without REPL:** The agent knows *how* to use `query_points` but not *what* to query. It guesses collection names. It assumes payload fields. It writes syntactically correct code that fails at runtime.
-**REPL without skill.md:** The agent can discover what exists but still uses deprecated methods. It creates collections with wrong configurations. It makes the same mistakes it would have made without the REPL, just with more information about the data.
+**REPL without SKILL.md:** The agent can discover what exists but still uses deprecated methods. It creates collections with wrong configurations. It makes the same mistakes it would have made without the REPL, just with more information about the data.
Together, the agent workflow looks like this:
@@ -100,7 +100,7 @@ Together, the agent workflow looks like this:
-
1. Read skill.md
+
1. Read SKILL.md
"Use query_points, not search"
"Never one collection per user"
@@ -124,11 +124,11 @@ Together, the agent workflow looks like this:
-The skill.md prevents known mistakes. The REPL handles environment-specific discovery. Both failure modes addressed.
+The SKILL.md prevents known mistakes. The REPL handles environment-specific discovery. Both failure modes are addressed.
## Implementation
-The skill.md is just a file you drop into your project. The REPL is an MCP tool. A minimal implementation:
+The SKILL.md is just a file you drop into your project. The REPL is an MCP tool. A minimal implementation:
```python
@server.call_tool()
@@ -150,7 +150,7 @@ State persists between calls. The agent builds up context incrementally.
This isn't specific to Qdrant. Any API with:
-- Deprecated methods or migration paths → needs skill.md
+- Deprecated methods or migration paths → needs SKILL.md
- User-specific state (databases, collections, schemas) → needs REPL
The two approaches complement because they address orthogonal problems. Static knowledge for static mistakes. Dynamic access for dynamic discovery.
@@ -159,9 +159,9 @@ Most developer tools need both.
## This Doesn't Make It Easy
-Adding skill.md and a REPL doesn't mean agents suddenly work flawlessly. They still hallucinate. They still misunderstand requirements. They still write code that technically runs but doesn't do what you wanted.
+Adding SKILL.md and a REPL doesn't mean agents suddenly work flawlessly. They still hallucinate. They still misunderstand requirements. They still write code that technically runs but doesn't do what you wanted.
-What these tools do is eliminate *unnecessary* failures. The agent won't fail because it used a deprecated method. That's a solved problem with skill.md. It won't fail because it guessed a collection name. The REPL lets it check. But it can still fail because it misunderstood what you meant by "similar products" or because the embedding model you're using doesn't capture the semantics you care about.
+What these tools do is eliminate *unnecessary* failures. The agent won't fail because it used a deprecated method. That's a solved problem with SKILL.md. It won't fail because it guessed a collection name. The REPL lets it check. But it can still fail because it misunderstood what you meant by "similar products" or because the embedding model you're using doesn't capture the semantics you care about.
You might ask: why not just pull context from docs automatically? Tools like [mcp-code-snippets](https://github.com/qdrant/mcp-code-snippets), Qdrant's MCP server for searching documentation and code examples, solve a real problem, but they solve a different one. Auto-generated context gives you API surface area. A SKILL.md gives you judgment. "Don't create one collection per user" isn't obvious from any API reference. "BM25 needs Modifier.IDF" is documented, but you have to know to look for it. Skills distill that intuition into a format agents can use immediately. The two approaches aren't in competition. Use both.