What format and size limits does a SKILL.md need so Tares accepts it?

Tares accepts a SKILL.md that has YAML front matter with a name and a description between two --- lines, followed by a markdown body. The name is 1 to 64 lowercase letters, digits and dashes and is unique on the instance. The description is one paragraph of up to 1,024 characters, and the body is up to 64 KB. A file that breaks a rule is refused with a message that says which rule.

How it works

A skill is a set of instructions your agents load when a task matches. It has three parts, and each has its own rule:

• name: 1 to 64 lowercase letters, digits and dashes, for example checkout-triage. It is unique on the instance, and the agent loads the skill by this name.
• description: one paragraph, up to 1,024 characters, with no blank line in it. The agent reads it to decide when to load the skill, so say what the skill covers and when to use it.
• body: markdown, up to 64 KB, and not empty. These are the instructions themselves.

In the file, the name and description go in YAML front matter between two --- lines, and the body follows. Any other front matter key is ignored, so extra keys do not cause a refusal.

A skill that breaks a rule is refused with a message naming the rule. Examples are a name with capitals, a description with a blank line in it, or an empty body. Over the API, a missing or invalid field answers 400 with a plain message, such as the front matter has no description:. A name that is already on the instance answers 409 when you create a skill.

Once accepted, every agent in a project that uses the skill sees its name and description. The agent loads the full body with the skill tool only when the task matches. Read Skills for the full model.

Set it up

1. Pick a name that fits the rules: lowercase letters, digits and dashes, 1 to 64 characters, not yet used on the instance.
2. Write the description as one paragraph under 1,024 characters. Name the situation, not the content. “Use when checkout returns 5xx errors” tells the agent when to load the skill. “Checkout knowledge” does not.
3. Write the body in markdown and keep it under 64 KB.
4. Save the file as SKILL.md with the front matter first:

---
name: checkout-triage
description: How to triage an incident on the checkout service. Use when checkout returns 5xx errors or its latency alert fires.
---
 
# Checkout triage
 
1. Read the last 30 minutes of the checkout service with `read`, then run `stats` by
   `status_code` to see which responses moved.
2. Check for a deploy of checkout or payments in the hour before the first error.
3. If the errors come from the payment provider (status 502 from `/pay`), say so and
   stop: that is the provider's incident, not ours.
4. End the note with the owning team: checkout is #team-payments.

5. Upload it in the console. Open the project, click Skills in its navigation, then choose Upload SKILL.md. If a skill with the same name exists, the upload replaces it in every project that uses it.
6. Or upload it over the API. The raw request body is the SKILL.md. 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

7. If you get a refusal, read the message, fix the named rule and upload again.

What you get

• A skill that Tares accepts and stores once on the instance, for any number of projects to use.
• A short prompt for each agent. It lists one line per skill, as the name and description, and loads a body only when the task matches.
• A clear message when a rule is broken, so you know which part of the file to fix.
• The response from the upload call returns the skill with created: true or false, so you can tell a new skill from a replaced one.
• Each run records the skills it loaded. They show as chips in the runs table on the agent and project pages, and in the project’s activity.

To see how skills fit into an incident workflow, start from AI SRE.

When something else fits

• If you only want to change the description or body of an existing skill, use Edit in the console or a PUT on the project’s skills route. The name stays, and the same limits apply.
• If the skill is already on Tares under another project, use Use one already on Tares instead of uploading a second copy. A duplicate name is refused.
• A skill is plain instructions and not a tool. To give an agent new abilities, set its tools and MCP servers, then let a skill tell the agent how to use them.

Related