How do I write a skill so an AI SRE loads the right steps for 5xx errors on an API?

Tares loads your 5xx steps when you write a skill as a SKILL.md with a name and a description that says when to use it, such as “Use when the API returns 5xx errors”. Every Tares agent in a project that uses the skill sees the name and description, and loads the full body with the skill tool only when its task matches. You write the runbook once and keep each agent’s prompt short.

How it works

A skill has three parts:

• name: 1 to 64 lowercase letters, digits and dashes, 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 whether to load the skill.
• body: Markdown, up to 64 KB. These are the steps themselves.

When a run is for a project that uses skills, Tares adds two things to the run. After the agent’s own prompt, a section called Skills available in this project lists every skill as a name and description line, with one line telling the agent to load a skill with the skill tool only when the task matches its description. The skill tool takes a name and returns that skill’s body. If the agent passes an unknown name, the error lists the skill names so it can correct itself.

The agent pays for a body only when it loads one. The list costs one line per skill. Each run records the skills it loaded, in order, and shows them as chips in the runs table on the agent and project pages.

An agent sees the skills of the projects its run is for, not every skill on the instance. Skills are plain instructions, not tools. What an agent can do is still set by its tools and MCP servers, and a skill can tell it how to use them. Details are on the Skills page.

Set it up

1. Pick a name. Use lowercase letters, digits and dashes, for example api-5xx-triage.

2. Write the description as a situation. Say when to load the skill, not what it contains. “Use when the API returns 5xx errors” tells the agent when to load it. A description such as “API knowledge” does not.

3. Write the body as numbered steps. Name the tools the agent should use and the point where it should stop. Save the file as SKILL.md. The front matter holds name and description between two --- lines, and other front matter keys are ignored.

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

4. Add it to a project. In the console, open the project, click Skills in its navigation and use Upload SKILL.md. You can also use New skill to fill in the name, description and body in a form with a preview. If another project already has a skill with that name, pick Use one already on Tares instead.

5. Or upload through the API. The raw request body is the SKILL.md file. The call creates the skill, or replaces the one with the same name in every project that uses it, and has the project use it. Creating or changing a skill needs the admin scope.

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

6. Keep it in your catalog if you want it versioned. Skills export and import under a top-level skills: section, each skill once.

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]

7. Check that it loads. After a run, look for the skill chip on the run in the runs table, or read the skills field on the run in the API. The skills overview also shows which of the project’s agents loaded the skill in the last 7 days.

A skill that breaks a rule, such as a name with capitals, a description with a blank line or an empty body, is refused with a message that says which rule.

What you get

• An AI SRE that loads your 5xx runbook when the task is a 5xx incident and leaves it unloaded otherwise.
• Short agent prompts, because the procedure lives in one skill and the prompt only carries a one-line entry for it.
• One runbook shared across projects. Editing the skill changes it for every project that uses it, and the name stays the same.
• A record of use. Each run lists the skills it loaded, in order, so you can confirm the agent picked up the right steps.
• Clear control over scope. Removing the skill from a project stops its agents seeing it from their next run, and the skill is deleted only when no other project uses it.

For how skills fit with watching and escalating, see AI SRE.

When something else fits

• If the instruction should apply to everything an agent does, put it in the agent’s own prompt instead of a skill.
• If the agent needs a new ability, such as reading another system, add it through the agent’s tools and MCP servers. A skill only tells the agent how to use what it already has.
• Ask in a project does not use skills, so put steps there in the question itself.

Related