Agents and skills
Publishing a skill from your web application
Your application declares tools. This is how it can also hand a visiting agent the procedure for using them, what the person at the keyboard is shown first, and how to write one they will accept.
Your tools say what your application can do. They do not say how it expects to be used — which status values mean what, which operation has to come before which, the thing every new person gets wrong in their first week. You can publish that too, over the same channel your tools go out on.
A skill is a tool whose result is instructions
There is no second mechanism and no file to serve. A skill is a read-only tool, marked as a skill, whose result is the text of the procedure. This one is from the Notes example:
registry.registerTool({
name: "notes_house_style",
description: "How notes in this app should be titled " +
"and written. Read this before adding a note.",
inputSchema: { type: "object", properties: {} },
annotations: { readOnlyHint: true, skill: true,
openWorldHint: false },
execute: async () => text(
"Title a note with two to four words in sentence case. " +
"Write the body as one line. " +
"Never delete a note without saying which one first.")
});
The text execute returns is the skill. Write
it as ordinary prose, specific to your application, and short.
The rule that governs it
skill: true is honoured only where the tool is
also declared read-only. A tool that changes anything is
judged by what it changes, like any other page tool, and is never
treated as a skill.
So a skill can tell an agent how your application works. It cannot be a way to get an operation past the question that operation would otherwise need.
What the person sees
Not your text arriving quietly in their conversation. The first time an agent uses a site’s skill, XataWorks shows the person the site, the skill and its full text, and asks:
- Allow once
- The agent gets the instructions for this call. Nothing is remembered; the next call asks again.
- Always allow this skill
- From now on, for this agent — remembered with a fingerprint of the text the person read.
- Allow all skills on this site
- This site may give this agent any instructions it publishes, including skills it adds later.
- Don't allow
- The instructions are discarded and never enter the conversation.
The dialog also offers a second opinion: a model reads the instructions and reports on them before the person decides.
Write it to be read by a person
It is shown in full to somebody deciding whether to trust it. That rules out what works on a model and alarms a human: instructions addressed to the agent rather than about your application, anything that reads as steering an agent past its user, and length nobody reaches the end of before deciding.
Rewriting it asks again
Always allow this skill is remembered with a fingerprint of the text. Change the text and the person is asked again. A skill regenerated on every deploy, or one carrying a timestamp or a build number, re-asks every user every time and trains them to click through. Keep the text stable and change it when the procedure changes.
Where it ranks
A skill your page publishes ranks below every other source of skills: the agent’s own, the person’s, and those that come with the application or its plugins. Where they disagree, yours gives way — which is the right order for instructions a website supplied.
Testing locally
The skill question is asked on localhost too: it is a
question about instructions, not about a site’s permission.