CLAUDE.md and CHION.md.Behavior file, skills file.

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 (OpenAI Codex) is the equivalent filename. The convention is shared; only the filename differs.

CHION.md is the skills-and-truth half of the pair: a compiled bundle of your team's verified 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 personas/finance".

When the data question arrives, the agent resolves the matching SKILL.md from the CHION.md bundle. The SQL inside that SKILL.md is the SQL it runs. It does not improvise. It does not pattern-match against a fresh prompt. It executes the verified query — the same query a human on the data team would have written.

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 verified 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 verified query, but the shape is the same.

---
name: monthly-recurring-revenue-by-plan
description: Use when asked for MRR, ARR, or recurring revenue split by plan on the production Postgres warehouse.
triggers: [mrr, arr, recurring revenue, plan, subscription]
must-read:
  - CHION.md
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 verified query Chion will keep in sync on every refresh. This is what we mean by a portable SKILL.md: it travels intact between Claude Code, Codex, and Cursor, with no rewriting.

The full anatomy of the CHION.md root header — including the shared rule layer and the verified query index — lives on the CHION.md reference page.

• CLAUDE.md = agent behavior file. Hand-authored. One per repo.
• CHION.md = verified SQL skills bundle. Compiled from your promoted queries.
• SKILL.md = the open file format inside the CHION.md bundle. One per query.
• SKILL.md export emits a portable SKILL.md set plus CLAUDE.md and AGENTS.md mirrors.
• The two files do not overlap. CLAUDE.md says how to act. CHION.md says what is true.
• 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 byte-identical SKILL.md files; the label refers to which database they were grounded in.