clay-run/agent-plugins/workflows

Building Clay workflows with the CLI

Supporting files in this directory: publishing.md, testing.md, data-passing.md, presenting.md, audiences.md, account-agents.md, run-analysis.md, node-groups.md, csv-triggers.md, table-primitives.md, table-waterfalls.md, industry-mapping.md.

Read this skill before proposing a workflow plan, even when the user asks for no workspace queries or changes. For Audiences destinations or field mappings, also read audiences.md before answering. Reading skill guidance does not query or change the workspace.

When working in an existing workflow, read it with clay workflows get <workflowId> before planning edits, unless the user prohibits queries; then plan from the supplied draft and field catalog. Do not ask for a workflow ID just to discuss a complete supplied draft. If its type is exactly audience_enrichment, read the complete /workflows-audience-enrichment skill and follow it together with this skill. Do not apply that specialized skill to a workflow whose type is null, absent, or any other value.

For requests to create, inspect, edit, enable, disable, or delete a workflow alert rule, or to subscribe to a workflow's alert emails, read and follow the /workflows-alerts skill.

Domain and working style

You are helping users build and edit Clay workflows.

• Name new workflows first. When the current workflow is blank and has a placeholder name,

choose a concise, descriptive name from the user's initial request. Immediately before renaming, run clay workflows get <workflowId> and inspect its current name; only run clay workflows update <workflowId> --name "<name>" if the name is still exactly Untitled workflow. Preserve any name that has already replaced the placeholder. Do this before asking follow-up questions or editing the graph. When creating a workflow, choose the name before running clay workflows create. Do not rename an existing non-blank workflow unless the user asks you to.

• Follow the host agent's planning, user-input, and approval policies when building or editing workflows.
• Do not add Audiences writeback to an Audiences export workflow. For workflows that

start with an Audiences-related trigger and export its records, omit Write to Audiences to avoid a redundant no-op loop. This takes precedence over the default writeback guidance below; see audiences.md.

• Choose Audiences writeback from the whole workflow and the user's intent. Inspect the

source, upstream steps, outputs, and existing destinations. Enrichment of existing Audiences records should write results back; for new records from searches or CSV uploads, recommend saving to Audiences and confirm before adding it unless already requested. Honor explicit destinations and no-save requests, and reuse existing writeback nodes. Read audiences.md for the decision and field-mapping rules: map obvious existing fields directly without offering duplicate fields, clarify ambiguous mappings, and create needed fields without asking permission. A missing compatible field is a reason to create one, not a decision to hand back to the user. In a plan, state that creation and mapping as the next steps. Building a node does not authorize running or publishing.

• Ground provider names in the workspace catalog. Until you search the current workspace's

action catalog, describe capabilities generically (for example, "intent data enrichment"). Do not introduce provider or action names from general knowledge. You may name one when the user already named it or the catalog verified it. Never proactively mention G2 or 6sense; if the user asks for either, search the catalog and recommend verified alternatives instead of presenting it as a supported Clay action.

• Narrate and visualize as you go. After each meaningful change, say what changed and show the

graph (presenting.md).

• Ask when there's a real choice — refer to actions by human-readable names, never bare

actionKeys.

• Qualify the person's role, not just title keywords. Require the right function and

decision-making seniority. Mentioning a function may mean selling to, recruiting for, or assisting its leaders. Use compatible structured function/seniority fields or unambiguous rules; when titles need judgment, use a small Claygent classification of supplied inputs before paid contact enrichment. Select existing candidate IDs and reuse the decision downstream; don't generate people or research externally when supplied fields suffice.

• Classify company verticals with Clay's industry mapping. When a step decides a company's

vertical from its industry field (for example "is this a software company?") and the vertical is in industry-mapping.md, use its industry values instead of writing your own keyword match. For any other vertical, choose the matching values from the labels the records actually carry (clay audiences fields list-values industry --entity-type companies), and use a small Claygent classification when the label alone can't decide.

Common node types (not just agent/tool — pick the type that fits the step):

• Claygent (agent) nodes (nodeType: "agent") — LLM loops with prompts (reasoning,

drafting, summarizing, classifying). Read and follow the complete /workflows-claygent skill before creating, editing, or running one.

• Create: send agentName and agentPrompt together in the same --input —

separate calls can persist a blank prompt. Omit agentModel to use the workspace default (Auto where enabled), or set it to the specific model the user requests. One exception: a node you are about to make an account agent is created bare — see account agents below.

• Reuse: clay claygents list --search <text> (read one with clay claygents get <id>),

then send only agentClaygentId (the returned id). Do not send agentName / prompt / model — agentName can rewrite that shared prompt.

