# Workato

> Drive a Workato account via its Platform REST API — inspect, build, fix, debug, and start/stop recipes; read connections, folders, projects, jobs. Use when a task touches a Workato account or recipe.

- **Type:** Skill
- **Install:** `agentstack add skill-ouhoy-claude-workato-skill-claude-workato-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ouhoy](https://agentstack.voostack.com/s/ouhoy)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ouhoy](https://github.com/ouhoy)
- **Source:** https://github.com/ouhoy/claude-workato-skill

## Install

```sh
agentstack add skill-ouhoy-claude-workato-skill-claude-workato-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Workato (Platform API)

Control a Workato account by calling its REST API with a token. This skill bakes in the
endpoint map, the recipe `code` JSON format, and the non-obvious traps that otherwise cost
hours. **Start every task by orienting (token + scope), then use `scripts/wk.py`** — it
encodes the base URL, auth, and the body quirks so you never rewrite curl.

## Setup & orientation (do this first)

- **Token:** `~/.config/workato/api_token` (or `$WORKATO_API_TOKEN`). A `wrkaus-…` prefix = US region.
- **Helper:** `python3 ~/.claude/skills/workato/scripts/wk.py …` (zero deps, stdlib only). Run `wk.py -h`.
- **Optional MCP server:** if a `workato` MCP server is registered, its read + start/stop tools
  also work — use fully-qualified names (`workato:list_recipes`, `workato:get_recipe`,
  `workato:list_connections`, `workato:list_folders`, `workato:list_projects`,
  `workato:list_recipe_jobs`, `workato:start_recipe`, `workato:stop_recipe`, `workato:workato_get`).
  Use them for reads if present, **but for creating/updating recipes use `wk.py`** (the MCP server
  has no write tools). The server is optional — `wk.py` alone covers everything.
- **Always check scope before promising anything:** `wk.py scope`. A token is scoped to one
  API client's role — many resources may be `401`. The token this was built for does
  **recipes (R/W) + jobs + versions + connections + folders + projects**; lookup tables,
  properties, roles, API platform, audit logs, tags, on-prem are typically `401`.

## What you can do (and the command for it)

| Goal | Command |
|---|---|
| See capability surface | `wk.py scope` |
| List recipes / running ones | `wk.py recipes [--folder ID] [--running]` |
| Inspect a recipe (and its code) | `wk.py recipe  [--code]` |
| List connections / folders / projects | `wk.py connections` · `wk.py folders [--parent ID]` · `wk.py projects` |
| Debug runs / discover field names | `wk.py jobs ` then `wk.py job   --outputs` |
| See version history | `wk.py versions ` |
| Create a recipe (left stopped) | `wk.py create --name N --folder ID --code code.json --config config.json` |
| Update a recipe (must be stopped) | `wk.py update  [--name N] [--code code.json] [--config config.json]` |
| Start / stop | `wk.py start ` · `wk.py stop ` |
| Delete a (scratch) recipe | `wk.py delete recipes/` |
| Anything else | `wk.py get|post|put|delete  [--data @file]` |

## Four golden rules (internalize these)

1. **The API stores recipe `code` verbatim and does NOT validate it.** A `{"success":true}`
   write can still be semantically broken (wrong operand key, wrong datapill field, bad input).
   Only the editor/runtime validate. So a created recipe isn't "working" until verified — never
   claim otherwise on the strength of the HTTP 200 alone.
2. **`wk.py start` IS a free validator.** It returns the editor's `code_errors` (invalid
   provider/action names, missing required fields, bad pills) without opening the UI — so
   unknown encodings can be discovered by probe loop on a scratch recipe (recipe-gotchas.md).
   Stop a scratch immediately if it starts and its trigger polls a real source.
3. **Discover real encodings empirically, don't guess.** Field names come from a real job:
   `GET /recipes/:id/jobs/:job_id` → per-step `lines[]` with RESOLVED input/output (unknown
   input keys are silently schema-filtered, so the surviving keys reveal an action's true
   schema). Pill/picklist encodings: build once in the editor and read back.
4. **Validation ≠ runtime.** Pills can validate yet resolve EMPTY (`_dp`+`"first"` trap),
   and runtime-only failures exist (`lookup()` wrong table name, nil-chain errors, Shopify
   "Sold out"/"Record is invalid"). Full verification = start + one real job + inspect the
   created record. Validation errors also hide behind HTTP 200 (`{"success":false,…}`).

## Core workflows

### Inspect / explore an account
`wk.py scope` → `wk.py recipes` / `connections` / `folders` / `projects`. To see how a recipe
ran, list jobs then dump a job. This is read-only and safe.

### Build a recipe
1. Pick a **non-root** folder (`wk.py folders`) and the **connection id** (`wk.py connections`).
2. Write the `code` tree (trigger = step 0; children in `block`) and a `config` array. Follow
   **references/recipe-code-dsl.md** for step structure, control flow (IF/ELSE_IF/ELSE as
   sibling steps, `foreach`/`repeat` loops, `try`/`catch`), the verified condition operand
   table, and datapill encoding. Get connector field names from **references/connectors-gmail.md**
   (or a real job for other connectors).
