SQL AI Analyst Framework

Your SQL AI analyst — agent skills plus verified scripts, compiled per persona.

A SQL AI analyst is a per-persona agent built from your team’s verified SQL queries, organized as agent skills (Markdown files using the Claude skills format) with executable verified scripts underneath. Chion compiles one analyst per role (finance-analyst, fp-and-a-analyst, ops-supply-chain, warehouse-operations, growth-marketing, product-analytics) from a single Postgres connection. Every query passes through a two-layer validator before execution. The output exports as CHION.md (mirrored as CLAUDE.md, AGENTS.md, SKILL.md) and runs in Claude Code, Codex, or Cursor.

Chion is an AI SQL workforce. A SQL AI analyst is one persona inside it. Finance, ops, growth. Each compiled from your team’s verified queries.

Problem. One general-purpose AI assistant cannot answer six different roles’ questions correctly. What Chion does. Compiles a per-persona SQL analyst from your team’s verified queries. One for finance, one for ops, one for growth. Each scoped to the tables and rules of its role.

The folder ships from Chion as the compile output of one Opus 4.7 pass per persona. Three tiers: workspace at the root, department in the middle, role at the leaf. Verified scripts live under each role.

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 persona
    │   │   ├── SKILL.md                    ← persona 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 verified queries underneath each role. Drop the folder into any agent that reads the Claude skills convention and it inherits your team’s analytics know-how on first run.

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, Codex, and Cursor. 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 verified 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 verified SQL, wrapped as a CTE by the agent

Every verified query 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 the verified query.sql as a CTE rather than rewriting it. Promotion frequency surfaces in the auto-generated index as confidence badges (✓ / ✓✓ / ✓✓✓).

The agent never regenerates SQL that already works. This is the difference between a SQL AI 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.

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

The combination (read-only enforcement at the parser plus a typed contract at execution) is what makes Chion’s SQL AI analyst verified. See SQL agent vs text-to-SQL: the validator difference 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 verified script. If the LLM had instead emitted UPDATE customers SET region = 'EMEA', the read-only enforcement layer rejects at the AST before execution. 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”.

Chion compiles each persona in a single Opus 4.7 pass at roughly 20 credits per compile. The pass is deterministic: same input produces the same SKILL.md and the same scripts/ folder. A Max plan ships 750 credits per month, enough for up to ~40 per-persona analyst files: a full ~40-person data team’s worth of verified analysts.

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 persona on demand from the Studio header.

A credit is Chion’s unit of compute consumption, roughly equivalent to one verified question end-to-end, or about one-twentieth of a persona compile. 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 and Cursor pick up the same shape from .agents/skills/. The discovery contract is identical across tools.

Chion ships the same content under four mirror filenames: CHION.md, CLAUDE.md, AGENTS.md, SKILL.md. Drop any one at the repo root and the agent reads it on every conversation. Drop the full workspace under .claude/skills/ and the agent inherits the per-persona cascade. Use the four filenames interchangeably depending on which agent your team uses.

The open-source reference workspace lives at github.com/jonfdag-dot/postgres-claude-skills-generator: our open reference workspace ships six analyst personas, fifteen verified 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) drop the .claude/skills/ folder into the root of any repo you work in and Claude Code, Codex, or Cursor will discover the six personas on their next conversation; (3) ask a question whose trigger keywords match one of the personas (“ARR by segment”, “on-time delivery rate”, “cohort retention”) and watch the agent route to the verified script under that role. Once you connect your own Postgres in Chion Studio, the compile produces the same shape from your team’s queries.