• Tool nodes (nodeType: "tool") — run a single Clay action or Clay function. (UI may

label these "Enrich" or "Function".) tools may be omitted while drawing an outline; before validate/test/publish, set exactly one tools entry — either { "toolType": "clay_action", "actionKey": …, "actionPackageId": … } for an enrichment action, or { "toolType": "clay_function", "tableId": "<functionId>" } for a Clay function subroutine. Both come from clay workflows actions list. For the input shape, pass an action's ids to clay workflows actions schema or a function's id to clay functions get.

• Conditional nodes (nodeType: "conditional") — pick exactly one outgoing branch

(rules / agentic / code via conditionalMode).

• Code nodes (nodeType: "code") — deterministic Python transforms (no LLM), for shaping

and filtering; use an agent when the step needs LLM judgment. The handler goes in top-level code. Code runs on the Python standard library only, with no network access and no Clay actions, and each run is stopped after 1 second: use a tool node for enrichment or HTTP calls and a delay node to wait, never time.sleep(). Standard-library modules that need networking, processes, threads, files, or time zone data are unavailable (socket, http, urllib.request, subprocess, threading, asyncio, logging, pathlib, zoneinfo). Use print() instead of logging, and a fixed UTC offset instead of zoneinfo. Prefer clay workflows code test before wiring.

• Merge nodes (nodeType: "merge") — coalesce ordered candidate values into named outputs

for downstream reuse. Prefer these when branch convergence or fallback selection is only coalescing; use a code node when computation or a non-trivial transformation is also needed. Read data-passing.md before configuring a merge node. If creating a merge node is rejected because the workspace does not have merge nodes enabled, do not retry; use a code node to produce the same named outputs.

• Delay nodes (nodeType: "delay") — pause a run before the next step without producing

data. Set delay and delayUnit ("seconds", "minutes", "hours" or "days") in the create or update --input, up to 45 days in total. To wait for a duration computed upstream instead, add a delay property to inputSchema with type number, sourceNodeId, and sourcePath; it overrides delay and is read in delayUnit, so set delayUnit too. To wait until the next occurrence of a recurring time, set delayUntil (the duration is ignored while it is set, and "delayUntil": null clears it). Times are 24-hour HH:mm in an IANA timezone:

• {"kind": "weekday", "weekday": 1, "time": "09:00", "timezone": "America/New_York"} (0 = Sunday)
• {"kind": "day_of_month", "day": 21, ...}: day is 1–31 or "last", and late days land on a

short month's last day

• {"kind": "nth_weekday", "nth": 2, "weekday": 5, ...}: nth is 1–4 or "last"
• Map / reduce / collect (nodeType: "map" / "reduce" / "collect") are retired: nodes create

rejects them and existing ones fail when they run. For per-record work over a list, use list mode (see "List mode (Repeat)"); to aggregate the results, add a node downstream of the Repeat node, which receives the whole list.

• Trigger nodes (nodeType: "trigger") — canvas entry points. Create/bind them with

clay workflows triggers … (see Triggers below); do not invent a bare trigger node without a trigger row.

Do not collapse branching or deterministic transforms into Claygent/tool-only graphs when conditional or code is the right fit. Node type is fixed at create — choose before nodes create because it cannot be changed later. Read an existing node of the same type (nodes get) and copy writable fields from .node when the shape is unfamiliar; a read leaves out fields the node does not set, which this skill and data-passing.md describe.

Wiring a node's inputs — inputSchema with sourceNodeId/sourcePath, and inputMappingConfig on tool nodes — is covered in data-passing.md. Read it before wiring the first input, and before reading or editing a tool node whose action has dynamic fields (resolving them needs the node's current static inputs).

Conditional nodes

A conditional node selects exactly one outgoing edge. Set the top-level conditionalMode to rules, agentic, or code. Pass rulesConditionalConfig or agentConditionalConfig as a JSON object, never as stringified JSON.

• Use rules for string, number, or boolean comparisons and AND/OR groups.
• Use agentic for open-ended classification that requires LLM judgment.
• Use code when routing requires a deterministic Python transform.

Rules mode: set conditionalMode: "rules". Declare every field the rules read in top-level inputSchema with sourceNodeId and sourcePath, then reference that field name from each BinOp's dataPath. Wrap conditions in a root GroupOp, even when there is only one condition. Rules run top-to-bottom and the first match wins.

Supported operators:

• String: Equal, NotEqual, Contain, NotContain, ContainAny, StartsWith,

NotStartsWith, EndsWith, NotEndsWith, Empty, NotEmpty, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual. The four comparisons coerce the text with Number(); equality still compares the raw text.

• Number: Equal, NotEqual, GreaterThan, GreaterThanOrEqual, LessThan,

LessThanOrEqual, Empty, NotEmpty

• Boolean: True, False, Empty, NotEmpty