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.

Single file
Skill directory
Bulk import

BASH

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.

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

orchestrate skills import --dir skills/invoice-management/

Add --recursive to walk subdirectories and import every skill that contains a SKILL.md:

BASH

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

orchestrate skills import --dir skills/ --recursive --upsert

Show command flags

string

Path to a single SKILL.md file to import.

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

boolean

Walk subdirectories of --dir and import every directory that contains a SKILL.md. Cannot be used without --dir.

boolean

When a skill with the same name already exists, update it instead of returning an error. Use with --dir for repeatable CI imports.

string

Scope the import to a specific workspace. Defaults to the global workspace.

Specifying both --file and --dir in the same command is not supported.

Listing skills

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

Summary table
Full details

BASH

orchestrate skills list

The default output is a table that shows each skill’s name, description, mode, tools, script count, and ID.

BASH

orchestrate skills list --verbose

Returns the full details of all skills in JSON format.

Show command flags

string

Filter the list to skills that belong to a specific workspace.

boolean

Print full details for all skills in JSON format instead of the summary table.

Inspecting a skill

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

By name
By ID

BASH

orchestrate skills get --skill-name invoice-management

BASH

orchestrate skills get --skill-id abc-123

Show command flags

string

The unique ID of the skill to inspect.

string

The name of the skill to inspect. Alternative to --skill-id.

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:

By name
By ID

BASH

orchestrate skills update --skill-name invoice-management --file skills/invoice-management/SKILL.md

BASH

orchestrate skills update --skill-id abc-123 --file skills/invoice-management/SKILL.md

Show command flags

string

required

Path to the updated SKILL.md file.

string

ID of the skill to update.

string

Name of the skill to update. Alternative to --skill-id.

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

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.

By name
By ID
Custom script path

BASH

orchestrate skills upload-script --skill-name invoice-management --file scripts/validate.py

BASH

orchestrate skills upload-script --skill-id abc-123 --file scripts/validate.py

BASH

orchestrate skills upload-script -n invoice-management -f validate.py --script-path scripts/validate.py

Show command flags

string

required

Local path to the Python (.py) script file to upload.

string

ID of the target skill.

string

Name of the target skill. Alternative to --skill-id.

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.

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.

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.

By name
By ID

BASH

orchestrate skills upload-reference --skill-name invoice-management --file references/REFERENCE.md

BASH

orchestrate skills upload-reference --skill-id abc-123 --file references/REFERENCE.md

Show command flags

string

required

Local path to the reference file to upload. Supported file types are .md, .txt, and .json.

string

ID of the target skill.

string

Name of the target skill. Alternative to --skill-id.

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.

Exporting skills

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

By name
By ID
Extract to directory

BASH

orchestrate skills export --skill-name invoice-management --output ./exported/invoice-management.zip

BASH

orchestrate skills export --skill-id abc-123 --output ./exported/invoice-management.zip

Pass a directory path instead of a .zip path to extract the skill contents directly:

BASH

orchestrate skills export --skill-name invoice-management --output ./exported/invoice-management/

Show command flags

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.

string

ID of the skill to export.

string

Name of the skill to export. Alternative to --skill-id.

Removing a skill

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

By name
By ID

BASH

orchestrate skills remove --skill-name invoice-management

BASH

orchestrate skills remove --skill-id abc-123

Show command flags

string

ID of the skill to remove.

string

Name of the skill to remove. Alternative to --skill-id.

You must specify exactly one of --skill-id or --skill-name.

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Importing skills

Listing skills

Inspecting a skill

Updating a skill

Uploading scripts

Uploading reference documents

Exporting skills

Removing a skill

​Importing skills

​Listing skills

​Inspecting a skill

​Updating a skill

​Uploading scripts

​Uploading reference documents

​Exporting skills

​Removing a skill

Importing skills

Listing skills

Inspecting a skill

Updating a skill

Uploading scripts

Uploading reference documents

Exporting skills

Removing a skill