SKILL.md SQL Example With a Read-Only SELECT

An exported Agent Skills.zip running natively across Chion, Claude Code, and Codex. — One bundle, four runtimes. The file is the contract; the runtime is a consumer.

Portable SQL skills: a saved and reviewed SELECT in a file, not instructions to write one

Portable SQL skills are compiled, reusable SQL skills stored as plain SKILL.md files: YAML frontmatter (a name and a description carrying the trigger vocabulary) plus the saved and reviewed SELECT that answers the question, with the semantic-layer definitions in the body. Four runtimes read the same file. Where each runtime looks for it, and what it is allowed to run once it finds it, stays that runtime's business.

.claude/skills/monthly-revenue/SKILL.md

---
name: monthly-revenue
description: Use when asked for monthly revenue or revenue by month from the orders table.
license: Proprietary
metadata:
  semantic_layer: revenue.month_grain
---

SELECT date_trunc('month', created_at) AS month,
       SUM(amount) AS revenue
FROM   orders
GROUP  BY 1
ORDER  BY 1
LIMIT  1000;

The Claude Code surface in detail (SKILL.md anatomy, how Claude reads .claude/skills/, the writing walkthrough) is the canonical reference on where Claude Code looks for skills. This page is the cross-tool argument: one SKILL.md that four runtimes read as-is, kept in your repo rather than a vendor control plane.

When your queries live in a vendor's control plane, switching tools is a migration project

Most "skills" today are skills inside one tool. Drop the vendor and the skill disappears with them. The queries your team wrote (the ones finance already signed off on, the ones that match the board pack) live in a vendor control plane you cannot export. That is not a skill library; that is a migration project waiting to happen.

Vendor-proprietary skill format

The skill lives inside the vendor's control plane. Export is "contact sales." Your queries are theirs to render.

Hard-coded model dependency

The skill only runs if a specific model is wired in. The next model wins the benchmark; your skill library does not move.

Runtime-coupled definitions

The semantic layer that "active customer" depends on is stored in the vendor's database, not in your repo. Switching tools means re-writing every definition.

No file you can check in

The skill is a row in a vendor table. There is nothing to put in pull-request review, nothing to grep, nothing to fork.

The fix is not "trust the vendor more." The fix is a portable file format the vendor does not control. Plain text. In your repo. Reviewed in pull requests. Readable by any runtime that knows the convention.

Claude Code, Codex, and Cursor read the same SKILL.md; each one wires discovery and execution its own way

The file is one SKILL.md; the wiring is four separate runtimes. Click a runtime to see the artifact path, the invocation shape, and any wrapper notes. The matrix below goes row by row through where the runtimes match and where a row falls back to your role or your wrapper, which is what Chion compiles per runtime from one saved and reviewed SELECT.

Studio chat + Postgres connection

Chion

Artifact: SKILL.md + CHION.md registry
Path: .chion/skills/<name>/SKILL.md
Invocation: Prompt matches skill triggers; the saved and reviewed SELECT becomes the base CTE and a new outer SELECT is generated against it
Notes: Native runtime. Validation, audit, and read-only enforcement happen here.

Capability	Chion	Claude Code	Codex / OpenAI agents	Cursor
Reads the same SKILL.md
Prompt matched against the description			Via your wrapper	Per Cursor rules config
Runs the saved SELECT verbatim		Via your role	Via your wrapper	Via your role
Read-only execution enforced	In runtime	Via your role	Via your role	Via your role
Audit log of every run		Via your wrapper	Via your wrapper	Via your wrapper
Semantic-layer definitions bundled
Model-agnostic		Claude only	OpenAI only
Diff-able in pull requests

The runtimes that need a thin wrapper (Codex, Cursor, Claude Code) still read the same SKILL.md. The wrapper is a few lines that pipes the saved and reviewed SELECT through your read-only Postgres adapter and returns rows. That is the entire integration surface.

Building a SQL skill library

A sql skill library is the accumulated set of compiled skills your team owns. The shortest viable shape: a git repo with one folder per skill, each folder a SKILL.md plus any auxiliary SQL files it depends on. Skills are reviewed in pull requests, versioned with the warehouse schema, and synced into whichever runtime needs them.

The library grows one validated query at a time. The first skill is whatever question gets re-asked in Slack every week. The tenth skill is a sql skills framework the team relies on for closes, reviews, and product decisions. The hundredth is the institutional definition of how the business measures itself, owned by the team, not by a vendor.

Auto-generating skills

A SQL skills generator turns a validated query into a compiled SKILL.md bundle without hand-authoring the frontmatter. In Chion, the path is: ask the question in studio chat, review the generated SELECT, save it. Saving writes the SKILL.md (name, description, semantic-layer dependencies, saved and reviewed SELECT) into your skill folder. The output is the same portable file every runtime in the matrix above reads.

The mechanics of the SKILL.md format and the CHION.md registry live in the CHION.md spec. The team-scale framing (why an auto-generated library is the asset and the model is interchangeable) lives on the AI SQL workforce.

Swap Claude for GPT for Gemini. The query text does not move.

The same reviewed SELECT runs, independent of which model is wired into the runtime.

"Model-agnostic" is a phrase that gets stretched until it means nothing. The operational definition this page uses is narrow: a model-agnostic SQL skill sends the same SQL text to the database, independent of which language model is wired into the runtime. What that SQL returns still depends on the data and on the role the query runs as.

The mechanism is unsurprising. The SELECT is the truth. The model is used for two things only: matching the prompt to a skill’s description, and explaining the rows that come back. Neither of those steps re-generates SQL. Swap Claude for GPT for Gemini and the query text is the same one a reviewer signed off on. That is the property llm-agnostic SQL skills exist to deliver.

