# 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