What portable SQL skills are
Portable SQL skills are compiled, reusable SQL skills stored as plain SKILL.md files — YAML frontmatter (name, triggers, description, semantic-layer dependencies) plus the verified SELECT that answers the question. The same bundle runs in Chion, Claude Code, Codex, and Cursor without translation. The file is the contract; the runtime is a consumer.
The Claude Code surface in detail — SKILL.md anatomy, how Claude reads skills/, the writing walkthrough — is the canonical reference on Claude Code SQL skills. This page is the cross-tool argument: same SKILL.md, four runtimes, no lock-in.
The lock-in problem
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.
How one skill runs across Claude Code, Codex, and Cursor
Four runtimes. One SKILL.md. Click a runtime to see the artifact path, the invocation shape, and any wrapper notes. The matrix below shows the cross-tool feature parity row by row — the property that lets Chion run the same verified SQL skills in any AI tool.
Studio chat + Postgres connection
Chion
- Artifact
- SKILL.md + CHION.md registry
- Path
- .chion/skills/<name>/SKILL.md
- Invocation
- Prompt matches skill triggers, agent routes to verified SELECT
- Notes
- Native runtime. Verification, audit, and read-only enforcement happen here.
| Capability | Chion | Claude Code | Codex / OpenAI agents | Cursor |
|---|---|---|---|---|
| Reads the same SKILL.md | ||||
| Trigger phrase matching | ||||
| Runs the verified SELECT verbatim | ||||
| 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 verified 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, promote it. The promotion step writes the SKILL.md — name, triggers, semantic-layer dependencies, verified 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.
Model-agnostic by design
Same SELECT, same rows — independent of which model is wired into the runtime.
"Model-agnostic" is a phrase that gets stretched until it means nothing. Here is the operational definition this page uses: a model-agnostic SQL skill produces the same SQL — and therefore the same rows — independent of which language model is wired into the runtime.
The mechanism is unsurprising. The SELECT is the truth. The model is used for two things only: matching the prompt to a skill’s triggers, and explaining the rows that come back. Neither of those steps re-generates SQL. Swap Claude for GPT for Gemini and Tuesday’s revenue equals Wednesday’s revenue. That is the property llm-agnostic SQL skills exist to deliver.
What stays constant across models
- The trigger phrases the skill matches.
- The verified SELECT that runs against Postgres.
- The semantic-layer definitions the SELECT depends on.
- The rows returned, byte for byte.
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. No rewrite, no re-validation, no "migration project." The skill that worked yesterday works tomorrow.
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 SQL. Same numbers.
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 — model-agnostic and llm-agnostic by construction.
- Cross-tool sql skills are plain files in your repo, diff-able in pull requests.
- Cursor SQL skills live under .cursor/skills/; Codex SQL skills live under tools/.
- 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 (name, triggers, description, semantic dependencies) plus a verified SELECT. The same bundle runs in Chion, Claude Code, Codex, and Cursor without translation.
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 produces the same number. That is what makes them llm-agnostic SQL skills in practice.
How do sql skills for Cursor work?
Drop the exported skill folder into .cursor/skills/<name>/ and reference it from .cursorrules. Cursor's agent surfaces the skill whenever the open project's prompt matches the trigger phrases. The verified 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, survives a vendor change, 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 AI SQL workforce?
The workforce is the library of compiled skills your team owns; portability is the property that lets that library outlive any single tool. The workforce page 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 promoted from a studio session a human reviewed — and emits the SKILL.md bundle: frontmatter, triggers, 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, Claude Code (skills/), Codex (tools/), or Cursor (.cursor/skills/) as needed. No translation step — the file is the contract.
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 anywhere.
Validate your team queries in Chion, export the SKILL.md bundle, and run the same skills in Claude Code, Codex, and Cursor.