Creating a Skill
A Skill is how you teach QRY something it can't read from your schema: a glossary, a house rule, a step-by-step playbook, or a reusable script. You author Skills in the Skills IDE, and once saved they apply automatically to the right conversations. This guide walks through creating one.
For the conceptual overview — the three dimensions and how they fit together — see the Skills feature reference.
Open the Skills IDE
Open Skills from the main navigation. The IDE works like the Notebooks editor: a list of your Skills on the left, multi-tab editing on the right. A single click opens a Skill in a transient (italic) preview tab; editing it or double-clicking makes the tab permanent.
Click New Skill to start.
Step 1 — Name and describe it
Give the Skill a clear name and a one-line description. The description matters more than you'd think: for model-driven Skills, the description is all the model sees in the catalog until it decides to load the Skill. Write it so the model can tell, at a glance, when this Skill is relevant.
- Good: "Definitions and SQL for finance metrics: MRR, ARR, churn, CAC."
- Vague: "Finance stuff."
Step 2 — Choose the scope
Scope decides who the Skill applies to:
| Scope | Use it for | You can create it if… |
|---|---|---|
| User | Your own preferences and shortcuts | always (it's yours) |
| Workspace | Knowledge and rules for a team | you own the workspace |
| Datasource | Facts tied to a specific database | you're a datasource admin |
| System | Tenant-wide conventions | you're a system admin |
When several Skills apply, the narrower scope wins on conflicts (user → workspace → datasource → system), but all of them are still provided to the model.
Step 3 — Choose the content type
| Content type | What you write | Example |
|---|---|---|
| Knowledge | Facts, glossaries, documents, business rules (Markdown) | "MRR = SUM(monthly_amount) WHERE status='active'" |
| Instruction | How QRY should behave | "Always show the SQL you ran. Prefer charts over tables." |
| Procedure | A numbered playbook for a class of request | "Monthly close: 1. pull trial balance, 2. reconcile…" |
| Script | Python that QRY runs in its sandbox | a cohort-retention calculation |
Knowledge Skills can also be backed by an uploaded document — see Domain Context for the document/RAG path.
Step 4 — Choose the trigger
The trigger decides when the Skill reaches the model:
- Always — injected into every matching conversation. Use for short, broadly-useful content. Keep it tight; it counts against the context window every time.
- Similarity — retrieved only when the question is semantically related. Use for long documents and playbooks.
- Model-driven — the model sees only your one-line description and pulls the full Skill in (or runs the script) when it decides it's relevant. Use for large libraries, procedures, and scripts. Requires an admin to enable model-driven Skills for the tenant — see Model-Driven Skills.
Short and always-relevant → Always. Big reference docs → Similarity. Playbooks, scripts, and "only sometimes relevant" → Model-driven.
Step 5 — Write the content and save
Write the body in the editor (Markdown for knowledge/instruction/procedure, Python for scripts). For a script Skill, use the Run button to test it inline — it executes in the sandbox under your permissions, so what you see is what a user with your access would get.
Click Save. The Skill takes effect on the next conversation turn for everyone in its scope.
Testing your Skill
- Start a new conversation in the scope the Skill targets (e.g. open the workspace, or select the datasource).
- Ask a question the Skill should influence.
- For always Skills, the effect is immediate. For similarity and model-driven Skills, phrase the question so it's clearly relevant — you'll see QRY load the Skill (model-driven Skills show a
load_skill/run_scriptstep).
If a model-driven Skill never fires, check that an admin has enabled model-driven Skills and that your description actually signals when to use it.
Versioning your Skills
Skills are tracked in Git Folders as .qryskill files, so you can review changes in pull requests, branch to experiment, and move Skills between QRY instances.
See also
- Skills (feature reference) — the full model
- Skill types and triggers — choosing the right combination
- Domain context — the everyday case: teaching QRY your vocabulary
- Model-Driven Skills (admin) — enabling the catalog +
load_skill/run_script