Why is my agent not loading the skill I wrote?

Tares agents load a skill body only when the task matches its description, so write the description to name the situation and check that the run’s project uses the skill. An agent sees only the name and description of each skill and loads the body with the skill tool. It sees only the skills of the projects its run is for, and Ask does not use skills.

How it works

Tares keeps every skill cheap until an agent needs it. When the projects a run is for use skills, Tares adds two things to the run:

• A section called Skills available in this project, placed after the agent’s own prompt. It lists every skill as - name: description, then one line telling the agent to load a skill with the skill tool before relying on it, and only when the task matches its 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 never sees the body until it calls the tool. The description is the only thing it has to decide whether your skill applies, so a vague description means the skill stays unloaded.

Three things decide whether your skill loads:

• The description. It should name the situation, not the content. “Use when checkout returns 5xx errors” tells the agent when to load the skill. “Checkout knowledge” does not.
• The project. An agent sees the skills of the projects its run is for, meaning the projects whose wiring started it. It does not see every skill on the instance. A skill that no project of the run uses is invisible to that agent.
• The entry point. Ask does not use skills, so testing a skill there never loads it.

Set it up

Work through these checks in order. Each one matches a reason a skill does not load.

1. Rewrite the description to name the situation. Keep it to one paragraph of up to 1,024 characters. Say what the skill covers, then add a line that starts with “Use when” and names the trigger, such as the error or the alert that fires.
2. Check the file format. A skill is a SKILL.md file with YAML front matter holding name and description between two --- lines, then the body. The name is 1 to 64 lowercase letters, digits and dashes. A skill that breaks a rule is refused with a message that says which rule.
3. Confirm the project uses the skill. Open the project, click Skills in its navigation and look for the skill in the overview. If another project already has it, choose Use one already on Tares and pick it by name.
4. Confirm the run is for that project. The agent sees skills only for the projects whose wiring started the run. If the run belongs to a different project, add the skill there too.
5. Test with an agent run, not Ask. Trigger a run on a task that matches the description, since Ask ignores skills.
6. Check what the run loaded. 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 also shows which agents of the project loaded each skill in the last 7 days.

Here is a skill with a description that names the situation:

---
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.

If you change the description, use Edit on the skill, or upload the corrected file with Upload SKILL.md. An upload with the same name replaces the skill in every project that uses it. Agents pick up the change on their next run.

What you get

• The skill loads when the task in front of the agent matches your description, such as a checkout 5xx incident.
• The agent pays for the body only when it loads one. The list costs one line per skill, so your prompts stay short.
• You can see which runs loaded the skill, in order, from the runs table, the project activity or the API.
• One edit updates the skill for every project that uses it, so you write the procedure once.
• A project with no skills keeps its prompt and tools exactly as they were.

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 if the agent lacks a capability, give it the tool and let the skill explain how to use it. If you want an answer from Ask, put the guidance in your question, because Ask does not load skills. For how skills fit into incident work, see AI SRE, and for the full rules on names, descriptions, the API and the catalog, see Skills.

Related