How do I write a skill so an AI SRE loads the right steps for a disk filling up?

In Tares, you write a SKILL.md with a name and a description that says when to use it, and the agent loads the body only when the task matches. For a disk filling up, name the skill for the situation and put your runbook steps in the body. Every agent in a project that uses the skill sees the description and loads the steps with the skill tool when a disk alert or symptom comes in.

How it works

A skill has three parts: a name, a description and a body.

• name: 1 to 64 lowercase letters, digits and dashes, unique on the instance. The agent loads the skill by this name, so disk-filling-up works and Disk Filling Up 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 a project that uses skills, Tares adds two things to the run. First, a section called Skills available in this project lists every skill as - name: description, with one line telling the agent to load a skill before relying on it and only when the task matches. Second, a 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.

This keeps prompts short. The list costs one line per skill, and the agent pays for the full body only when it loads one. That is why the description matters most: it is the only part the agent sees before deciding. Describe the situation, not the content. “Use when a disk is filling up” tells the agent when to load the skill. “Disk knowledge” does not.

An agent sees the skills of the projects its run is for, meaning the projects whose wiring started it. For the wider picture of how agents watch and respond, see AI SRE.

Set it up

1. Pick a name that matches the situation, such as disk-filling-up.
2. Write a description that says what the skill covers and when to use it. Name the triggers an agent will actually meet: a disk usage alert firing, a host running out of space, writes failing because there is no space left.
3. Write the body as numbered steps that an agent can follow with its own tools. Use the read and stats tools the way the checkout example in the skills docs does.
4. Save the file as SKILL.md. The YAML front matter carries name and description between two --- lines, then the body follows. Other front matter keys are ignored.

---
name: disk-filling-up
description: How to triage a disk that is filling up. Use when a disk usage alert fires, a host reports little free space, or writes fail because the disk is full.
---
 
# Disk filling up
 
1. Read the last 30 minutes of the affected host with `read`, then run `stats` by
   your service label to see which service is writing the most.
2. Check for a deploy or a config change in the hour before the disk started to grow.
3. Say whether the growth is steady or sudden, and name the likely source: logs,
   a data directory or a temporary files area.
4. End the note with the owning team and what you checked, so the next person
   does not repeat it.

5. Add the skill to a project. Open the project, click Skills in its navigation, then use Upload SKILL.md to read your file, or New skill to fill in name, description and body in a form with a preview. If another project already has the skill, choose Use one already on Tares and pick it by name.
6. If you prefer the API, the project’s skills upload endpoint takes the raw SKILL.md as the request body. Creating, changing or deleting a skill needs the admin scope, because a skill changes what the project’s agents do. Reading skills needs read.

The full reference for the console, the API and the catalog is on the Skills page. 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

• One disk runbook written once and used by every agent in every project that uses it. Edit it, and the change applies to all of them.
• Short agent prompts. Each agent carries one line for the skill and loads the steps only when a disk problem is in front of it.
• Visibility into use. 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.
• A skill overview in the project’s Skills page with each skill’s size, last update and the agents that loaded it in the last 7 days.
• Portable setup. 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. If the agent needs to do something new, such as reach a system, set that up in its tools and MCP servers. The skill can then tell it how to use them.
• Ask in Tares does not use skills, so a runbook there will not load. Put it in a project whose agents run the investigation.
• If a short fact belongs in every run, such as the owning team for one host, put it in the agent’s own prompt instead. Use a skill for a procedure the agent should load only when the task matches.

Related