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

Tares loads a skill for failed deploys when its description names the situation, so write a SKILL.md whose name is failed-deploys and whose description says when to use it. Agents in the project see the name and description on every run. They load the full steps with the skill tool only when the task matches. You write the procedure once and keep each agent’s prompt short.

How it works

A skill has three parts, and the description does the routing:

• name: 1 to 64 lowercase letters, digits and dashes, unique on the instance. The agent loads the skill by this name, so failed-deploys works and Failed Deploys does not.
• 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 projects that use skills, Tares adds two things to it. After the agent’s own prompt, a section called Skills available in this project 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. The skill tool takes a name and returns that skill’s body. If the name is unknown, the tool 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. Each run records the skills it loaded, in order, and shows them as chips in the runs table. This is how an AI SRE agent picks up your deploy runbook at the moment a deploy fails and not before.

An agent sees the skills of the projects its run is for, meaning the projects whose wiring started it. It does not see every skill on the instance. Full details are on the Skills page.

Set it up

1. Pick the name. Use failed-deploys. It is lowercase, short and unique on the instance.
2. Write a description that names the situation, not the content. “Use when a deploy fails” tells the agent when to load the skill. “Deploy knowledge” does not. Keep it to one paragraph with no blank line.
3. Write the body as numbered steps. Name the tools the agent should use, such as read and stats, and say where it should stop and who owns the next step.
4. Save it as SKILL.md. The file is YAML front matter with name and description between two --- lines, then the body. Other front matter keys are ignored.

---
name: failed-deploys
description: How to investigate a failed deploy. Use when a deploy fails, a rollout does not finish, or errors start right after a release.
---
 
# Failed deploys
 
1. Read the last 30 minutes of the service with `read`, then run `stats` by
   `status_code` to see which responses moved.
2. Find the deploy in the hour before the first error and note what it changed.
3. Say whether the errors started after the deploy or were already there.
4. End the note with the owning team and the deploy you suspect.

5. Add it to the project. In the console, open the project, click Skills, then + and choose New skill or Upload SKILL.md. To reuse a skill another project already has, choose Use one already on Tares. You can also upload the file over the API:

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

6. Check that it loads. After the next run, look for the skill chip in the runs table on the agent or project page. If a skill breaks a rule, such as a name with capitals or an empty body, Tares refuses it and says which rule.

Creating, changing or deleting a skill over the API needs the admin scope. Reading skills needs read.

What you get

• An agent that loads your failed-deploy steps when a deploy problem is in front of it, and leaves them unloaded otherwise.
• One runbook shared by any number of projects. Editing the skill changes it for all of them, and the name stays.
• Shorter agent prompts, because the procedure lives in the skill and not in each prompt.
• A record of use. The runs table, the project’s Activity and the skills field on each run in the API show which skills a run loaded. The Skills overview shows which of the project’s agents loaded each skill in the last 7 days.
• Easy cleanup. Remove takes the skill out of one project, and Tares deletes it only when no other project uses it.

When something else fits

• A skill is plain instructions, not a tool. If the agent needs to do something new, change its tools and MCP servers, and use the skill to tell it how to use them.
• Ask does not use skills, so put guidance for Ask somewhere else.
• If every run needs a short rule, such as a tone or a format, keep it in the agent’s prompt. Use a skill for steps that only some tasks need.

Related