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

# Managing agent skills

Use the `orchestrate skills` command group to import, inspect, update, and remove skills from your active environment without using the Agent Builder interface.

## Importing skills

Use `orchestrate skills import` to register one or more skills in your active environment.

<Tabs>
  <Tab title="Single file">
    ```bash BASH theme={null}
    orchestrate skills import --file skills/invoice-management/SKILL.md
    ```

    If a skill with the same name already exists, the command updates it instead of returning an error.
  </Tab>

  <Tab title="Skill directory">
    Pass a directory path to have the CLI upload `SKILL.md`, all `scripts/*.py` files, and all files under `references/` in a single operation:

    ```bash BASH theme={null}
    orchestrate skills import --dir skills/invoice-management/
    ```
  </Tab>

  <Tab title="Bulk import">
    Add `--recursive` to walk subdirectories and import every skill that contains a `SKILL.md`:

    ```bash BASH theme={null}
    orchestrate skills import --dir skills/ --recursive
    ```

    Use `--upsert` to update existing skills by name instead of returning an error for duplicates. This is the recommended pattern for CI pipelines — run it as part of your deployment pipeline so that every environment always reflects the latest skill definitions from your repository:

    ```bash BASH theme={null}
    orchestrate skills import --dir skills/ --recursive --upsert
    ```
  </Tab>
</Tabs>

<Expandable title="command flags">
  <ResponseField name="--file / -f" type="string">
    Path to a single `SKILL.md` file to import.
  </ResponseField>

  <ResponseField name="--dir / -d" type="string">
    Path to a skill directory, or a parent directory when combined with `--recursive`. The CLI automatically uploads `SKILL.md`, all Python scripts under `scripts/`, and all files under `references/`.
  </ResponseField>

  <ResponseField name="--recursive / -r" type="boolean">
    Walk subdirectories of `--dir` and import every directory that contains a `SKILL.md`. Cannot be used without `--dir`.
  </ResponseField>

  <ResponseField name="--upsert / -u" type="boolean">
    When a skill with the same name already exists, update it instead of returning an error. Use with `--dir` for repeatable CI imports.
  </ResponseField>

  <ResponseField name="--workspace-id / -w" type="string">
    Scope the import to a specific workspace. Defaults to the global workspace.
  </ResponseField>
</Expandable>

<Note>
  Specifying both `--file` and `--dir` in the same command is not supported.
</Note>

## Listing skills

To list all skills that are registered in your active environment, run:

<Tabs>
  <Tab title="Summary table">
    ```bash BASH theme={null}
    orchestrate skills list
    ```

    The default output is a table that shows each skill's name, description, mode, tools, script count, and ID.
  </Tab>

  <Tab title="Full details">
    ```bash BASH theme={null}
    orchestrate skills list --verbose
    ```

    Returns the full details of all skills in JSON format.
  </Tab>
</Tabs>

<Expandable title="command flags">
  <ResponseField name="--workspace-id / -w" type="string">
    Filter the list to skills that belong to a specific workspace.
  </ResponseField>

  <ResponseField name="--verbose / -v" type="boolean">
    Print full details for all skills in JSON format instead of the summary table.
  </ResponseField>
</Expandable>

## Inspecting a skill

To view the complete details of a single skill, including its full instructions body, run:

<Tabs>
  <Tab title="By name">
    ```bash BASH theme={null}
    orchestrate skills get --skill-name invoice-management
    ```
  </Tab>

  <Tab title="By ID">
    ```bash BASH theme={null}
    orchestrate skills get --skill-id abc-123
    ```
  </Tab>
</Tabs>

<Expandable title="command flags">
  <ResponseField name="--skill-id / -s" type="string">
    The unique ID of the skill to inspect.
  </ResponseField>

  <ResponseField name="--skill-name / -n" type="string">
    The name of the skill to inspect. Alternative to `--skill-id`.
  </ResponseField>
</Expandable>

## Updating a skill

To update an existing skill's definition, provide the path to the revised `SKILL.md` and identify the skill by name or ID:

<Tabs>
  <Tab title="By name">
    ```bash BASH theme={null}
    orchestrate skills update --skill-name invoice-management --file skills/invoice-management/SKILL.md
    ```
  </Tab>

  <Tab title="By ID">
    ```bash BASH theme={null}
    orchestrate skills update --skill-id abc-123 --file skills/invoice-management/SKILL.md
    ```
  </Tab>
</Tabs>

<Expandable title="command flags">
  <ResponseField name="--file / -f" type="string" required>
    Path to the updated `SKILL.md` file.
  </ResponseField>

  <ResponseField name="--skill-id / -s" type="string">
    ID of the skill to update.
  </ResponseField>

  <ResponseField name="--skill-name / -n" type="string">
    Name of the skill to update. Alternative to `--skill-id`.
  </ResponseField>
</Expandable>

<Note>
  You must specify exactly one of `--skill-id` or `--skill-name`. The skill must already exist before you can update it.
</Note>

## Uploading scripts

Skills can reference Python scripts that the agent runs. Upload individual script files after you import the skill. The CLI derives the script path inside the skill — for example, `scripts/validate.py` — from the local file path. Use `--script-path` to override this when the local path does not match the expected relative path inside the skill.

<Tabs>
  <Tab title="By name">
    ```bash BASH theme={null}
    orchestrate skills upload-script --skill-name invoice-management --file scripts/validate.py
    ```
  </Tab>

  <Tab title="By ID">
    ```bash BASH theme={null}
    orchestrate skills upload-script --skill-id abc-123 --file scripts/validate.py
    ```
  </Tab>

  <Tab title="Custom script path">
    ```bash BASH theme={null}
    orchestrate skills upload-script -n invoice-management -f validate.py --script-path scripts/validate.py
    ```
  </Tab>
