Skills

A skill is a named block of instructions the agent can pull into a conversation when it is useful: how your team writes release notes, the escalation ladder for a support ticket, the house conventions, what “done” means on your board.

Skills exist because a long procedure should cost nothing until it is relevant. The agent is not handed every skill you have written at the start of every conversation. It is told each one’s name and one-line description, and reads the rest only when it decides that would help. Twenty skills cost twenty lines, not twenty procedures.

What a skill is not

A skill is instructions, not capability. It cannot let the agent do anything it could not already do — it tells the agent how you want a thing done, using abilities it already has. If what you need is a new ability, you want a connection or a page tool instead.

When to write one

The test is simple: have you explained this to the agent more than once?

Good candidates:

• A procedure with steps that are easy to get subtly wrong — a release checklist, an escalation path, the order in which two systems must be updated.
• House conventions — how your team names things, what your status values actually mean, which fields are mandatory in practice regardless of what the form says.
• Anything where the right answer depends on knowledge the agent has no way to have: which customers are on which plan, which environment is safe to touch, who to ask.

Poor candidates:

• One-off instructions. Just say them in the chat.
• Anything secret. A skill is a file on your machine in plain text; it is not a password vault.
• Restating what a tool’s own description already says.

Writing one

Your own skills live in the Skills section of Preferences, reached from File ▸ Preferences…. A skill that should belong to one agent alone is written in that agent’s own Skills tab instead — the fields are identical, and so is everything below.

Either way, Add… opens this:

The six fields

• Name: — how the agent asks for it. Short and specific: zendesk-triage, not notes.
• Description: — one line, and this is the field that matters most. It is what the agent sees in its list of available skills, and what it uses to decide whether the skill is worth reading. Write it for that decision, not as a title. “How this team triages Zendesk tickets” is useful. “Triage” is not.
• Enabled — switch a skill off without deleting it.
• When: — blank means always available. Fill it in and the skill appears only on matching pages.
• Load: — how much of the skill arrives, and when.
• Instructions: — the body. Ordinary prose, as long as it needs to be.

It works immediately

Save it and it is live. No restart, and no need to start a new chat: a conversation you already have open picks it up on its next message. You can notice a gap mid-conversation, write the skill, switch back, and carry on.

One wrinkle: an always-available skill added mid-conversation is loadable by name in that chat, but it will not be announced there until you start a new one — the always-on list is assembled when the chat starts. Skills scoped to a site have no such gap; they are worked out fresh on every message.

When: skills that appear where they are relevant

Leave When: blank and a skill is always available. Fill it in and the skill joins the conversation only while the chat’s browser has a matching page open. A Zendesk skill appears the moment you navigate to Zendesk and is absent everywhere else — so you can write a dozen system-specific procedures without any of them cluttering a conversation about something else.

One pattern per line. Three shapes, told apart by how they look:

A look-alike host never matches: acme.zendesk.com.attacker.example does not match zendesk.com, and no amount of resemblance changes that.

Matching is re-evaluated every turn, against every tab open in the chat’s browser. Navigate away and the skill is simply not there on your next message; navigate back and it returns. A chat with no browser — a sub-agent dispatched to do a job on its own — never picks up a site-scoped skill at all, so a procedure that must apply to unattended work should not be scoped to a site.

Choosing a pattern: start with the host, because it covers every subdomain your organisation uses. Use a URL pattern when one system holds several worlds — a test instance and a live instance on one host are told apart by the path, and a bare host pattern matches both. Do not try to be clever: a skill appearing slightly too often is a line of noise, while a skill that fails to appear when you needed it is a procedure not followed.

Load: how much of it arrives

Two settings, and the choice is about length.

• Announce (the default) — the name and description join the agent’s list of available skills, and it reads the body only if it decides the skill is relevant. The right choice for anything long: it costs one line until the moment it is needed.
• Load in full — the instructions themselves go into the conversation, with no decision and no lookup, so the agent behaves accordingly from the first word. The right choice for something short and unconditional.

Ask whether the agent should be able to follow the procedure, or already following it. A twelve-step escalation ladder is Announce: it applies to some conversations, and when it applies the agent will go and read it. “Never promise a delivery date without checking stock first” is Load in full: one sentence, always applicable, and a rule the agent has to decide to read is a rule that will sometimes not be read.

