The Precision Tool

SenseQl

Precision where intelligence meets structured data.

SenseQl is a portable AI agent skill that acts as a virtual data analyst — translating business questions into validated, explainable SQL, with confidence scores, plain-language explanations, and every assumption disclosed.

Install SenseQlView on GitHub

What Is SenseQl?

Not a SQL generator. A trustworthy-answer engine.

SenseQl exists to help non-technical users answer business questions using data — without requiring SQL expertise. Its stated north star: never optimize for producing SQL, optimize for producing a trustworthy answer.

SQL is treated as an implementation detail. What SenseQl actually delivers is a validated answer in business language, accompanied by the metric definition used, the source table queried, the time period applied, any assumptions made, and a confidence rating.

It is built for teams and individuals who need answers from structured data — analysts, founders, operators, and engineers wiring an AI agent up to a database — who want that answer checked before it's trusted, not just generated quickly.

The Problem

Structured data punishes ambiguity.

A natural-language question can be answered by several technically-valid queries that mean different things — the wrong grain, an unstated definition of a metric, a join that silently duplicates rows, an assumption that never gets said out loud. None of that shows up as an error. It just produces a confident, wrong number.

SenseQl's Golden Rules exist to close that gap: never invent schema, columns, relationships, or metric definitions; always check table grain before joins or aggregations; validate generated SQL against the actual schema and business logic; and state every assumption instead of burying it.

Challenge Mode — verifying the premise

User: "Why did churn increase 20%?"

SenseQl: "I found a discrepancy. Churn rate increased 4.8%, while cancellation volume increased 20.1%. The 20% figure refers to cancellations, not the churn rate. Which would you like to investigate?"

How It Works

The Core Loop

AskUnderstandClarifyDefineDiscoverPlanGenerateValidateExplainChallenge

Five Layers

  1. 01

    Business Interaction

    Natural language questions, follow-ups, and insights.

  2. 02

    Business Intelligence

    Governed metrics, glossary, and definitions.

  3. 03

    Data Layer

    Schema, relationships, grain, and freshness.

  4. 04

    Query Intelligence

    SQL generation, 10-point validation, and optimization.

  5. 05

    Execution Layer

    Read-only enforcement, safety, and cost awareness.

Features

Seven user modes

  1. Ask

    Answer a business question in plain language.

  2. Generate

    Generate validated SQL for a requested analysis.

  3. Explain

    Explain what an existing SQL query does.

  4. Review

    Review SQL for correctness, logic, performance, and safety.

  5. Debug

    Investigate incorrect or failing SQL.

  6. Explore

    Suggest useful analyses and next questions.

  7. Optimize

    Improve query performance and cost.

Trust Model — every answer exposes

Answer
Direct response in business language
Definition
Which metric definition was used
Source
Table and schema queried
Time period
Exact date range applied
Data freshness
When the source data was last updated
Assumptions
Everything assumed when context was incomplete
Confidence
High / Medium / Low with rationale

The 15 Golden Rules

  1. 01Understand the business question before writing SQL
  2. 02Never invent schema, columns, relationships, or metric definitions
  3. 03Prefer trusted business definitions over inferred ones
  4. 04Ask clarifying questions only when ambiguity materially affects the answer
  5. 05Always check table grain before joins or aggregations
  6. 06Validate generated SQL against available schema and business logic
  7. 07Treat database access as read-only by default
  8. 08Never execute destructive or mutating SQL
  9. 09Consider data freshness before trusting results
  10. 10Prefer simple, readable SQL over clever complexity
  11. 11Explain results in business language
  12. 12State all assumptions and limitations
  13. 13Challenge incorrect assumptions when data contradicts them
  14. 14Never present uncertain results as facts
  15. 15Optimize for trustworthy answers, not SQL generation

Installation

Install SenseQl

One command installs the skill files into .agents/skills/senseql/ in your current project. Every agent below then needs, at most, one extra line of configuration.

curl -fsSL https://raw.githubusercontent.com/bishoy-bishai/SenseQl/main/install.sh | bash

Claude Code

Supported

1. Installation — run the command above.

2. Configuration — Nothing extra for a project-scoped install — Claude Code picks it up from .agents/skills/senseql/. For a global install instead, re-run with DEST set:

DEST=~/.claude/skills/senseql bash install.sh

3. Usage — Mention "SenseQL" in a message — there is no slash command.

4. Verification — Ask Claude Code a business question that includes the word "SenseQL" and confirm it follows the skill's Core Loop instead of answering generically.

Cursor

Supported

1. Installation — run the command above.

2. Configuration — Add this line to .cursorrules:

Follow all rules in .agents/skills/senseql/SKILL.md

3. Usage — Mention "SenseQL" in a message.

4. Verification — Confirm .cursorrules references the installed SKILL.md path, then ask a data question naming SenseQL.

Codex

Supported

1. Installation — run the command above.

2. Configuration — Add this line to AGENTS.md:

Follow all rules in .agents/skills/senseql/SKILL.md

3. Usage — Mention "SenseQL" in a message.

4. Verification — Confirm AGENTS.md references the installed SKILL.md path, then ask a data question naming SenseQL.

Antigravity

Supported — auto-detected

1. Installation — run the command above.

2. Configuration — Nothing to do — auto-detected from .agents/skills/senseql/SKILL.md.

