Skip to main content
Agent skills provide a targeted set of instructions for a specific task, such as processing an invoice, running a data validation, or following a policy review workflow. Instead of writing all instructions directly into the agent configuration, package each capability as a separate skill. The agent loads only the skill that is relevant to each request. Use agent skills when you want to:
  • Break a complex agent into independently maintained capabilities.
  • Reduce context size and token usage by loading instructions only when they are relevant.
  • Reuse the same skill across multiple agents without duplicating instructions.
A skill is a directory that contains a SKILL.md file. That file has two parts: a YAML frontmatter block with the name and description fields, and a Markdown body with the instructions the agent follows.

​
How the agent activates skills

When an agent has skills attached to it, it does not load all instructions at once. Instead, it uses a progressive disclosure approach and loads only the skill that is relevant to the current request:
  1. Discovery: The agent reads only each skill’s name and description, not the full instructions.
  2. Activation: When a user sends a message, the agent matches it to the most relevant skill based on the skill’s description, then loads the full SKILL.md body into context.
  3. Execution: The agent follows the instructions in the body and invokes the tools declared in the skill.

​
Creating agent skills

1

Create your skill directory

Create a directory with a SKILL.md file at its root. Add a YAML frontmatter block with at least name and description, then write the instructions in the body. Optionally, include a scripts/ subdirectory for Python files and a references/ subdirectory for supporting documents.For more information, see Skill directory structure.
2

Import the skill into your environment

Register the skill in your active environment by using the import command. Use --dir to upload the skill directory in one step, or --recursive to bulk-import a directory that contains multiple skills.For more information, see Importing skills.
3

Inspect and verify

Confirm that the skill registered correctly by listing all skills or retrieving the details of a specific one.For more information, see Listing skills and Inspecting a skill.
4

Update or remove as needed

Replace a skill’s definition at any time by running the update command. Remove skills that you no longer need to keep your environment clean.For more information, see Updating a skill and Removing a skill.
To add or refresh a single script or reference file after the initial import, use the dedicated upload commands instead of re-importing the entire skill. For more information, see Uploading scripts and Uploading reference documents.

​
Skill directory structure

A skill directory uses the following structure:
SKILL.md file
SKILL.md has two sections separated by --- delimiters. The top section is YAML frontmatter, a structured metadata block. The section below it is the instructions body, written in plain Markdown. The frontmatter must include at least name and description. The agent reads description to decide whether this skill is relevant to a user request. Write it as a clear statement of what the skill does and when to use it.
Why description matters
An agent can have several skills bound to it. When a user makes a request, the agent determines which skill is relevant based on each skill’s name and description. The name and description are the only signals the agent uses to distinguish one skill from another. The agent does not read the full skill body or scripts to make that determination, it matches the request against the description text. Follow these guidelines when you write a description:
  • State when to use the skill: Describe not only what the skill does, but also the situation that triggers it. For example: “Use when a user asks for order status or details.”
  • Be specific enough to disambiguate: Two skills with vague, overlapping descriptions such as “handles orders” and “manages order stuff” make it difficult for the agent to select the correct one.
  • Keep it short: One or two sentences. The description is a matching signal, not documentation. Include procedural detail in the skill body instead.
allowed-tools
allowed-tools is an optional frontmatter field. When present, the agent can call only the tools listed under it while the skill is active.
After the agent selects a skill, its full instruction body takes over. The agent follows those instructions step by step, with only that skill’s allowed-tools available.
scripts/ directory
The scripts/ directory holds Python (.py) files that the agent can run as part of the skill, for example, to perform a validation or transform data before passing it to a tool. When you import the skill by using orchestrate skills import --dir, the CLI uploads all .py files under scripts/ automatically.
references/ directory
The references/ directory holds documents that provide the agent with additional context while the skill runs, for example, a policy file, a lookup table, or a set of guidelines. The agent can read these files as it follows the skill instructions. Supported file types are .md, .txt, and .json.

​
Invoking scripts and references from the skill body

A skill can include Python scripts (scripts/) and reference documents (references/). Neither is invoked automatically. The skill body must instruct the agent when and how to use them.
Scripts
Specify which script to run and the required arguments:
The script is a plain Python function. Its parameters are defined by the function signature:
References
Specify which file to consult and when:
In each case, write plain-language instructions in the skill body that name the exact script or reference file and the condition under which the agent must use it. The agent follows the instruction text and does not infer intent independently.