Skills

How to write skills, the instructions an agent opens on demand, keep them in the project's skill library or in one agent, and give them to an agent.

A skill is a block of instructions for one kind of task: how to triage a ticket, how to write a release note, which checks to run before answering a contract question. The model always sees a skill's one-line header; it reads the full instructions only when it decides it needs them and opens the skill. An agent can carry many skills without putting all of their text in its system prompt on every call.

A skill is text only. It does not add tools: the tools the instructions mention must be bound to the agent like any other tool (see Tools overview).

Two places a skill can live

	Skill library	A skill of one agent
Where you create it	Build → Agents → Skills (/dashboard/agents/skills)	The agent's Build → Skills, New skill
Who can use it	Any agent of the project that picks it	That agent only
Listed in the library	Yes	No
Edited and deleted	From the library	From the agent's Build → Skills (pencil and bin on its card)
When the agent is deleted	Stays	Deleted with the agent

Both kinds are stored the same way, by key; keys are unique within the project.

The skill library

Build → Agents → Skills lists the project's shared skills with their Model tier, Status and Key, and counts Total skills, Active and Inactive. Filter by title, key or header, or by status. A row's menu has Edit, Enable / Disable and Delete; New skill opens the editor.

Write a skill

Field	What it is
Title	The name people see. Required.
Key	The identifier agents reference. Leave it blank to derive it from the title; it is made lower-case and unique within the project (-2, -3, … when taken). It cannot be changed later.
Header	One line: what the skill does and when to use it. Required. This is the only part the model sees before it opens the skill, so write it like a tool description.
Model tier	Any model, Large models only or Small models only. It is kept with the skill and shown on the agent's card; Console does not classify an agent's model by tier, so it does not hide a skill from any model.
Status	Active, or Inactive — hidden from every agent.
Body	The instructions, in Markdown. Required. Write them like a focused part of a system prompt, not like documentation for a person.

A skill has no versions: a saved change reaches every agent that uses the skill on its next run.

Give a skill to an agent

1. Open Build → Agents → your agent → Build → Skills.
2. Pick skills from the list (Select skills…). Skills of the library and the agent's own skills are both offered; the agent's own are marked (this agent).
3. Or press New skill ("New skill for this agent"). A skill created here belongs to this agent and is attached at once.
4. Publish the agent for API and portal traffic to see the change.

Each attached skill is shown as a card with its header, an inactive — will not load badge when it is switched off, and a This agent badge on the agent's own skills. Saving an agent with a skill key that does not exist (or belongs to another agent) is refused; an inactive skill only gives a warning and is skipped at run time.

Discovery & budget

Once the agent has a skill, the Discovery & budget card sets how the model finds and opens skills:

Setting	Default	Effect
Discovery	catalog	catalog lists every header in the system prompt (cheapest per call). search keeps the prompt the same and gives the model a search_skills tool instead, which is better once an agent has many skills.
Max open at once	3	How many skills the model may have open in one run.
Max tools per skill / Max tools total	10 / 20	Limits for skills that bring their own tools. Skills written in Console bring none, so these do not change anything for them.

How the agent uses a skill

1. Every model call carries the headers of the agent's active skills (or, with search, the search_skills tool).
2. When a header matches the task, the model calls open_skill with the skill's key. The body comes back as the tool result, and the model follows it for the rest of the run.
3. A skill that is deleted, inactive or belongs to another agent is left out of the run without an error.

Opening a skill is a step of the agent itself, not an external tool, so it never waits for an approval.

Who may use a skill

By default every person who can run the agent gets its skills. Through the API a library skill can carry an access list (access: { "mode": "all" | "selected", "userIds": [...], "groupIds": [...] }, at most 500 entries). A run made for a person the list leaves out does not get the skill: the model never sees its header. A list that cannot be read admits nobody.

API

The dashboard API serves skills under /api/skills (GET, POST, GET/PATCH/DELETE /api/skills/{id}).

Request	What it returns or does
GET /api/skills	The library: shared skills only. status (active, inactive) and search filter it.
GET /api/skills?agentId={id}	The library plus that agent's own skills (what the agent's picker shows).
GET /api/skills?agentId={id}&owned=only	That agent's own skills only. owned=only without agentId is a 400.
POST /api/skills	Creates a skill (title, header, body, optional key, minModelTier, status, access). With ownerAgentId it belongs to that agent, which must be an agent of the same project (400 otherwise). The owner cannot be changed afterwards.

An agent references its skills by key in config.skills, and the Discovery & budget settings in config.skillPolicy (disclosure, maxOpenSkills, maxBoundToolsPerSkill, maxBoundToolsTotal).

An agent export that embeds its resources carries its skills, but not their owner: a skill that belonged to the exported agent arrives as a shared skill of the library.

Who can do this

Skills belong to the agents service. Reading them needs read on Agents; creating, changing and deleting them needs write. See the Permissions reference.