What is an AI SQL analyst?

An AI SQL analyst turns a plain-English business question into a SQL query, runs it against your database, and returns the number together with the statement that produced it. Chion writes a new read-only SELECT for every question, built on a base query someone on your team saved and reviewed in Studio, so each answer starts from logic a reviewer approved.

The compiler knows six role archetypes (finance-analyst, fp-and-a-analyst, ops-supply-chain, warehouse-operations, growth-marketing, product-analytics); each export compiles one role, from the queries your team saved and reviewed and scoped to the tables and rules of that role, and every answer in Chion Studio ships with a chart and a written narrative. One general-purpose assistant cannot answer six roles’ questions correctly; a role-scoped analyst can. Chion ships a full AI SQL workforce; this page covers the analyst role inside it.

The folder ships from Chion as the compile output of three model passes per role. Three tiers: workspace at the root, department in the middle, role at the leaf. Saved scripts live under each role. The tree below shows the layout after activation; the export itself arrives with skills/ un-dotted, and one move or symlink puts it under .claude/skills/.

chion-skills-workspace/
├── CHION.md                                ← root agent file (canonical)
├── README.md
└── .claude/skills/
    ├── _INDEX.md                           ← workspace catalog + routing
    ├── finance/                            ← department
    │   ├── _INDEX.md
    │   ├── finance-analyst/                ← role · the analyst
    │   │   ├── SKILL.md                    ← role brain + scripts index
    │   │   └── scripts/
    │   │       ├── arr-by-segment/{README.md, query.sql}
    │   │       └── mrr-trend-12mo/{README.md, query.sql}
    │   └── fp-and-a-analyst/{SKILL.md, scripts/}
    ├── operations/
    │   ├── ops-supply-chain/{SKILL.md, scripts/}
    │   └── warehouse-operations/{SKILL.md, scripts/}
    └── growth/
        ├── growth-marketing/{SKILL.md, scripts/}
        └── product-analytics/{SKILL.md, scripts/}

The CHION.md at the root is the canonical agent file. The .claude/skills/ cascade beneath it carries one folder per department, one folder per role, then a SKILL.md brain and a scripts/ folder of saved queries underneath each role. Move that cascade into the directory your agent reads and it inherits your team’s analytics know-how on the next conversation.

Each role’s SKILL.md opens with an 11-field frontmatter block. Skills are not loose prose; they are a typed contract the agent parses before reading anything else.

---
name: finance-analyst
description: |
  The default analyst role for the finance department.
  Owns recognized-revenue P&L, segment-margin reconstruction,
  ARR/MRR roll-ups, and renewal recognition.
must-read: [_INDEX.md, ../_INDEX.md]
trigger-keywords: [revenue, recognized revenue, ARR, MRR,
                   GAAP, gross margin, segment margin, renewal]
department: finance
role: finance-analyst
archetype: saas_finance
chosen_primitives: [pre_aggregate_grain,
                    period_over_period_lag,
                    ratio_reconstruction]
framework_version: 7
refreshed_at: 2026-04-30T18:22:11Z
status: verified
---

name and description drive native skill discovery in Claude Code and Codex. trigger-keywords route a question to the skill: “revenue”, “ARR”, “MRR” land in finance-analyst, not ops-supply-chain. must-read lists the parent index files the agent loads before answering. archetype and chosen_primitives tell the agent which SQL patterns are valid for this role’s data shape: pre_aggregate_grain, ratio_reconstruction, period_over_period_lag. framework_version and refreshed_at make the file diffable across compile runs.

Underneath every role’s SKILL.md lives a scripts/ folder of saved queries. Each script is a {README.md, query.sql} pair.

finance/finance-analyst/scripts/arr-by-segment/
├── README.md       ← what the script computes, who reviewed it, when
└── query.sql       ← executable saved SQL, wrapped as a CTE by the agent

