How do I write a skill so an AI SRE loads the right steps for slow database queries?

Tares loads your slow database queries steps when you write a SKILL.md whose description says when to use it. Agents in a project that uses the skill see only its name and description. They load the full body with the skill tool when the task matches. You write the runbook once and the agent prompt stays short.

How it works

A skill has three parts: a name, a description and a body. The skills page sets the rules for each.

• name: 1 to 64 lowercase letters, digits and dashes, unique on the instance. For this topic, slow-database-queries fits. 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 instructions themselves.

When a run is for projects that use skills, Tares adds two things to it. After the agent’s own prompt comes a section called Skills available in this project, which lists every skill as - name: description. The run also gets a skill tool that takes a name and returns the 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. This is how an AI SRE agent gets the slow query steps at the moment a latency incident matches, and not on every run.

The description does the routing, so name the situation and not the content. “Use when query latency rises” tells the agent when to load the skill. “Database knowledge” does not.

Set it up

1. Write a SKILL.md file. Put YAML front matter with name and description between two --- lines, then the body. Other front matter keys are ignored. Here is one for slow database queries:

---
name: slow-database-queries
description: How to triage slow database queries. Use when query latency rises, a database latency alert fires, or requests time out waiting on the database.
---
 
# Slow database queries
 
1. Read the last 30 minutes of the affected service with `read`, then run `stats`
   to see which responses and callers moved.
2. Check for a deploy in the hour before the first slow query.
3. If one caller or one table accounts for the slowness, name it in the note.
4. End the note with the owning team.

2. Add it to a project in the console. Open the project, click Skills in its navigation, then use + next to Skills. Choose Upload SKILL.md to read your file, or New skill to fill in the name, description and body with a preview.
3. Or upload it over the API. Creating 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

4. To reuse the skill in another project, pick Use one already on Tares and choose it by name. Any number of projects can use the same skill.
5. Check that it works. 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. The Skills overview also shows which agents loaded the skill in the last 7 days.

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

What you get

• Agents load the slow query steps only when the task matches the description, so other runs stay lean.
• One skill serves every project that uses it. Edit it once and all of them change. An upload with the same name replaces it in every project that uses it.
• You can see which runs loaded the skill, and which agents loaded it in the last 7 days.
• The skill travels with your setup. Skills export and import with the catalog under a top-level skills: section.

A skill is plain instructions, not a tool. What an agent can do is still set by its tools and MCP servers. Your skill can tell it how to use them, as the example does with read and stats.

When something else fits

• An agent sees only the skills of the projects its run is for, so make sure the project that runs your SRE agent uses the skill. Ask does not use skills.
• For a rule that should apply on every run, put it in the agent’s own prompt. Keep skills for procedures that fit one kind of incident.

Related