Separate project-wide rules from on-demand skills with CLAUDE.md for SQL

CLAUDE.md is a Markdown file at the root of a repository. Claude Code loads it on the first turn of every conversation. It is the place teams encode the things they would otherwise say out loud to a new contributor: "we use pnpm, never npm", "API routes live under apps/api/src/routes", "prefer named exports".

The job CLAUDE.md does is configuration of agent behavior. It does not, and should not, contain the answers to data questions. It contains the rules the agent should follow when answering anything.

Same idea, other vendors: AGENTS.md is the file OpenAI Codex reads. The convention is shared. What each vendor's agent does with the file is that vendor's call, so read their docs before assuming identical behavior.

CHION.md is the skills-and-truth half of the pair: a compiled bundle of your team's saved and reviewed PostgreSQL queries, with a shared-rules header (the canonical revenue definition, the active-customer rule, the timezone convention) that every query inherits. Where CLAUDE.md tells the agent how to behave, CHION.md tells it which SQL the business has already agreed on. It is a contract, not a prompt: the answer is the query finance already signed off on.

The full anatomy (the root header, the per-query SKILL.md files, and the Postgres-grounded refresh model) lives in the CHION.md spec.

The clearest way to see the difference is to put the two files in adjacent columns and read across each row.

Notice that no row contains overlap. The two files answer different questions, which is why teams who adopt both stop arguing about whether the agent or the data is wrong, and start fixing whichever one actually is.

At runtime, the two files run a tiny relay. CLAUDE.md goes first, because it is loaded before the conversation begins. It teaches the agent your conventions and tells it where to look when a data question appears: "if the user asks about revenue, MRR, or churn, route to the relevant SKILL.md under skills/finance".

When the data question arrives, the agent resolves the matching SKILL.md from the CHION.md bundle. That SKILL.md carries a saved and reviewed SELECT rather than a description of one, so the agent has a reviewed query to run instead of a blank page. What the runtime does with it is the runtime's behavior, not a Chion guarantee.

For more on how skills get authored on the Claude side of that relay, the claude code skills practical guide walks the SKILL.md authoring convention in depth. This page stays on the file contract itself.

SKILL.md export is the operational verb that turns a workspace of saved and reviewed queries into a folder you can commit. It is intentionally short: four steps, the same every time.

Here is what one of the resulting files looks like. Keep this minimal. A real export contains one file per saved and reviewed query, but the shape is the same.

---
name: monthly-recurring-revenue-by-plan
description: Use when asked for MRR, ARR, recurring revenue, or subscription revenue split by plan on the production Postgres warehouse.
license: Proprietary
metadata:
  generator: chion.ai
  source: chion://verified-queries/finance/mrr-by-plan
  verified_at: 2026-05-22
---

# MRR by plan (verified)

Returns monthly recurring revenue grouped by plan_id for the
trailing 13 months. Uses the finance team's canonical revenue
rule from CHION.md (active subscriptions only, excludes refunds
inside the period).

```sql
SELECT date_trunc('month', billed_at) AS month,
       plan_id,
       SUM(amount_cents) / 100.0 AS mrr
FROM   billing.invoice_line_items
WHERE  status = 'paid'
  AND  billed_at >= now() - interval '13 months'
GROUP  BY 1, 2
ORDER  BY 1, 2;
```

The frontmatter is the contract. The body is human-readable context. The SQL block is the saved and reviewed query Chion will keep in sync on every refresh. That is what a portable SKILL.md buys you: one file to move between Claude Code and Codex rather than two to maintain, with each runtime's discovery path still its own. Inside Chion the query runs as a read-only SELECT, capped at 1,000 rows, against credentials held in an AES-256-GCM vault, and the run is written to the security audit log.

The full anatomy of the CHION.md root header (including the shared rule layer and the saved and reviewed query index) lives on the CHION.md reference page.

• CLAUDE.md = agent behavior file. Hand-authored. One per repo.
• CHION.md = saved SQL skills bundle. Compiled from your saved and reviewed queries.
• SKILL.md = the open file format inside the CHION.md bundle. One per query.
• SKILL.md export emits CHION.md, CONNECT.md, and one SKILL.md for the role you exported.
• The two files do not overlap. CLAUDE.md says how to act. CHION.md says what is true. A CLAUDE.md SQL file is really both: CLAUDE.md routes the question, CHION.md holds the SQL.
• SQL skills export means: take the queries your team already trusts, package them as SKILL.md, ship them with your repo.
• Postgres Claude skills and SQL skills for Claude are the same SKILL.md format; the label refers to which database they were grounded in.