Skills
Teach QRY your organization's knowledge, conventions, playbooks, and even reusable scripts — once — and have it apply automatically across every conversation. Skills is the single, unified way to give QRY context and capabilities beyond what it can read from your schema.
Overview
Out of the box, QRY can read your tables and answer general questions. But every organization has its own vocabulary, business rules, reporting playbooks, and one-off automations. Skills is how you encode all of that.
A Skill is a named, versioned, permission-scoped unit of guidance or capability. The same model covers four things that used to be separate features:
| What you want to give QRY | Skill content type |
|---|---|
| Facts, glossaries, documents, business rules | Knowledge |
| Behavioral guidance ("always be terse", "prefer SQL over Python") | Instruction |
| A multi-step playbook the model follows for a class of question | Procedure |
| A reusable Python script QRY can run on demand | Script |
If you used Domain Contexts (knowledge bases / glossaries) or Domain Agents (the finance/healthcare expert agents), those are now Skills — a knowledge Skill and a procedure Skill respectively. Existing Domain Contexts keep working unchanged; see Domain Context for the knowledge-Skill deep dive.
The three dimensions
Every Skill is defined by three independent choices. Together they decide who sees it, when it reaches the model, and what kind of content it carries.
1. Scope — who the Skill applies to
Scope controls visibility and is always resolved against the user's permissions.
| Scope | Applies to | Who can manage it |
|---|---|---|
| System | Every conversation in the tenant | System admins |
| Datasource | Conversations using that datasource | Datasource admins (RBAC Admin) |
| Workspace | Conversations bound to that workspace | Workspace owner |
| User | Only your own conversations | You |
When more than one Skill matches, the narrower scope wins on conflicts: user → workspace → datasource → system. Lower-priority guidance is still provided; it just yields to the more specific one.
2. Trigger — when the Skill reaches the model
| Trigger | Behavior | Best for |
|---|---|---|
| Always | Injected into the system prompt of every matching conversation | Short, broadly-useful facts and rules (glossaries, conventions) |
| Similarity | Retrieved (RAG-style) only when the question is semantically relevant | Large documents, long playbooks, anything too big to always inject |
| Model-driven | QRY sees a short catalog of available Skills and loads the full content only when it decides the Skill is relevant | Large libraries of Skills, scripts, and procedures where always-injecting everything would bloat the prompt |
The Domain Context strategies map directly onto triggers: Full Document → Always, RAG → Similarity, Smart/Hybrid → Model-driven (QRY chooses what to pull in). See Domain Context for the document-processing details.
3. Content type — what the Skill carries
- Knowledge — documents, glossaries, data dictionaries, business rules. Injected or retrieved as context. This is the classic Domain Context.
- Instruction — behavioral guidance that shapes how QRY answers (tone, preferred tools, output format). Workspace-scoped instructions live here.
- Procedure — a step-by-step playbook the model follows when it recognizes a class of request (e.g. "monthly close analysis"). Replaces the hand-built Domain Agents.
- Script — a Python script that runs in QRY's sandbox with the triggering user's permissions. The model invokes it with the
run_scripttool. Useful for deterministic, reusable computations you don't want the model to re-derive every time.
Model-driven Skills & progressive disclosure
Always-injecting every Skill into the prompt doesn't scale once you have dozens of them. Model-driven trigger solves this with progressive disclosure:
- QRY is shown a compact catalog — just each Skill's name and one-line description.
- When a Skill looks relevant to the question, the model calls the built-in
load_skilltool to pull in its full content, orrun_scriptto execute a script Skill. - Only the Skills actually used consume context-window tokens.
This keeps the base prompt small while making a large library of Skills available on demand. Model-driven Skills are gated by a tenant-level admin switch (see Administering Skills) so an admin opts in deliberately.
Script Skills run through the same sandbox as Python execution — isolated, resource-limited, and executed under the requesting user's RBAC/ABAC. A user can only run a script Skill they're allowed to manage at its scope.
The Skills IDE
Skills are authored in a dedicated IDE (the same editing experience as Notebooks): multi-tab editing, single-click transient preview tabs, dirty/double-click permanent tabs, and a Run button to test script Skills inline. You set the scope, trigger, and content type per Skill, write the content in Markdown (or Python for scripts), and save.
Skill health
A Skill has no compiler. When a rule stops matching the data — a table renamed, a column dropped — QRY either ignores the rule or follows it and the query fails, and the answer reads fine either way. Nobody finds out. Skill health makes that visible to the person who can fix it.
You see it in three places: an amber panel above the Skill's content in the IDE, an amber dot beside the Skill in the explorer tree, and a notification to administrators when a Skill newly breaks.
Findings are ordered by how strong the evidence is, and they are not equally serious:
| Finding | What it means |
|---|---|
| Broke queries | Proof. A query written under this Skill named an object, and the database rejected it as missing. The count tells you how many times. |
| Gone from the schema | An identifier in the Skill used to exist in its datasource and no longer does. It was renamed or dropped. |
| Figures in the text | The Skill states row counts or totals. Those age, and QRY will recite them as current data instead of querying. |
What it deliberately does not do
It reports drift, not absence. "Gone from the schema" only fires for a name that previously resolved. That is why a Skill you have just written, or an instance where the feature has just been enabled, shows no schema warnings at first: QRY is recording which names currently exist, and only reports the ones that later stop existing. This is intentional. Checking for names simply absent from the schema sounds stricter, but a rule body puts backticks around status values, function names, date formats and regions exactly the way it does around table names — measured on a real instance, that check produced dozens of warnings and nearly all of them were wrong. A panel like that stops being read within a week.
It does not check identifiers in knowledge Skills. Uploaded documentation quotes error codes, ticket references, filenames and status values freely; none of those are schema objects. Knowledge Skills are covered by Broke queries instead, which needs no guesswork because the database has already given its verdict.
Which datasource a Skill is checked against
Its bound datasource, if it has one; otherwise, for a workspace Skill, the workspace's default datasource. A Skill with neither only gets the Figures in the text check.
Clearing a finding
Edit the Skill and save: schema and figure findings are recomputed, so a fix makes them disappear. If a finding is intentional — figures that belong in the text, say — dismiss it with the tick (requires manage rights on the Skill). Broke queries is historical evidence rather than a property of the current text, so editing does not clear it; dismiss it once you have dealt with it, and it will reopen by itself if the same failure happens again.
Version control
Skills are first-class citizens in Git Folders. They serialize to a human-readable .qryskill format, so you can review Skill changes in pull requests, branch and experiment, and sync them across QRY instances alongside your notebooks, pipelines, and jobs.
Permissions
Skills respect QRY's permission model at every step:
- Reading: A Skill only reaches the model if the user can see its scope (and, for datasource-scoped Skills, has access to that datasource).
- Managing: Creating/editing a Skill requires admin at system or datasource scope, ownership at workspace scope, or being the owner at user scope.
- Running scripts: Script execution runs under the triggering user's permissions, so a Skill can never escalate access.
Use cases
Knowledge — a finance glossary (Always, system scope)
- MRR (Monthly Recurring Revenue): SUM(monthly_amount) WHERE status='active'
on the snapshot date.
- Active customer: at least one completed order in the last 90 days.
- Fiscal year starts July 1.
Every conversation in the tenant now uses these definitions without anyone re-explaining them.
Procedure — a monthly-close playbook (Model-driven, datasource scope)
A step-by-step Skill named "Monthly close analysis" that, when the model recognizes the request, walks through pulling the trial balance, reconciling against the prior period, and flagging variances over a threshold. The model loads it only when relevant.
Script — a reusable cohort calculation (Model-driven, workspace scope)
A Python Skill that computes retention cohorts from a query result. The model calls run_script instead of re-deriving the logic each time, and the result is deterministic.
Administering Skills
Most Skill management happens in the Skills IDE under the relevant scope. Two tenant-level controls live in the admin panel:
- Model-driven Skills toggle — Admin → System Settings → Model-Driven Skills. Off by default. When enabled, QRY exposes the Skill catalog plus the
load_skill/run_scripttools to the model. The panel warns if the toggle is on but the unified Skills pipeline isn't active for the tenant yet. - Seed Skills — new tenants can ship with built-in showcase Skills (e.g. a financial-analysis procedure) so users have a working example to learn from.
Administrators are also notified when a Skill newly stops matching its data — see Skill health. The notification covers what changed, not what is already known to be wrong, and repeats at most once a day per Skill.
FAQ
Q: Do I have to migrate my existing Domain Contexts? A: No. They continue to work as knowledge Skills with no action required. See Domain Context.
Q: What happened to Domain Agents? A: The finance/healthcare expert agents are re-authored as built-in procedure Skills delivered via the model-driven path. They're no longer separate, hard-coded agents. See Domain Agents.
Q: Will model-driven Skills slow down or bloat my prompts? A: No — that's the point. Only a one-line description per Skill is in the base prompt; full content loads only when the model chooses to use it.
Q: Can a script Skill access data the user can't? A: No. Scripts run under the triggering user's RBAC/ABAC, in the sandboxed Python environment.
Q: Skill health isn't warning me about tables I know were dropped. Is it broken? A: Almost certainly not. It reports names that stop resolving, so it has to see a name working before it can tell you it stopped — a Skill that was already broken when the check first ran has no "before" to compare against. Rename or drop something from now on and it will be caught, and a query that actually fails will be attributed straight away as Broke queries. See Skill health.
Q: Why doesn't my knowledge Skill ever show schema warnings? A: By design — documents quote codes, filenames and status values in the same backticks as table names, so checking them produces far more noise than signal. Knowledge Skills are covered by Broke queries, which relies on the database's own verdict rather than on guessing.
Next Steps
- Domain Context — the knowledge-Skill deep dive (documents, RAG, processing strategies)
- Workspaces — workspace-scoped Skills for team-wide knowledge and instructions
- Git Folders — version-control your Skills with
.qryskill - Domain context (tips & tricks) — practical guidance on what to put in a Skill
Skills unify everything QRY needs to know about your business — facts, rules, playbooks, and automations — into one scoped, versioned, permission-aware system.