Skip to main content
This feature is in beta. We encourage you to try it out and provide us with feedback.
Skills are building blocks that combine instructions with optional bundled tools and reference files. Adding a skill to an agent gives it one clear ability. For example, a skill can handle tasks such as checking order status or looking up account details. You create each skill yourself, with your own description, instructions, and tools.

​
Key benefits

  • Focused agents. Each skill bundles the instructions and tools for one ability, so you don’t need to put everything in the agent’s main configuration.
  • Reduced context bloat. A skill puts only its name and description in the agent’s prompt. Its instructions, bundled tools, and reference files stay out until needed, so you use fewer tokens than if you included everything upfront.
  • Progressive disclosure. The agent first sees only each skill’s name and description. When a request matches a skill, the agent loads its instructions and bundled tools. It opens a reference file only when the instructions point to it.
  • Independent updates. Each skill is saved separately, so you can change one skill’s instructions, tools, or reference files without editing the agent’s other skills or its main instructions.

​
How the agent uses skills

The agent’s prompt lists the name and description of each skill. When a request matches a skill, the agent activates it and receives the skill’s instructions and the list of its bundled tools. The bundled tools become available from that point. The agent opens a reference file only when it decides it needs one. A skill stays active for the rest of the conversation, and several skills can be active at the same time. If you customize the agent’s system prompt, keep the skills variable in it, or the agent can’t tell when to use a skill.

​
Limitations

  • The maximum length of the Skill name field is 64 characters.
  • The maximum length of the Description field is 1024 characters.
  • A skill’s instructions and all its reference files are saved together, and the total can be at most about 2 MB. Images count about a third more than their file size. The upload dialog accepts files of up to 5 MB, but a skill that’s larger than the total limit can’t be saved.

​
Working with skills

To create a skill, follow these steps:
  1. Go to Design > Agent.
  2. Select an existing agent, or create one first. The Skills tab is available only after the agent is created.
  3. On the Skills tab, click Add skill.
  4. On the Create new skill page, fill in the following fields:
    • Skill name - enter a name for the skill. The agent sees the name together with the description. Give each skill on an agent a different name. Use only lowercase letters, numbers, and hyphens, with no leading, trailing, or consecutive hyphens.
    • Description - describe what the skill does and when the agent should use it. The agent reads the description to decide when to activate the skill.
    • Instructions - describe how the agent behaves while the skill is active. Include the steps, tool calls, conditions, and response requirements the agent must follow. You can use Markdown, such as headings and lists. The agent receives the instructions exactly as you write them. Turn on Markdown text to see the formatted result in a read-only preview, and turn it off to edit the instructions. When you open a saved skill, the preview is on.
  5. (Optional) In the Tools section, click Add tool. In the Attach tools to this skill dialog, select the project tools to bundle with the skill, and click Attach selected. The tools become available to the agent whenever the skill is active. A bundled tool is available only while the skill is active, even if the tool is also on the agent’s Tools tab. A tool that’s disabled for the agent stays unavailable through the skill.
  6. (Optional) To add a reference file, turn off Markdown text to edit the instructions. Type / where the agent should use the file, then select Upload and choose the file, or select a file you already uploaded. A reference chip appears at that position. You can also click Add reference, which adds the chip at the end of the instructions. Use references for lookup data, such as status tables, policies, or price lists. The agent can open a file only through a reference chip in the instructions, and it decides when to open it. Reference files can be text files (.md, .json, .csv, .xml, .html, .svg, .txt) or images (.png, .jpg, .jpeg, .gif). The agent receives every file as text, so it can’t view the content of an image.
  7. Save the skill.
On the Skills tab, you can search skills by name, open a skill to edit it, clone it, or delete it. Clone adds a copy named <skill name>-copy to the agent right away, and the copy is active together with the original. Delete removes the skill and its reference files permanently.

​
Tips for writing effective skills

Write the description as a set of concrete trigger scenarios rather than a topic label.
A description like Handles refund requests is too abstract to match reliably. Include the actual phrases a user would type. For example: I want a refund, can I get my money back, or this order was wrong, refund me. The more literal phrasings you include, the more reliably the agent can recognize when to use the skill.
  • List trigger phrases, not categories. Write the words a user would say, not a summary of the topic.
  • Include indirect signals. Make a refund skill match this is broken and I want my money back, not only I want a refund.
  • State the scope clearly if it’s broad. If the skill applies across every use case or persona your agent handles, say so. Don’t rely on the agent to guess that from context.
  • Mention any need for a bundled tool. If the skill can’t work without a tool, say so in the description, not only in the instructions.
Treat the instructions as a prompt, not a policy summary. The agent receives the instructions exactly as you write them.
  • Separate when to start from when to stop. After the agent activates a skill, the skill stays active for the rest of the conversation. Describe what the agent does when the skill starts, how it knows the task is complete, and what to do if the user changes their mind partway through.
  • Number the steps and name the tool. Say which tool the agent calls at each step.
  • Say what information to collect. State what the agent must confirm before acting, one question at a time and in a fixed order. If information is missing, tell the agent to ask for it and wait rather than guess.
  • Define how to handle failures. Describe the failure types you expect. For each one, say exactly what the agent tells the user. Don’t say to handle errors gracefully.
  • Prevent early success messages. Tell the agent not to say that an action worked until the tool response confirms that it did.
  • Rely on the tool for input validation. Don’t repeat the tool’s validation rules in the instructions. Doing this can cause the agent to skip a call it needs to make.
  • Say what the agent must not output. Don’t rely only on positive guidance such as be concise or sound natural. Instead, name the exact outputs or patterns to avoid.
  • Give paired good and bad examples of the exact reply shape you want. Don’t only describe the tone you want.
  • Bound the output format when it matters, for example, a single sentence, no headers, no internal IDs.
  • List specific words or phrases to avoid. Use this if testing shows the agent leaks internal details, such as system names, statuses, or reference IDs. These details mean nothing to the user.
To test a skill, chat with the agent in the Interaction Panel and look for the Skill loaded span in tracing. After you change a skill, start a new conversation, because a conversation that already activated the skill keeps the instructions it loaded. Tracing doesn’t show when the agent opens a reference file.

​
Examples

Instructions
Hand Over to Advisor is a Route to Flow tool. Set its History mode to AI-generated summary, so that the target Flow receives the agent’s summary in input.data.handoffContext.summary. The target Flow hands the conversation over to an advisor, for example with a Handover to Human Agent Node.Instructions

​
More information

Last modified on November 11, 2026