> This page is for Harness.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Convert an Existing Skill to the Agentic Orchestrator

> **Controlled Availability**
>
> The Agentic Orchestrator is in Controlled Availability and comes to your Enterprise Assistant in Q1 2027. Capabilities, limits, and interface labels described here may change before general availability. To request access, contact your Moveworks account team.

If your team already has agent skill bundles written for another host, for example Claude Agent Skills, most of the content carries over to the Agentic Orchestrator unchanged. What changes is the platform coupling: host filesystem paths, UI verbs, shell and Node execution, and tool spellings. This page walks through that adaptation. For the Skill format and how the Agentic Orchestrator loads a Skill, see [Skills](/harness/agentic-orchestrator/skills).

A Skill is a packaged set of instructions and supporting files that the Agentic Orchestrator loads on demand. It is not a Tool Studio plugin and installs no tools.

## What Carries Over Unchanged

* `SKILL.md` and its frontmatter. The Agentic Orchestrator reads `name` and `description` and ignores other keys, so leave the original frontmatter in place.
* Markdown reference files under `references/` or similar directories.
* Declarative workflow language such as "read `references/x.md` from skill Y", "invoke skill Z", and "return to the orchestrator". The Agentic Orchestrator's planner follows these in the same context.
* Bundled assets: templates, images, fonts, data files.

## The Agentic Orchestrator Contract

| Area                              | The Agentic Orchestrator                                                            |
| --------------------------------- | ----------------------------------------------------------------------------------- |
| Code                              | Python only, in a sandbox with a fixed library list                                 |
| Shell, terminal, package installs | None                                                                                |
| Network from code                 | None                                                                                |
| Node or JavaScript execution      | None. Browser JS may ship inside an HTML artifact as inert content.                 |
| Files per code call               | 5 inputs, 1 output                                                                  |
| Inline text reads                 | `.md`, `.txt`, `.html` up to 200,000 bytes                                          |
| Skill resources                   | Requested by relative path; staged flat under `INPUT_DIR` as `<stem>__<8hex>.<ext>` |
| Deliverables                      | Artifacts, returned by the artifact tools                                           |
| Connectors                        | MCP servers and plugins are attached to the assistant, not installed by the Skill   |

## Conversion Steps

Work on a copy of the bundle. Keep the wording declarative and platform-neutral: do not write the Agentic Orchestrator's tool-call syntax into Skill content either, because the Orchestrator chooses its own loading and execution tools.

#### Replace host filesystem paths

Paths such as `/mnt/skills/...`, `/mnt/user-data/...`, and `/tmp/...` do not exist. Text reads become declarative references; code paths become `INPUT_DIR` and `OUTPUT_DIR`.

* Before: `Read /mnt/skills/public/brand/SKILL.md`
* After: Read `SKILL.md` from the `brand` Skill.
* Before: `pd.read_excel('/mnt/skills/user/pricing/assets/rates.xlsx')`
* After: Provide `assets/rates.xlsx` from this Skill as a code input and open it from `INPUT_DIR` under the file name issued for it.

#### Replace host UI verbs and callbacks

`view()`, `present_files`, `create_file`, widget callbacks, phrases like "renders in the artifact panel", and implicit Markdown-to-Office conversion are host features. The Agentic Orchestrator delivers files as artifacts and never converts Markdown to Office formats on its own.

* Before: "Generate structured Markdown (the host renders it as .docx)."
* After: "Generate the .docx with code execution (`python-docx`) and return it as an artifact."
* Interactive buttons inside generated widgets become ordinary conversation: "offer to draft talking points next."

#### Remove fixed progress announcements

Delete any requirement to open with a line such as "Account Lookup is working...". The Agentic Orchestrator shows progress to the user itself. Remove the whole step that mandates the announcement, not just the quoted text.

#### Replace connector-specific tool spellings

Spellings such as `Microsoft 365:get_me`, `WebSearch`, or `WebFetch` are host-specific. Name the capability instead. Connectors are provisioned on the assistant through [MCP Workspace](/tool-studio/mcp-workspace/overview), and the admin maps each capability to a server.

* Before: `Call Data_Analytics:account_insights for the account.`
* After: "Query account insights through the data analytics connection. If no such connection is available, tell the user which one is missing."
* Before: `Use WebFetch on the release notes page.`
* After: "Fetch the release notes page from the web."

#### Remove direct model and API access

Delete SDK calls, model IDs, API endpoints, keys, and CLI invocations of a model. The reasoning that call performed becomes an instruction the planner carries out.

* Before: `client.messages.create(model=..., messages=[{"role": "user", "content": prompt}])`
* After: "Analyze the entitlement data and classify each account as expand, hold, or at risk."

#### Convert shell and child processes to in-process Python

