{"id":"630b8a33-1d1f-4628-85df-ef55c6d5a344","entityType":"agent","slug":"clawhub-wangjipeng977-text-to-sql","name":"Text To Sql","canonicalUrl":"https://www.xpersona.co/agent/clawhub-wangjipeng977-text-to-sql","canonicalPath":"/agent/clawhub-wangjipeng977-text-to-sql","generatedAt":"2026-10-10T04:38:22.821Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:35:17.032Z","emptyReason":null},"description":"Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to qu...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s179qwqch3yp9926afz4rxbz0h85z9mm:text-to-sql","sourceUrl":"https://clawhub.ai/wangjipeng977/text-to-sql","homepage":"https://clawhub.ai/wangjipeng977/skills/text-to-sql","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/wangjipeng977/text-to-sql","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/wangjipeng977/skills/text-to-sql","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":66,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Text To Sql technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:35:17.032Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:35:17.032Z","emptyReason":null},"stars":null,"forks":null,"downloads":1973,"packageName":null,"latestVersion":"2.0.3","tractionLabel":"2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:35:17.032Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T21:35:17.032Z","lastCrawledAt":"2026-10-09T21:35:17.032Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T21:35:17.032Z","lastVerifiedAt":null,"highlights":[{"version":"2.0.3","createdAt":"2026-05-29T09:36:50.444Z","changelog":"Initial release","fileCount":9,"zipByteSize":12320},{"version":"1.0.8","createdAt":"2026-05-28T18:19:42.284Z","changelog":"Retry publish","fileCount":9,"zipByteSize":12316},{"version":"10.0.0","createdAt":"2026-05-28T10:08:13.780Z","changelog":"Retry at high version","fileCount":9,"zipByteSize":12150},{"version":"99.0.0","createdAt":"2026-05-28T02:58:39.783Z","changelog":"Initial release","fileCount":9,"zipByteSize":12125},{"version":"1.2.0","createdAt":"2026-05-27T22:53:31.561Z","changelog":"Initial release","fileCount":9,"zipByteSize":11210},{"version":"2.1.0","createdAt":"2026-05-27T19:50:58.505Z","changelog":"Retry publish with new version","fileCount":9,"zipByteSize":12106},{"version":"999.0.0","createdAt":"2026-05-27T06:34:55.739Z","changelog":"Initial release","fileCount":9,"zipByteSize":12061},{"version":"9.9.9","createdAt":"2026-05-26T22:22:13.224Z","changelog":"Initial release","fileCount":9,"zipByteSize":12137}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s179qwqch3yp9926afz4rxbz0h85z9mm:text-to-sql","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s179qwqch3yp9926afz4rxbz0h85z9mm:text-to-sql` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/wangjipeng977/text-to-sql before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T04:38:22.817Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wangjipeng977-text-to-sql/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:35:17.032Z","emptyReason":null},"readme":"Skill: Text To Sql\n\nOwner: wangjipeng977\n\nSummary: Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to qu...\n\nTags: latest:999.0.0\n\nVersion history:\n\nv2.0.3 | 2026-05-29T09:36:50.444Z | user\n\nInitial release\n\nv1.0.8 | 2026-05-28T18:19:42.284Z | user\n\nRetry publish\n\nv10.0.0 | 2026-05-28T10:08:13.780Z | user\n\nRetry at high version\n\nv99.0.0 | 2026-05-28T02:58:39.783Z | user\n\nInitial release\n\nv1.2.0 | 2026-05-27T22:53:31.561Z | user\n\nInitial release\n\nv2.1.0 | 2026-05-27T19:50:58.505Z | user\n\nRetry publish with new version\n\nv999.0.0 | 2026-05-27T06:34:55.739Z | user\n\nInitial release\n\nv9.9.9 | 2026-05-26T22:22:13.224Z | user\n\nInitial release\n\nv6.0.1 | 2026-05-25T21:53:56.515Z | user\n\nInitial release\n\nv1.0.3 | 2026-05-25T20:51:54.691Z | user\n\nRetry publish\n\nv6.0.0 | 2026-05-25T16:47:42.097Z | user\n\nUpdate skill\n\nv1.5.0 | 2026-05-25T03:11:58.350Z | user\n\nRetry release v1.5\n\nv1.0.5 | 2026-05-20T20:15:21.296Z | user\n\nRetry with new version\n\nv5.0.0 | 2026-05-20T19:14:10.385Z | user\n\nRetry publish\n\nv4.0.0 | 2026-05-20T06:54:03.793Z | user\n\nInitial release\n\nv3.0.0 | 2026-05-19T20:42:23.399Z | user\n\nInitial release\n\nv2.0.1 | 2026-05-19T18:38:20.742Z | user\n\nRetry with bumped version\n\nv1.0.2 | 2026-05-19T17:36:57.875Z | user\n\nRetry publication\n\nv1.1.0 | 2026-05-19T13:30:01.915Z | user\n\nInitial release\n\nv2.0.0 | 2026-05-19T11:27:59.610Z | user\n\nRetry with new version\n\nv1.0.1 | 2026-05-19T05:56:08.293Z | user\n\nUpdate README with real Features and 功能特性 content\n\nv1.0.0 | 2026-05-19T05:25:17.069Z | user\n\nInitial release\n\nArchive index:\n\nArchive v2.0.3: 9 files, 12320 bytes\n\nFiles: CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (2412b), README.md (2628b), references/index.md (125b), skill-card.md (2398b), SKILL.md (6327b), tests/test_skill.py (12119b), _meta.json (130b)\n\nFile v2.0.3:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0.1\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v2.0.3:README.md\n\n# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode shows different JOIN strategies or subquery vs CTE approaches\n\n## Quick Start\n\n```bash\n# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### Usage\n\n```\n/text-to-sql\n```\n\nProvide schema (table names + columns) and describe what data you want in English.\n\n```\n/text-to-sql/explain\n```\n\nOutputs query with inline comments explaining each clause — for learning purposes.\n\n```\n/text-to-sql/alternatives\n```\n\nShows 2-3 different query approaches for the same question.\n\n## Modes\n\n| Mode | Description |\n|------|-------------|\n| `/text-to-sql` | Converts natural language to SQL query |\n| `/text-to-sql/explain` | Query with inline comments explaining each clause |\n| `/text-to-sql/alternatives` | 2-3 alternative query strategies |\n\n## Examples\n\n| Request | Query |\n|---------|-------|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | `ORDER BY total DESC LIMIT 10` added |\n| \"revenue by month\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| No schema provided | Asks for schema first — doesn't guess column names |\n\n## Directory Structure\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\nFile v2.0.3:_meta.json\n\n{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"2.0.3\",\n \"publishedAt\": 1780047410444\n}\n\nFile v2.0.3:references/index.md\n\n# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed.\n\nFile v2.0.3:CHANGELOG.md\n\n# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release\n\nFile v2.0.3:CONTRIBUTING.md\n\n# Contributing to `User Describes Data`\n\nThank you for your interest in contributing! Please follow these steps to set up your development environment and submit changes.\n\n## Development Setup\n\n```bash\n# 1. Fork the repository on GitHub\n\n# 2. Clone your fork\ngit clone https://github.com//User Describes Data.git\ncd User Describes Data\n\n# 3. Install dependencies (if any)\npip install -r scripts/requirements.txt\n\n# 4. Run the self-audit to verify quality\npython scripts/audit_skill.py .\n```\n\n## Workflow\n\nWe use a standard feature branch workflow:\n\n```bash\n# 1. Create a new branch from main\ngit checkout -b feat/\n\n# 2. Make your changes\n# - Follow the SKILL.md structure standards\n# - Keep SKILL.md body in English\n# - Do not hardcode API keys or secrets\n\n# 3. Run the audit to check for issues\npython scripts/audit_skill.py .\n\n# 4. Commit your changes\ngit add .\ngit commit -m \"feat(text-to-sql): add \"\n\n# 5. Push to your fork\ngit push origin feat/\n\n# 6. Open a Pull Request on GitHub\n# - Title: feat(text-to-sql): add \n# - Description: What + Why + Testing\n```\n\n## Code Standards\n\n- **SKILL.md**: Follow the YAML frontmatter standard (name, description, license, metadata)\n- **Scripts**: Must include shebang, requirements.txt, and graceful error handling\n- **Language**: SKILL.md body must be in English; reference docs in English\n- **No secrets**: Never commit API keys, tokens, or credentials\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] `audit_skill.py` exits with code 0 or 2\n- [ ] `validate_skills.py` exits with code 0\n- [ ] README.md and README_zh.md are both present\n- [ ] CONTRIBUTING.md is present\n- [ ] .gitignore is present\n- [ ] No hardcoded secrets anywhere in the codebase\n\n## Reporting Issues\n\nPlease report issues via GitHub Issues with:\n\n1. **What you expected to happen**\n2. **What actually happened**\n3. **Steps to reproduce**\n4. **Environment** (OS, Python version, etc.)\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under the MIT License.\n\nFile v2.0.3:README_zh.md\n\n# Text To Sql\n\n[English](./README.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![版本](https://img.shields.io/badge/version-1.0-blue)\n\n> 将自然语言描述转换为语法正确的 SQL 查询\n\n## 解决什么问题\n\n非技术用户知道想要什么数据（\"显示前 10 客户每月收入\"）但不会写 SQL。这个技能弥合这个差距——接收 schema + 自然语言请求，生成带表别名、正确 JOIN 和 GROUP BY 的语法正确的查询。\n\n**触发条件：** 数据库 schema + 自然语言问题 + 写 SQL 意图。\n\n## 功能特性\n\n- **Schema 感知翻译** — 写查询前先询问表/列 schema（绝不虚构列名）\n- **完整 SQL 覆盖** — SELECT、WHERE、GROUP BY、ORDER BY、LIMIT、JOIN（INNER、LEFT、RIGHT）、聚合函数\n- **通俗英文解释** — 同时输出查询和一行描述其作用\n- **多方法选项** — `/alternatives` 模式展示不同 JOIN 策略或子查询 vs CTE 方法\n\n## 快速开始\n\n```bash\n# 通过 ClawHub 安装\nclawhub install text-to-sql\n\n# 或手动复制\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### 使用方法\n\n```\n/text-to-sql\n```\n\n提供 schema（表名 + 列）并用英文描述想要什么数据。\n\n```\n/text-to-sql/explain\n```\n\n输出带内联注释的查询，解释每个子句——用于学习。\n\n```\n/text-to-sql/alternatives\n```\n\n展示同一问题的 2-3 种不同查询方法。\n\n## 工作模式\n\n| 模式 | 说明 |\n|------|------|\n| `/text-to-sql` | 将自然语言转换为 SQL 查询 |\n| `/text-to-sql/explain` | 带内联注释的查询，解释每个子句 |\n| `/text-to-sql/alternatives` | 2-3 种替代查询策略 |\n\n## 示例\n\n| 请求 | 查询 |\n|---------|-------|\n| Schema: `users(id, name)`，`orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"前 10 客户\" | 添加 `ORDER BY total DESC LIMIT 10` |\n| \"按月收入\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| 未提供 schema | 先询问 schema——不猜测列名 |\n\n## 目录结构\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL 方言速查表、JOIN 指南、意图映射\n└── tests/\n```\n\n## 许可证\n\nMIT 许可证 — 详见 [LICENSE](LICENSE)。\n\nFile v2.0.3:skill-card.md\n\n## Description:
\nConverts natural-language data requests and user-provided database schema into syntactically correct SQL queries, with optional explanations or alternative query approaches.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[wangjipeng977](https://clawhub.ai/user/wangjipeng977)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, analysts, and non-technical users use this skill to turn an English data request plus an existing database schema into SQL. It is intended for query drafting and learning, not for executing SQL or validating database results.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Security evidence marks the release as suspicious because a bundled helper may launch nested review with broad filesystem and network authority.
\nMitigation: Install only if the publisher is trusted, review the helper before use, prefer non-yolo operation when full-access review is not needed, and reserve permission-sensitive workflows for authorized operators.
\nRisk: Generated SQL can be incorrect, inefficient, or unsafe if the supplied schema or intent is incomplete.
\nMitigation: Review generated queries before execution, confirm table and column names against the real schema, and test against non-production data where possible.
\n\n\n## Reference(s):
\n- [ClawHub release page](https://clawhub.ai/wangjipeng977/text-to-sql)
\n- [Metadata source: MiniMax-AI skills](https://github.com/MiniMax-AI/skills)
\n- [text-to-sql references index](references/index.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [Code, Markdown, Guidance]
\n**Output Format:** [Markdown containing SQL code blocks, inline SQL comments, and short plain-English explanations]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [The skill asks for schema details before drafting a query when the schema is missing.]
\n\n## Skill Version(s):
\n2.0.3 (source: server release metadata; artifact frontmatter and changelog list 1.0.1)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v1.0.8: 9 files, 12316 bytes\n\nFiles: CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (2412b), README.md (2628b), references/index.md (125b), skill-card.md (2453b), SKILL.md (6327b), tests/test_skill.py (12119b), _meta.json (130b)\n\nFile v1.0.8:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0.1\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v1.0.8:README.md\n\n# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode shows different JOIN strategies or subquery vs CTE approaches\n\n## Quick Start\n\n```bash\n# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### Usage\n\n```\n/text-to-sql\n```\n\nProvide schema (table names + columns) and describe what data you want in English.\n\n```\n/text-to-sql/explain\n```\n\nOutputs query with inline comments explaining each clause — for learning purposes.\n\n```\n/text-to-sql/alternatives\n```\n\nShows 2-3 different query approaches for the same question.\n\n## Modes\n\n| Mode | Description |\n|------|-------------|\n| `/text-to-sql` | Converts natural language to SQL query |\n| `/text-to-sql/explain` | Query with inline comments explaining each clause |\n| `/text-to-sql/alternatives` | 2-3 alternative query strategies |\n\n## Examples\n\n| Request | Query |\n|---------|-------|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | `ORDER BY total DESC LIMIT 10` added |\n| \"revenue by month\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| No schema provided | Asks for schema first — doesn't guess column names |\n\n## Directory Structure\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\nFile v1.0.8:_meta.json\n\n{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"1.0.8\",\n \"publishedAt\": 1779992382284\n}\n\nFile v1.0.8:references/index.md\n\n# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed.\n\nFile v1.0.8:CHANGELOG.md\n\n# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release\n\nFile v1.0.8:CONTRIBUTING.md\n\n# Contributing to `User Describes Data`\n\nThank you for your interest in contributing! Please follow these steps to set up your development environment and submit changes.\n\n## Development Setup\n\n```bash\n# 1. Fork the repository on GitHub\n\n# 2. Clone your fork\ngit clone https://github.com//User Describes Data.git\ncd User Describes Data\n\n# 3. Install dependencies (if any)\npip install -r scripts/requirements.txt\n\n# 4. Run the self-audit to verify quality\npython scripts/audit_skill.py .\n```\n\n## Workflow\n\nWe use a standard feature branch workflow:\n\n```bash\n# 1. Create a new branch from main\ngit checkout -b feat/\n\n# 2. Make your changes\n# - Follow the SKILL.md structure standards\n# - Keep SKILL.md body in English\n# - Do not hardcode API keys or secrets\n\n# 3. Run the audit to check for issues\npython scripts/audit_skill.py .\n\n# 4. Commit your changes\ngit add .\ngit commit -m \"feat(text-to-sql): add \"\n\n# 5. Push to your fork\ngit push origin feat/\n\n# 6. Open a Pull Request on GitHub\n# - Title: feat(text-to-sql): add \n# - Description: What + Why + Testing\n```\n\n## Code Standards\n\n- **SKILL.md**: Follow the YAML frontmatter standard (name, description, license, metadata)\n- **Scripts**: Must include shebang, requirements.txt, and graceful error handling\n- **Language**: SKILL.md body must be in English; reference docs in English\n- **No secrets**: Never commit API keys, tokens, or credentials\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] `audit_skill.py` exits with code 0 or 2\n- [ ] `validate_skills.py` exits with code 0\n- [ ] README.md and README_zh.md are both present\n- [ ] CONTRIBUTING.md is present\n- [ ] .gitignore is present\n- [ ] No hardcoded secrets anywhere in the codebase\n\n## Reporting Issues\n\nPlease report issues via GitHub Issues with:\n\n1. **What you expected to happen**\n2. **What actually happened**\n3. **Steps to reproduce**\n4. **Environment** (OS, Python version, etc.)\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under the MIT License.\n\nFile v1.0.8:README_zh.md\n\n# Text To Sql\n\n[English](./README.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![版本](https://img.shields.io/badge/version-1.0-blue)\n\n> 将自然语言描述转换为语法正确的 SQL 查询\n\n## 解决什么问题\n\n非技术用户知道想要什么数据（\"显示前 10 客户每月收入\"）但不会写 SQL。这个技能弥合这个差距——接收 schema + 自然语言请求，生成带表别名、正确 JOIN 和 GROUP BY 的语法正确的查询。\n\n**触发条件：** 数据库 schema + 自然语言问题 + 写 SQL 意图。\n\n## 功能特性\n\n- **Schema 感知翻译** — 写查询前先询问表/列 schema（绝不虚构列名）\n- **完整 SQL 覆盖** — SELECT、WHERE、GROUP BY、ORDER BY、LIMIT、JOIN（INNER、LEFT、RIGHT）、聚合函数\n- **通俗英文解释** — 同时输出查询和一行描述其作用\n- **多方法选项** — `/alternatives` 模式展示不同 JOIN 策略或子查询 vs CTE 方法\n\n## 快速开始\n\n```bash\n# 通过 ClawHub 安装\nclawhub install text-to-sql\n\n# 或手动复制\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### 使用方法\n\n```\n/text-to-sql\n```\n\n提供 schema（表名 + 列）并用英文描述想要什么数据。\n\n```\n/text-to-sql/explain\n```\n\n输出带内联注释的查询，解释每个子句——用于学习。\n\n```\n/text-to-sql/alternatives\n```\n\n展示同一问题的 2-3 种不同查询方法。\n\n## 工作模式\n\n| 模式 | 说明 |\n|------|------|\n| `/text-to-sql` | 将自然语言转换为 SQL 查询 |\n| `/text-to-sql/explain` | 带内联注释的查询，解释每个子句 |\n| `/text-to-sql/alternatives` | 2-3 种替代查询策略 |\n\n## 示例\n\n| 请求 | 查询 |\n|---------|-------|\n| Schema: `users(id, name)`，`orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"前 10 客户\" | 添加 `ORDER BY total DESC LIMIT 10` |\n| \"按月收入\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| 未提供 schema | 先询问 schema——不猜测列名 |\n\n## 目录结构\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL 方言速查表、JOIN 指南、意图映射\n└── tests/\n```\n\n## 许可证\n\nMIT 许可证 — 详见 [LICENSE](LICENSE)。\n\nFile v1.0.8:skill-card.md\n\n## Description:
\nConverts natural-language data requests and user-provided database schemas into syntactically correct SQL queries.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[wangjipeng977](https://clawhub.ai/user/wangjipeng977)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nExternal users, developers, and data practitioners use this skill to turn plain-English data questions plus an explicit database schema into SQL queries, explanatory SQL, or alternative query approaches.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Generated SQL may be syntactically invalid or may not match the user's intended database semantics.
\nMitigation: Review generated SQL against the supplied schema and test it in a safe environment before running it on real data.
\nRisk: Users may disclose sensitive schema details or operational context while requesting a query.
\nMitigation: Provide only the schema details needed for the query and avoid sharing credentials, secrets, or unnecessary sensitive data.
\nRisk: Running generated SQL directly against production or sensitive databases could produce unintended reads, updates, or misleading results.
\nMitigation: Treat the skill output as SQL-writing assistance only; the security evidence says the skill does not execute queries, and users should review SQL before execution.
\n\n\n## Reference(s):
\n- [Text To Sql reference index](artifact/references/index.md)
\n- [Source repository from skill metadata](https://github.com/MiniMax-AI/skills)
\n- [ClawHub skill page](https://clawhub.ai/wangjipeng977/text-to-sql)
\n\n\n## Skill Output:
\n**Output Type(s):** [Code, Markdown, Guidance]
\n**Output Format:** [Markdown containing SQL code blocks and brief natural-language explanations]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May include inline SQL comments or 2-3 alternative query approaches depending on the selected mode.]
\n\n## Skill Version(s):
\n1.0.8 (source: server release metadata, published 2026-05-28T18:19:42.284Z)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v10.0.0: 9 files, 12150 bytes\n\nFiles: CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (2412b), README.md (2628b), references/index.md (125b), skill-card.md (2078b), SKILL.md (6327b), tests/test_skill.py (12119b), _meta.json (131b)\n\nFile v10.0.0:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0.1\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v10.0.0:README.md\n\n# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode shows different JOIN strategies or subquery vs CTE approaches\n\n## Quick Start\n\n```bash\n# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### Usage\n\n```\n/text-to-sql\n```\n\nProvide schema (table names + columns) and describe what data you want in English.\n\n```\n/text-to-sql/explain\n```\n\nOutputs query with inline comments explaining each clause — for learning purposes.\n\n```\n/text-to-sql/alternatives\n```\n\nShows 2-3 different query approaches for the same question.\n\n## Modes\n\n| Mode | Description |\n|------|-------------|\n| `/text-to-sql` | Converts natural language to SQL query |\n| `/text-to-sql/explain` | Query with inline comments explaining each clause |\n| `/text-to-sql/alternatives` | 2-3 alternative query strategies |\n\n## Examples\n\n| Request | Query |\n|---------|-------|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | `ORDER BY total DESC LIMIT 10` added |\n| \"revenue by month\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| No schema provided | Asks for schema first — doesn't guess column names |\n\n## Directory Structure\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\nFile v10.0.0:_meta.json\n\n{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"10.0.0\",\n \"publishedAt\": 1779962893780\n}\n\nFile v10.0.0:references/index.md\n\n# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed.\n\nFile v10.0.0:CHANGELOG.md\n\n# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release\n\nFile v10.0.0:CONTRIBUTING.md\n\n# Contributing to `User Describes Data`\n\nThank you for your interest in contributing! Please follow these steps to set up your development environment and submit changes.\n\n## Development Setup\n\n```bash\n# 1. Fork the repository on GitHub\n\n# 2. Clone your fork\ngit clone https://github.com//User Describes Data.git\ncd User Describes Data\n\n# 3. Install dependencies (if any)\npip install -r scripts/requirements.txt\n\n# 4. Run the self-audit to verify quality\npython scripts/audit_skill.py .\n```\n\n## Workflow\n\nWe use a standard feature branch workflow:\n\n```bash\n# 1. Create a new branch from main\ngit checkout -b feat/\n\n# 2. Make your changes\n# - Follow the SKILL.md structure standards\n# - Keep SKILL.md body in English\n# - Do not hardcode API keys or secrets\n\n# 3. Run the audit to check for issues\npython scripts/audit_skill.py .\n\n# 4. Commit your changes\ngit add .\ngit commit -m \"feat(text-to-sql): add \"\n\n# 5. Push to your fork\ngit push origin feat/\n\n# 6. Open a Pull Request on GitHub\n# - Title: feat(text-to-sql): add \n# - Description: What + Why + Testing\n```\n\n## Code Standards\n\n- **SKILL.md**: Follow the YAML frontmatter standard (name, description, license, metadata)\n- **Scripts**: Must include shebang, requirements.txt, and graceful error handling\n- **Language**: SKILL.md body must be in English; reference docs in English\n- **No secrets**: Never commit API keys, tokens, or credentials\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] `audit_skill.py` exits with code 0 or 2\n- [ ] `validate_skills.py` exits with code 0\n- [ ] README.md and README_zh.md are both present\n- [ ] CONTRIBUTING.md is present\n- [ ] .gitignore is present\n- [ ] No hardcoded secrets anywhere in the codebase\n\n## Reporting Issues\n\nPlease report issues via GitHub Issues with:\n\n1. **What you expected to happen**\n2. **What actually happened**\n3. **Steps to reproduce**\n4. **Environment** (OS, Python version, etc.)\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under the MIT License.\n\nFile v10.0.0:README_zh.md\n\n# Text To Sql\n\n[English](./README.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![版本](https://img.shields.io/badge/version-1.0-blue)\n\n> 将自然语言描述转换为语法正确的 SQL 查询\n\n## 解决什么问题\n\n非技术用户知道想要什么数据（\"显示前 10 客户每月收入\"）但不会写 SQL。这个技能弥合这个差距——接收 schema + 自然语言请求，生成带表别名、正确 JOIN 和 GROUP BY 的语法正确的查询。\n\n**触发条件：** 数据库 schema + 自然语言问题 + 写 SQL 意图。\n\n## 功能特性\n\n- **Schema 感知翻译** — 写查询前先询问表/列 schema（绝不虚构列名）\n- **完整 SQL 覆盖** — SELECT、WHERE、GROUP BY、ORDER BY、LIMIT、JOIN（INNER、LEFT、RIGHT）、聚合函数\n- **通俗英文解释** — 同时输出查询和一行描述其作用\n- **多方法选项** — `/alternatives` 模式展示不同 JOIN 策略或子查询 vs CTE 方法\n\n## 快速开始\n\n```bash\n# 通过 ClawHub 安装\nclawhub install text-to-sql\n\n# 或手动复制\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### 使用方法\n\n```\n/text-to-sql\n```\n\n提供 schema（表名 + 列）并用英文描述想要什么数据。\n\n```\n/text-to-sql/explain\n```\n\n输出带内联注释的查询，解释每个子句——用于学习。\n\n```\n/text-to-sql/alternatives\n```\n\n展示同一问题的 2-3 种不同查询方法。\n\n## 工作模式\n\n| 模式 | 说明 |\n|------|------|\n| `/text-to-sql` | 将自然语言转换为 SQL 查询 |\n| `/text-to-sql/explain` | 带内联注释的查询，解释每个子句 |\n| `/text-to-sql/alternatives` | 2-3 种替代查询策略 |\n\n## 示例\n\n| 请求 | 查询 |\n|---------|-------|\n| Schema: `users(id, name)`，`orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"前 10 客户\" | 添加 `ORDER BY total DESC LIMIT 10` |\n| \"按月收入\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| 未提供 schema | 先询问 schema——不猜测列名 |\n\n## 目录结构\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL 方言速查表、JOIN 指南、意图映射\n└── tests/\n```\n\n## 许可证\n\nMIT 许可证 — 详见 [LICENSE](LICENSE)。\n\nFile v10.0.0:skill-card.md\n\n## Description:
\nConverts natural language requests and user-provided database schemas into syntactically correct SQL queries, with optional explanations or alternative query approaches.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[wangjipeng977](https://clawhub.ai/user/wangjipeng977)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, analysts, and non-technical users use this skill to translate a natural-language data question plus an existing database schema into SQL. It is intended to draft queries, explain clauses, or compare alternative query strategies without executing database operations.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Generated SQL may be syntactically valid but still incorrect for the user's real database or business intent.
\nMitigation: Review generated SQL before running it on a real database.
\nRisk: User-provided schemas or examples may contain sensitive production information.
\nMitigation: Avoid pasting sensitive production data unless the user is comfortable sharing it with the agent.
\n\n\n## Reference(s):
\n- [Artifact reference index](artifact/references/index.md)
\n- [Metadata source: MiniMax-AI skills repository](https://github.com/MiniMax-AI/skills)
\n\n\n## Skill Output:
\n**Output Type(s):** [Text, Markdown, Code, Guidance]
\n**Output Format:** [Markdown with SQL code blocks and plain-English explanations]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Produces SQL drafts only; it does not execute queries or access databases.]
\n\n## Skill Version(s):
\n10.0.0 (source: server release metadata; artifact frontmatter and changelog show 1.0.1)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v99.0.0: 9 files, 12125 bytes\n\nFiles: CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (2412b), README.md (2628b), references/index.md (125b), skill-card.md (2017b), SKILL.md (6327b), tests/test_skill.py (12119b), _meta.json (131b)\n\nFile v99.0.0:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0.1\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v99.0.0:README.md\n\n# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode shows different JOIN strategies or subquery vs CTE approaches\n\n## Quick Start\n\n```bash\n# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### Usage\n\n```\n/text-to-sql\n```\n\nProvide schema (table names + columns) and describe what data you want in English.\n\n```\n/text-to-sql/explain\n```\n\nOutputs query with inline comments explaining each clause — for learning purposes.\n\n```\n/text-to-sql/alternatives\n```\n\nShows 2-3 different query approaches for the same question.\n\n## Modes\n\n| Mode | Description |\n|------|-------------|\n| `/text-to-sql` | Converts natural language to SQL query |\n| `/text-to-sql/explain` | Query with inline comments explaining each clause |\n| `/text-to-sql/alternatives` | 2-3 alternative query strategies |\n\n## Examples\n\n| Request | Query |\n|---------|-------|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | `ORDER BY total DESC LIMIT 10` added |\n| \"revenue by month\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| No schema provided | Asks for schema first — doesn't guess column names |\n\n## Directory Structure\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\nFile v99.0.0:_meta.json\n\n{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"99.0.0\",\n \"publishedAt\": 1779937119783\n}\n\nFile v99.0.0:references/index.md\n\n# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed.\n\nFile v99.0.0:CHANGELOG.md\n\n# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release\n\nFile v99.0.0:CONTRIBUTING.md\n\n# Contributing to `User Describes Data`\n\nThank you for your interest in contributing! Please follow these steps to set up your development environment and submit changes.\n\n## Development Setup\n\n```bash\n# 1. Fork the repository on GitHub\n\n# 2. Clone your fork\ngit clone https://github.com//User Describes Data.git\ncd User Describes Data\n\n# 3. Install dependencies (if any)\npip install -r scripts/requirements.txt\n\n# 4. Run the self-audit to verify quality\npython scripts/audit_skill.py .\n```\n\n## Workflow\n\nWe use a standard feature branch workflow:\n\n```bash\n# 1. Create a new branch from main\ngit checkout -b feat/\n\n# 2. Make your changes\n# - Follow the SKILL.md structure standards\n# - Keep SKILL.md body in English\n# - Do not hardcode API keys or secrets\n\n# 3. Run the audit to check for issues\npython scripts/audit_skill.py .\n\n# 4. Commit your changes\ngit add .\ngit commit -m \"feat(text-to-sql): add \"\n\n# 5. Push to your fork\ngit push origin feat/\n\n# 6. Open a Pull Request on GitHub\n# - Title: feat(text-to-sql): add \n# - Description: What + Why + Testing\n```\n\n## Code Standards\n\n- **SKILL.md**: Follow the YAML frontmatter standard (name, description, license, metadata)\n- **Scripts**: Must include shebang, requirements.txt, and graceful error handling\n- **Language**: SKILL.md body must be in English; reference docs in English\n- **No secrets**: Never commit API keys, tokens, or credentials\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] `audit_skill.py` exits with code 0 or 2\n- [ ] `validate_skills.py` exits with code 0\n- [ ] README.md and README_zh.md are both present\n- [ ] CONTRIBUTING.md is present\n- [ ] .gitignore is present\n- [ ] No hardcoded secrets anywhere in the codebase\n\n## Reporting Issues\n\nPlease report issues via GitHub Issues with:\n\n1. **What you expected to happen**\n2. **What actually happened**\n3. **Steps to reproduce**\n4. **Environment** (OS, Python version, etc.)\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under the MIT License.\n\nFile v99.0.0:README_zh.md\n\n# Text To Sql\n\n[English](./README.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![版本](https://img.shields.io/badge/version-1.0-blue)\n\n> 将自然语言描述转换为语法正确的 SQL 查询\n\n## 解决什么问题\n\n非技术用户知道想要什么数据（\"显示前 10 客户每月收入\"）但不会写 SQL。这个技能弥合这个差距——接收 schema + 自然语言请求，生成带表别名、正确 JOIN 和 GROUP BY 的语法正确的查询。\n\n**触发条件：** 数据库 schema + 自然语言问题 + 写 SQL 意图。\n\n## 功能特性\n\n- **Schema 感知翻译** — 写查询前先询问表/列 schema（绝不虚构列名）\n- **完整 SQL 覆盖** — SELECT、WHERE、GROUP BY、ORDER BY、LIMIT、JOIN（INNER、LEFT、RIGHT）、聚合函数\n- **通俗英文解释** — 同时输出查询和一行描述其作用\n- **多方法选项** — `/alternatives` 模式展示不同 JOIN 策略或子查询 vs CTE 方法\n\n## 快速开始\n\n```bash\n# 通过 ClawHub 安装\nclawhub install text-to-sql\n\n# 或手动复制\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### 使用方法\n\n```\n/text-to-sql\n```\n\n提供 schema（表名 + 列）并用英文描述想要什么数据。\n\n```\n/text-to-sql/explain\n```\n\n输出带内联注释的查询，解释每个子句——用于学习。\n\n```\n/text-to-sql/alternatives\n```\n\n展示同一问题的 2-3 种不同查询方法。\n\n## 工作模式\n\n| 模式 | 说明 |\n|------|------|\n| `/text-to-sql` | 将自然语言转换为 SQL 查询 |\n| `/text-to-sql/explain` | 带内联注释的查询，解释每个子句 |\n| `/text-to-sql/alternatives` | 2-3 种替代查询策略 |\n\n## 示例\n\n| 请求 | 查询 |\n|---------|-------|\n| Schema: `users(id, name)`，`orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"前 10 客户\" | 添加 `ORDER BY total DESC LIMIT 10` |\n| \"按月收入\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| 未提供 schema | 先询问 schema——不猜测列名 |\n\n## 目录结构\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL 方言速查表、JOIN 指南、意图映射\n└── tests/\n```\n\n## 许可证\n\nMIT 许可证 — 详见 [LICENSE](LICENSE)。\n\nFile v99.0.0:skill-card.md\n\n## Description:
\nConverts natural language requests and provided database schema details into syntactically correct SQL queries.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[wangjipeng977](https://clawhub.ai/user/wangjipeng977)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nExternal users, developers, and analysts use this skill to turn a plain-English data question and supplied table schema into SQL, with optional explanations or alternative query strategies.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Users may share database schema details with the agent.
\nMitigation: Review schema sensitivity before use and avoid sharing confidential production schema details unless the environment is approved for that data.
\nRisk: Generated SQL may be incorrect or may modify data if used without review.
\nMitigation: Treat SQL as a draft, review it manually, prefer read-only database roles, and test against non-production data before using it in production.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/wangjipeng977/text-to-sql)
\n- [Metadata source: MiniMax-AI skills](https://github.com/MiniMax-AI/skills)
\n- [Reference index](references/index.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, code, guidance]
\n**Output Format:** [Markdown with SQL code blocks and concise explanations]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [The skill writes SQL drafts and explanatory text; it does not execute queries or access databases.]
\n\n## Skill Version(s):
\n99.0.0 (source: server release evidence)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v1.2.0: 9 files, 11210 bytes\n\nFiles: _meta.json (130b), CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (1459b), README.md (1525b), references/index.md (125b), skill-card.md (2208b), SKILL.md (6327b), tests/test_skill.py (12119b)\n\nFile v1.2.0:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"6.0.1\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v1.2.0:README.md\n\n# User Describes Data\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0.1-blue)](SKILL.md)\n\n> user describes data needs in plain English and wants to generate the corresponding SQL query\n\n## What Problem This Solves\n\nBrief paragraph explaining the specific engineering problem this skill solves.\nWhen triggered: [trigger condition].\n\n## Features\n\n- Feature 1\n- Feature 2\n- Feature 3\n\n## Quick Start\n\n### Installation\n\n```bash\n# Via ClawHub\nclawhub install User Describes Data\n\n# Or manually\ncp -r User Describes Data ~/.openclaw/skills/\n```\n\n### Usage\n\n```bash\n# Mode 1\nclawhub run User Describes Data --mode read\n\n# Mode 2\nclawhub run User Describes Data --mode write --input ./data.json\n```\n\n## Directory Structure\n\n```\nUser Describes Data/\n├── SKILL.md # Entry point\n├── LICENSE # MIT\n├── README.md # This file\n├── README_zh.md # Chinese version\n├── CONTRIBUTING.md # Contribution guide\n├── .gitignore\n├── references/ # Templates and schemas\n│ └── ...\n└── scripts/ # Helper scripts (if any)\n └── ...\n```\n\n## Configuration\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `API_KEY` | Yes | API key for the service |\n\n## License\n\nThis project is licensed under the MIT License — see [LICENSE](LICENSE) for details.\n\n---\n\nPowered by [MiniMax](https://minimax.io).\n\nFile v1.2.0:_meta.json\n\n{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"1.2.0\",\n \"publishedAt\": 1779922411561\n}\n\nFile v1.2.0:references/index.md\n\n# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed.\n\nFile v1.2.0:CHANGELOG.md\n\n# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release\n\nFile v1.2.0:CONTRIBUTING.md\n\n# Contributing to `User Describes Data`\n\nThank you for your interest in contributing! Please follow these steps to set up your development environment and submit changes.\n\n## Development Setup\n\n```bash\n# 1. Fork the repository on GitHub\n\n# 2. Clone your fork\ngit clone https://github.com//User Describes Data.git\ncd User Describes Data\n\n# 3. Install dependencies (if any)\npip install -r scripts/requirements.txt\n\n# 4. Run the self-audit to verify quality\npython scripts/audit_skill.py .\n```\n\n## Workflow\n\nWe use a standard feature branch workflow:\n\n```bash\n# 1. Create a new branch from main\ngit checkout -b feat/\n\n# 2. Make your changes\n# - Follow the SKILL.md structure standards\n# - Keep SKILL.md body in English\n# - Do not hardcode API keys or secrets\n\n# 3. Run the audit to check for issues\npython scripts/audit_skill.py .\n\n# 4. Commit your changes\ngit add .\ngit commit -m \"feat(text-to-sql): add \"\n\n# 5. Push to your fork\ngit push origin feat/\n\n# 6. Open a Pull Request on GitHub\n# - Title: feat(text-to-sql): add \n# - Description: What + Why + Testing\n```\n\n## Code Standards\n\n- **SKILL.md**: Follow the YAML frontmatter standard (name, description, license, metadata)\n- **Scripts**: Must include shebang, requirements.txt, and graceful error handling\n- **Language**: SKILL.md body must be in English; reference docs in English\n- **No secrets**: Never commit API keys, tokens, or credentials\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] `audit_skill.py` exits with code 0 or 2\n- [ ] `validate_skills.py` exits with code 0\n- [ ] README.md and README_zh.md are both present\n- [ ] CONTRIBUTING.md is present\n- [ ] .gitignore is present\n- [ ] No hardcoded secrets anywhere in the codebase\n\n## Reporting Issues\n\nPlease report issues via GitHub Issues with:\n\n1. **What you expected to happen**\n2. **What actually happened**\n3. **Steps to reproduce**\n4. **Environment** (OS, Python version, etc.)\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under the MIT License.\n\nFile v1.2.0:README_zh.md\n\n# User Describes Data\n\n[English](./README.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![版本](https://img.shields.io/badge/version-1.0.1-blue)\n\n> user describes data needs in plain English and wants to generate the corresponding SQL query\n\n## 解决什么问题\n\n简要说明这个技能解决的具体工程问题。\n触发条件：[trigger condition]。\n\n## 功能特性\n\n- 特性 1\n- 特性 2\n- 特性 3\n\n## 快速开始\n\n### 安装\n\n```bash\n# 通过 ClawHub 安装\nclawhub install User Describes Data\n\n# 或手动复制\ncp -r User Describes Data ~/.openclaw/skills/\n```\n\n### 使用方法\n\n```bash\n# 模式 1：读取\nclawhub run User Describes Data --mode read\n\n# 模式 2：写入\nclawhub run User Describes Data --mode write --input ./data.json\n```\n\n## 目录结构\n\n```\nUser Describes Data/\n├── SKILL.md # 技能入口\n├── LICENSE # MIT 许可证\n├── README.md # 英文说明\n├── README_zh.md # 本文件\n├── CONTRIBUTING.md # 贡献指南\n├── .gitignore\n├── references/ # 模板和 schema\n│ └── ...\n└── scripts/ # 辅助脚本（如有）\n └── ...\n```\n\n## 配置\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| `API_KEY` | 是 | 服务 API Key |\n\n## 许可证\n\n本项目采用 MIT 许可证 — 详见 [LICENSE](LICENSE)。\n\n---\n\n由 [MiniMax](https://minimax.io) 提供支持。\n\nFile v1.2.0:skill-card.md\n\n## Description:
\nConverts natural-language data requests and provided database schemas into SQL queries, explanations, or alternative query approaches without executing them.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[wangjipeng977](https://clawhub.ai/user/wangjipeng977)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, analysts, and non-technical users use this skill to draft SQL from plain-English data requests when they can provide schema or table descriptions. It can also explain generated queries or compare alternative query structures.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Generated SQL may be incorrect, inefficient, or destructive if executed without review.
\nMitigation: Review generated SQL before running it, especially INSERT, UPDATE, DELETE, DROP, or production queries.
\nRisk: Artifact README files contain leftover template text about read/write modes and API keys that does not match the prompt-only skill behavior.
\nMitigation: Use the SKILL.md behavior and server security guidance as the operational source of truth, and do not provide credentials for this skill unless separate trusted tooling requires them.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/wangjipeng977/text-to-sql)
\n- [Metadata source: MiniMax-AI skills](https://github.com/MiniMax-AI/skills)
\n- [text-to-sql references index](references/index.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, code, guidance]
\n**Output Format:** [Markdown with SQL code blocks and concise explanatory text]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [The skill drafts SQL only; it does not execute queries or connect to databases.]
\n\n## Skill Version(s):
\n1.2.0 (source: server release evidence)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v2.1.0: 9 files, 12106 bytes\n\nFiles: CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (2412b), README.md (2628b), references/index.md (125b), skill-card.md (1960b), SKILL.md (6327b), tests/test_skill.py (12119b), _meta.json (130b)\n\nFile v2.1.0:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0.1\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v2.1.0:README.md\n\n# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode shows different JOIN strategies or subquery vs CTE approaches\n\n## Quick Start\n\n```bash\n# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### Usage\n\n```\n/text-to-sql\n```\n\nProvide schema (table names + columns) and describe what data you want in English.\n\n```\n/text-to-sql/explain\n```\n\nOutputs query with inline comments explaining each clause — for learning purposes.\n\n```\n/text-to-sql/alternatives\n```\n\nShows 2-3 different query approaches for the same question.\n\n## Modes\n\n| Mode | Description |\n|------|-------------|\n| `/text-to-sql` | Converts natural language to SQL query |\n| `/text-to-sql/explain` | Query with inline comments explaining each clause |\n| `/text-to-sql/alternatives` | 2-3 alternative query strategies |\n\n## Examples\n\n| Request | Query |\n|---------|-------|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | `ORDER BY total DESC LIMIT 10` added |\n| \"revenue by month\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| No schema provided | Asks for schema first — doesn't guess column names |\n\n## Directory Structure\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\nFile v2.1.0:_meta.json\n\n{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"2.1.0\",\n \"publishedAt\": 1779911458505\n}\n\nFile v2.1.0:references/index.md\n\n# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed.\n\nFile v2.1.0:CHANGELOG.md\n\n# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release\n\nFile v2.1.0:CONTRIBUTING.md\n\n# Contributing to `User Describes Data`\n\nThank you for your interest in contributing! Please follow these steps to set up your development environment and submit changes.\n\n## Development Setup\n\n```bash\n# 1. Fork the repository on GitHub\n\n# 2. Clone your fork\ngit clone https://github.com//User Describes Data.git\ncd User Describes Data\n\n# 3. Install dependencies (if any)\npip install -r scripts/requirements.txt\n\n# 4. Run the self-audit to verify quality\npython scripts/audit_skill.py .\n```\n\n## Workflow\n\nWe use a standard feature branch workflow:\n\n```bash\n# 1. Create a new branch from main\ngit checkout -b feat/\n\n# 2. Make your changes\n# - Follow the SKILL.md structure standards\n# - Keep SKILL.md body in English\n# - Do not hardcode API keys or secrets\n\n# 3. Run the audit to check for issues\npython scripts/audit_skill.py .\n\n# 4. Commit your changes\ngit add .\ngit commit -m \"feat(text-to-sql): add \"\n\n# 5. Push to your fork\ngit push origin feat/\n\n# 6. Open a Pull Request on GitHub\n# - Title: feat(text-to-sql): add \n# - Description: What + Why + Testing\n```\n\n## Code Standards\n\n- **SKILL.md**: Follow the YAML frontmatter standard (name, description, license, metadata)\n- **Scripts**: Must include shebang, requirements.txt, and graceful error handling\n- **Language**: SKILL.md body must be in English; reference docs in English\n- **No secrets**: Never commit API keys, tokens, or credentials\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] `audit_skill.py` exits with code 0 or 2\n- [ ] `validate_skills.py` exits with code 0\n- [ ] README.md and README_zh.md are both present\n- [ ] CONTRIBUTING.md is present\n- [ ] .gitignore is present\n- [ ] No hardcoded secrets anywhere in the codebase\n\n## Reporting Issues\n\nPlease report issues via GitHub Issues with:\n\n1. **What you expected to happen**\n2. **What actually happened**\n3. **Steps to reproduce**\n4. **Environment** (OS, Python version, etc.)\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under the MIT License.\n\nFile v2.1.0:README_zh.md\n\n# Text To Sql\n\n[English](./README.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![版本](https://img.shields.io/badge/version-1.0-blue)\n\n> 将自然语言描述转换为语法正确的 SQL 查询\n\n## 解决什么问题\n\n非技术用户知道想要什么数据（\"显示前 10 客户每月收入\"）但不会写 SQL。这个技能弥合这个差距——接收 schema + 自然语言请求，生成带表别名、正确 JOIN 和 GROUP BY 的语法正确的查询。\n\n**触发条件：** 数据库 schema + 自然语言问题 + 写 SQL 意图。\n\n## 功能特性\n\n- **Schema 感知翻译** — 写查询前先询问表/列 schema（绝不虚构列名）\n- **完整 SQL 覆盖** — SELECT、WHERE、GROUP BY、ORDER BY、LIMIT、JOIN（INNER、LEFT、RIGHT）、聚合函数\n- **通俗英文解释** — 同时输出查询和一行描述其作用\n- **多方法选项** — `/alternatives` 模式展示不同 JOIN 策略或子查询 vs CTE 方法\n\n## 快速开始\n\n```bash\n# 通过 ClawHub 安装\nclawhub install text-to-sql\n\n# 或手动复制\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### 使用方法\n\n```\n/text-to-sql\n```\n\n提供 schema（表名 + 列）并用英文描述想要什么数据。\n\n```\n/text-to-sql/explain\n```\n\n输出带内联注释的查询，解释每个子句——用于学习。\n\n```\n/text-to-sql/alternatives\n```\n\n展示同一问题的 2-3 种不同查询方法。\n\n## 工作模式\n\n| 模式 | 说明 |\n|------|------|\n| `/text-to-sql` | 将自然语言转换为 SQL 查询 |\n| `/text-to-sql/explain` | 带内联注释的查询，解释每个子句 |\n| `/text-to-sql/alternatives` | 2-3 种替代查询策略 |\n\n## 示例\n\n| 请求 | 查询 |\n|---------|-------|\n| Schema: `users(id, name)`，`orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"前 10 客户\" | 添加 `ORDER BY total DESC LIMIT 10` |\n| \"按月收入\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| 未提供 schema | 先询问 schema——不猜测列名 |\n\n## 目录结构\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL 方言速查表、JOIN 指南、意图映射\n└── tests/\n```\n\n## 许可证\n\nMIT 许可证 — 详见 [LICENSE](LICENSE)。\n\nFile v2.1.0:skill-card.md\n\n## Description:
\nConverts natural-language data requests and supplied database schemas into SQL queries, explanations, or alternative query strategies.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[wangjipeng977](https://clawhub.ai/user/wangjipeng977)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, analysts, and non-technical users use this skill to translate schema-backed questions into SQL they can review before running. It is suited for drafting SELECT queries, explaining query clauses, and comparing alternative SQL approaches.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Generated SQL can be incorrect or harmful if run against a real database without review.
\nMitigation: Review generated SQL against the provided schema and intended operation before execution, especially for queries that could modify or delete data.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/wangjipeng977/text-to-sql)
\n- [Declared metadata source: MiniMax-AI skills](https://github.com/MiniMax-AI/skills)
\n- [Local SQL reference index](references/index.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, code, guidance]
\n**Output Format:** [Markdown containing SQL code blocks or inline SQL with a short plain-English explanation.]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Does not execute SQL; asks for schema when missing and may provide inline comments or alternative query approaches.]
\n\n## Skill Version(s):
\n2.1.0 (source: server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v999.0.0: 9 files, 12061 bytes\n\nFiles: CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (2412b), README.md (2628b), references/index.md (125b), skill-card.md (1780b), SKILL.md (6327b), tests/test_skill.py (12119b), _meta.json (132b)\n\nFile v999.0.0:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0.1\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v999.0.0:README.md\n\n# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode shows different JOIN strategies or subquery vs CTE approaches\n\n## Quick Start\n\n```bash\n# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### Usage\n\n```\n/text-to-sql\n```\n\nProvide schema (table names + columns) and describe what data you want in English.\n\n```\n/text-to-sql/explain\n```\n\nOutputs query with inline comments explaining each clause — for learning purposes.\n\n```\n/text-to-sql/alternatives\n```\n\nShows 2-3 different query approaches for the same question.\n\n## Modes\n\n| Mode | Description |\n|------|-------------|\n| `/text-to-sql` | Converts natural language to SQL query |\n| `/text-to-sql/explain` | Query with inline comments explaining each clause |\n| `/text-to-sql/alternatives` | 2-3 alternative query strategies |\n\n## Examples\n\n| Request | Query |\n|---------|-------|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | `ORDER BY total DESC LIMIT 10` added |\n| \"revenue by month\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| No schema provided | Asks for schema first — doesn't guess column names |\n\n## Directory Structure\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\nFile v999.0.0:_meta.json\n\n{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"999.0.0\",\n \"publishedAt\": 1779863695739\n}\n\nFile v999.0.0:references/index.md\n\n# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed.\n\nFile v999.0.0:CHANGELOG.md\n\n# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release\n\nFile v999.0.0:CONTRIBUTING.md\n\n# Contributing to `User Describes Data`\n\nThank you for your interest in contributing! Please follow these steps to set up your development environment and submit changes.\n\n## Development Setup\n\n```bash\n# 1. Fork the repository on GitHub\n\n# 2. Clone your fork\ngit clone https://github.com//User Describes Data.git\ncd User Describes Data\n\n# 3. Install dependencies (if any)\npip install -r scripts/requirements.txt\n\n# 4. Run the self-audit to verify quality\npython scripts/audit_skill.py .\n```\n\n## Workflow\n\nWe use a standard feature branch workflow:\n\n```bash\n# 1. Create a new branch from main\ngit checkout -b feat/\n\n# 2. Make your changes\n# - Follow the SKILL.md structure standards\n# - Keep SKILL.md body in English\n# - Do not hardcode API keys or secrets\n\n# 3. Run the audit to check for issues\npython scripts/audit_skill.py .\n\n# 4. Commit your changes\ngit add .\ngit commit -m \"feat(text-to-sql): add \"\n\n# 5. Push to your fork\ngit push origin feat/\n\n# 6. Open a Pull Request on GitHub\n# - Title: feat(text-to-sql): add \n# - Description: What + Why + Testing\n```\n\n## Code Standards\n\n- **SKILL.md**: Follow the YAML frontmatter standard (name, description, license, metadata)\n- **Scripts**: Must include shebang, requirements.txt, and graceful error handling\n- **Language**: SKILL.md body must be in English; reference docs in English\n- **No secrets**: Never commit API keys, tokens, or credentials\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] `audit_skill.py` exits with code 0 or 2\n- [ ] `validate_skills.py` exits with code 0\n- [ ] README.md and README_zh.md are both present\n- [ ] CONTRIBUTING.md is present\n- [ ] .gitignore is present\n- [ ] No hardcoded secrets anywhere in the codebase\n\n## Reporting Issues\n\nPlease report issues via GitHub Issues with:\n\n1. **What you expected to happen**\n2. **What actually happened**\n3. **Steps to reproduce**\n4. **Environment** (OS, Python version, etc.)\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under the MIT License.\n\nFile v999.0.0:README_zh.md\n\n# Text To Sql\n\n[English](./README.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![版本](https://img.shields.io/badge/version-1.0-blue)\n\n> 将自然语言描述转换为语法正确的 SQL 查询\n\n## 解决什么问题\n\n非技术用户知道想要什么数据（\"显示前 10 客户每月收入\"）但不会写 SQL。这个技能弥合这个差距——接收 schema + 自然语言请求，生成带表别名、正确 JOIN 和 GROUP BY 的语法正确的查询。\n\n**触发条件：** 数据库 schema + 自然语言问题 + 写 SQL 意图。\n\n## 功能特性\n\n- **Schema 感知翻译** — 写查询前先询问表/列 schema（绝不虚构列名）\n- **完整 SQL 覆盖** — SELECT、WHERE、GROUP BY、ORDER BY、LIMIT、JOIN（INNER、LEFT、RIGHT）、聚合函数\n- **通俗英文解释** — 同时输出查询和一行描述其作用\n- **多方法选项** — `/alternatives` 模式展示不同 JOIN 策略或子查询 vs CTE 方法\n\n## 快速开始\n\n```bash\n# 通过 ClawHub 安装\nclawhub install text-to-sql\n\n# 或手动复制\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### 使用方法\n\n```\n/text-to-sql\n```\n\n提供 schema（表名 + 列）并用英文描述想要什么数据。\n\n```\n/text-to-sql/explain\n```\n\n输出带内联注释的查询，解释每个子句——用于学习。\n\n```\n/text-to-sql/alternatives\n```\n\n展示同一问题的 2-3 种不同查询方法。\n\n## 工作模式\n\n| 模式 | 说明 |\n|------|------|\n| `/text-to-sql` | 将自然语言转换为 SQL 查询 |\n| `/text-to-sql/explain` | 带内联注释的查询，解释每个子句 |\n| `/text-to-sql/alternatives` | 2-3 种替代查询策略 |\n\n## 示例\n\n| 请求 | 查询 |\n|---------|-------|\n| Schema: `users(id, name)`，`orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"前 10 客户\" | 添加 `ORDER BY total DESC LIMIT 10` |\n| \"按月收入\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| 未提供 schema | 先询问 schema——不猜测列名 |\n\n## 目录结构\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL 方言速查表、JOIN 指南、意图映射\n└── tests/\n```\n\n## 许可证\n\nMIT 许可证 — 详见 [LICENSE](LICENSE)。\n\nFile v999.0.0:skill-card.md\n\n## Description:\n\nConverts natural-language data requests plus a provided database schema into syntactically correct SQL queries.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[wangjipeng977](https://clawhub.ai/user/wangjipeng977)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, analysts, and external users use this skill to draft SQL from plain-English data questions when they can provide the relevant database schema. It can also produce commented queries or alternative query approaches for learning and comparison.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Generated SQL can be incorrect for the schema, SQL dialect, or user-supplied filter values.\n\nMitigation: Review the generated query before execution, verify table and column names, prefer bind parameters, and use a read-only database account where practical.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/wangjipeng977/skills/text-to-sql)\n- [Metadata source: MiniMax-AI skills](https://github.com/MiniMax-AI/skills)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, guidance]\n\n**Output Format:** [Markdown with SQL code blocks and concise explanatory text]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Generated SQL should be reviewed for schema accuracy, SQL dialect, and parameters before execution.]\n\n## Skill Version(s):\n\n999.0.0 (source: ClawHub release metadata; artifact frontmatter and changelog report 1.0.1)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v9.9.9: 9 files, 12137 bytes\n\nFiles: CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (2412b), README.md (2628b), references/index.md (125b), skill-card.md (2078b), SKILL.md (6327b), tests/test_skill.py (12119b), _meta.json (130b)\n\nFile v9.9.9:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0.1\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v9.9.9:README.md\n\n# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode shows different JOIN strategies or subquery vs CTE approaches\n\n## Quick Start\n\n```bash\n# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### Usage\n\n```\n/text-to-sql\n```\n\nProvide schema (table names + columns) and describe what data you want in English.\n\n```\n/text-to-sql/explain\n```\n\nOutputs query with inline comments explaining each clause — for learning purposes.\n\n```\n/text-to-sql/alternatives\n```\n\nShows 2-3 different query approaches for the same question.\n\n## Modes\n\n| Mode | Description |\n|------|-------------|\n| `/text-to-sql` | Converts natural language to SQL query |\n| `/text-to-sql/explain` | Query with inline comments explaining each clause |\n| `/text-to-sql/alternatives` | 2-3 alternative query strategies |\n\n## Examples\n\n| Request | Query |\n|---------|-------|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | `ORDER BY total DESC LIMIT 10` added |\n| \"revenue by month\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| No schema provided | Asks for schema first — doesn't guess column names |\n\n## Directory Structure\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\nFile v9.9.9:_meta.json\n\n{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"9.9.9\",\n \"publishedAt\": 1779834133224\n}\n\nFile v9.9.9:references/index.md\n\n# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed.\n\nFile v9.9.9:CHANGELOG.md\n\n# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release\n\nFile v9.9.9:CONTRIBUTING.md\n\n# Contributing to `User Describes Data`\n\nThank you for your interest in contributing! Please follow these steps to set up your development environment and submit changes.\n\n## Development Setup\n\n```bash\n# 1. Fork the repository on GitHub\n\n# 2. Clone your fork\ngit clone https://github.com//User Describes Data.git\ncd User Describes Data\n\n# 3. Install dependencies (if any)\npip install -r scripts/requirements.txt\n\n# 4. Run the self-audit to verify quality\npython scripts/audit_skill.py .\n```\n\n## Workflow\n\nWe use a standard feature branch workflow:\n\n```bash\n# 1. Create a new branch from main\ngit checkout -b feat/\n\n# 2. Make your changes\n# - Follow the SKILL.md structure standards\n# - Keep SKILL.md body in English\n# - Do not hardcode API keys or secrets\n\n# 3. Run the audit to check for issues\npython scripts/audit_skill.py .\n\n# 4. Commit your changes\ngit add .\ngit commit -m \"feat(text-to-sql): add \"\n\n# 5. Push to your fork\ngit push origin feat/\n\n# 6. Open a Pull Request on GitHub\n# - Title: feat(text-to-sql): add \n# - Description: What + Why + Testing\n```\n\n## Code Standards\n\n- **SKILL.md**: Follow the YAML frontmatter standard (name, description, license, metadata)\n- **Scripts**: Must include shebang, requirements.txt, and graceful error handling\n- **Language**: SKILL.md body must be in English; reference docs in English\n- **No secrets**: Never commit API keys, tokens, or credentials\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] `audit_skill.py` exits with code 0 or 2\n- [ ] `validate_skills.py` exits with code 0\n- [ ] README.md and README_zh.md are both present\n- [ ] CONTRIBUTING.md is present\n- [ ] .gitignore is present\n- [ ] No hardcoded secrets anywhere in the codebase\n\n## Reporting Issues\n\nPlease report issues via GitHub Issues with:\n\n1. **What you expected to happen**\n2. **What actually happened**\n3. **Steps to reproduce**\n4. **Environment** (OS, Python version, etc.)\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under the MIT License.\n\nFile v9.9.9:README_zh.md\n\n# Text To Sql\n\n[English](./README.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![版本](https://img.shields.io/badge/version-1.0-blue)\n\n> 将自然语言描述转换为语法正确的 SQL 查询\n\n## 解决什么问题\n\n非技术用户知道想要什么数据（\"显示前 10 客户每月收入\"）但不会写 SQL。这个技能弥合这个差距——接收 schema + 自然语言请求，生成带表别名、正确 JOIN 和 GROUP BY 的语法正确的查询。\n\n**触发条件：** 数据库 schema + 自然语言问题 + 写 SQL 意图。\n\n## 功能特性\n\n- **Schema 感知翻译** — 写查询前先询问表/列 schema（绝不虚构列名）\n- **完整 SQL 覆盖** — SELECT、WHERE、GROUP BY、ORDER BY、LIMIT、JOIN（INNER、LEFT、RIGHT）、聚合函数\n- **通俗英文解释** — 同时输出查询和一行描述其作用\n- **多方法选项** — `/alternatives` 模式展示不同 JOIN 策略或子查询 vs CTE 方法\n\n## 快速开始\n\n```bash\n# 通过 ClawHub 安装\nclawhub install text-to-sql\n\n# 或手动复制\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### 使用方法\n\n```\n/text-to-sql\n```\n\n提供 schema（表名 + 列）并用英文描述想要什么数据。\n\n```\n/text-to-sql/explain\n```\n\n输出带内联注释的查询，解释每个子句——用于学习。\n\n```\n/text-to-sql/alternatives\n```\n\n展示同一问题的 2-3 种不同查询方法。\n\n## 工作模式\n\n| 模式 | 说明 |\n|------|------|\n| `/text-to-sql` | 将自然语言转换为 SQL 查询 |\n| `/text-to-sql/explain` | 带内联注释的查询，解释每个子句 |\n| `/text-to-sql/alternatives` | 2-3 种替代查询策略 |\n\n## 示例\n\n| 请求 | 查询 |\n|---------|-------|\n| Schema: `users(id, name)`，`orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"前 10 客户\" | 添加 `ORDER BY total DESC LIMIT 10` |\n| \"按月收入\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| 未提供 schema | 先询问 schema——不猜测列名 |\n\n## 目录结构\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL 方言速查表、JOIN 指南、意图映射\n└── tests/\n```\n\n## 许可证\n\nMIT 许可证 — 详见 [LICENSE](LICENSE)。\n\nFile v9.9.9:skill-card.md\n\n## Description:
\nConverts natural language requests and user-provided database schemas into SQL queries, explanations, or alternative query strategies.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[wangjipeng977](https://clawhub.ai/user/wangjipeng977)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, analysts, and non-technical users use this skill to turn a provided database schema and plain-language data request into SQL. It can also explain a generated query or provide alternative query approaches for comparison.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Generated SQL may be incorrect, inefficient, or unsafe to run directly against production data.
\nMitigation: Review generated SQL before execution and prefer a read-only or test database role.
\nRisk: Schema details or sample values may expose sensitive database structure or business data.
\nMitigation: Provide only the schema details needed for the query and avoid pasting sensitive data unless necessary.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/wangjipeng977/text-to-sql)
\n- [Upstream source listed in skill metadata](https://github.com/MiniMax-AI/skills)
\n- [Skill reference index](references/index.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, code, guidance]
\n**Output Format:** [Markdown with SQL code blocks and plain-English explanation]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May ask for schema details before generating SQL; does not execute generated queries.]
\n\n## Skill Version(s):
\n9.9.9 (source: server release metadata; artifact metadata version is 1.0.1)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v6.0.1: 8 files, 11006 bytes\n\nFiles: CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (2412b), README.md (2628b), references/index.md (125b), SKILL.md (6325b), tests/test_skill.py (12119b), _meta.json (130b)\n\nFile v6.0.1:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v6.0.1:README.md\n\n# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode shows different JOIN strategies or subquery vs CTE approaches\n\n## Quick Start\n\n```bash\n# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### Usage\n\n```\n/text-to-sql\n```\n\nProvide schema (table names + columns) and describe what data you want in English.\n\n```\n/text-to-sql/explain\n```\n\nOutputs query with inline comments explaining each clause — for learning purposes.\n\n```\n/text-to-sql/alternatives\n```\n\nShows 2-3 different query approaches for the same question.\n\n## Modes\n\n| Mode | Description |\n|------|-------------|\n| `/text-to-sql` | Converts natural language to SQL query |\n| `/text-to-sql/explain` | Query with inline comments explaining each clause |\n| `/text-to-sql/alternatives` | 2-3 alternative query strategies |\n\n## Examples\n\n| Request | Query |\n|---------|-------|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | `ORDER BY total DESC LIMIT 10` added |\n| \"revenue by month\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| No schema provided | Asks for schema first — doesn't guess column names |\n\n## Directory Structure\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\nFile v6.0.1:_meta.json\n\n{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"6.0.1\",\n \"publishedAt\": 1779746036515\n}\n\nFile v6.0.1:references/index.md\n\n# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed.\n\nFile v6.0.1:CHANGELOG.md\n\n# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release\n\nFile v6.0.1:CONTRIBUTING.md\n\n# Contributing to `User Describes Data`\n\nThank you for your interest in contributing! Please follow these steps to set up your development environment and submit changes.\n\n## Development Setup\n\n```bash\n# 1. Fork the repository on GitHub\n\n# 2. Clone your fork\ngit clone https://github.com//User Describes Data.git\ncd User Describes Data\n\n# 3. Install dependencies (if any)\npip install -r scripts/requirements.txt\n\n# 4. Run the self-audit to verify quality\npython scripts/audit_skill.py .\n```\n\n## Workflow\n\nWe use a standard feature branch workflow:\n\n```bash\n# 1. Create a new branch from main\ngit checkout -b feat/\n\n# 2. Make your changes\n# - Follow the SKILL.md structure standards\n# - Keep SKILL.md body in English\n# - Do not hardcode API keys or secrets\n\n# 3. Run the audit to check for issues\npython scripts/audit_skill.py .\n\n# 4. Commit your changes\ngit add .\ngit commit -m \"feat(text-to-sql): add \"\n\n# 5. Push to your fork\ngit push origin feat/\n\n# 6. Open a Pull Request on GitHub\n# - Title: feat(text-to-sql): add \n# - Description: What + Why + Testing\n```\n\n## Code Standards\n\n- **SKILL.md**: Follow the YAML frontmatter standard (name, description, license, metadata)\n- **Scripts**: Must include shebang, requirements.txt, and graceful error handling\n- **Language**: SKILL.md body must be in English; reference docs in English\n- **No secrets**: Never commit API keys, tokens, or credentials\n\n## Quality Checklist\n\nBefore opening a PR, verify:\n\n- [ ] `audit_skill.py` exits with code 0 or 2\n- [ ] `validate_skills.py` exits with code 0\n- [ ] README.md and README_zh.md are both present\n- [ ] CONTRIBUTING.md is present\n- [ ] .gitignore is present\n- [ ] No hardcoded secrets anywhere in the codebase\n\n## Reporting Issues\n\nPlease report issues via GitHub Issues with:\n\n1. **What you expected to happen**\n2. **What actually happened**\n3. **Steps to reproduce**\n4. **Environment** (OS, Python version, etc.)\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under the MIT License.\n\nFile v6.0.1:README_zh.md\n\n# Text To Sql\n\n[English](./README.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![版本](https://img.shields.io/badge/version-1.0-blue)\n\n> 将自然语言描述转换为语法正确的 SQL 查询\n\n## 解决什么问题\n\n非技术用户知道想要什么数据（\"显示前 10 客户每月收入\"）但不会写 SQL。这个技能弥合这个差距——接收 schema + 自然语言请求，生成带表别名、正确 JOIN 和 GROUP BY 的语法正确的查询。\n\n**触发条件：** 数据库 schema + 自然语言问题 + 写 SQL 意图。\n\n## 功能特性\n\n- **Schema 感知翻译** — 写查询前先询问表/列 schema（绝不虚构列名）\n- **完整 SQL 覆盖** — SELECT、WHERE、GROUP BY、ORDER BY、LIMIT、JOIN（INNER、LEFT、RIGHT）、聚合函数\n- **通俗英文解释** — 同时输出查询和一行描述其作用\n- **多方法选项** — `/alternatives` 模式展示不同 JOIN 策略或子查询 vs CTE 方法\n\n## 快速开始\n\n```bash\n# 通过 ClawHub 安装\nclawhub install text-to-sql\n\n# 或手动复制\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### 使用方法\n\n```\n/text-to-sql\n```\n\n提供 schema（表名 + 列）并用英文描述想要什么数据。\n\n```\n/text-to-sql/explain\n```\n\n输出带内联注释的查询，解释每个子句——用于学习。\n\n```\n/text-to-sql/alternatives\n```\n\n展示同一问题的 2-3 种不同查询方法。\n\n## 工作模式\n\n| 模式 | 说明 |\n|------|------|\n| `/text-to-sql` | 将自然语言转换为 SQL 查询 |\n| `/text-to-sql/explain` | 带内联注释的查询，解释每个子句 |\n| `/text-to-sql/alternatives` | 2-3 种替代查询策略 |\n\n## 示例\n\n| 请求 | 查询 |\n|---------|-------|\n| Schema: `users(id, name)`，`orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"前 10 客户\" | 添加 `ORDER BY total DESC LIMIT 10` |\n| \"按月收入\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| 未提供 schema | 先询问 schema——不猜测列名 |\n\n## 目录结构\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL 方言速查表、JOIN 指南、意图映射\n└── tests/\n```\n\n## 许可证\n\nMIT 许可证 — 详见 [LICENSE](LICENSE)。\n\nArchive v1.0.3: 8 files, 11006 bytes\n\nFiles: CHANGELOG.md (179b), CONTRIBUTING.md (2119b), README_zh.md (2412b), README.md (2628b), references/index.md (125b), SKILL.md (6325b), tests/test_skill.py (12119b), _meta.json (130b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"between X and Y\" | `BETWEEN` |\n| \"like\", \"containing\", \"includes\" | `LIKE '%value%'` |\n| \"before\", \"after\", \"earlier than\" | `WHERE date_column < 'date'` |\n| \"latest\", \"most recent\", \"newest\" | `ORDER BY date DESC LIMIT 1` |\n| \"count of\", \"how many\" | `COUNT(*)` aggregate |\n| \"total of\", \"sum of\" | `SUM(column)` |\n| \"average of\" | `AVG(column)` |\n\n### Step 3 — Handle Joins and Relationships\n\nIf the request involves multiple tables:\n1. Identify which tables contain the needed columns\n2. Determine the join key (foreign key relationship)\n3. Select join type: `INNER JOIN` (default), `LEFT JOIN` (if some side may be empty), `RIGHT JOIN` (rare)\n4. Write join on the correct key pair\n\nIf schema doesn't include relationship info, ask user to clarify which column links the tables.\n\n### Step 4 — Generate and Validate\n\n```sql\nSELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;\n```\n\nCheck:\n- All columns referenced exist in the schema\n- All table aliases are defined\n- JOIN conditions are valid (same type, correct keys)\n- No ambiguous column references (all tables have aliases)\n- Aggregate queries have appropriate GROUP BY\n\n## Mandatory Rules\n\n### Do not\n\n- Do not invent table names or column names not in the provided schema\n- Do not use SQL keywords as column names without backtick quoting where needed\n- Do not write `SELECT *` in production queries — list specific columns\n- Do not assume which table a column belongs to — qualify all column references\n\n### Do\n\n- Ask for schema information before writing the query if it wasn't provided\n- Qualify all column references with table aliases (e.g., `o.order_id`)\n- Use backtick or quoted identifiers if column names are SQL reserved words\n- Provide both the query and a one-line plain English translation of what it does\n\n## Quality Bar\n\n**A good output:**\n- Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)\n- All column and table names match the provided schema exactly\n- JOIN conditions are valid and use the correct key types\n- The query actually answers the stated question\n\n**A bad output:**\n- References a column not in the schema\n- `SELECT *` without justification in a query that should return specific columns\n- Missing `GROUP BY` for an aggregate query\n- JOIN on mismatched types (string ID to integer ID)\n\n## Good vs. Bad Examples\n\n| Scenario | Bad Output | Good Output |\n|---|---|---|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT * FROM orders` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | No `LIMIT 10` or `ORDER BY` | `ORDER BY total DESC LIMIT 10` |\n| No schema provided | Writes a query with invented columns | \"Could you share the table schema (column names and types)?\" |\n| \"show me revenue by month\" | `SELECT revenue` without `GROUP BY` | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n\n## References\n\n- `references/` — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping\n\nFile v1.0.3:README.md\n\n# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode sho","readmeExcerpt":"Skill: Text To Sql Owner: wangjipeng977 Summary: Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to qu... Tags: latest:999.0.0 Version history: v2.0.3 | 2026-05-29T09:36:50.444Z | user Initial release v1.0.8 | 2026-05-28T18:19:42.284Z | user Retry publish v10.0.0 | 2026-05-28T10:08:13.780Z | user Retry at high vers","codeSnippets":[],"executableExamples":[{"language":"sql","snippet":"SELECT\n o.order_id,\n o.created_at,\n c.customer_name,\n SUM(o.total_amount) AS total_revenue\nFROM orders o\nINNER JOIN customers c ON o.customer_id = c.id\nWHERE o.created_at >= '2024-01-01'\nGROUP BY o.order_id, o.created_at, c.customer_name\nORDER BY total_revenue DESC\nLIMIT 10;"},{"language":"bash","snippet":"# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/"},{"language":"text","snippet":"/text-to-sql"},{"language":"text","snippet":"/text-to-sql/explain"},{"language":"text","snippet":"/text-to-sql/alternatives"},{"language":"text","snippet":"text-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: text-to-sql\ndescription: >\n Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. \n (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". \n (3) user provides a database schema or table descriptions and asks a question answerable by SQL. \nlicense: MIT\nmetadata:\n version: \"1.0.1\"\n category: data\n author: wangjipeng\n sources:\n - https://github.com/MiniMax-AI/skills\n---\n\n# Text to SQL\n\nUse when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says \"write SQL for this\", \"convert to query\", \"how do I select\", or \"give me the SQL\". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.\n\n## Core Position\n\nThis skill solves the specific problem of: *non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.*\n\nThis skill IS NOT:\n- A SQL execution environment — it writes queries, does not run them\n- A schema design tool — it works with existing schema the user provides\n- A data analysis tool — it produces SQL, not results or insights\n\nThis skill IS activated ONLY when: natural language description + database schema + SQL request are all present.\n\n## Modes\n\n### `/text-to-sql`\n\n**Default mode.** Converts natural language into a syntactically correct SQL query.\n\nWhen to use: User describes data needs and provides schema — wants the query.\n\n### `/text-to-sql/explain`\n\nOutputs the SQL query with inline comments explaining each clause.\n\nWhen to use: User wants to understand the query while seeing it, for learning purposes.\n\n### `/text-to-sql/alternatives`\n\nProvides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).\n\nWhen to use: User is learning SQL or wants to compare query strategies.\n\n## Execution Steps\n\n### Step 1 — Confirm Schema\n\n1. Receive natural language request and detect if schema is present\n2. Schema may be provided as:\n - Table/column names explicitly in the request\n - A CREATE TABLE statement\n - A DESCRIBE output\n - Column names from a previous query\n3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names\n4. Build a schema map: `table_name → {column: type}`\n\n### Step 2 — Translate Intent to SQL Clauses\n\nMap natural language intent to SQL components:\n\n| Natural Language | SQL Clause |\n|---|---|\n| \"all\", \"every\", \"complete list\" | `SELECT *` or `SELECT all columns` |\n| \"only\", \"just\", \"specifically\" | `SELECT [specific columns]` |\n| \"where [condition]\" | `WHERE` clause |\n| \"sorted by\", \"in order of\" | `ORDER BY` |\n| \"grouped by\", \"each [X]\" | `GROUP BY` |\n| \"top N\", \"first N\", \"N most\" | `LIMIT N` + `ORDER BY` |\n| \"not\", \"exclude\", \"without\" | `WHERE NOT` or `!=` / `<>` |\n| \"both X and Y\", \"along with\" | `AND` in WHERE, or JOIN |\n| \"either X or Y\", \"or\" | `OR` in WHERE |\n| \"be"},{"path":"README.md","content":"# Text To Sql\n\n[中文版](./README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0-blue)](SKILL.md)\n\n> Converts natural language descriptions into syntactically correct SQL queries\n\n## What Problem This Solves\n\nNon-technical users know what data they want (\"show me revenue by month for the top 10 customers\") but can't write SQL. This skill bridges the gap — takes a schema + natural language request and produces a syntactically correct query with table aliases, proper JOINs, and GROUP BY.\n\n**When triggered:** Database schema + natural language question + write SQL intent.\n\n## Features\n\n- **Schema-aware translation** — asks for table/column schema before writing queries (never invents column names)\n- **Complete SQL coverage** — SELECT, WHERE, GROUP BY, ORDER BY, LIMIT, JOIN (INNER, LEFT, RIGHT), aggregate functions\n- **Plain English explanation** — outputs both the query AND a one-line description of what it does\n- **Multiple approach options** — `/alternatives` mode shows different JOIN strategies or subquery vs CTE approaches\n\n## Quick Start\n\n```bash\n# Via ClawHub\nclawhub install text-to-sql\n\n# Or manually\ncp -r text-to-sql ~/.openclaw/skills/\n```\n\n### Usage\n\n```\n/text-to-sql\n```\n\nProvide schema (table names + columns) and describe what data you want in English.\n\n```\n/text-to-sql/explain\n```\n\nOutputs query with inline comments explaining each clause — for learning purposes.\n\n```\n/text-to-sql/alternatives\n```\n\nShows 2-3 different query approaches for the same question.\n\n## Modes\n\n| Mode | Description |\n|------|-------------|\n| `/text-to-sql` | Converts natural language to SQL query |\n| `/text-to-sql/explain` | Query with inline comments explaining each clause |\n| `/text-to-sql/alternatives` | 2-3 alternative query strategies |\n\n## Examples\n\n| Request | Query |\n|---------|-------|\n| Schema: `users(id, name)`, `orders(user_id, total)` | `SELECT u.name, SUM(o.total) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name` |\n| \"top 10 customers\" | `ORDER BY total DESC LIMIT 10` added |\n| \"revenue by month\" | `SELECT DATE_TRUNC('month', date), SUM(revenue) FROM orders GROUP BY 1` |\n| No schema provided | Asks for schema first — doesn't guess column names |\n\n## Directory Structure\n\n```\ntext-to-sql/\n├── SKILL.md\n├── LICENSE\n├── README.md\n├── README_zh.md\n├── CONTRIBUTING.md\n├── .gitignore\n├── references/ # SQL dialect cheat sheet, JOIN guide, intent mapping\n└── tests/\n```\n\n## License\n\nMIT License — see [LICENSE](LICENSE)."},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn70zthc74p61mvctddrancx0s832g4r\",\n \"slug\": \"text-to-sql\",\n \"version\": \"2.0.3\",\n \"publishedAt\": 1780047410444\n}"},{"path":"references/index.md","content":"# text-to-sql — References\n\nDetailed documents for `user-describes-data` skill.\n\nTODO: Add reference files here as needed."},{"path":"CHANGELOG.md","content":"# Changelog\n## [1.0.1] - 2026-05-18\n\n### Minor update\n\n- **Previous:** 1.0\n- **Changed:** Updated skill content and quality\n\n\n\n## [1.0] - 2026-05-18\n\n### Added\n\n- Initial release"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1180,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T21:35:17.032Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T21:35:17.032Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:38:22.821Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}