Agent-generated SQL drifts. A frozen SELECT your team saved and reviewed doesn’t. When an agent writes the query fresh on every run, a reworded prompt, a new model, or a slightly different plan quietly changes the JOIN, the filter, or the GROUP BY, and the number moves with it. A portable SQL skill removes that variable: the SELECT a human already reviewed is the artifact that runs, every time. The model routes and explains; it does not rewrite.

What stays constant across models

The description the prompt is matched against.
The saved and reviewed SELECT that runs against Postgres.
The semantic-layer definitions the SELECT depends on.
The query text sent to the database.

The anti-vendor-lock-in payoff

When the skill bundle is a file in your repo, the cost of switching runtimes drops to the cost of pointing a new runtime at the same folder. The library, the actual investment, moves with you. That is the asset the workforce page argues for; portability is what makes that asset durable.

Switching runtimes

Point Claude Code or Codex at the existing skill folder. The SELECT is not rewritten: Claude Code reads the folder as-is, and Codex adds the thin wrapper described above. You re-point the runtime, not the query.

Running multiple runtimes

The same skill can serve the studio chat in Chion, the IDE agent in Cursor, and the CLI agent in Claude Code at the same time. Same SELECT text. The rows still depend on the data and the role it runs as.

Surviving a model change

The next model release does not invalidate the library. The SELECT does not depend on the model. Only the routing and explanation do.

Auditable in source control

Pull requests review the SELECT and the trigger phrases. Skills are versioned like application code, not like spreadsheet macros.

Anti vendor lock-in SQL is not a slogan; it is a file format. Plain SKILL.md, plain SELECT, in your repo, runnable anywhere.

Anti vendor lock-in SQL is not a slogan; it is a file format.

For the file format that makes this possible, see CHION.md and SKILL.md, or how CLAUDE.md and CHION.md compose. For the Claude Code surface in detail, see Claude Code SQL skills. For why the library is the asset in the first place, see the AI SQL workforce.

Quick reference

One SKILL.md runs in Chion, Claude Code, Codex, and Cursor.
The SELECT is the truth: the file carries the query text, not a prompt that regenerates it.
Cross-tool sql skills are plain files in your repo, diff-able in pull requests.
Claude Code SQL skills live under .claude/skills/ or ~/.claude/skills/; Cursor and Codex each document their own location, and those move.
The postgresql skills library is exportable, retrievable, and reusable across runtimes.
Anti vendor lock-in SQL is a file format, not a slogan.

Frequently asked

What are portable SQL skills?

Portable SQL skills are compiled, reusable SQL skills stored as plain SKILL.md files: YAML frontmatter (a name and a description carrying the trigger vocabulary) plus a saved and reviewed SELECT, with the semantic dependencies in the body. Four runtimes read the same file; each one wires discovery and execution its own way.

What does model-agnostic SQL skills mean?

The SELECT is the truth. The model is used for routing prompts to skills and for explaining the result, not for generating SQL on the fly. Swap GPT for Claude for Gemini and the same skill sends the same query text. That is what makes them llm-agnostic SQL skills in practice.

How do I use a Claude SQL skill in Cursor?

Put the exported skill folder wherever Cursor's current rules configuration reads from, and reference it there; Cursor changes that path more often than the file format changes, so check their docs rather than a blog post. Cursor then surfaces the skill when the open project's prompt matches the description. The saved and reviewed SELECT runs against whichever read-only Postgres role the project already uses.

How do Codex SQL skills work?

Each compiled skill is registered as a tool through the OpenAI Agents SDK. The tool wrapper is a thin shim that runs the SELECT through your read-only adapter and returns rows. The skill file is the same SKILL.md every other runtime reads.

Why an exportable format instead of a hosted catalog?

Because lock-in is the most expensive bug a data team can ship. An exportable, retrievable SQL skill lives in your repo, gets diff-ed in pull requests, moves with you when the vendor changes, and is portable across runtimes. A hosted catalog you cannot export is a future migration project.

Where does the postgresql skills library live?

Wherever you want. Most teams keep the canonical library in a git repo alongside the warehouse schema, then sync it into Chion, Claude Code, Codex, or Cursor as needed. The skill file is the source of truth; the runtimes are consumers.

What is the relationship between this and the SQL skill library?

The SQL skill library is the set of compiled skills your team owns, each grounded in the semantic layer Chion profiles from your columns; portability is what lets that library outlive any single tool. The library guide argues why to compile; this page proves the compiled bundle is not trapped.

Can I auto-generate SQL skills from queries my team already runs?

Yes. A sql skills generator (Chion in our case) takes a validated SELECT, typically saved from a studio session a human reviewed, and emits the SKILL.md bundle: the name and description that carry routing, the semantic-layer dependencies, and the SELECT itself. The output is the same portable file format every runtime on this page reads.

How do I reuse SQL across tools without rewriting it?

Keep the canonical SKILL.md in a git repo next to your warehouse schema. Sync the folder into Chion, into Claude Code under .claude/skills/ (or ~/.claude/skills/ for every repo), or into whichever location Codex and Cursor currently document. The file is the contract; the discovery path belongs to the runtime.

How do I avoid AI vendor lock-in for SQL?

Insist on an exportable, plain-file skill format. If the vendor stores your queries in a control plane you cannot grep, fork, or check into git, lock-in is the default. Portable SQL skills are the opposite design: file in your repo, vendor is a consumer, swap is a folder pointer.

Compile once. Run it where your team already works.

Validate your team queries in Chion, export the SKILL.md bundle, and run the same skills in Claude Code and Codex.

Start your 7-day trial The SKILL.md format