Every query your team saved and reviewed under a role lands in scripts/<name>/ as a {README.md, query.sql} pair. When a question matches the script’s trigger pattern, the agent wraps that query.sql as a CTE rather than rewriting it.

The saved query.sql is not rewritten; the new statement wraps it. This is the difference between an AI SQL analyst and a text-to-SQL tool: the analyst’s library compounds with every question your team asks; the text-to-SQL prompt resets every turn.

Saved scripts and fresh-generated queries both pass through the same two validator layers. Validation happens at the runtime, not in the prompt.

The combination (read-only pattern enforcement in the application plus a typed contract at execution) is what makes Chion’s AI SQL analyst code-validated. See Chion vs text-to-SQL tools for the full architectural comparison.

Worked example. A question lands: show me last quarter’s revenue by region. The agent matches the trigger and routes to the saved script. If the LLM had instead emitted UPDATE customers SET region = 'EMEA', the read-only enforcement layer rejects it before execution because the statement does not begin with SELECT or WITH. If the LLM had emitted SELECT customer_lifetime_value FROM customers against a schema where the real column is ltv_usd, the SQL contract validator rejects before the query touches your database. Both failures surface to the user with the rejected SQL visible. No silent fallback, no auto-coerced query, no “maybe this worked”.

Read-only SELECT. Credentials in an AES-256-GCM vault. Results capped at 1,000 rows. Each executed query leaves an audit row, written fire-and-forget so a logging failure never blocks your answer. Read the full security model →

Chion compiles each role in three model passes at roughly 20 credits per compile. See how Chion compiles skills end to end. The slot-filling pass runs at temperature 0, so the same evidence produces the same SKILL.md structure and the same scripts/ folder; role voice and rule selection allow mild variation. A Max plan ships 750 credits per month, enough for up to ~37 compiles, one role per export today.

Each compile writes a new domain_agents row in your workspace and transitions it from in_progress to draft to published. The prior version is superseded cleanly. You can diff analyst files across releases the same way you diff code. Recompile any role on demand from the Studio header.

A credit is Chion’s unit of compute consumption, and how many a request draws depends on the work it performs rather than on a flat per-question rate. Starter ships 50 credits, Pro 250, Max 750. Schema-exploration queries (“what tables do I have”, “describe this column”) stay free on every plan and never count against the allotment. Lifecycle states are persisted: in_progress means the compile is running, draft means it finished and is awaiting publish, published means it’s the active agent. Older rows stay queryable in the audit log so you can roll back without losing context.

The Claude skills format is the convention Claude Code uses to load skills from .claude/skills/. Codex CLI picks up the same shape from .agents/skills/. The discovery contract is identical across tools.

Chion compiles CHION.md, CONNECT.md, and a skills/ folder holding one SKILL.md per role. CHION.md carries the seven Layer 1 rules in full; each SKILL.md inlines them as a seven-line quick reference. The folder arrives un-dotted so you can read every file before you activate it, then one move puts it where your agent looks: mv skills .claude/skills for Claude Code, or a symlink that leaves the tree in place. CLAUDE.md and AGENTS.md are host conventions, not compiler output. See how the analyst skills run inside Claude Code.

The open-source reference workspace lives at github.com/jonfdag-dot/postgres-claude-skills-generator: our open reference workspace ships six analyst roles, fifteen saved Postgres scripts, and three sister-role pairings, published as the exact folder shape Chion exports. Read it end-to-end before you compile your own.

To onboard in three steps: (1) clone the reference workspace and read one SKILL.md to see the frontmatter shape and the scripts index; (2) copy its .claude/skills/ folder into the root of any repo you work in and Claude Code discovers the role on its next conversation, or move the same tree to .agents/skills/ for Codex; (3) ask a question whose trigger keywords match that role (“ARR by segment”, “on-time delivery rate”, “cohort retention”) and watch the agent route to the saved script under it. Once you connect your own Postgres in Chion Studio, the compile produces the same shape from your team’s queries: an AI analyst for PostgreSQL built only from SQL your team signed.