Convert Natural Language

Core Position

This skill converts natural language input into structured machine-readable formats: SQL queries, JSON objects, API request specifications, search queries, regular expressions, and formal grammar productions. It does NOT just find-replace — it understands intent, extracts entities, resolves ambiguity, and produces semantically equivalent structured output.

Key responsibilities:

• Parse natural language to identify intent (what the user wants to do), entities (objects being referenced), and constraints (filters, conditions, limits)
• Map ambiguous conversational terms to precise structured syntax (e.g., "last week" → date >= NOW() - 7 days)
• Validate that the generated output is structurally correct (SQL parses, JSON is valid, regex compiles)
• Handle incomplete or ambiguous input by asking clarifying questions before generating wrong output

Modes

/convert-natural-language --sql

Natural language → SQL query. Converts a plain-language description into a syntactically valid SQL statement (SELECT, INSERT, UPDATE, DELETE). Supports PostgreSQL, MySQL, SQLite, and MongoDB query syntax.

Example: "show me all users who signed up in the last 30 days and have never made a purchase" → SELECT * FROM users WHERE created_at >= NOW() - INTERVAL '30 days' AND id NOT IN (SELECT user_id FROM purchases);

/convert-natural-language --json

Natural language → JSON object. Converts a description into a structured JSON document. Use when the user describes a data structure or configuration in plain terms.

Example: "a user with name John, email [email protected], age 30, and optional phone number" → {"name": "John", "email": "[email protected]", "age": 30, "phone": null}

/convert-natural-language --api

Natural language → API request specification. Converts a description into an HTTP API call: method, URL path, query parameters, headers, body.

Example: "get the profile of user ID 123 from the /users endpoint" → GET /users/123 (with auth header)

/convert-natural-language --search

Natural language → search query. Converts a conversational search request into a precise query string for a specific search engine or database full-text search.

Example: "find articles about AI from 2023 that mention GPT and were published in Nature or Science" → AI GPT 2023 site:nature.com OR site:science.com (or WHERE ... for DB)

/convert-natural-language --regex

Natural language → Regular expression. Converts a description of a text pattern into a regex pattern with named capture groups.

Example: "a date in the format YYYY-MM-DD, like 2024-01-15" → (?P\x3Cyear>\d{4})-(?P\x3Cmonth>\d{2})-(?P\x3Cday>\d{2})

/convert-natural-language --schema

Natural language → JSON Schema or TypeScript interface. Converts a description of a data structure into a formal schema definition.

Example: "an array of order objects, each with order_id (string), amount (number), status (enum: pending/paid/refunded), and optional notes" → TypeScript interface or JSON Schema.

/convert-natural-language --command

Natural language → shell command or CLI command. Converts a description into a valid shell command (bash, zsh) or CLI tool invocation (git, docker, kubectl, etc.).

Example: "show me all docker containers that are stopped" → docker ps -a --filter "status=exited"

Execution Steps

Step 1: Identify target format and intent

Detect target format from user input:

• Contains "SQL", "query", "database" → --sql
• Contains "JSON", "data structure", "object", "schema" → --json or --schema
• Contains "API", "endpoint", "GET", "POST", "request", "call" → --api
• Contains "search", "find articles", "google", "look for" → --search
• Contains "regex", "pattern", "match", "validate format" → --regex
• Contains "command", "terminal", "run", "execute", "docker", "kubectl", "git" → --command

If format is still ambiguous, ask: "Should this be converted to SQL, JSON, an API call, a search query, or another format?"

Identify intent components from the input:

1. Action: what to do (SELECT, CREATE, SEARCH, VALIDATE, etc.)
2. Subject: the primary entity (users, orders, articles)
3. Conditions: filters, constraints (date ranges, status values, IDs)
4. Fields: what to return or include (columns, properties)
5. Modifiers:排序 (order by), limit, group by

Step 2: Extract entities and map to structured syntax

Entity extraction patterns:

Step 3: Handle ambiguous or incomplete input

Ambiguous time references:

• "yesterday" → if today is 2024-01-16: DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY) (2024-01-15)
• "last week" → 7 days ago (or Monday to Sunday of last week — clarify)
• "recently" → ask for specific date range or use last 30 days as default

Ambiguous entity references:

• "the user", "they", "him" → ask for ID or use most recent if referentially clear
• "that order" → confirm which order if multiple candidates in context

Incomplete conditions:

• "show orders over $100" → infer ORDER BY amount DESC or ask for limit
• "users in California" → infer SELECT * but ask what fields to return

