How do I write a skill so an AI SRE loads the right steps for a cron job that stopped?

Tares loads a skill when its description matches the task, so you write a SKILL.md with a name and a description that says when to use it. Agents in the project see the name and description, and they load the body with the skill tool only when the task fits. For a stopped cron job, name the situation in the description, such as a missed run or a heartbeat alert, and put the investigation steps in the body.

How it works

A skill has three parts: a name, a description and a body. The name is 1 to 64 lowercase letters, digits and dashes, and it is unique on the instance. The description is one paragraph of up to 1,024 characters. The body is Markdown of up to 64 KB.

When a project uses skills, Tares adds two things to each agent run:

• A section called Skills available in this project, which lists every skill as a line with its name and description. It tells the agent to load a skill with the skill tool only when the task matches the description.
• 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 agent pays for a body only when it loads one. The list costs one line per skill. Each run records the skills it loaded, and they show as chips in the runs table and in the project’s activity.

The description is what decides whether your skill loads. Name the situation, not the content. “Use when a scheduled job misses its run” tells the agent when to load the skill. “Cron knowledge” does not.

For background on how skills fit into agent prompts and tools, see Skills. For the wider picture of how Tares investigates incidents, see AI SRE.

Set it up

1. Pick a name that says what the skill covers, such as cron-job-stopped.
2. Write a description that states when to use it. Include the signals an agent will see: a missed run, a heartbeat or last-run alert, an expected nightly or hourly event that never arrived.
3. Write the body as numbered steps the agent can follow. Use the tools the agent already has, such as read and stats.
4. Save the file as SKILL.md. The front matter holds name and description between two --- lines, then the body follows. Other front matter keys are ignored.

---
name: cron-job-stopped
description: How to investigate a cron job that stopped running. Use when a scheduled job misses its run, a heartbeat or last-run alert fires, or an expected nightly or hourly event is missing.
---
 
# Cron job stopped
 
1. Find the job's last event with `read` and note when it last ran and whether
   that run succeeded.
2. Compare that time with the schedule and say how many runs were missed.
3. Check for a deploy, a config change or a host restart in the hour before the
   last run.
4. Read the job's logs around the last run for an error, a timeout or a lock
   that was never released.
5. If the job never started, say so and point to the scheduler. If it started and
   failed, quote the error.
6. End the note with the owning team and the next step to restart the job.

5. Add the skill to a project. In the console, open the project, click Skills, then use New skill for a form or Upload SKILL.md for the file. Over the API, post the raw file to the project’s upload endpoint:

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

6. Replace the project id with your own from GET /api/projects. Creating or changing a skill needs the admin scope, and reading skills needs read.
7. If another project already has the skill, pick Use one already on Tares in the console instead of creating a copy.

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 says which rule.

What you get

• An agent that loads your cron runbook when a scheduled job goes quiet, and leaves it unloaded for other incidents.
• Short agent prompts. The procedure lives in one place, and each agent pays for it only when it loads it.
• One skill shared by many projects. Editing it changes it for every project that uses it.
• A record of use. Each run lists the skills it loaded, in order, so you can check that the cron skill loaded for the right incident.
• A portable skill. Skills export and import with the catalog under a top-level skills: section, each skill once.

When something else fits

• A skill is plain instructions, not a tool. If the agent needs to reach a system it cannot reach today, change its tools and MCP servers, then use the skill to say how to use them.
• An agent sees only the skills of the projects its run is for, and Ask does not use skills. For a one-off question, put the detail in the question instead.

Related