3. `wk.py create …` (leaves it **stopped**). Read it back: `wk.py recipe  --code`.
4. **Verify** before declaring success (golden rule #1): have the user open it in the editor, or
   inspect a job once it runs. Then `wk.py start ` when ready.

### Fix / debug a recipe
`wk.py recipe  --code` to see the current tree → locate the bad step → fix in a local
`code.json` → `wk.py update  --code code.json`. The usual culprits (all in
**references/recipe-gotchas.md**): an invalid operand key (`doesnt_contain` → must be
`not_contains`; full table in the DSL ref), a datapill pointing at a non-existent field
(e.g. `from` instead of `from_email`), or `folder_id`/`code` body-type mistakes on create.
**A fix isn't done at the `update` 200** (golden rule #1): re-read the code, then re-validate
with `wk.py start` and/or one real job before declaring it fixed.

### Trigger timing
Most triggers (Gmail `new_email` included) are **polling**, not real-time; the interval is
plan-gated and **cannot be changed via the API**. Real-time needs a webhook trigger / external
push (Gmail → Pub/Sub). Details in recipe-gotchas.md.

## When to read which reference

- **references/recipe-code-dsl.md** — building/fixing recipe `code`: step keywords, control
  flow (IF/ELSE, `foreach`/`repeat` loops, `try`/`catch`), the verified operand table, datapill
  formats (incl. the **array-pill validation-vs-runtime
  table**, **`=` formula mode** for non-first elements/ternaries/`lookup()`, list
  **`.where(field:'val')` filtering + the backward-compatible null-safe guard** for the
  `[0]['x']`-on-nil crash, the **DB batch-insert `rows`/`____source` shape**, the
  extended-schema rules, formula conditions, and the `stop` step), a full worked example.
  *Read this for any build-or-fix task.*
- **references/recipe-gotchas.md** — before any create/update: the verbatim-storage trap, the
  **start-as-validator probe loop**, job `lines[]` debugging (incl. `?include_payloads=true`
  and the **try/catch-hides-failure** trap — job `succeeded` while the source system shows
  FAILED), **editing a live recipe safely** (backup → leaf-diff assert → stop/update/start →
  rollback → re-test), forcing an immediate poll (stop+start), editor re-save rewrites,
  `folder_id`-string / `code`-string rules, field discovery, polling vs real-time.
- **references/connectors-utilities.md** — verified encodings for **json_parser** (parse a
  JSON-string output into pills; `document` root + labeled-schema traps), **logger**
  (`log_message` as a pill-resolution probe), **lookup tables** (the `lookup()` formula vs
  the half-mapped `lookup_table` connector; API is 401 — tables are UI-maintained).
  *Read this whenever a connector returns JSON as a string, or a mapping needs a lookup table.*
- **references/api-endpoints.md** — exact endpoints, regions, rate limits, the broader (often
  `401`) API surface, the error model, and how to widen token scope.
- **references/connectors-gmail.md** — Gmail `new_email` outputs + `send_mail` inputs.
- **references/connectors-orderful-shopify.md** — inbound-EDI playbook: Orderful → Workato →
  Shopify (Walmart 850 PO → Shopify draft order). The poller-bucket **routing trap**
  (Orderful Communication Channels, UI-only — recipe gets 0 jobs if inbound isn't routed to a
  POLLER channel), the bucketId trailing-space bug, the Orderful poller trigger + `get_record`
  (returns the parsed message as a JSON **string** → json_parser), Shopify
  `create_draft_order` (full verified input incl. addresses/note, the
  extended_input_schema requirement, `province`/`country` naming, "Sold out" /
  "Record is invalid" causes) and `search_product` (handle-only lookup → handle=UPC
  convention), the **three-tier item matching** pattern (Shopify → lookup table → stop with
  details), how to inject a test 850, and the full proven recipe with mapping formulas.
  *Read this for any Orderful/EDI-inbound recipe or Shopify draft-order action.*
- **references/connector-sdk.md** — the boundary case: a task needs a **connector** built or
  changed (not a recipe). This skill can't do that — connectors are authored with the Ruby
  **Workato Connector SDK** (`workato new/exec/push`). *Read this only when no connector
  exists for the app, or you must edit a custom connector's internals; for recipes, stay here.*

## Not the same as Workato's hosted MCP

This skill calls the **Workato REST API** with your own token from local scripts (deterministic,
endpoint-shaped). Workato also offers **Remote MCP servers** — Workato *hosts* an MCP server that
exposes selected recipes as LLM tools at a `https://.apim.mcp.workato.com/…?wkt_token=…`
URL you'd add as a Claude connector. That's a different, LLM-tool-shaped surface. Don't conflate
them: for "use my token to build/fix/inspect recipes," use this skill.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ouhoy](https://github.com/ouhoy)
- **Source:** [ouhoy/claude-workato-skill](https://github.com/ouhoy/claude-workato-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ouhoy-claude-workato-skill-claude-workato-skill
- Seller: https://agentstack.voostack.com/s/ouhoy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.