</Tabs>

<Expandable title="command flags">
  <ResponseField name="--file / -f" type="string" required>
    Local path to the Python (`.py`) script file to upload.
  </ResponseField>

  <ResponseField name="--skill-id / -s" type="string">
    ID of the target skill.
  </ResponseField>

  <ResponseField name="--skill-name / -n" type="string">
    Name of the target skill. Alternative to `--skill-id`.
  </ResponseField>

  <ResponseField name="--script-path / -p" type="string">
    Relative path under which the script is stored in the skill, such as `scripts/validate.py`. Derived from the file path when not specified.
  </ResponseField>
</Expandable>

<Note>
  Script files must be Python (`.py`) files. You must declare scripts in the skill's `SKILL.md` frontmatter. When you use `orchestrate skills import --dir`, the CLI uploads all scripts under `scripts/` automatically.
</Note>

Scripts are intended for compute tasks such as pre- and post-validation steps. They run in isolation and are validated at upload time. The following items are blocked:

| Category           | Blocked items                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Imports            | `os`, `sys`, `subprocess`, `socket`, `shutil`, `importlib`, `ctypes`, `multiprocessing`, `threading`, `pickle`, `shelve`, `marshal`, `code`, `pty`, `fcntl`, `resource`, `signal`, `tempfile`, `glob`, `pathlib`, `platform`, `urllib`, `urllib3`, `http`, `httplib`, `httplib2`, `requests`, `aiohttp`, `httpx`, `websocket`, `websockets`, `ftplib`, `smtplib`, `poplib`, `imaplib`, `nntplib`, `telnetlib`, `xmlrpc`, `asyncio` |
| Built-in functions | `eval`, `exec`, `compile`, `open`, `__import__`, `globals`, `locals`, `vars`, `input`, `breakpoint`                                                                                                                                                                                                                                                                                                                                |
| Patterns           | URL strings, `pip install` calls, and other network-access patterns                                                                                                                                                                                                                                                                                                                                                                |

Any script that contains blocked imports, built-in functions, or patterns is rejected at upload time and is not stored.

## Uploading reference documents

Reference documents provide the agent with additional context, such as policy files, lookup tables, and reference guides. Supported file types are `.md`, `.txt`, and `.json`.

<Tabs>
  <Tab title="By name">
    ```bash BASH theme={null}
    orchestrate skills upload-reference --skill-name invoice-management --file references/REFERENCE.md
    ```
  </Tab>

  <Tab title="By ID">
    ```bash BASH theme={null}
    orchestrate skills upload-reference --skill-id abc-123 --file references/REFERENCE.md
    ```
  </Tab>
</Tabs>

<Expandable title="command flags">
  <ResponseField name="--file / -f" type="string" required>
    Local path to the reference file to upload. Supported file types are `.md`, `.txt`, and `.json`.
  </ResponseField>

  <ResponseField name="--skill-id / -s" type="string">
    ID of the target skill.
  </ResponseField>

  <ResponseField name="--skill-name / -n" type="string">
    Name of the target skill. Alternative to `--skill-id`.
  </ResponseField>

  <ResponseField name="--reference-path / -p" type="string">
    Relative path under which the reference is stored in the skill, such as `references/policy.md`. Derived from the file path when not specified.
  </ResponseField>
</Expandable>

## Exporting skills

Export a skill to move it between environments, share it with your team, or add it to source control.

<Tabs>
  <Tab title="By name">
    ```bash BASH theme={null}
    orchestrate skills export --skill-name invoice-management --output ./exported/invoice-management.zip
    ```
  </Tab>

  <Tab title="By ID">
    ```bash BASH theme={null}
    orchestrate skills export --skill-id abc-123 --output ./exported/invoice-management.zip
    ```
  </Tab>

  <Tab title="Extract to directory">
    Pass a directory path instead of a `.zip` path to extract the skill contents directly:

    ```bash BASH theme={null}
    orchestrate skills export --skill-name invoice-management --output ./exported/invoice-management/
    ```
  </Tab>
</Tabs>

<Expandable title="command flags">
  <ResponseField name="--output / -o" type="string" required>
    Destination path. A path ending in `.zip` saves the skill as a compressed archive. A directory path extracts the contents directly into that directory.
  </ResponseField>

  <ResponseField name="--skill-id / -s" type="string">
    ID of the skill to export.
  </ResponseField>

  <ResponseField name="--skill-name / -n" type="string">
    Name of the skill to export. Alternative to `--skill-id`.
  </ResponseField>
</Expandable>

## Removing a skill

To remove a skill that you no longer need from your active environment, run:

<Tabs>
  <Tab title="By name">
    ```bash BASH theme={null}
    orchestrate skills remove --skill-name invoice-management
    ```
  </Tab>

  <Tab title="By ID">
    ```bash BASH theme={null}
    orchestrate skills remove --skill-id abc-123
    ```
  </Tab>
</Tabs>

<Expandable title="command flags">
  <ResponseField name="--skill-id / -s" type="string">
    ID of the skill to remove.
  </ResponseField>

  <ResponseField name="--skill-name / -n" type="string">
    Name of the skill to remove. Alternative to `--skill-id`.
  </ResponseField>
</Expandable>

<Note>
  You must specify exactly one of `--skill-id` or `--skill-name`.
</Note>