Text To Sql

Name: Text To Sql
Author: oimiragieo

oimiragieo/agent-studio

142 installs
36 repo stars
Updated July 14, 2026
oimiragieo/agent-studio

Turn natural-language questions into safe, correct SQL for analytics agents, dashboards, and data exploration tools backed by relational databases.

About

Enables agents to convert natural-language requests into SQL against relational schemas, supporting analytics, exploration, and data-backed features in agent-studio builds.

Natural language to SQL translation
Relational schema-aware query generation
Agent-friendly database access patterns
Analytics and exploration use cases
Safer structured querying from prompts

Text To Sql by the numbers

142 all-time installs (skills.sh)
+6 installs in the week ending Aug 4, 2026 (Skillselion tracking)
Ranked #281 of 911 Databases skills by installs in the Skillselion catalog
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/oimiragieo/agent-studio --skill text-to-sql

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/oimiragieo/agent-studio/text-to-sql.svg)](https://skillselion.com/skills/oimiragieo/agent-studio/text-to-sql)

Installs	142
repo stars	★ 36
Last updated	July 14, 2026
Repository	oimiragieo/agent-studio ↗

What it does

Turn natural-language questions into safe, correct SQL for analytics agents, dashboards, and data exploration tools backed by relational databases.

Files

SKILL.mdMarkdownGitHub ↗

Mode: Cognitive/Prompt-Driven — No standalone utility script; use via agent context.

Text-to-SQL Skill

Identity

Text-to-SQL - Converts natural language queries to SQL using database schema context and query patterns.

Capabilities

Query Generation: Convert natural language to SQL
Schema Awareness: Uses database schema for accurate queries
Query Optimization: Generates optimized SQL queries
Parameterized Queries: Creates safe, parameterized queries

Usage

Basic SQL Generation

When to Use:

Database queries from natural language
Data analysis requests
Reporting queries
Ad-hoc database queries

How to Invoke:

"Generate SQL to find all users who signed up in the last month"
"Create a query to calculate total revenue by product"
"Write SQL to find duplicate records"

What It Does:

Analyzes natural language query
References database schema
Generates SQL query
Validates query syntax
Returns parameterized query

Advanced Features

Schema Integration:

Loads database schema
Understands table relationships
Uses column types and constraints
Handles joins and aggregations

Query Optimization:

Generates efficient queries
Uses appropriate indexes
Optimizes joins
Minimizes data transfer

Safety:

Parameterized queries (prevents SQL injection)
Validates query syntax
Tests on sample data
Error handling

Best Practices

1. Schema Context: Provide complete database schema 2. Query Validation: Validate SQL before execution 3. Parameterization: Always use parameterized queries 4. Testing: Test queries on sample data 5. Optimization: Review query performance

Integration

With Database Architect

Text-to-SQL uses schema from database-architect:

Table definitions
Relationships
Constraints
Indexes

With Developer

Text-to-SQL generates queries for developers:

Query templates
Parameterized queries
Query optimization
Error handling

Examples

Example 1: Simple Query

User: "Find all users who signed up in the last month"

Text-to-SQL:
1. Analyzes query
2. References users table schema
3. Generates SQL:
   SELECT * FROM users
   WHERE created_at >= DATE_SUB(NOW(), INTERVAL 1 MONTH)
4. Returns parameterized query

Example 2: Complex Query

User: "Calculate total revenue by product for Q4"

Text-to-SQL:
1. Analyzes query
2. References orders and products tables
3. Generates SQL:
   SELECT p.name, SUM(o.total) as revenue
   FROM orders o
   JOIN products p ON o.product_id = p.id
   WHERE o.created_at >= '2024-10-01'
     AND o.created_at < '2025-01-01'
   GROUP BY p.id, p.name
4. Returns optimized query

Evaluation

Evaluation Framework

Based on Claude Cookbooks patterns, text-to-SQL evaluation includes:

Syntax Validation:

SQL syntax correctness
Schema compliance
Query structure validation

Functional Testing:

Query execution on test database
Result correctness
Performance validation

Promptfoo Integration:

Multiple prompt variants (basic, few-shot, chain-of-thought, RAG)
Temperature sweeps
Model comparisons (Haiku vs Sonnet)

Evaluation Configuration: Create a promptfoo config file for your evaluation setup (e.g., text_to_sql_config.yaml).

Running Evaluations

# Run text-to-SQL evaluation (create config first)
npx promptfoo@latest eval -c text_to_sql_config.yaml

Evaluation Metrics

Syntax Accuracy: Percentage of queries with valid SQL syntax
Functional Correctness: Percentage of queries returning correct results
Schema Compliance: Percentage of queries using correct schema
Performance: Query execution time and optimization

Best Practices from Cookbooks

1. Provide Schema Context

Always include complete database schema:

Table definitions with column types
Relationships and foreign keys
Constraints and indexes
Sample data patterns

2. Use Few-Shot Examples

Provide examples of similar queries:

Simple queries
Complex queries with joins
Aggregation queries
Subquery patterns

3. Chain-of-Thought for Complex Queries

For complex queries, use chain-of-thought reasoning:

Break down query into steps
Identify required tables
Plan joins and aggregations
Generate SQL step by step

4. RAG for Schema Understanding

Use RAG to retrieve relevant schema information:

Find relevant tables for query
Understand relationships
Get column details
Retrieve query patterns

Related Skills

classifier: Classify database queries
database-architect: Use for schema design
developer: Generate query code

Iron Laws

1. ALWAYS validate all table and column names against the provided schema before generating SQL 2. NEVER use string interpolation for query values — parameterized queries are mandatory without exception 3. ALWAYS apply a LIMIT clause (default 100) to SELECT queries unless the user explicitly overrides it 4. NEVER execute DROP, DELETE, TRUNCATE, or UPDATE statements without explicit user confirmation 5. ALWAYS explain the generated query logic in plain language so the user understands what will execute

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
String interpolation for values	SQL injection vulnerability	Use parameterized queries with `?` or `$N` placeholders
No LIMIT clause on SELECT	Returns all rows, risk of OOM and timeout	Default `LIMIT 100`, require explicit user override
Destructive SQL without confirmation	Irreversible data loss	Gate DROP/DELETE/TRUNCATE behind user confirmation
No schema validation	References non-existent tables or columns	Validate all identifiers against the provided schema
SELECT \* without column list	Unpredictable results and performance waste	Always specify an explicit column list

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

#!/usr/bin/env node

/**
 * text-to-sql - Post-Execute Hook
 * Runs after the skill executes for cleanup, logging, or follow-up actions.
 */

const fs = require('fs');
const path = require('path');
const { safeParseJSON } = require('../../../lib/utils/safe-json.cjs');

// Parse hook input
const result = safeParseJSON(process.argv[2] || '{}');

console.log('📝 [TEXT-TO-SQL] Post-execute processing...');

/**
 * Process execution result
 */
function processResult(_result) {
  // TODO: Add your post-processing logic here

  return { success: true };
}

// Run post-processing
const outcome = processResult(result);

if (outcome.success) {
  console.log('✅ [TEXT-TO-SQL] Post-processing complete');
  process.exit(0);
} else {
  console.error('⚠️  [TEXT-TO-SQL] Post-processing had issues');
  process.exit(0);
}

#!/usr/bin/env node

/**
 * text-to-sql - Pre-Execute Hook
 * Runs before the skill executes to validate input or prepare context.
 */

const fs = require('fs');
const path = require('path');
const { safeParseJSON } = require('../../../lib/utils/safe-json.cjs');

// Parse hook input
const input = safeParseJSON(process.argv[2] || '{}');

console.log('🔍 [TEXT-TO-SQL] Pre-execute validation...');

/**
 * Validate input before execution
 */
function validateInput(_input) {
  const errors = [];

  // TODO: Add your validation logic here

  return errors;
}

// Run validation
const errors = validateInput(input);

if (errors.length > 0) {
  console.error('❌ Validation failed:');
  errors.forEach(e => console.error('   - ' + e));
  process.exit(1);
}

console.log('✅ [TEXT-TO-SQL] Validation passed');
process.exit(0);

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "text-to-sql Input Schema",
  "description": "Input validation schema for text-to-sql skill",
  "type": "object",
  "required": [],
  "properties": {},
  "additionalProperties": true
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "text-to-sql Output Schema",
  "description": "Output validation schema for text-to-sql skill",
  "type": "object",
  "required": ["success"],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the skill executed successfully"
    },
    "result": {
      "type": "object",
      "description": "The skill execution result",
      "additionalProperties": true
    },
    "error": {
      "type": "string",
      "description": "Error message if execution failed"
    }
  },
  "additionalProperties": true
}