A full-load skill is placed into a conversation once. On later turns the agent is reminded that it is in effect rather than being sent the whole text again — so it costs its length once, not once per message. It still costs it, which is why length is the deciding question.

A full-load skill with a blank When: is simply an always-on instruction block, and that is a tidier home for standing instructions than the bottom of every agent’s instructions: one place to edit, switchable off with a checkbox, and visible in the list where somebody can find it.

Which skill wins

Skills reach a conversation from five places. Two of them can define a skill with the same name, and one wins. The order is fixed and runs from most specific to least.

The order reads best from the bottom. A website is offering instructions to a program acting on your behalf, and anything you or your organisation has said on the subject outranks it. The application’s own skills sit second-from-bottom deliberately, and that surprises people: surely what the organisation shipped should win? No — the application’s skills are it addressing everyone who runs it, which is the least specific statement anybody on the list has made. You, looking at your own work, know more about your situation than a decision taken for all users at build time.

An organisation that needs an instruction nobody can displace does not ship it as a skill; it puts it in the application’s own instructions, which are not a skill and cannot be overridden. If something behaves in a way no skill of yours will budge, that is where it is coming from, and it is intentional.

Because a more specific skill wins by name, you can replace one you disagree with without renaming anything. Write a skill called release-notes in Preferences and your chats use yours — and the application’s is still listed beside it, marked as coming from the app, so the substitution is visible rather than mysterious. That is also why the application’s own skills cannot be edited, renamed, disabled or removed.

The ladder has a sharp edge. A skill named generically — notes, process, review — may silently displace something you did not know existed, or be displaced by it. Two different procedures should not share a name; two versions of one procedure should.

Seeing what a chat can run

The graduation-cap control in the chat header lists the skills this chat can use, and lets you run one with a prompt of your own.

Skills a website offers you

A website can hand your agent a procedure of its own — how this team triages a ticket — over the same channel it uses to publish page tools. This is genuinely useful: the system knows how it is meant to be used. It is also the one case where instructions reach your agent from a party you have no relationship with, so XataWorks asks, and asks carefully.

A site can only offer something as a skill if it has also declared it read-only. An action that changes anything is judged by what it changes, exactly as any other page tool is, and is never offered to you as a procedure. A site cannot get a gentler question by calling a destructive action a skill.

The text stops before it reaches the conversation. You see the site, the skill, its full text, and everything else that site publishes as a skill. Then: allow once; always allow this skill; always allow all skills on this site; or don’t allow. Closing the dialog is the same as not allowing it.

Always allow this skill remembers a fingerprint of the text you read. If the site later rewrites those instructions you are asked again, and told why.

The dialog can also have the model read the instructions for you, in a context of its own — no tools, nothing from your conversation — and report what it found, with a verdict of Looks safe, Worth a look or Unsafe. The text is handed over as clearly-labelled untrusted content and only that closed set of verdicts is recognised, so a skill that tries to talk the reviewer into blessing it produces No clear verdict rather than a forged one. The verdict is advice: it never allows or refuses anything, and nothing is pre-selected from it.

Once allowed, it becomes an ordinary skill — listed while you are on that site, marked as provided by the website, and sitting at the very bottom of the ladder. What the agent gets is the text you approved, kept by XataWorks, not whatever the site returns today.

To take one back: in the browser toolbar, Skills ▸ Manage skills for this site…, then revoke one or all. It disappears from every list at once, stops resolving by name, and the site’s next attempt asks you again.

Where they live

A skill is an ordinary folder on disk, under XataWorks’s configuration directory: skills/app/ for one you wrote in Preferences, skills/agents/ for one belonging to an agent. Each holds a SKILL.md — the fields you filled in, plus the instructions — and optionally other files beside it, which the agent can read. That makes a skill a reasonable home for a checklist or a reference table that would be awkward inline.

Which also makes it portable: copy the whole folder to another machine and it appears in the list, with nothing to import and nothing to restart. Two things to check after a move — that the When: patterns still make sense on that machine, and that any supporting files came too. Your data says where the directory is on your platform.