How do I write a skill so an AI SRE loads the right steps for error spikes?

Tares loads a skill when its description matches the task, so you write a SKILL.md named error-spikes whose description says when to use it. Agents in the project see only the name and description, and load the full steps with the skill tool when an error spike matches. Put the situation in the description and the runbook in the body.

How it works

A skill is a SKILL.md file with three parts. Read the Skills page for the full reference. The parts are:

• name: 1 to 64 lowercase letters, digits and dashes, such as error-spikes. It is unique on the instance, and 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.
• body: Markdown, up to 64 KB. These are the steps themselves.

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

1. A section called Skills available in this project after the agent’s own prompt. It lists every skill as - name: description, with one line telling the agent to load a skill with the skill tool only when the task matches its description.
2. 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 list costs one line per skill, and the agent pays for a body only when it loads one. This is why the description matters most: it is the only part the agent sees before it decides. Good descriptions name the situation, not the content. “Use when error rates jump” tells the agent when to load the skill. “Error knowledge” does not.

An agent sees the skills of the projects its run is for, not every skill on the instance. If you work with the AI SRE guide, this is how a runbook reaches the agent that investigates a spike.

Set it up

1. Pick a lowercase name, such as error-spikes.
2. Write a description that states the situation and when to use the skill. Keep it to one paragraph with no blank line.
3. Write the body as numbered steps an agent can follow. Reference the tools it already has, such as read and stats. A skill is plain instructions, not a tool, so it can tell an agent how to use its tools but cannot add new ones.
4. Save the file as SKILL.md with the name and description in YAML front matter between two --- lines. Other front matter keys are ignored.

---
name: error-spikes
description: How to investigate a spike in errors on a service. Use when the error rate jumps, a 5xx alert fires, or a service starts returning many failed responses.
---
 
# Error spikes
 
1. Read the last 30 minutes of the service with `read`, then run `stats` by
   `status_code` to see which responses moved.
2. Check for a deploy of the service in the hour before the first error.
3. If the errors come from a dependency, say so and stop: that is the
   dependency's incident, not ours.
4. End the note with the owning team.

5. Add it to a project. In the console, open the project, click Skills, then use Upload SKILL.md to read your file, or New skill to fill in name, description and body with a preview. To reuse a skill another project already has, choose Use one already on Tares.
6. Check the result. The Skills overview shows each skill’s size, update time and the agents that loaded it in the last 7 days. Each run also records the skills it loaded, in order, as chips in the runs table.

You can do the same over the API, where an upload endpoint under the project’s skills takes a SKILL.md as the raw request body. Reading skills needs the read scope. Creating, changing or deleting one needs admin, since a skill changes what the project’s agents do. 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 names the rule.

What you get

• Agents load your error spike steps only when the task matches, so each agent’s prompt stays short.
• One runbook serves many projects. Any number of projects can use the same skill, and editing it changes it for all of them.
• You can see which agents loaded the skill and when, in the console and in the skills field on each run in the API.
• The skill moves with your setup. Skills export and import with the catalog under a top-level skills: section, each skill once, with project and used_by.

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]

When something else fits

• Ask in a project does not use skills, so put one-off instructions in your question or in the agent’s own prompt.
• If the agent needs a new capability rather than better steps, change its tools and MCP servers. A skill only tells an agent how to use what it already has.
• If a note applies to every run, keep it in the agent’s prompt. Use a skill for a procedure that only some tasks need.

Related