Remove bash wrappers, heredocs, `pip` or `npm` installs, `subprocess`, and command-line document tools. Exit codes become exceptions; stdout parsing becomes return values. Visual QA that depended on `soffice` or `pdftoppm` becomes structural checks with `python-pptx` (slide count, text present, placeholders filled), with a note in the Skill that layout is not pixel-verified.

Before:

```python
result = subprocess.run(["python3", script_path, "--mode", mode], capture_output=True)
if result.returncode != 0:
    raise RuntimeError(result.stderr)
```

After:

```python
try:
    output = run_step(mode=mode)  # defined inline or loaded from the staged helper
except PipelineError as e:
    ...
```

#### Port Node-based Office generation

docx-js becomes `python-docx`; PptxGenJS becomes `python-pptx`. Port the semantics (fonts, sizes, colors, positions), not the JS API shape, and prefer one reusable builder function over translating snippets one by one. Browser JavaScript may remain inside an HTML artifact as content only; the sandbox never runs or validates it.

```python
from docx import Document
doc = Document()
doc.add_heading(title, level=1)
doc.add_paragraph(body_text)
doc.save(os.path.join(OUTPUT_DIR, "brief.docx"))
```

#### Replace local scratch state

Workflows that persist intermediates under `/tmp/{customer}/` across steps have no disk to use. Produce each intermediate as an artifact, keep its returned reference in the conversation, and pass it as an input to the next code call.

* Before: "Write `state.json` to `/tmp/acme/` and read it back in step 3."
* After: "Produce `state.json` as an artifact. In step 3, provide that artifact as a code input."

#### Make bundled scripts importable and self-contained

Scripts invoked as `python3 scripts/build.py in out template` become functions with explicit arguments. Staged files land flat under `INPUT_DIR`, so there is no importable package root: remove `sys.path` edits and sibling imports, merge helpers into one file, and pass asset paths as arguments. For small helpers, inline the logic into the Skill's instructions instead of shipping a `.py`.

* Before: `sys.path.insert(0, "/mnt/skills/org/brand"); from brand_helpers import apply_theme`
* After: a single self-contained `scripts/build.py` exposing `build(notes_path, output_path, template_path)`, loaded from its staged file.

#### Map dependencies on the host's public skills

References to the host's built-in `docx`, `pptx`, or `frontend-design` skills do not resolve on the Agentic Orchestrator. Point them at your own companion Skills published to the same organization, or inline the generation instructions.

* Before: `Route one-pagers to /mnt/skills/public/docx/SKILL.md`
* After: Read `SKILL.md` from the `docx-brand` Skill (published alongside this one).

## Resources Checklist

* Keep each text resource at or under 200,000 bytes, or split it. Larger text is staged for code instead of read inline.
* Rename extensionless files and dotfiles (`LICENSE`, `.env`) with an extension if anything needs to read them. Otherwise remove them.
* Drop host-specific machinery: `.claude/`, `skill.json`, marketplace files, install and session scripts, `.DS_Store`.
* Check every Python import against the available libraries: Beautiful Soup, NLTK, NumPy, OpenPyXL, pandas, Pillow, Plotly, PyCryptodomeX, python-docx, python-gnupg, python-pptx, ReportLab, scikit-learn, seaborn, and the standard library. Anything else is unavailable and cannot be installed at runtime.
* Count the files each code step needs. More than 5 means splitting the step.

## Package and Upload

Zip the directory with `SKILL.md` at the root (or inside one wrapper directory named exactly as the `name`), as `.zip` or `.skill`, up to 100 MiB unpacked. In Assistant Builder, open **Add Skills** and select **Upload a skill**.

Expect upload to fail if `name` or `description` is missing, `name` does not match `^[a-z0-9]+(-[a-z0-9]+)*$`, `description` exceeds 1,024 characters, or the wrapper directory name differs from `name`.

## Verify

1. Ask a request phrased like the description. Confirm the Skill loads and the response follows its steps.
2. Ask for something that requires a reference file. Confirm the file is read.
3. Run a step that generates a file. Confirm the artifact is returned and opens correctly.
4. Ask an out-of-scope request. Confirm the Skill does not load.

## Common Pitfalls

* **Tool IDs in content.** `mcp_server__tool` names are deployment-specific. Describe the capability.
* **TODO markers.** The planner reads them as instructions. Finish the adaptation or remove the line.
* **Description over 1,024 characters.** Upload fails. Move detail into the body.
* **More than 5 input files in one code step.** Split the step or inline small helpers.
* **Expecting the sandbox to see Skill files.** Nothing is mounted. Every file a code step uses must be named and staged as an input.
* **Expecting multiple files from one code call.** Each call returns exactly one file. Chain calls, passing earlier artifacts as inputs.