Skills

A skill is a set of instructions for your agents: a runbook for one kind of incident, the checklist for a release, the house style for incident notes. A skill lives on the instance and projects use it: any number of projects can use the same skill, and editing it changes it for all of them. Every Tares agent in a project that uses a skill sees its name and description, and loads the full text only when the task in front of it matches. You write a procedure once and keep each agent’s prompt short.

A skill has three parts:

Part	Rules
name	1 to 64 lowercase letters, digits and dashes, e.g. `checkout-triage`. Unique on the instance; the agent loads the skill by this name.
description	One paragraph, up to 1,024 characters. The agent reads it to decide when to load the skill, so say what the skill covers and when to use it.
body	Markdown, up to 64 KB. The instructions themselves.

How agents use skills

When the projects a run is for use skills, Tares adds two things to the run:

After the agent’s own prompt, a section Skills available in this project lists every skill as - name: description, followed by one line telling the agent to load a skill with the skill tool before relying on it, and only when the task matches its description.
A skill tool that takes a name and returns that skill’s body. An unknown name returns an error that lists the skill names, so the agent can correct itself.

The agent pays for a body only when it loads one; the list costs one line per skill. A project with no skills leaves the prompt and tools exactly as they were.

Each run records the skills it loaded, in order. They show as chips in the runs table on the agent and project pages and in the project’s Activity, and as skills on each run in the API.

An agent sees the skills of the projects its run is for (the projects whose wiring started it), not every skill on the instance. Ask does not use skills.

Write a skill

A skill is written as a SKILL.md file: YAML front matter with name and description between two --- lines, then the body. Other front matter keys are ignored.


---
name: checkout-triage
description: How to triage an incident on the checkout service. Use when checkout returns 5xx errors or its latency alert fires.
---
 
# Checkout triage
 
1. Read the last 30 minutes of the checkout service with `read`, then run `stats` by
   `status_code` to see which responses moved.
2. Check for a deploy of checkout or payments in the hour before the first error.
3. If the errors come from the payment provider (status 502 from `/pay`), say so and
   stop: that is the provider's incident, not ours.
4. End the note with the owning team: checkout is #team-payments.

Good descriptions name the situation, not the content: “Use when checkout returns 5xx errors” tells the agent when to load the skill; “Checkout knowledge” does not.

In the console

Open the project and click Skills in its navigation. The overview shows each skill’s name, description, size, when it was last updated, and the agents of the project that loaded it in the last 7 days. Click a skill to see its body and which agents loaded it; + next to Skills adds one.

New skill opens a form with name, description and body, and a preview of the body as it renders. A name already on the instance is refused: use that skill instead.
Use one already on Tares picks a skill another project uses, by name from a list, and this project uses it too.
Upload SKILL.md reads a file in the format above. A skill with the same name is replaced, in every project that uses it.
Edit changes the description and body for every project that uses the skill; the name stays.
Remove takes the skill out of this project. Its agents stop seeing it from their next run. The skill is deleted only when no other project uses it.

All resources in the sidebar lists every skill with the projects that use it.

A skill that breaks a rule (a name with capitals, a description with a blank line in it, an empty body) is refused with a message that says which rule.

On the API

{id} is the project id from GET /api/projects.

Call	Does
`GET /api/skills`	every skill on the instance, without bodies: `name`, `description`, and `used_by`, the projects that use it
`GET /api/projects/{id}/skills`	the project’s skills without their bodies: `name`, `description`, `updated_at`, `size` (bytes), and `loaded_by` (the project’s agents that loaded it in the last 7 days)
`GET /api/projects/{id}/skills/{name}`	one skill: `name`, `description`, `body`, `updated_at`
`POST /api/projects/{id}/skills` `{name, description, body}`	create a skill; 409 when a skill with that name is already on the instance
`POST /api/projects/{id}/skills/{name}/use`	the project uses a skill already on the instance; 404 when there is none by that name
`PUT /api/projects/{id}/skills/{name}` `{description?, body?}`	change the description, the body, or both, for every project that uses it; a field left out keeps its value
`DELETE /api/projects/{id}/skills/{name}`	the project stops using the skill; it is deleted when no other project uses it. The response has `removed`, `deleted` (the name, or `null` when kept) and `kept_for`, the projects still using it
`POST /api/projects/{id}/skills/upload`	the raw request body is a `SKILL.md`; creates the skill or replaces the one with the same name (in every project that uses it), has the project use it, and returns it with `created: true` or `false`

Upload a file:


curl -s -XPOST localhost:8787/api/projects/uc_1a2b3c/skills/upload \
  -H 'content-type: text/markdown' --data-binary @SKILL.md

A missing or invalid field answers 400 with a plain message, such as the front matter has no description:. Reading skills needs the read scope; creating, changing or deleting one needs admin, since a skill changes what the project’s agents do.

In the catalog

Skills export and import with the catalog, under a top-level skills: section, each skill once. project names the project that made it (a skill with no project goes to the Default project) and used_by lists the other projects that use it.


skills:
  - project: checkout watch
    name: checkout-triage
    description: How to triage an incident on the checkout service. Use when checkout returns 5xx errors or its latency alert fires.
    body: |
      # Checkout triage
      ...
    used_by: [payments watch]

Deleting a project deletes the skills no other project uses; a skill another project uses stays. A project template can also plan skills, which it creates with the rest of the project.

Skills are plain instructions, not tools. What an agent can do is still set by its tools and MCP servers; a skill can tell it how to use them.

Projects: the projects that use skills.
Tares agents: prompts, tools and guardrails.