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

Tares loads your crash loop steps when you write a skill as a SKILL.md with a name and a description that says when to use it. Agents in a project that uses the skill see the name and description, and they load the body with the skill tool only when the task matches. Write the description around the situation, such as a service that keeps restarting, and put the procedure in the body.

How it works

A skill has three parts: a name, a description and a body. Tares adds the skill to every run for a project that uses it.

• 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’s projects use skills, the agent’s prompt gets a section called Skills available in this project. It lists each skill as a name and description line, and tells 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 the body. If the agent asks for 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, so you keep each agent’s prompt short and write the crash loop procedure once. Any number of projects can use the same skill, and an edit changes it for all of them.

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

The skill is the way to give an AI SRE a repeatable procedure. For the wider picture, see AI SRE.

Set it up

1. Pick a name that says what the skill covers, such as crash-loop-triage.
2. Write a description that names the situation, not the topic. “Use when a service keeps restarting” tells the agent when to load the skill. “Crash loop knowledge” does not.
3. Write the body as numbered steps the agent can follow, and finish with who owns the service.
4. Save it as a SKILL.md file with front matter between two --- lines. Other front matter keys are ignored.

---
name: crash-loop-triage
description: How to triage a service that keeps restarting. Use when a service crash loops, restarts repeatedly, or its restart alert fires.
---
 
# Crash loop triage
 
1. Read the last 30 minutes of the service with `read` to find the first error before the restarts began.
2. Run `stats` by `service` to see which services are affected, one or many.
3. Check for a deploy in the hour before the first error.
4. If only one service is affected and a deploy came first, say the deploy is the likely cause.
5. End the note with the owning team.

5. Add the skill to your project. In the console, open the project, click Skills, then use Upload SKILL.md, or use + next to Skills for the New skill form. To reuse a skill another project already has, choose Use one already on Tares.
6. Or upload over the API. Creating or changing a skill needs the admin scope, because a skill changes what the project’s agents do.

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

If a skill breaks a rule, such as a name with capitals, a blank line in the description or an empty body, Tares refuses it and the message says which rule. Full details are on the Skills page.

What you get

• Agents load the crash loop steps only when the task matches the description, so unrelated runs do not carry the body.
• One procedure serves every project that uses the skill. You edit it once with Edit, or with a PUT call, and every project gets the change.
• 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.
• The Skills overview in the project shows each skill’s size, when it was last updated and which of the project’s agents loaded it in the last 7 days. You can check that the crash loop skill is being picked up.
• Skills export and import with the catalog under a top-level skills: section, so you can move the runbook between instances.

When something else fits

• A skill is plain instructions, not a tool. What an agent can do is still set by its tools and MCP servers, so use a skill to tell it how to use them.
• For a short rule that applies to every run, put it in the agent’s own prompt. A skill fits a procedure you want loaded only when the task calls for it.

Related