3. Usage — Mention "SenseQL" in a message.

4. Verification — Confirm .agents/skills/senseql/SKILL.md exists, then ask a data question naming SenseQL.

Also documented in the repository: activation inside Claude.ai Projects (upload skill/ to Project knowledge, paste SKILL.md into Project instructions) and a ChatGPT Custom GPT (same pattern via Knowledge and Instructions).

Quick Start

A real worked example

From the repository's own example set — no invented syntax:

Input

"How many active customers do we have?"

SenseQl

  • Parses intent: metric, entity, time range, grain.
  • Looks up "Active Customers" in the Business Glossary — governed definition found, 95% confidence.
  • Generates and validates SQL against the discovered schema.

Output

Definition:
Customers with ≥1 active subscription (excl. test accounts)
Source:
subscriptions table
Assumptions:
Test accounts excluded via customers.is_test = TRUE
Confidence:
High — governed definition used
SELECT
  COUNT(DISTINCT customer_id) AS active_customers
FROM subscriptions
WHERE
  status = 'active'
  AND customer_id NOT IN (
    SELECT id FROM customers WHERE is_test = TRUE
  );

Use Cases

Where precision matters

Ask a plain-language business question

"How many active customers do we have?" is answered in business language, with the definition, source table, and confidence level attached — not a bare SQL dump.

Generate validated SQL for a real analysis

SQL is generated against actual discovered schema and passes a 10-point validation pipeline before being presented — never invented columns or relationships.

Review or debug an existing query

Review mode checks correctness, logic, performance, and safety; Debug mode investigates why a query is failing or returning wrong results.

Catch a wrong assumption before it becomes a wrong answer

Challenge Mode checks the premise of a question against the data itself — e.g. distinguishing a 20% rise in cancellation volume from a 4.8% rise in churn rate.

Technical Details

For developers

SenseQl ships as a markdown-only skill package — no source code, no build step. Everything under skill/ is instructions, knowledge, templates, and examples that an agent loads as context:

skill/
├── SKILL.md                 # main entry point (install this)
├── instructions/             # 01–10, the operating protocol
│   ├── skill-contract.md
│   ├── business-glossary.md
│   ├── schema-discovery.md
│   ├── query-planning.md
│   ├── sql-validation.md
│   ├── result-analysis.md
│   ├── safety.md
│   ├── output-format.md
│   └── ...(definition-fallback, schema-inference,
│           grain-detection, error-recovery, and more)
├── knowledge/
│   ├── metrics.md            # canonical metric definitions
│   ├── glossary.md           # business term → data mappings
│   └── query-memory.md
├── templates/
│   └── report-export.md
└── examples/
    ├── simple-question.md
    ├── ambiguous-question.md
    └── wrong-assumption.md

Roadmap

MVP — shipped now
Natural language → SQL, schema awareness, glossary, validation, explanation, read-only safety, report export.
V2 — next
Live query execution, result analysis, data quality awareness, grain detection automation.
V3 — future
Metric governance, data lineage, anomaly detection, cross-database analysis.

Database adapters — planned

Core intelligence is database-agnostic. Adapters are planned — not yet shipped — for PostgreSQL, MySQL, BigQuery, Snowflake, Redshift, DuckDB, SQLite, and CSV/Excel.

Built with

Built with AICraft — AI Engineering Discipline. License: MIT.

Compatibility

Supported AI Coding Agents

  • Claude CodeSupported
  • CursorSupported
  • CodexSupported
  • AntigravitySupported — auto-detected

Claude.ai Projects and Custom GPTs are also supported through a manual upload of the skill files — see the note under Install above.

FAQ

Frequently asked questions

What is SenseQl?
SenseQl is a portable AI agent skill that acts as a virtual data analyst — it translates business questions into validated, explainable SQL, with confidence scores, plain-language explanations, and assumption disclosure. It is not a SQL generator; SQL is an implementation detail in service of a trustworthy answer.
What does SenseQl do?
It runs a ten-step Core Loop (Ask → Understand → Clarify → Define → Discover → Plan → Generate → Validate → Explain → Challenge) across five layers — business interaction, business intelligence, data, query intelligence, and execution — to turn a natural-language question into a validated, explained answer.
How do I install SenseQl?
Run the one-command installer, which copies the skill files into .agents/skills/senseql/ in your current project, then activate it for your specific agent as described in the Install SenseQl section on this page.
Who should use SenseQl?
Non-technical users who need to answer business questions from data without writing SQL themselves, and teams who want AI-generated SQL to come with validation, explanation, and stated assumptions rather than a bare, unverified query.
Can SenseQl work with AI coding agents?
Yes. Beyond Claude.ai Projects and Custom GPTs, it activates in coding-agent environments including Claude Code, Cursor, Codex, and Antigravity by loading its SKILL.md as agent instructions.
Can I use SenseQl with Claude Code?
Yes. The installer's output is picked up automatically for a project-scoped install; a global install is available by re-running the installer with a DEST override.
Can I use SenseQl with Codex?
Yes, with one manual step: add a line to AGENTS.md pointing at the installed SKILL.md.
Can I use SenseQl with Cursor?
Yes, with one manual step: add a line to .cursorrules pointing at the installed SKILL.md.

The Precision Tool

SenseQl

Precision is a feature.

Install SenseQlView on GitHub

Part of the SIMURAI Arsenal