What happens when I upload a SKILL.md with an existing name or remove a skill from one project?

Tares replaces the skill with the same name in every project that uses it when you upload a SKILL.md, and Remove only takes the skill out of the project you are in. Edit changes the description and body for all projects while the name stays. Tares deletes a skill only when no other project uses it, and creating or changing skills over the API needs the admin scope.

How it works

A skill lives on the instance, and projects use it. Any number of projects can use the same skill, and the name is unique on the instance. Because of this, each action below affects either one project or every project that uses the skill.

• Upload SKILL.md reads a file with YAML front matter (name and description) followed by the body. If a skill with that name exists, Tares replaces it in every project that uses it. If none exists, Tares creates it. The project you uploaded from then uses it.
• Edit changes the description and body for every project that uses the skill. The name stays the same.
• Remove takes the skill out of this project only. Its agents stop seeing the skill from their next run. Other projects keep using it.
• Deletion happens only when no other project uses the skill. If other projects still use it, Tares keeps it.
• New skill is different from upload. A name already on the instance is refused, so you use that skill instead with Use one already on Tares.

Agents in a project see the name and description of each skill the project uses, and load the full body with the skill tool only when the task matches. So a replaced or edited skill takes effect for those agents the next time they load it, and a removed skill disappears from their list on the next run.

Set it up

1. Write the skill as a SKILL.md file. Put name and description between two --- lines, then the body in Markdown. The name is 1 to 64 lowercase letters, digits and dashes. The description is one paragraph of up to 1,024 characters. The body is up to 64 KB.

---
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. In the console, open the project and click Skills in its navigation. Click + next to Skills to add one, then choose Upload SKILL.md and pick your file. If the name already exists, the skill is replaced in every project that uses it.
3. To change only the description or body, click the skill and use Edit. The change applies to every project that uses it.
4. To stop one project from using a skill, click Remove in that project. Check the skill’s list under All resources in the sidebar to see which projects use it before you decide.
5. To do the same over the API, post the raw file to the project’s upload endpoint. The call creates the skill or replaces the one with the same name, has the project use it, and returns it with created: true or false.

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

6. To remove a skill over the API, send a DELETE to the project’s skill path, for example DELETE /api/projects/uc_1a2b3c/skills/checkout-triage. The response has removed, deleted (the name, or null when the skill is kept) and kept_for, the projects still using it.
7. Use a key with the admin scope for these calls. Reading skills needs only read, but creating, changing or deleting one needs admin, since a skill changes what the project’s agents do.

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. Over the API a missing or invalid field answers 400 with a plain message. For the full list of calls, see Skills.

What you get

• One upload updates a shared runbook everywhere it is used, so projects never drift apart on the same procedure.
• Edit keeps the name fixed, so agents that load the skill by name keep working.
• Remove is safe for the other projects: the skill stays for them, and the delete response tells you through kept_for which projects still use it.
• Each run records the skills it loaded. You see them as chips in the runs table and in the project’s Activity, so you can confirm which agents picked up the new version.
• Admin-only writes keep changes to agent behavior in the hands of people with the admin scope.

This fits the way AI SRE uses skills: you write a procedure once and keep each agent’s prompt short.

When something else fits

• If you want a change in one project only, create a skill with a different name for that project. A name is unique on the instance, so you cannot keep two versions under one name.
• If you need to restrict what an agent can do, use its tools and MCP servers. Skills are plain instructions, not tools.
• If you only want to see what a skill contains or which agents loaded it, open it in the console. You do not need an edit or an upload for that.

Related