Claude Code Skills for SQLYour verified SQL, as a SKILL.md.

A Claude Code Skill is a single Markdown file — SKILL.md — placed under .claude/skills/<persona>/ at the root of your repo. Claude Code discovers it on conversation start, indexes its YAML frontmatter, and routes prompts to the matching skill at runtime.

Where CLAUDE.md is one root file describing the whole repo, skills are many small files describing one job each: answer revenue questions, run a security review, generate a verified SQL query against the Postgres warehouse. The unit shrinks; the context grows sharper.

For SQL, the killer feature is grounding. A SKILL.md can declare a must-read on a CHION.md that contains the verified queries, schema mappings, and read-only discipline your team has already vetted — so the agent never invents a join or guesses at a column name.

Before SKILL.md was a thing, Claude Code shipped with CLAUDE.md as the root agent file and OpenAI's Codex shipped with AGENTS.md. The skills convention narrows the unit of work. Instead of one big file describing the whole repo, a skill describes one job.

The bytes are interchangeable. Pick the filename your agent prefers. The skill behind it is the same.

Every skill is two layers: a YAML frontmatter block the agent parses, and a Markdown body the agent reads as context. The frontmatter is what makes routing work. Below is the exact shape Chion emits for a finance-analyst skill.

---
name: finance-analyst
description: Use when answering revenue, MRR, ARR, churn, or cohort questions on the production Postgres warehouse.
triggers: [revenue, mrr, arr, churn, cohort, ltv, billing]
must-read:
  - CHION.md
  - personas/finance-analyst/_INDEX.md
mutability:
  layer_1: locked
  layer_2: overwrite-on-refresh
  persona: pass-A
  rules: pass-B
profiles:
  portable: true
  claude_code: true
metadata:
  tags: [postgres, finance, verified-sql]
---

Five fields do all the work. name is the persona slug. description always starts with "Use when" so the agent's routing layer can match prompts to skills. triggers are the high-signal vocabulary that pulls a prompt toward this skill. must-read declares the upstream files the agent should load alongside this skill. mutability tells Chion which blocks to regenerate on refresh and which to leave alone.

Before you reach for a compiler, it helps to write one skill by hand. This is what a minimum viable Postgres skill for Claude Code looks like — copy, paste, edit, commit.

---
name: revenue
description: Use when answering monthly recurring revenue, ARR, or revenue-by-plan questions on the Postgres warehouse.
triggers: [mrr, arr, revenue, recurring, plan]
must-read:
  - CHION.md
---

# Revenue skill

## Source of truth
- table: `billing.subscriptions`
- grain: one row per subscription per active day
- metric column: `amount_cents` (additive, sum is safe)

## Verified query
```sql
SELECT date_trunc('month', billed_on) AS month,
       plan,
       SUM(amount_cents) / 100.0 AS mrr_usd
FROM   billing.subscriptions
WHERE  status = 'active'
  AND  billed_on >= now() - interval '12 months'
GROUP  BY 1, 2
ORDER  BY 1, 2
LIMIT  1000;
```

## Example prompt
"What was MRR by plan for the last 6 months?"

Three things matter for routing: the description must start with "Use when", the triggers must match the vocabulary your team actually uses, and the verified SQL must be SELECT only, capped with LIMIT. Everything else is context the agent reads at the moment it picks the skill.

The fix is to compile your team's verified queries into one root CHION.md (shared SQL discipline, schema map, read-only rules) and a SKILL.md per persona that must-reads back into it. The SQL-to-skill compilation flow is named, sequential, and deterministic — not a prompt that returns vibes. Source lives in supabase/functions/capability-context/compile/.

One Opus pass per persona, roughly twenty credits each. A six-persona default workspace compiles a full agent repo in a single sitting. The artifact bundle is portable — see portable SQL skills for the cross-tool runtime details.

A workspace ships with named personas out of the box. Pick one to see the trigger vocabulary and the kind of skill artifact Chion will emit for it.

SKILL.md is an open standard, but Claude Code accepts a richer set of fields than the portable baseline. Chion writes both. The portable profile keeps the file readable in Cursor, Codex, or anywhere else. The claude_code profile layers on the optional fields that unlock Claude Code's routing and must-read behaviour.

The practical effect: the same artifact runs cleanly in three agents without forking.

Every block in a Chion SKILL.md has a declared mutability. This is what lets you re-run the compile on Friday afternoon without losing the rule edits you made on Monday morning.

• Layer 1 (locked): universal SQL discipline. Lives in CHION.md, referenced from every SKILL.md. Never overwritten by a persona compile.
• Layer 2 (overwrite-on-refresh): the persona body, regenerated from the latest verified queries every time the compile runs.
• Rules (pass-B): hand-authored conventions that survive refresh. This is where you put "always coalesce nulls in the revenue column".

1. Inside Chion, export your persona skills. You get a folder with one SKILL.md per persona, plus the shared CHION.md and a CLAUDE.md / AGENTS.md mirror.
2. Commit the folder to the root of your repo. The structure follows the published Claude Code skills convention so no rewriting is needed.
3. Open Claude Code, Codex, or Cursor. The agent picks up the root file on next launch and the skills folder on first prompt.
4. When the database changes, re-run the compile in Chion and push the updated artifacts. Diff the SKILL.md the same way you diff source code.

For a deeper look at running the same skill across runtimes (Chion, Claude Code, Codex, Cursor), see the portable SQL skills explainer. Chion compiles and hosts these as portable SQL skills; the analyst-facing surface is Chion's SQL AI Analyst framework.

• Claude Code Skills are persona-scoped SKILL.md files with YAML frontmatter that Claude Code loads on conversation start.
• The five load-bearing frontmatter fields are name, description, triggers, must-read, and mutability.
• Chion auto-compiles SQL SKILL.md files from your verified queries via a four step pipeline: harvest, stitch, validate, publish.
• Two-profile frontmatter (portable plus claude_code) makes the same artifact run in Claude Code, Codex, and Cursor.
• The mutability model separates locked discipline, refreshable persona content, and durable hand-authored rules.
• CHION.md, CLAUDE.md, AGENTS.md, and SKILL.md mirrors are byte identical. Pick the filename your agent prefers.