If critical information is missing and guessing would produce wrong output, ask before generating:

Cannot generate SQL: "users who bought something" — what table contains purchase records?
Please specify: (a) purchase/orders table name, (b) the link between users and orders tables (e.g., user_id foreign key).

Step 4: Generate structured output

For SQL mode:

1. Determine SELECT columns (use * if not specified, or list specific columns)
2. Determine FROM table (infer from context or ask)
3. Determine WHERE conditions (map from natural language)
4. Add ORDER BY, LIMIT, GROUP BY if specified
5. Validate: parse with SQL grammar checker if available

For JSON mode:

1. Identify required fields from description
2. Map natural language to JSON types: string, number, boolean, array, object, null
3. Apply format constraints: email format, date format, enum values
4. Validate: json.loads() to confirm valid JSON

For API mode:

1. Determine HTTP method from action (get → GET, create → POST, update → PUT/PATCH, delete → DELETE)
2. Build URL path with path parameters (/users/{id})
3. Add query parameters for filters
4. Add headers (auth: Bearer token from env)
5. Validate: URL is well-formed, method is appropriate for resource

For Regex mode:

1. Identify required segments and their formats
2. Add named capture groups for each extracted entity
3. Add anchors (^ at start, $ at end) if pattern represents a complete match
4. Validate: compile with re.compile() — if fails, report syntax error with position

Step 5: Validate output

SQL validation:

# Use sqlparse (if available) to check syntax
import sqlparse
parsed = sqlparse.parse(output)
if not parsed:
    report_error("Invalid SQL syntax at character {pos}")
# Check for dangerous operations (DROP, DELETE without WHERE — warn but don't block)

JSON validation:

import json
try:
    json.loads(output)
except json.JSONDecodeError as e:
    report_error(f"Invalid JSON: {e.msg} at position {e.pos}")

Regex validation:

import re
try:
    re.compile(output)
except re.error as e:
    report_error(f"Invalid regex: {e.msg} at position {e.pos}")

API validation:

• Method + URL must match (e.g., GET with body → warn)
• Path parameters must be present in URL
• Auth header must be included (or document required header)

Step 6: Return with explanation

For every conversion, return:

1. The structured output (the SQL, JSON, etc.)
2. A mapping explanation — how each NL phrase was interpreted:

   "last 30 days" → WHERE created_at >= NOW() - INTERVAL '30 days'
   "never made a purchase" → AND id NOT IN (SELECT user_id FROM purchases)
   

3. Confidence — how confident the conversion is:
   • high: intent clear, entities unambiguous, conditions complete
   • medium: some ambiguity resolved by reasonable default
   • low: significant assumptions made — flag for user review

{
  "output": "SELECT * FROM users WHERE created_at >= NOW() - INTERVAL '30 days' AND id NOT IN (SELECT user_id FROM purchases);",
  "format": "sql",
  "dialect": "postgresql",
  "confidence": "high",
  "explanation": {
    "last 30 days": "WHERE created_at >= NOW() - INTERVAL '30 days'",
    "never made a purchase": "AND id NOT IN (SELECT user_id FROM purchases)",
    "all users": "SELECT * FROM users"
  },
  "warnings": [],
  "assumptions": []
}

Mandatory Rules

Do not

• Do not generate SQL INSERT/UPDATE/DELETE from natural language without explicitly confirming — destructive operations require --confirm-dml flag
• Do not guess table names or column names when they're absent from the description — ask instead of assuming
• Do not produce SQL that performs a full table scan without at least warning the user (e.g., SELECT * FROM huge_table without WHERE)
• Do not generate regex that matches extremely broad patterns (e.g., .*) without flagging as too permissive
• Do not convert natural language to shell commands that contain rm -rf or other destructive operations without explicit confirmation
• Do not assume a specific database dialect when the user didn't specify — default to the most common (PostgreSQL) but flag in output

Do

• Show the mapping between natural language phrases and generated syntax (Step 6 explanation)
• Flag low-confidence conversions and explain why: "Assumed 'orders' table exists — verify table name matches your schema"
• Handle time zone references: "today" means current date in the user's configured timezone (default UTC)
• Handle plurals and mass nouns: "users" → users table, "order items" → order_items table (snake_case plural)
• Preserve case sensitivity when the user specifies it: "userID" different from "user_id"
• For SQL, always include a semicolon at end of statement

Quality Bar

A good output is syntactically valid, semantically equivalent to the input natural language, includes a clear explanation of how each phrase was interpreted, and flags any areas of ambiguity that required assumptions.

Good vs. Bad Examples