#!/usr/bin/env node

/**
 * Text To Sql - Main Script
 * Convert natural language queries to SQL. Use for database queries, data analysis, and reporting.
 *
 * Usage:
 *   node main.cjs [options]
 *
 * Options:
 *   --help     Show this help message
 */

const fs = require('fs');
const path = require('path');

// Find project root
function findProjectRoot() {
  let dir = __dirname;
  while (dir !== path.parse(dir).root) {
    if (fs.existsSync(path.join(dir, '.claude'))) {
      return dir;
    }
    dir = path.dirname(dir);
  }
  return process.cwd();
}

const PROJECT_ROOT = findProjectRoot();

// Parse command line arguments
const args = process.argv.slice(2);
const options = {};
for (let i = 0; i < args.length; i++) {
  if (args[i].startsWith('--')) {
    const key = args[i].slice(2);
    const value = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
    options[key] = value;
  }
}

/**
 * Main execution
 */
function main() {
  if (options.help) {
    console.log(`
Text To Sql - Main Script

Usage:
  node main.cjs [options]

Options:
  --help     Show this help message
`);
    process.exit(0);
  }

  console.log(
    'Text-to-SQL skill provides in-context guidance for converting natural language to SQL. Invoke via the agent; no standalone script.'
  );
  process.exit(0);
}

main();