A Claude Code Skill is a single Markdown file, SKILL.md, placed under .claude/skills/<role>/ in your repo, or ~/.claude/skills/<role>/ when you want it in every repo. Claude Code carries the name and description from its YAML frontmatter and loads the body on demand, when a prompt matches. The format follows the Agent Skills open standard.

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 code-validated SELECT against the Postgres warehouse. The unit shrinks; the context grows sharper.

For SQL, the killer feature is grounding. A SKILL.md body can point at a CHION.md that contains the saved and reviewed queries, schema mappings, and read-only discipline your team has already vetted, so the agent reads a reviewed join instead of guessing 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.

Pick the filename your agent reads. The saved and reviewed SELECT and its context are the same in each. What differs is how much Layer 1 rule text the file carries and where each runtime looks for it.

Every skill is two layers: a YAML frontmatter block the agent parses, and a Markdown body the agent reads as context once the skill is matched. 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, cohort, or LTV questions on the
  production Postgres warehouse.
license: Proprietary
allowed-tools: Read Grep Glob Bash(python scripts/*) Bash(psql -c *)
model: claude-opus-4-7
paths: "*.sql, models/finance/**"
metadata:
  generator: chion.ai
  framework_version: "7"
  archetype: revenue-analyst
  department: finance
  analytical_pattern: trend
  tags: [postgres, finance, verified-sql]
---

Routing runs on two of these. name is the role slug. description starts with "Use when" and front-loads the high-signal vocabulary, because the format has no separate trigger-keywords field and an invented one would be ignored. The rest is bookkeeping the agent does not route on: license, a metadata map Chion stamps with the generator, framework version, archetype, department, analytical pattern, and tags, and the claude_code additions allowed-tools, model, and paths. Which blocks Chion regenerates on refresh is recorded in an audit comment at the end of the file, not in the frontmatter.

One failure mode is worth knowing: if the YAML block is malformed, the skill still loads but with empty metadata, so /skill-name keeps working while routing silently stops. Validate the frontmatter before committing. If Claude Code rejects the file outright, the fixes live in the SKILL.md frontmatter error guide.

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 MRR, ARR, recurring revenue, or revenue-by-plan questions on the Postgres warehouse.
---

# Revenue skill

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

## Saved 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?"

Two things matter for routing: the description must start with "Use when" and carry the vocabulary your team actually types, and the saved and reviewed 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 saved and reviewed queries into one root CHION.md (shared SQL discipline, schema map, read-only rules) and a SKILL.md per role that 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/.

Three model passes per role, roughly twenty credits per compile, one role per export today. The artifact bundle is portable. See portable SQL skills for the cross-tool runtime details.

A workspace ships with named roles out of the box. Pick one to see the trigger vocabulary and the kind of skill artifact Chion's Claude SQL skills generator emits for it.

SKILL.md is an open standard, but Claude Code accepts a few fields beyond the portable baseline. Chion writes both profiles. The portable profile is name, description, license, and metadata, which any host can read. The claude_code profile appends allowed-tools, model, and paths between the description and the metadata map, and a host that does not know those keys ignores them.

The practical effect: one artifact, no per-agent fork. What each agent does with it still depends on that agent.

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. Inlined into every compiled SKILL.md so the file stands alone, with CHION.md carrying the same seven rules in full as an optional reference. Never overwritten by a role compile.
• Layer 2 (overwrite-on-refresh): the role body, regenerated from the latest saved and reviewed queries on every compile.
• 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 skills. You get a folder with CHION.md and CONNECT.md at the root and one SKILL.md for the role you exported under skills/.
2. Commit the folder. For Claude Code, the skills go under .claude/skills/ in the repo or ~/.claude/skills/ for every repo; Codex has its own documented location, so check it before assuming the folder is picked up.
3. Open Claude Code or Codex. The root file is read at launch; a skill body is pulled in when a prompt matches its description.
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), see the portable SQL skills explainer. Chion compiles and hosts these as portable SQL skills; the analyst-facing surface is Chion's AI SQL Analyst framework.

Nothing in the SKILL.md contract is specific to SQL. Frontmatter routes on a name and a description, and the body tells the agent what it is allowed to treat as true. Swap the evidence store and the same file governs a skill that reads pictures, or one that reads the open web.

That shape already runs outside analytics. Lensmark, an AI landmark identifier built on the same rule, takes a photograph of a building, a monument, or a museum piece and returns its history: what it is, when it went up, who made it, and why it mattered. Independent identifiers have to agree before a name reaches the reader, every date traces to a retrieved source the reader can open, and a subject nothing can confirm comes back as unconfirmed rather than as a plausible guess.

Only the evidence store differs. Chion's is a read-only SELECT your team saved, reviewed, and already trusts; a photo skill's is the public record. The frontmatter, the routing, and the rule against answering past your evidence are the same three moves.

• Claude Code Skills are role-scoped SKILL.md files under .claude/skills/ in the repo or ~/.claude/skills/ for every repo. Claude Code carries the name and description and loads the body on demand.
• Routing runs on two frontmatter fields, name and description. There is no triggers field, so the trigger vocabulary is front-loaded into the description.
• Chion auto-compiles SQL SKILL.md files from your saved and reviewed queries via a four step pipeline: harvest, stitch, validate, publish.
• Two-profile frontmatter (portable name/description/license/metadata, plus claude_code allowed-tools/model/paths) keeps one artifact readable in Claude Code and Codex.
• The mutability model separates locked discipline, refreshable role content, and durable hand-authored rules. It is recorded in the file's audit comment, not the frontmatter.
• The bundle shares one thing across filenames: the saved and reviewed SELECT and the context around it. CHION.md holds the seven Layer 1 rules in full while a compiled SKILL.md inlines a summary of each, so pick the filename your agent reads and check that agent's own discovery path.