286 lines
20 KiB
Markdown
286 lines
20 KiB
Markdown
# How Kimi Decides to Use Skills + MCP
|
|
|
|
## The Decision Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ USER INPUT │
|
|
│ "What's the most expensive book?" │
|
|
└────────────────────────────────────────┬────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ STEP 1: SKILL TRIGGER EVALUATION │
|
|
│ ───────────────────────────────── │
|
|
│ │
|
|
│ Kimi checks ALL skill frontmatters (always loaded): │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ postgres-analyzer skill │ │
|
|
│ │ │ │
|
|
│ │ description: "PostgreSQL database analysis and querying. Use when the │ │
|
|
│ │ user needs to explore database schema, query data, analyze table stats..." │ │
|
|
│ │ │ │
|
|
│ │ ✅ MATCH! Keywords detected: │ │
|
|
│ │ • "book" → relates to database content │ │
|
|
│ │ • "expensive" → implies analysis/comparison │ │
|
|
│ │ • "most" → implies aggregation query (MAX) │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Other skills checked (no match): │
|
|
│ • docx-skill → "book" doesn't mean document │
|
|
│ • python-skill → not a coding question │
|
|
│ • git-skill → not related to version control │
|
|
└────────────────────────────────────────┬────────────────────────────────────────────┘
|
|
│
|
|
│ ✅ TRIGGERED: postgres-analyzer
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ STEP 2: SKILL BODY LOADED │
|
|
│ ───────────────────────── │
|
|
│ │
|
|
│ Now Kimi reads pg_analyzer_skill/SKILL.md for guidance: │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ From SKILL.md: │ │
|
|
│ │ │ │
|
|
│ │ ## When to Use │ │
|
|
│ │ "- Querying data with SQL" ← ✅ THIS APPLIES │ │
|
|
│ │ "- Analyzing table statistics" ← ✅ THIS APPLIES │ │
|
|
│ │ │ │
|
|
│ │ ## Available Tools │ │
|
|
│ │ "| execute_query | Run SELECT queries | Getting specific data |" │ │
|
|
│ │ ← ✅ USE THIS TOOL │ │
|
|
│ │ │ │
|
|
│ │ ## Query Patterns │ │
|
|
│ │ "Custom analysis: Use execute_query() with appropriate SQL" │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└────────────────────────────────────────┬────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ STEP 3: MCP TOOL SELECTION │
|
|
│ ──────────────────────────── │
|
|
│ │
|
|
│ Kimi sees available MCP tools from postgres-analyzer server: │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Available Tools: │ │
|
|
│ │ │ │
|
|
│ │ 1. get_schema → "List tables and columns" │ │
|
|
│ │ ❌ Not needed - we know we need books table │ │
|
|
│ │ │ │
|
|
│ │ 2. execute_query → "Run SELECT queries" │ │
|
|
│ │ ✅ PERFECT! Can query products WHERE category='Books'│ │
|
|
│ │ │ │
|
|
│ │ 3. get_table_stats → "Table statistics + sample" │ │
|
|
│ │ ❌ Not needed - we need specific aggregation │ │
|
|
│ │ │ │
|
|
│ │ 4. analyze_column → "Deep column analysis" │ │
|
|
│ │ ❌ Not needed - we need comparison across rows │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ✅ SELECTED: execute_query │
|
|
└────────────────────────────────────────┬────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ STEP 4: QUERY GENERATION │
|
|
│ ───────────────────────── │
|
|
│ │
|
|
│ Kimi constructs SQL based on user intent + skill guidance: │
|
|
│ │
|
|
│ User wants: "most expensive book" │
|
|
│ Skill says: "Use execute_query with SELECT...WHERE category='Books'...ORDER BY" │
|
|
│ │
|
|
│ Generated SQL: │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ SELECT │ │
|
|
│ │ p.name as book_name, │ │
|
|
│ │ p.price, │ │
|
|
│ │ COALESCE(SUM(oi.quantity), 0) as total_sold │ │
|
|
│ │ FROM products p │ │
|
|
│ │ LEFT JOIN order_items oi ON p.id = oi.product_id │ │
|
|
│ │ WHERE p.category = 'Books' │ │
|
|
│ │ GROUP BY p.id, p.name, p.price │ │
|
|
│ │ ORDER BY p.price DESC │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
└────────────────────────────────────────┬────────────────────────────────────────────┘
|
|
│
|
|
│ MCP Protocol Call
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ STEP 5: EXECUTION │
|
|
│ ───────────────── │
|
|
│ │
|
|
│ MCP Server receives: │
|
|
│ { │
|
|
│ "tool": "execute_query", │
|
|
│ "arguments": { │
|
|
│ "query": "SELECT p.name, p.price...", │
|
|
│ "limit": 100 │
|
|
│ } │
|
|
│ } │
|
|
│ │
|
|
│ → PostgreSQL executes query │
|
|
│ → Returns results │
|
|
│ → MCP formats as markdown table │
|
|
│ → Returns to Kimi │
|
|
└────────────────────────────────────────┬────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ STEP 6: RESPONSE SYNTHESIS │
|
|
│ ────────────────────────── │
|
|
│ │
|
|
│ Raw data from MCP: │
|
|
│ | book_name | price | total_sold | │
|
|
│ | Novel Collection| 65.00 | 212 | │
|
|
│ | Science Fiction | 55.00 | 176 | │
|
|
│ | Python Book | 45.00 | 213 | │
|
|
│ │
|
|
│ Kimi synthesizes natural language response: │
|
|
│ │
|
|
│ "The most expensive book is the Novel Collection at $65.00. Interestingly, │
|
|
│ despite being the priciest, it sold 212 copies - nearly matching the cheaper │
|
|
│ Python Programming Book (213 copies) which costs $20 less." │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Key Decision Points
|
|
|
|
### 1. Why Not a General Answer?
|
|
|
|
| Approach | Would Kimi Use It? | Why? |
|
|
|----------|-------------------|------|
|
|
| General knowledge ("Books usually cost $10-30") | ❌ No | User asked about THEIR database, not general market |
|
|
| Web search | ❌ No | Question is specific to user's private data |
|
|
| File search | ❌ No | No files mentioned, data is in database |
|
|
| **MCP + Skill** | ✅ Yes | Only way to access user's PostgreSQL database |
|
|
|
|
### 2. What If The Question Was Different?
|
|
|
|
| User Question | Skill Triggered | Tool Used | Reason |
|
|
|---------------|-----------------|-----------|--------|
|
|
| "What's in my database?" | postgres-analyzer | `get_schema` | Discovery |
|
|
| "Analyze the users table" | postgres-analyzer | `get_table_stats` | Overview |
|
|
| "Tell me about the email column" | postgres-analyzer | `analyze_column` | Deep dive |
|
|
| "Show top customers" | postgres-analyzer | `execute_query` | Custom analysis |
|
|
| "Write a Python script" | python-skill | N/A (no MCP) | Different domain |
|
|
| "Fix this git issue" | git-skill | N/A (no MCP) | Different domain |
|
|
|
|
---
|
|
|
|
## How Triggers Work
|
|
|
|
### Frontmatter Matching (Always Active)
|
|
|
|
```yaml
|
|
---
|
|
name: postgres-analyzer
|
|
description: PostgreSQL database analysis and querying.
|
|
Use when the user needs to:
|
|
1. Explore database schema
|
|
2. Query data
|
|
3. Analyze table statistics
|
|
4. Get insights from PostgreSQL
|
|
Requires PG_CONNECTION_STRING environment variable.
|
|
---
|
|
```
|
|
|
|
Kimi evaluates:
|
|
- **Keywords**: "database", "table", "query", "SQL", "analyze", "expensive" (implies comparison)
|
|
- **Context**: "book" in context of data implies database content, not a document
|
|
- **Intent**: "what's the most" implies aggregation query (MAX/ORDER BY)
|
|
|
|
### Skill Body (Loaded After Trigger)
|
|
|
|
The SKILL.md provides:
|
|
1. **Workflow guidance** → "Use execute_query for specific data"
|
|
2. **Tool selection** → "execute_query: Run SELECT queries"
|
|
3. **SQL patterns** → "Use WHERE, GROUP BY, ORDER BY for analysis"
|
|
|
|
---
|
|
|
|
## Why This Is Powerful
|
|
|
|
### Without MCP + Skills
|
|
|
|
```
|
|
User: "What's the most expensive book?"
|
|
Kimi: "I don't have access to your database.
|
|
Please provide the data or export it to a file."
|
|
```
|
|
|
|
### With MCP + Skills
|
|
|
|
```
|
|
User: "What's the most expensive book?"
|
|
Kimi: [Connects via MCP] → [Queries database] → [Analyzes results]
|
|
"The most expensive book is Novel Collection at $65.
|
|
It sold 212 copies, nearly matching the cheaper Python
|
|
book at 213 copies - showing strong demand despite
|
|
the premium price."
|
|
```
|
|
|
|
---
|
|
|
|
## Debug: How to See What's Happening
|
|
|
|
### 1. Check MCP Connection
|
|
|
|
```bash
|
|
kimi
|
|
|
|
# In Kimi shell:
|
|
/mcp
|
|
|
|
# Shows:
|
|
# Connected MCP servers:
|
|
# postgres
|
|
# Tools: get_schema, execute_query, get_table_stats, analyze_column
|
|
```
|
|
|
|
### 2. Check Skill Trigger
|
|
|
|
```bash
|
|
# In Kimi shell, ask with verbose:
|
|
# (Kimi will show thinking process)
|
|
|
|
User: What's the most expensive book?
|
|
|
|
[Thinking: User asking about "book" - checking skills...]
|
|
[Thinking: postgres-analyzer skill matches (database content)]
|
|
[Thinking: Loading postgres-analyzer skill...]
|
|
[Thinking: User wants MAX(price) WHERE category='Books']
|
|
[Thinking: execute_query tool is appropriate]
|
|
[Thinking: Generating SQL: SELECT name, MAX(price)...]
|
|
```
|
|
|
|
### 3. Test Tool Directly
|
|
|
|
You can force a specific tool:
|
|
|
|
```
|
|
User: Use the execute_query tool to find the most expensive book
|
|
```
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
| Component | Role | When Loaded |
|
|
|-----------|------|-------------|
|
|
| **Skill Frontmatter** | Trigger detection | Always (metadata only) |
|
|
| **Skill Body** | Usage guidance | Only when triggered |
|
|
| **MCP Tools** | Execution capability | When MCP server connected |
|
|
|
|
The magic happens when:
|
|
1. **Frontmatter** matches user intent → Triggers skill
|
|
2. **Skill body** guides tool selection → Chooses MCP tool
|
|
3. **MCP server** executes safely → Returns structured data
|
|
4. **Kimi synthesizes** → Natural language response with insights
|