> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent skills

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

<Steps>
  <Step title="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](/agent_skills/overview#skill-directory-structure).
  </Step>

  <Step title="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](/agent_skills/manage_skills#importing-skills).
  </Step>

  <Step title="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](/agent_skills/manage_skills#listing-skills) and [Inspecting a skill](/agent_skills/manage_skills#inspecting-a-skill).
  </Step>

  <Step title="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](manage_skills#updating-a-skill) and [Removing a skill](manage_skills#removing-a-skill).
  </Step>
</Steps>

<Note>
  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](manage_skills#uploading-scripts) and [Uploading reference documents](manage_skills#uploading-reference-documents).
</Note>

## Skill directory structure

A skill directory uses the following structure:

```
my-skill/
├── SKILL.md          # Required: frontmatter (name, description) + instructions
├── scripts/          # Optional: Python scripts referenced by the skill
└── references/       # Optional: reference documents (.md, .txt, .json)
```

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

```yaml wrap theme={null}
---
name: invoice-management
description: Handles invoice creation, validation, and approval workflows.
---

# Invoice Management

## Procedure

1. Confirm the invoice details with the user.
2. Call the invoice creation tool with the confirmed details.
3. Return the created invoice ID and status to the user.
```

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

```yaml wrap theme={null}
---
name: order-submit
description: Place and track customer orders. Use when a user wants to submit a new order or check the status of an existing order.
allowed-tools:
  - create_order
  - update_order_status
---
```

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:

```markdown theme={null}
Before placing any order, run the validation script order_validate.py with:
args={"product_id": "<product_id>", "quantity": <quantity>, "unit_price": <unit_price>}
```

The script is a plain Python function. Its parameters are defined by the function signature:

```python theme={null}
def run(product_id: str, quantity: int, unit_price: float) -> dict:
    ...
```

##### References

Specify which file to consult and when:

```markdown theme={null}
For detailed order limits and shipping rules, read the policy reference: ORDER_POLICY.md
```

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.