← Plugin catalog
Business & Operations

Clay

Clay Labs Inc. v2.38.0

Find your next customers

Create a free account to save this plugin.

From the developer

Declared capabilities

  • Read
  • Write

Declared limitations

  • Unsupported search filter. Expected: Explains that Clay Search does not support email-address filtering; does not fabricate matches.
  • Contradictory filters. Expected: Identifies the contradiction or returns zero matches without dropping either condition.
  • Missing audience. Expected: Reports that the audience was not found, rather than reporting zero members or substituting another audience.

Not specified in the available declarations: pricing & account requirements.

Onboarding example

Find me sales leaders at Acme

View onboarding source →

Sources & dates

Developer declarations; not independently tested. Listing last checked Nov 18, 2026. Package observed Nov 18, 2026.

View package source →

Description

From the marketplace listing

Find and research your next customers. Find emails, send customized outreach, build workflows to qualify leads, and more with Clay.

Language: English · Automatically detected from descriptions.

Changes

No changes recorded yet. Follow this plugin to keep track of future changes.

First seen Nov 18, 2026. Last seen Nov 18, 2026.

Similar plugins

Similar plugins could not be prepared right now. Please try again in a moment.

Browse plugins →

Files & skills

File archives

Plugin package80 files · 493 KBBrowse files →
Skill instructions
ad-syncs10.6 KB

View saved version →

---
name: ad-syncs
description: Clay ad syncs — push an audience segment to ad platforms (LinkedIn, Meta, Google, Bing, Reddit, Vibe) as a custom audience. Use to create, edit, start, pause, or map the fields of an ad sync, or to check its status, match rate, or run history.
---

# Ad syncs

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

An ad sync pushes an audience segment to ad accounts on ad platforms, called its destinations. Each
platform matches the records and builds an audience to advertise to.

## Supported commands

- `clay ad-syncs list [--limit <n>] [--cursor <cursor>]`
- `clay ad-syncs get <adSyncId>`
- `clay ad-syncs get-by-source --source-id <segmentId> --entity-type <people|companies>`
- `clay audiences get <segmentId>`
- `clay ad-syncs create --name <name> --source-id <segmentId> --entity-type <people|companies> --schedule-type <ONE_TIME|RECURRING>`
- `clay ad-syncs update <adSyncId> [--name <name>] [--schedule <ONE_TIME|RECURRING>] [--tier <PREMIUM|STANDARD>]`
- `clay app-accounts list --filter type=<provider>-ad-audience`
- `clay ad-syncs ad-accounts list <appAccountId> --provider <provider>`
- `clay ad-syncs destinations create <adSyncId> --provider <provider> --app-account-id <appAccountId> --ad-account-id <accountId> [--ad-user-data-consent <status> --ad-personalization-consent <status>]`
- `clay ad-syncs destinations update <adSyncId> --destination-id <destinationId> [--app-account-id <appAccountId>] [--ad-account-id <accountId>] [--ad-user-data-consent <status>] [--ad-personalization-consent <status>]`
- `clay ad-syncs destinations delete <adSyncId> --destination-id <destinationId>`
- `clay ad-syncs field-mapping update <adSyncId> --input '<json>'`
- `clay ad-syncs pause <adSyncId>`
- `clay ad-syncs trigger <adSyncId>`
- `clay ad-syncs runs list <adSyncId> [--limit <n>]`

Use only the subcommands `clay ad-syncs --help` lists; some ship to only some channels. When one is
missing, the user does that step in the Clay app, from the sync's `url`. Run
`clay ad-syncs <subcommand> --help` before a subcommand's first use. It has the exact output
shape, value sets, and error codes. `<provider>` is `LinkedIn`, `Meta`, `Google`, `Bing`, `Reddit`,
or `Vibe`, written in lowercase inside `type=<provider>-ad-audience` (e.g.
`type=linkedin-ad-audience`). An `<accountId>` is an `accountId` from `ad-accounts list`, and a
`<destinationId>` is a `providerSyncConfigs[].id` from `get`.

## Limits

- You can always create an ad sync, and edit it while it is a draft or paused.
- You cannot delete an ad sync: the user deletes it in the Clay app. A segment can have only one ad
  sync, so create one only for a segment the user confirmed.
- Pause a running sync only when the user asks. Before running `pause`, tell them what pausing does
  (see Statuses) and ask them to confirm, even when they asked for it.
- Start or resume a sync with `trigger` only when the user explicitly asks; follow Start.

## Schedules

- `ONE_TIME`: it exports once, when the user starts it.
- `RECURRING`: it syncs continuously to its destinations, so they stay up to date with the people
  or companies the user wants to target.

## Statuses

Tell the user the label in parentheses, not the raw value.

- `DRAFT` (Draft): not started yet.
- `PROCESSING` (Processing): an export is running, including enrichment when the sync has a tier.
- `ACTIVE` (Active): a recurring sync whose latest export reached every destination. It exports
  again on its schedule.
- `DONE` (Exported): a one-time sync that reached every destination.
- `WARNING` (Warning): some destinations failed. A one-time sync reached only some of them, or a
  later export of a recurring sync failed on at least one, and the sync stays live. `runs list`
  shows which destinations failed.
- `FAILED` (Failed): a one-time sync that failed on every destination, or a recurring sync whose
  first export failed on any destination.
- `BU

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

audiences25.1 KB

View saved version →

---
name: audiences
description: Clay Audiences — the workspace's own people, companies, and deals (contacts, leads, accounts, customers). Use for any request about their records when no surface is named, including counts, fill rates, lookups ("how many people have a phone?"), saved segments, and field definitions. Also deal and pipeline questions like largest opportunities, biggest pipeline items, recent wins, closed-won, deal stage, and ACV. Also Data hub enrichment configuration, audience assignments, and parity checks. Also the calls and meetings synced onto those records, such as Gong recordings, and which accounts discussed a topic on their calls.
---

# Clay Audiences

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Audiences is Clay's CRM-shaped store of **people** and **companies** (plus deal
records). An **audience** — also called a saved segment — is a named filter over
one entity type. Nothing is copied into it: it selects records live, so its
membership changes as records change.

**Audiences is the default home for the workspace's own people and companies.**
When a user mentions people, companies, contacts, leads, accounts, customers,
deals, or opportunities without naming a surface, they mean these records —
start here, not in the tables entry-point skill (a separate surface, right only
when the user names a table) and not in `search` (net-new prospects that are not
in the workspace yet).

Read this before any audiences work. Supporting references:

- `answering-data-questions.md` — **read this first for any request to count,
  find, or filter existing records.** Before filtering a categorical field, call
  `fields list-values` as described there. Also covers field coverage and when
  to enrich.
- `queries.md` — **read before searching or counting records. Prefer `--query`,
  including activity and signal criteria, even when the task will later save an audience.** Audiences DSL grammar,
  relationship semantics, data or date filters, and server-side sorting for
  top-N questions.
- `filters.md` — writing the filter AST to create/update a saved audience, or
  validate that saved filter. Use it for record searches only when DSL cannot express the criteria.
- `frontend-ast-filters.md` — supported AST segment-editor fields, operators, and collection
  shapes. Consult when choosing a saved filter; backend search support is broader.
- `custom_objects.md` — **deals / opportunities.** Read it before anything that
  touches them, including vague rankings such as "largest opportunities",
  "biggest things in our pipeline", or "recent wins", and GTM phrasings:
  closed-won, closed-lost, open pipeline, deal stage, deal size / ACV / ARR,
  close date, forecast, win rate,
  renewal, expansion, churn, "our customers". Deals are read-only. Use the DSL
  `opportunities` root for deal counts and IDs; use people/company roots when
  the requested results are contacts/accounts associated with those deals.
- The `workflows` skill’s [enrichments.md](../workflows/enrichments.md) — **read for Data hub enrichment inspection, parity checks, and reuse across
  segments.** Maps native assignments, provider order, mappings, overwrite rules, schedules,
  and budgets to the workflow CLI; separates inspection from edits and execution.
- The `workflows` skill's `audiences.md` — writing values onto records (the
  `upsert-audiences-record` action) and triggering a workflow off an audience.

**Read with the CLI, write records with the action.** `clay audiences` covers
every Audiences primitive — segments, fields, and reading records — but it has no
command that writes a field value onto a record. That is the
`upsert-audiences-record` action's job.

**Net-new people or companies** — not in the workspace yet. When `search` and `routines`
are available CLI commands, start in the `searches` skill, then persist via a routine
wrapping an upsert workflow (the `workflows` skill's `

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

clay23.5 KB

View saved version →

---
name: clay
description: Clay — start here. A table of contents for working with Clay and which skill to use for each thing — audiences (the workspace's own people/companies/deals), sequences (formerly campaigns; create, improve, and analyze outbound email sequences in Sequencer), ad syncs (push audience segments to ad platforms), search (find net-new people/companies), routines (run Clay-managed and custom functions), tables (query/export data), the CLI (ephemeral programmatic access), the Public API (build services on Clay), workflows (build automations), feedback, and getting help — reaching Clay support or a human about billing, refunds, or account problems. Read this first to answer "what can I do with Clay?"
---

# Working with Clay

Clay is a GTM (go-to-market) data and automation product. This skill is a table of
contents: find what you want to do and go to that skill.

## Accessing Clay

Use the Clay CLI or the connected Clay MCP tools, whichever is available in your
session. The examples in these skills use CLI syntax to describe the operations;
the leaf MCP server exposes those operations as tools with structured arguments.
Discover the tools advertised by the connected server rather than inferring support
from a different or older Clay server.
Discover the available commands or tools and use their help when you need details.
When a connected Clay MCP tool supports the task, use it without installing or
signing into the CLI. CLI setup and readiness hooks
apply only when you choose the CLI. A missing or unauthenticated CLI
does not mean the MCP connection is unauthenticated; use the connected tool and
handle any authentication error it returns.

If no Clay interface is available, ask the user to connect Clay through their
client’s connector settings or choose CLI access via `cli-setup`. Do not install
or authenticate the CLI merely because a connected MCP tool returns an error.

When using connected tools, match operations by their descriptions and input
schemas rather than mechanically converting CLI commands. Tool names may have a
connector prefix. Pass structured arguments and reuse returned IDs directly.
Preserve the domain skills' planning, credit approval, and execution requirements.

For onboarding, use the connected `whoami`, `onboard_options`, and `onboard_select`
operations, passing the returned option ID to selection. Follow the shared
`onboard` skill's eligibility and starter-task flow, but skip its terminal banner
step when using connected tools in ChatGPT. Do not install the CLI, probe terminal
width, or run shell commands there; use the host's Clay connection flow if
authentication fails.

The skills' local-file and shell examples apply to CLI sessions. In ChatGPT, use
uploaded files or pasted records instead. For search query guidance, start with the
`searches` skill. Its documented simple patterns do not require a full reference read.
When it routes to `searches-advanced`, read the connected
`searches_query_mode_reference` operation's returned `reference` text as directed there.
If an operation or required reference section is unavailable, explain what is
missing rather than guessing or switching transports.

### CLI readiness

Only when no Clay MCP tools are connected, or the user chooses the CLI: before the
first CLI task in Claude Code, Codex, Cursor, or Cowork, follow any session-start
readiness message. Resolve `<PLUGIN_ROOT>` as two levels above this skill’s directory.
If no hook message was available, run `bash "<PLUGIN_ROOT>/scripts/check-cli.sh" plain`
from this plugin copy. Follow `cli-setup` if it reports a missing, old, or
plugin-managed CLI; do not reinstall or check for latest releases on every command.
Skip this in managed Clay sessions.

## How to work

Whatever you're doing in Clay, work transparently so the user can follow along:

- **Read the relevant skill before responding.** This file is an index, not the full
  guidance. Follow its links and read the relevant skill and appli

Preview of the first 4,000 characters. Read full instructions →

clay-docs6.9 KB

View saved version →

---
name: clay-docs
allowed-tools: WebFetch(domain:www.clay.com), WebFetch(domain:university.clay.com), WebFetch(domain:trust.clay.com), WebFetch(domain:developers.clay.com)
description: Use when the user asks a Clay product question — how a feature works, whether Clay supports or integrates with something, what plans include, security/compliance, or what's new — and the answer isn't operational guidance another skill owns. Answer from Clay's live public documentation, fetched and cited, never from memory.
---

# Clay product documentation

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Clay's public documentation is the source of truth for product questions. Your training
data about Clay is stale and incomplete: features ship weekly, integrations are added
and renamed, and plans change. Answering a Clay product question from memory risks
telling the user something that is no longer true, or denying something that now exists.

**The rule: fetch a live doc page, answer from what it says, and cite its URL.** If you
cannot find the answer in the docs, say so plainly — "I couldn't find this documented".
Never fill the gap by guessing.

## Not this skill

- **Doing things** (run a search, query a table, build a workflow) — use the area skill
  (`searches`, `tables-cli`, `workflows`, …). This skill answers questions, it does not
  operate Clay.
- **Live workspace state** — credit balances, quotas, plan limits in effect for this
  workspace: use `credits-quotas-plans`. This skill covers what plans and pricing _are_
  publicly, not what this workspace has.
- **Upgrading or changing a plan** — use `credits-quotas-plans` for the workspace’s
  direct plan-selector link, including when the user still has credits.
- **API and CLI reference** — endpoints, schemas, flags: the `public-api` and `cli`
  skills point at <https://developers.clay.com/llms.txt>.
- **Something looks broken** — use `clay-feedback`.

## Docs map

Start from the most specific hub that matches the question:

| Question is about                                                            | Fetch                                                                         |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| How a feature works (find, enrich, transform, scraping, AI, export, signals) | <https://university.clay.com/docs> — the product docs hub, organized by topic |
| Whether Clay integrates with a specific tool                                 | <https://www.clay.com/integrations> — the catalog; tool pages hang off it     |
| Plans and pricing                                                            | <https://www.clay.com/pricing>                                                |
| Common product questions                                                     | <https://www.clay.com/faq>                                                    |
| GTM tactics and playbooks built on Clay                                      | <https://www.clay.com/claybooks>                                              |
| Prebuilt table templates                                                     | <https://www.clay.com/templates>                                              |
| What a GTM term means                                                        | <https://www.clay.com/glossary>                                               |
| What shipped recently                                                        | <https://www.clay.com/changelog>                                              |
| Security, compliance, subprocessors                                          | <https://trust.clay.com>                                                      |
| Structured learning (courses, lessons, certifications)                       | <https://university.clay.com/courses>                                   

Preview of the first 4,000 characters. Read full instructions →

clay-feedback3.3 KB

View saved version →

---
name: clay-feedback
description: Clay feedback — send a bug report or product feedback to the Clay team via the `clay feedback` CLI.
allowed-tools: AskUserQuestion
---

# Clay Feedback

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Send feedback or a bug report to the Clay team using `clay feedback`. It reads the message from **stdin** and automatically attaches environment details.

The CLI does no confirmation of its own, so confirm with the user before sending.

Feedback is one-way: it lands in the Clay team's triage queue and nobody replies. When the
user wants a human who responds — they explicitly ask for support, or the matter needs staff
action (a disputed or duplicate charge, a refund, account recovery) — use `clay support`
instead (see the `clay` skill's "Getting help and reporting problems"). Product feedback
_about_ billing or plans (confusing UX, a feature request) is still feedback and belongs here.

## Steps

1. **Determine type.** The test is: did Clay fail, or behave differently from how it is documented or built to work? First occurrences count, and you do not need to know whether it worked before.
   - Choose `bug` for: errors, crashes, timeouts or hangs; failures on valid input; wrong, empty, stale or duplicated output; output that contradicts the docs or `--help`; data lost or changed unexpectedly; documented features that do not work.
   - Choose `feedback` only when Clay worked as designed and the user wants something different: feature requests, capabilities Clay does not claim to have, UX or naming suggestions, working-but-confusing flows, general ideas.
   - Tiebreaker: if the user saw an error or unexpected result while doing something Clay supports, use `bug`; if it is still ambiguous, use `bug` without asking.

2. **Get feedback text.** Use the argument if provided (e.g. `/clay-feedback would love CSV export from the enrichment table`). Otherwise ask the user what feedback or bug report they'd like to send. For a bug, include the command that was run, the error output, and expected versus actual behavior in the message.

3. **Confirm.** Use your ask-user tool (`AskUserQuestion`; `askUser` inside the Clay app). List what the report will include, and offer "Send" / "Cancel":

   > This report will include:
   >
   > - Type: {bug or feedback}
   > - Your feedback: {feedback text}
   > - Environment info (auto-collected)
   >
   > Send this feedback?

4. **If confirmed**, send the message on stdin. The CLI reads the feedback from stdin. Do **not** pass it inline in the shell command (no heredoc, no `echo`): the feedback is arbitrary user text, and a here-doc delimiter or quote appearing in it would truncate or mis-parse the message — or let pasted text run as shell. Instead, write the text to a temp file with your file-writing tool (which never goes through the shell), then redirect that file into the command. Always pass `--type bug` or `--type feedback` from step 1.
   - Write the feedback text verbatim to a temp file with an unpredictable name (a shared
     fixed path lets other local sessions read or clobber it), e.g. `/tmp/clay-feedback-<random>.txt`.
   - Then run:

   ```bash
   clay feedback --type <bug|feedback> < /tmp/clay-feedback-<random>.txt
   rm -f /tmp/clay-feedback-<random>.txt
   ```
cli4.79 KB

View saved version →

---
name: cli
description: Clay CLI — the primary scripting surface (JSON output, typed errors). Use when running or discovering `clay` commands. For what Clay can do and which skill to use, read the `clay` skill when it is available; otherwise run `clay --help`. Use `clay --help` for command names, flags, JSON shape, and error codes.
---

# The `clay` CLI

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

The `clay` CLI provides command-line access optimized for agents: JSON
output and typed error codes. For tool access or authentication problems, read the `clay` entry skill before continuing. The workspace is resolved from
the stored session — there is no workspace id to pass.

## Use workspace context internally

Once the CLI knows which workspace a credential is for, every successful command's JSON
carries a `workspace: { id, name }` key naming the workspace it authenticated as. Use this
information internally. Only mention authentication, the user, or the workspace when the
user asks or an actual account/workspace issue needs their attention. Running the first
command, receiving identity in a result, or loading this skill later in a conversation
does not call for an identity announcement. This applies to managed and standalone CLI
sessions. Don't ask the user for workspace information merely because the key is absent — it is
absent when a command never had to resolve the workspace, and when its result is a top-level
JSON array with nowhere to put it.

A browser sign-in covers every workspace the user selects on the consent screen, and leaves
the first one selected active; `clay login --device` covers one workspace per run. Either way
the workspaces already signed in are kept, so `clay login` again adds more rather than
replacing them. `clay workspaces list` shows the ids and `clay workspaces switch <id>` moves
between them, so switch explicitly to work in one the sign-in did not leave active. When a
payload carries no workspace key and you need to know, `clay workspaces current` answers
directly. Inside a managed Clay session none of this applies: the session runs in the one
workspace it was created in, and `clay login` / `clay logout` / `clay workspaces` are
unavailable there. Never ask the user to sign in — but if they ask to work in a different
workspace, tell them to switch workspaces in Clay and start a new chat there, since this
session cannot move.

## Discovering commands

When a user asks what they can do with Clay, use the `clay` skill when it is available — that is the table of
contents for product surfaces. This skill is how to invoke the CLI.

`clay --help` is the live list of top-level commands. The help text is a machine-readable
spec: use it for command names, flags, JSON output shape, and error codes. Do not treat
it as the answer to "what can I do with Clay?"

```bash
clay --help                 # top-level commands
clay <group> --help         # a group's subcommands
clay <group> <cmd> --help   # exact flags, JSON output shape, and error codes
```

## Prefer simple, single commands

Prefer running one plain `clay` command at a time. Avoid redirecting or
substituting (`&&`, `||`, `>`, `$(…)`, backticks, `$VAR`, etc.) unless it's genuinely
necessary — those forms fall through to a manual approval prompt, whereas a simple
`clay <group> <cmd>` call is auto-approved.

Piping (`|`) is fine when the other stages are common read-only helpers like `jq` that
transform stdin without opening files. Semicolon chaining (`;`) is narrower: each
clause must be `clay`, or a literal `echo` / `printf` (not `cat` / `jq` / …). Anything
else falls through to a prompt.

## When a command needs approval

Some commands that delete, send or run things at scale can answer `approval_required`
instead of running. Nothing has happened yet: tell the user what the request would do (from
the error's `details`) and let them decide. `clay approvals approve <requestId>

Preview of the first 4,000 characters. Read full instructions →

cli-setup8.58 KB

View saved version →

---
name: cli-setup
description: Clay CLI setup — install, repair, and authenticate the Clay command-line interface. Use when the user requests CLI setup or the clay entry skill selects CLI access and requires setup. Do not trigger solely because the clay executable is missing; consult the clay entry skill to choose the access method first.
allowed-tools: Bash(clay --version), Bash(clay whoami), Bash(echo "exit_code=$?"), Bash(clay login), Bash(clay login --device), Bash(npm list --global --depth=0), Read
---

# Clay CLI setup

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

## 0. Check whether the task needs CLI setup

Continue with this skill when the user asks to install or sign into the CLI,
asks to fix plugin registration (for example, a Cursor plugin that never appears), or
the task uses the CLI. Honor the user's choice of CLI even when Clay MCP tools are
connected. First check your available tools for Clay MCP tools. When they are
connected and the user hasn't asked for the CLI, stop and return to the skill you came
from. When they are connected and the user asked to run operations with the CLI but not
to install or sign in to it, ask before installing or signing in: CLI sign-in needs the
user to approve it in a browser, and the connected tools can run the same operations
now. A missing, outdated, or signed-out `clay` executable does not affect the MCP
session.

Install the CLI independently of the plugin, then check authentication. The same flow
applies to Claude Code, Codex, Cursor, and Cowork. Keep existing credentials and the
user's installation method when upgrading.

## 1. Check current state

Resolve `<PLUGIN_ROOT>` as two levels above this skill's directory. Use that exact
plugin copy, not whichever older cache directory was most recently modified.

```bash
bash "<PLUGIN_ROOT>/scripts/check-cli.sh" plain
cat "<PLUGIN_ROOT>/cli-min-version"
```

The check is local and does not sign in or download anything. A missing, old, or
plugin-managed CLI needs step 3, even if an old cached launcher still works. The
metadata is a minimum supported version, not an exact pin: leave a newer independent
CLI installed. If the check prints nothing, the installed CLI is compatible; proceed
to the authentication check below.

For a reported Cursor plugin registration problem, do step 2 even when the CLI works.

## 2. Cursor only: resolve which plugin install path applies

Skip this section unless installing the plugin into Cursor or investigating a plugin
that never appears in Settings → Plugins. Read `cursor-install.md` in this directory
and follow its policy checks before choosing marketplace import or local sideload.
A working CLI alone does not prove that Cursor loaded the plugin. If policy blocks
installation, follow that guide's admin handoff; do not bypass the policy.

## 3. Install or migrate the CLI

```bash
bash "<PLUGIN_ROOT>/scripts/install-cli.sh" --version "$(cat "<PLUGIN_ROOT>/cli-min-version")"
```

For a missing CLI or a recognized old plugin forwarder, this installs a native
macOS/Linux executable at `~/.local/bin/clay`, verifying its checksum and version.
For an existing native CLI below the minimum, it invokes that executable's `update`
command instead of reinstalling it. It checks `~/.local/bin/clay` even when that
directory is outside PATH and preserves compatible or newer versions. An existing
npm install keeps using npm. It never changes credentials.

If the user's organization requires Node-based execution, or the user explicitly
chooses npm, use this alternative (requires Node 22.21+ within Node 22 and npm):

```bash
bash "<PLUGIN_ROOT>/scripts/install-cli.sh" --method npm --version "$(cat "<PLUGIN_ROOT>/cli-min-version")"
```

Do not silently switch methods after a failed download or checksum check. If a native
binary is blocked by enterprise allowlisting, explain that the Node-based install is
available and use it when the user cho

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

credits-quotas-plans6.75 KB

View saved version →

---
name: credits-quotas-plans
description: Use when the user asks how to upgrade or change their Clay plan, where to manage billing, or about credits, quotas, or plan limits — including upgrade requests when credits remain. Provides the workspace’s direct plan-selector link and handles data-credit balances, action-execution balances, search caps, period quotas, and verified spending limits before paid work.
---

# Credits, quotas, and plans

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Follow the shared cost policy in `workflows-discover-actions/cost-and-budget.md`. Check headroom internally before paid work;
do not announce balances or suggest purchases just because a tool returned billing data.
Stop and explain a verified shortfall rather than knowingly starting a partial run.
An unknown cost does not establish a shortfall or require a cost-only approval.

## Upgrade or change plan

When the user asks how to upgrade, give their workspace’s plan-selector link below,
even when credits remain. Do not require a shortfall or recommend waiting because of
the remaining balance. Product documentation can supplement the answer, but must not
replace the direct upgrade link with a docs link or general settings directions.

## Triage

After checking what remains (below), route by what is short:

- **`balance` short** — CLI top-up or billing UI (`addCredits`). Prefer auto top-up.
- **`actionExecutionBalance` short** (when the field is present) — plan selector only.
  There is no top-up for action executions. Do not offer `once`, `auto`, or
  `addCredits`.
- **`user.balance` short** (when `user.limit` is not null) — the
  user's personal monthly credit limit. A top-up does not raise it; a workspace admin
  does, from the MCP page in Clay. It applies only to runs billed to the user, so
  mention it as a possible blocker rather than refusing the run on it alone.
- **Search `quota_exceeded` or period cap exhausted** — plan selector and/or wait for
  the named reset in the error message. Defer shrink/retry rules to the `search`
  skill; do not invent a top-up path for result caps.

Plan selector URL (upgrade or change plan):

```bash
clay whoami | jq -r '.workspace.id'
```

`https://app.clay.com/workspaces/<workspaceId>/billing/plan-selector`

## Check what remains

```bash
clay credits balance | jq '{ balance, actionExecutionBalance, user }'
```

`balance` is the data-credit pool. `actionExecutionBalance` is optional — present
only on action-execution pricing plans; omit or ignore it when the field is null
or absent (legacy billing). Plenty of one does not cover the other.

For routine runs, `clay routines get <id>` includes per-item cost estimates.
When the estimate applies to the configured execution and its counts are known, multiply
each cost by the number of items and compare against the matching balance. See the
`routines` skill for estimate limitations and the stop-before-partial-run rule.

`user` identifies the user (`id`, `name`, `email`) and carries their personal monthly
credit `limit` and remaining `balance`, both null when they have no personal limit. That limit can also stop a run billed to the user while
workspace credits remain. These fields are not a complete capacity check: a credit budget
assigned to the user can also stop a run, and this command does not report it.

Read `clay credits balance --help` for field semantics.

## CLI top-up

Applies to data-credit `balance` only — not `actionExecutionBalance`.

**Prefer auto top-up.** Lead with enabling (or confirming) auto so the workspace
stays funded without another interrupt. Only offer a one-time purchase if the
user pushes back against auto, or if auto is unavailable.

Read `clay credits top-up <subcommand> --help` for the exact JSON output shape,
flags, and examples; that help is the contract.

```bash
clay credits top-up auto get
clay credits top-up auto enable --threshold <n> --credits <n> 

Preview of the first 4,000 characters. Read full instructions →

onboard6.63 KB

View saved version →

---
name: onboard
description: Clay first-run onboarding — banner, what Clay can do, and starter tasks served by the Clay API. Run this right after a sign-in that just happened — from `clay login` directly, or invoked by the CLI setup skill after its sign-in step. It checks server-side whether this user has been onboarded and stands down if so. Assumes the CLI is already signed in; for access or authentication problems, consult the clay entry skill first.
allowed-tools: Bash(clay whoami), Bash(command -v jq), Bash(printf '%s\n' "${COLUMNS:-0}"), Read
---

# Clay onboarding

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Before continuing, read the `clay` entry skill and follow its access guidance.

Give a brand-new user a fast first win. Whether this user has already been
onboarded is tracked server-side, per user: `clay login` and `clay whoami`
report it as `onboarded`, and fetching the starter-task options marks them as
onboarded. There is nothing to record locally.

**This skill runs signed-in.** For access or authentication problems, consult the
`clay` entry skill before continuing. If CLI access uses an absolute executable
path, use that path in the examples below.

**The user's own request always wins.** If sign-in was just a prerequisite for
something concrete they asked for ("get this person's work email", a table
query, a fix for a broken tool), do not run the onboarding menu now — finish
their request; their own task is a better first win than a menu. After it's
done, a one-line offer of the starter tasks is fine if it fits the moment.
Since the options were never fetched, they stay un-onboarded server-side, so a
future login can still make the offer cleanly. Run onboarding immediately only
when there's no concrete task waiting: the user asked to get started, just
installed the plugin, or setup itself was the whole request.

Keep your own prose short — the banner and the starter tasks are the show. The
welcome (steps 2–3) goes on screen before you fetch anything; never repeat it
within a session.

## 1. Check that onboarding applies

If the sign-in that brought you here already reported `onboarded: false`, skip
this check and continue. Otherwise read the field yourself:

```bash
clay whoami
```

- **`onboarded: false`** — continue to step 2.
- **`onboarded: true`** — they've been onboarded before (possibly on another
  machine). Stand down: skip the rest of this skill without ceremony. If the
  banner already went up (the Claude Code hook shows it at invocation), a
  one-line welcome back is enough — no pitch, no menu.
- **The field is absent** — do not infer onboarding status. Consult the `clay` entry
  skill if access needs repair; otherwise stand down.

## 2. Show the banner

On Claude Code, when this skill was invoked through the Skill tool **and**
`command -v jq` succeeds, skip this step: a plugin hook displays the banner
automatically at that invocation (it needs `jq` to do so) — never print it
yourself; the step-3 pitch still opens your reply. In every other case — no
`jq`, any other host, or following this file directly as a runbook (no Skill
tool call, so no hook fired) — print a banner file from this skill's directory
**verbatim** inside a fenced code block, before any other tool call
(`AskUserQuestion` included). Pick the file by terminal width: run
`printf '%s\n' "${COLUMNS:-0}"` and use `banner.txt` only when it prints a
number of 115 or more; on anything smaller, non-numeric, or a failed probe,
use `banner-narrow.txt` — it fits every host. Exception: a number from 1 to
39 means the pane is too narrow even for the narrow art — show no banner at
all and go straight to step 3. Do not redraw, trim, or restyle
the art. Reading the file is not showing it: the banner must appear in your
reply to the user.

## 3. Say what Clay is

Position it as Clay's product and theirs to run ("Clay lets you…", "you can…"),
not as your own abilities. 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

public-api1.79 KB

View saved version →

---
name: public-api
description: 'Clay Public API — HTTP access for building services, apps, and integrations: GTM database search, structured table queries, and async routine and batch runs.'
---

# The Clay Public API

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Beyond the CLI, Clay exposes a Public API you can develop against directly over HTTP.
Reach for it when building a service, app, or integration — not for one-off agent tasks
(use the `clay` entry skill to select access and the relevant domain skill).

## What it offers

- **Search** — find people or companies in Clay's GTM database with **advanced queries**:
  criteria from the fields catalog, cross-entity filters, and nested Boolean logic.
  Use the `searches` skill for one-off searches and search behavior.
- **Tables** — structured queries against Clay tables.
- **Routines / batches** — async routine and batch runs.

## Auth

The public API needs its **own** key — the credential from `clay login` is **not**
scoped for it. Issue a dedicated public-API key with the CLI:

```bash
clay api-keys create --name "<name>"   # → { ..., "apiKey": "<secret>" }
```

CLI-created keys are always scoped to the public API. The `apiKey` secret is returned
**only once**, at creation — store it immediately; it can't be retrieved later. Send it
as a Bearer token against `https://api.clay.com/public/v0`. Manage existing keys with
`clay api-keys list | update | delete`.

## Reference

Full developer documentation — Public API reference, CLI reference, concepts, and the
OpenAPI spec — lives at:

- <https://developers.clay.com/llms.txt>

Fetch that first to get exact endpoints, request/response shapes, pagination, and rate
limits before writing integration code.
routines12.7 KB

View saved version →

---
name: routines
description: Clay routines — create a routine from an existing function/workflow, then run a saved routine that exists in this workspace. Use when the user asks to create/register a routine, or to run, execute, or trigger a function, workflow, or routine (by name or id), pass it inputs, or check the results/status of a run. For building a new workflow, use the workflows entry-point skill instead.
---

# Running Clay routines

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

A **routine** is the runnable unit in Clay: a saved **function** or **workflow** that
already exists in this workspace. This skill is about _running_ an existing routine and
getting its results — not building one.

- To **build or edit** a workflow, use the workflows entry-point skill.
- If no existing routine matches a request for custom Claygent or LLM work, use the
  `/workflows-claygent` skill to build and run it.
- To **query data** out of a Clay table, use the tables entry-point skill.
- To **find the records** to run a routine over, use the `searches` skill for net-new people
  or companies, or the `audiences` skill for members of a saved audience, then feed the
  results in here.
- To **write people or companies into Audiences**, run a routine whose underlying
  workflow contains `upsert-audiences-record` (for example, to persist Search results).
  Items pipe in the same as other runs, using `workflow:<id>` instead of `function:<id>`.
  If no such workflow exists, build it via the `workflows` skill's
  `audiences.md`, then `clay routines create workflow`.
- To run a routine **over HTTP** from a service or app (not a one-off shell task), use
  the `public-api` skill.

Routines run **asynchronously**: you start a run, then poll for results.

## 1. Find the routine

Don't assume a routine id. List what exists and match the user's request to one:

```bash
clay routines list            # routines in this workspace
clay routines get <id>        # full config and input schema
```

`clay routines list` is **paginated** — a workspace can have far more routines than one
page. Page through with `--cursor` until the response has no `cursor` before concluding a
routine doesn't exist. Each routine carries a `source` field in the response — `list` has no
filter flag, so filter client-side (e.g. `| jq '.data | map(select(.source == "managed"))'`).
`managed` routines are Clay's built-in enrichers
(emails, domains, firmographics) and should be your first choice for standard enrichment;
`custom` are workspace-built. Decide by **input schema**, not name — e.g. the managed
**Work Email** routine needs Full Name + Company Name + Company Domain, so resolve the
domain first with the managed **Company Domain** routine when you only have a company name.

`clay routines get <id>` is important before running: it shows the routine's **input
schema** so you know exactly which fields each item needs.

### Link the user to the underlying function or workflow

Whenever you show the user a routine — from `clay routines list` or `clay routines get` —
give them a link to open its underlying object in the Clay app so they can inspect or edit
it. This matters most in a headless environment (Claude Code, Cursor, a shell) where the
user has no Clay tab open.

A routine id encodes the object it wraps: `function:<tableId>` wraps a table,
`workflow:<workflowId>` wraps a workflow. Split off the id after the `:` and combine it
with the workspace id (`clay whoami | jq -r '.workspace.id'`) to build the link:

- **Function** (`function:<tableId>`) → `https://app.clay.com/workspaces/<workspaceId>/tables/<tableId>`
- **Workflow** (`workflow:<workflowId>`) → `https://app.clay.com/workspaces/<workspaceId>/terracotta/tc-workflows/<workflowId>`

For **function** routines, both `list` and `get` return a `source` (`managed` for a
Clay-managed default function, `custom` for one built in this workspace) and, for cu

Preview of the first 4,000 characters. Read full instructions →

schedules17.6 KB

View saved version →

---
name: schedules
description: 'Clay agent schedules — recurring prompts the Clay agent runs on a cadence, each occurrence starting a fresh agent task. Use for recurring work that needs the agent''s reasoning on every run: a daily digest, a weekly report, checking or changing when a scheduled run happens next, pausing or deleting one. Running a workflow on a schedule is a scheduled trigger on that workflow (the workflows skill), not an agent schedule.'
---

# Clay agent schedules

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

A schedule runs the Clay agent on a cadence. Each occurrence starts a **fresh
agent task** with the schedule's `prompt` as its first message, run as the
schedule's creator. Nothing carries over between occurrences — no conversation,
no working files — so a schedule prompt must stand alone: name the audience,
table, or workflow it works on explicitly, and say what the output should be.

## Schedule or scheduled workflow?

Schedules are for recurring work that needs reasoning. Decide before creating one:

- **Scheduling a workflow** — the one open on screen, one you built or edited in this
  conversation, or one the user names — is a scheduled trigger on that workflow, published (see
  `/workflows`), not a schedule. Pausing, resuming, or changing it later is
  `clay workflows triggers update`, not `clay schedules`.
- **Fixed steps** — finding leads, enriching, qualifying, routing, writing back — go in a
  workflow on a scheduled trigger, not a schedule. Per-record judgment is an agent node in that
  workflow. "Find me 100 leads every 2 weeks and qualify them" is a workflow on a biweekly
  schedule with a qualification node.
- **Reasoning about each run's results** — analysing them, deciding what to do next, tracking a
  goal, a digest that interprets what changed — needs a schedule. If it wraps fixed steps, keep
  those in a workflow with no schedule of its own and have the schedule's prompt start it by
  workflow id, plus trigger id for a source trigger. Scheduling both runs the work twice.

Schedules run at most daily; workflows can run every minute. If it is unclear whether runs need
judgment, ask the user rather than defaulting to either.

"The schedule" can mean a schedule or a workflow's scheduled trigger. When a request to pause,
change, or delete one could mean either, as in a scheduled task whose workflow also runs on a
schedule, ask which one the user means before changing anything.

## The commands

```bash
clay schedules create --input '{...}'      # create; starts active with nextRunAt computed
clay schedules list                        # the schedules you created, status, cadence, next run
clay schedules update <scheduleId> --input '{...}'  # partial update; also pause/resume via status
clay schedules delete <scheduleId>         # remove it and every run it produced
```

Read `clay schedules <subcommand> --help` for the exact input and output
shapes; they are the contract.

## Writing the prompt

The `prompt` is the entire brief every occurrence gets. Write it as exactly three
short sections, in this order:

- **Objective** — one sentence: the ongoing job this schedule exists to do.
- **Goal** — the measurable end state, and any hard limits (spend, volume). When the
  goal can be measured from workspace data, state it in those terms and name the
  measure — the audience id, filter, or activity types a run should count (see
  "Measuring the goal") — so a run can tell from the reading alone whether it is done.
- **Instructions** — a short numbered list of what one occurrence does, naming every
  audience, field, and workflow by id (a fresh task cannot infer them).

Write the Instructions for the **minimum work that makes progress toward the goal**,
not for finishing it in one run. When the Goal names a measure, the first step is
taking it; the reading then decides the rest — a goal at its target means skip that
work e

Preview of the first 4,000 characters. Read full instructions →

searches5.2 KB

View saved version →

---
name: searches
description: Use to find net-new people/companies by employer, name or title, refine criteria and page results. Other filters route to searches-advanced.
allowed-tools: Read, Grep
---

# Clay search

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Search finds net-new people/companies; use `audiences` for workspace records.

## Simple queries

Outside Sculptor's Search panel, use these patterns without the full reference when they
capture **every** criterion. In that panel, read its required DSL reference before querying.
Preserve lists/exclusions; add no unrequested filters. Otherwise read **`searches-advanced`
before querying**: geography/metro/HQ versus offices, industry, growth, size, similarity,
employer history, hiring, audiences, education, counts, per-company limits or unknown
fields. It routes to the full runtime reference. Never drop criteria to avoid it.

Syntax: `select from people|companies where <predicate>`. Double-quote strings;
parenthesize lists. `and` binds tighter than `or`; group alternatives. Text matching is
case-insensitive; `contains` matches tokens, not substrings. Omit the DSL `limit` unless
the user explicitly caps the total across all pages, so "show me more" can continue the
same search. For ordinary requested counts, use the executing tool's page-size `limit`
within its allowed maximum; fetch additional pages only as needed.
Translate ordinary terms to English; preserve proper names/IDs.

**Current employer + role:**

```text
select from people where clay.filter_to_companies(("stripe.com")) and experiences.any(is_current = true and job_title is_similar_to ("software engineer"))
```

Use supplied identifiers or confidently known household-name domains. The company
function belongs at the root. Keep title/seniority in **one current experience**;
neither is a people-root field.
For an uncertain employer name, replace the identifier function with
`company_name contains "Name"` inside that same experience; never guess a domain.

Person names use root-level `full_name contains "Person Name"`; no first/last-name fields.

Titles default to `job_title is_similar_to ("role")`; use only user-supplied roles,
not invented synonyms. Exact titles use `=` or `in (...)`; literal keyword requests
use `contains`, keeping exclusions with `not`. Lists mean OR; required co-occurring
words need AND. Quote full phrases. Keep title predicates inside experience.

Only filter seniority when requested: senior individual contributors use
`seniority = "Senior"`, not leadership. Complete experience values: `Founder`, `Owner`,
`Board Member`, `Partner`, `C-suite`, `VP`, `Director`, `Head`, `Manager`, `Senior`,
`Mid-level`, `Entry`, `Intern / In Training`, `Unknown`. Use `=`, `!=`, `in`, `not_in`;
leadership tiers require leadership intent. Not job-posting values.

**Specific companies:** one inclusion call, all supplied identifiers (at most 1,000):

```text
select from companies where clay.include_company_identifiers(("stripe.com", "https://www.linkedin.com/company/notionhq/"))
```

Do not substitute `domain =`, guess domains or fabricate LinkedIn slugs. Ambiguous
company names and "companies like X" require advanced identification guidance.

## Execute and page

Use the access method selected by `clay`. Discover operation schemas;
CLI equivalents are `clay searches query-mode create --query '<query>'`, then
`clay searches query-mode run <searchId> [--limit <n>]`. Create returns `searchId`, not
records; run returns `data`, `hasMore` and optional `periodQuota`.

**Forward-only iterator:** reuse its ID for the next page; no replayable cursor.
Page size is separate from total limit.
Read only enough pages to satisfy the current request; for an unspecified count, show
one page. On "show more", advance only when `hasMore` is true. Check quota before each
page and stop near exhaustion unless the user confirms continuation. Changed criteria
r

Preview of the first 4,000 characters. Read full instructions →

searches-advanced13 KB

View saved version →

---
name: searches-advanced
description: Use for advanced Clay people/company searches involving geography, industry, growth, employer history, audiences, relationships, counts or fields beyond the searches starter, and for query validation or quota errors.
allowed-tools: Read, Grep
---

# Advanced Clay search

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Search Clay's GTM database with advanced queries and return matching records — people or
companies.

**Audiences** is the workspace's own people and companies — read and segment what they already have.
**Search** is Clay's GTM database for net-new lists. This is not the tables entry-point skill (querying
data already in a table) and not the workflows entry-point skill (automations). Reach for Search when the
user wants to _find_ prospects or accounts not in the workspace yet.

## How it works

A search is a three-step, forward-only iterator:

1. **Discover** the query grammar and queryable fields.
2. **Create** the search and receive a `searchId`.
3. **Run** it to pull the next page of records. Repeat while `hasMore`
   is `true`.

There is no cursor: the iterator's position lives server-side and can't be replayed, so
each `run` call returns the records after the previous one.

Before authoring a query, fetch only the reference sections the query needs, once per
conversation. Start with `grammar`, `rules`, and the field catalog for your entity:

```bash
clay searches query-mode reference --sections grammar,rules,people-fields | jq -r '.reference'
```

| Section                 | Fetch when                                                                                                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `grammar`, `rules`      | Before you write the first query in a conversation: syntax, scopes, functions, and query policies. Skip them on later fetches.                                                             |
| `people-fields`         | The search returns people.                                                                                                                                                                 |
| `company-fields`        | The search returns companies, or a people search filters on employer attributes (`company.*` inside `experiences.any(...)`). It is the largest section, so skip it when you don't need it. |
| `company-people-fields` | A companies search filters on its employees. It lists only what differs from `people-fields`; add `people-fields` too only if you need the shared fields and their allowed values.         |
| `job-fields`            | The query filters on hiring.                                                                                                                                                               |
| `examples`              | You want worked queries.                                                                                                                                                                   |
| `workspace-resources`   | The query references audiences or tables.                                                                                                                                                  |

Every field name and allowed enum value is in the field catalogs; a value that is not listed
fails validation. Request the fewest sections that cover the query and make a second call if
you find you need another. Sections come back in a fixed order, and an unknown name fails with `validation_error`.

If you do need every section, omit `--sections`. It is too large for one tool result, so
save it to a file and never print it to stdout:

Preview of the first 4,000 characters. Read full instructions →

sequences27.3 KB

View saved version →

---
name: sequences
description: Inspect, create, compare, analyze, and edit Clay sequences (formerly campaigns) in Sequencer through the clay CLI. Use when the user asks about Clay sequences, Sequencer, or Clay campaigns.
---

# Clay Sequencer assistant

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Sequencer was formerly called Campaigns, and each sequence was called a campaign. Users may still use the old names; route those requests to this skill and `clay sequences`. A sequence's steps are the ordered emails it sends, and each variant has its own steps.

Help users understand and improve sequences in their current Clay workspace. You may compare reads across sequences. Use the target-selection workflow before every mutation of an existing sequence.

## Supported commands

- `clay sequences list [--search <name>] [--filter status=<status>] [--with-analytics]`
- `clay sequences create --name <name>`
- `clay sequences get <sequence-id>`
- `clay sequences context resolve <sequence-id> [--query <drafting-focus>]`
- `clay sequences analytics <sequence-id> [--start-date <date>] [--end-date <date>] [--timezone <iana>]`
- `clay sequences audience <sequence-id>`
- `clay audiences list --entity-type people [--cursor <cursor>]`
- `clay sequences options sender-accounts`
- `clay sequences options skills`
- `clay sequences options business-context`
- `clay sequences options files`
- `clay sequences update <sequence-id> --input <json-or-file>`
- `clay sequences launch <sequence-id>` (only when `clay sequences --help` lists it)
- `clay sequences pause <sequence-id>` (only when `clay sequences --help` lists it)
- `clay sequences resume <sequence-id>` (only when `clay sequences --help` lists it)
- `clay sequences update-claygent <sequence-id> --input <json-or-file>`
- `clay sequences steps edit <sequence-id> --input <json-or-file>`
- `clay sequences steps spam-check <sequence-id> --variant-id <variant-id>`
- `clay sequences variants start-test <sequence-id>`
- `clay sequences variants end-test <sequence-id> --keep-variant-id <variant-id>`
- `clay sequences variants rename <sequence-id> --variant-id <variant-id> --name <name>`
- `clay sequences variants preview-sequence <sequence-id> --variant-id <id> [--lead-index <index>]`
- `clay sequences variants send-test <sequence-id> --variant-id <id> --sequence-step-index <index> [--lead-index <index>] --email-account-id <id> --recipient <email>`

Before first using a `sequences` subcommand, read `clay sequences <subcommand> --help` for its input and output schema. Reuse help already read in this conversation. Build inputs and JSON projections from that command’s documented schema, including its response root. All successful commands return JSON on stdout. Errors return structured JSON on stderr with a stable error code and exit category.

## Hard boundaries

You can create sequences. You can launch, pause, or resume a sequence only through `sequences launch`, `sequences pause`, or `sequences resume`, and only when `clay sequences --help` lists that command. You cannot delete or complete a sequence, or replace its provider. Do not claim that you can. For anything you cannot do, explain that the user must make the change in the Sequencer UI.

The `variants end-test` command ends a variant test. It does not complete the sequence.

These boundaries govern Sequencer work. Do not work around them through another CLI group, direct HTTP calls, scripts, or shell utilities. Use only the supported sequence operations above and workspace identity lookup while doing Sequencer work. If the user explicitly asks to create or edit a resource on another Clay surface, follow the applicable loaded skill for that separate work; never mutate another resource merely as an incidental workaround for a Sequencer boundary.

## Creation workflow

1. Get or derive a clear sequence name from the user's request.
2. State the exact new sequence name.
3. 

Preview of the first 4,000 characters. Read full instructions →

sequences-events13.3 KB

View saved version →

---
name: sequences-events
description: Use when the user asks what happened to a lead in a Clay sequence (formerly campaign) — replied, out of office, bounced, unsubscribed, stopped getting emails, needs resuming — or works in the Campaign events table, including how replies and out-of-office count in reply rate, reply categories, rep routing, and automations or workflows built on sequence events.
---

# Sequence events

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Use this to explain, filter, or build on sequence activity: the **Campaign events** table, a column, workflow, or
automation that reads it, or a question such as "why did this lead stop getting emails?". Answer from this skill, not
from general email-sequencing knowledge: Clay configures its email provider in ways that differ from common defaults,
especially for out-of-office replies.

## The Campaign events table

Each workspace has one shared Campaign events table (named Campaign webhook events in older workspaces). Every
sequence writes to it, and each sequence also gets a view named `<sequence name> events` that is filtered to that
sequence. The table keeps only the most recent 10,000 events. Older rows move to the table's read-only archive,
which the user opens with the View archive button at the bottom right of the table. The table and its per-sequence
views therefore show only recent events, and columns, exports, and automations on the table never see archived rows.
For an older sequence's full history, point the user to the archive or the sequence's Activity tab, and use `clay
sequences analytics` for totals.

Events usually appear within a few minutes of happening. Replies from a mailbox the user connected themselves (rather
than one bought in Clay) can be delayed or missing while that mailbox is disconnected.

Each row is one event. The raw payload is in the source column. Managed formula columns extract the common fields:

| Column                 | Payload path                                | Notes                                                                  |
| ---------------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
| `Campaign ID`          | `smartlead.campaign_id`                     | The email provider's campaign id, not the Clay sequence id             |
| `Event type`           | `event_type`                                | One of the types below                                                 |
| `Lead ID`              | `smartlead.lead_id`                         | The email provider's lead id                                           |
| `Audience ID`          | `lead.audience_entity_id`                   | Links to the Audiences contact; `Audience record` looks the contact up |
| `Lead email address`   | `lead.email`, else `recipient.email`        | Always the enrolled lead                                               |
| `Last reply content`   | `reply.html`                                | Only `EMAIL_REPLY`                                                     |
| `Reply category`       | `reply.category_name`, else `category.name` | `EMAIL_REPLY` and `LEAD_CATEGORY_UPDATED`                              |
| `Sender email address` | `sender.email`                              | Direction depends on the event type; see `EMAIL_REPLY`                 |

The default view shows only `EMAIL_SENT`, `EMAIL_REPLY`, `EMAIL_OPEN`, `EMAIL_LINK_CLICK`, `EMAIL_BOUNCE`, and
`CAMPAIGN_STATUS_CHANGED`. Unsubscribes and category updates are still in the table. Remove the view filter or use
a different view to see them.

## Fields on every event

- `event_type`
- `event.description`
- `event.occurred_at`: when the event happened at the provider (for example, the send, open, click, or reply time).
  Use this field for time, not the row's creation time. It can be missing.
- `campaign.name`, `c

Preview of the first 4,000 characters. Read full instructions →

sequences-interview3.03 KB

View saved version →

---
name: sequences-interview
description: Use when a fresh Clay sequence (formerly campaign) has no meaningful subject or body copy and needs its first draft.
---

# Fresh sequence interview

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

If the `sequences` skill is not already loaded, load it before acting. Use it for sequence discovery, context, target selection, commands, and mutation boundaries. Use this skill for the interview and first-draft decisions.

Use this skill whenever a fresh `clay sequences get` shows that the target sequence has no meaningful subject or body copy. It may require no questions. Do not trigger merely because one step is blank in an otherwise authored sequence.

## Gather context first

Before asking the user anything:

- Read the user's request and the relevant conversation.
- Read the sequence goal.
- Resolve AI context, then read the selected skill instructions, My Business Context, and selected reference content that it returns.
- Inspect the configured audience, sequence settings, and every step.

Context resolution and audience inspection are best-effort. Treat unavailable sources as absent, never imply that they were read, and continue from the context gathered successfully unless the user explicitly requires the missing source.

Ask only about an unresolved gap when different answers would materially change the draft, and ask it through the question tool. Do not use a preset questionnaire, question order, grouping, or target count. Do not ask about tone, number of steps, or personalization when the available context supports a credible choice. When there is enough context, state the assumptions that matter and continue without asking. Omit unsupported proof instead of blocking or inventing it.

## Sequence goal

Use the gathered context to assess the sequence goal. Propose a concise goal when the existing goal is empty or materially conflicts with the intended audience, relevant situation, offer, or desired recipient action. Otherwise preserve it. Never replace a non-empty goal unless the user explicitly asks for or accepts the proposed replacement, and continue drafting if the user declines.

After the user accepts a proposed goal:

1. Run `get` again immediately before saving it. If the current goal changed during the conversation, do not overwrite it; reconcile the goals with the user first.
2. If the fresh status is `draft` or `paused`, save the goal to `claygentContext.campaignIntent` with a separate context edit. If it is `active` or `completed`, do not attempt the edit; explain that sequence settings are locked and keep the accepted goal in the conversation.
3. Resolve AI context before drafting the steps. Read the sequence again only when the context-edit response lacks the state needed to report the saved goal or resolve AI context.

Move directly to the draft when the material context is sufficient; a brief summary and approval of the step plan are not required. Never expose sequence, variant, step, segment, or field ids.
sequences-reviewing2.59 KB

View saved version →

---
name: sequences-reviewing
description: Review Clay sequence (formerly campaign) email copy as the intended recipient and identify only material, actionable objections.
---

# Clay sequence reviewing

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

If the `sequences` skill is not already loaded, load it before acting. Use it for sequence discovery, context, target selection, commands, and mutation boundaries. Use this skill for sequence-review decisions.

Use this skill after drafting or revising sequence copy, or when the user asks for a review. The same agent that writes the copy performs the review.

Become the specific intended recipient: busy, skeptical, and triaging the inbox. Read from that person's actual situation, not as a generic copy editor. Center the review on one honest question: “Why wouldn’t I respond?”

## Review order

Review message strategy before copy execution. Determine whether the recipient, situation, problem or opportunity, mechanism, value, offer, and requested response form a credible reason to engage. Then review how clearly and effectively the copy executes that strategy.

Use specificity, credibility, relevance, value exchange, ask size, and spam patterns as lenses rather than a checklist. Raise only concerns that would materially affect the intended recipient. Never invent an objection when the copy is strong.

## Critiques and revisions

Keep each critique concise and self-contained. Identify:

- the exact email or passage targeted;
- the recipient's material concern; and
- the direction of the change that would address it.

For a targeted change, read enough surrounding sequence copy to detect a material contradiction it would introduce or expose. Keep this check scoped; do not turn it into a full-sequence audit. Never change linked copy outside the requested scope. Flag the contradiction and ask the user through the question tool to expand the scope before changing that copy.

When revision is requested, revise only the affected passage and preserve everything else. For review-only work, return the critique without rewriting or mutating the sequence.

## Stop conditions

Stop the review loop when no material copy-fixable concern remains. Also stop when an issue requires missing facts or proof, the choice is a judgment call with no clearly better option, another change would only polish already-effective copy, or the offer or strategy must change before copy can improve.

Put non-copy-fixable concerns under `Unresolved`. Do not rewrite around missing evidence or a strategy problem.
sequences-writing2.43 KB

View saved version →

---
name: sequences-writing
description: Draft and revise the email copy of Clay sequences (formerly campaigns) using the supplied sequence strategy and context.
---

# Clay sequence writing

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

If the `sequences` skill is not already loaded, load it before acting. Use it for sequence discovery, context, target selection, commands, and mutation boundaries. Use this skill for sequence-writing decisions.

Use this skill to draft every step of a sequence or revise sequence copy. Treat the supplied sequence strategy and context as the source of truth.

## Message strategy

Establish the intended recipient and the situation that makes the message relevant. Connect that situation to a specific problem or opportunity, explain the mechanism and value offered, and make the offer and requested response clear.

Give each email one primary purpose and one response path. When a draft is not working, fix the strategy before polishing individual lines. Omit proof that the supplied context does not support. Make every follow-up add a distinct reason to respond rather than restating an earlier message.

## Copy execution

- Use direct language with concrete actors and outcomes.
- Give each sentence one purpose.
- Ground relevance in supplied facts and context rather than generic personalization.
- Remove filler and redundant restatement.
- Choose tone and punctuation for the recipient, situation, and established voice.
- Preserve copy outside the requested revision scope.

## Dynamic copy

- When the language is shared across the audience, use fixed copy.
- When only one known value changes, use a direct lead-field token.
- When bounded lexical variation does not depend on lead facts, use spintax.
- Do not discard useful, supported lead data only because some leads lack it. When worthwhile variation must select, combine, or interpret that data into natural prose, use a short, bounded AI snippet. Do not let missing data produce unsupported copy.
- When meaningful per-lead variation can improve relevance and impact, use it. Treat its support for deliverability as possible, not guaranteed.
- Never use an AI snippet as unfinished fixed copy or for generic variation. Never add one only to clear a personalization warning or meet a quota.
- Give each snippet one role, explicit evidence, and an output bound.
- Prioritize grounding over variation.
signals34.5 KB

View saved version →

---
name: signals
description: 'Clay Signals — watches that detect real-world changes (job changes, new hires, promotions, funding news, job postings, topic intent) and write them as events onto a table or an audience. Use for any request about a workspace''s signals: which ones exist, what one watches or writes to, whether one is running, turning one on or off, and why one is or is not producing events.'
---

# Clay Signals

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

A signal watches a set of records and emits an **event** when something changes
in the real world — someone changes job, a company posts a role or raises a
round. It has two halves, and telling them apart is the first thing to get right.

**Resolve the population before discovery.** For a historical question, use the
request and context to distinguish existing workspace records from net-new
prospects; ask if unclear before exploring either surface. For existing records,
read the `audiences` skill's `queries.md` and query captured events directly.
List triggers when managing watches, not as a prerequisite for historical
queries. An empty trigger inventory or summary field does not establish that
captured events are absent; check history before proposing a new watch.

| Record             | Id prefix | What it is                                           |
| ------------------ | --------- | ---------------------------------------------------- |
| Trigger definition | `td_…`    | The runnable unit: name, run status, filter, output. |
| Signal             | `sig_…`   | The underlying watch that trigger definitions share. |

**`id` in CLI output is the trigger definition (`td_…`), and it is the only id
these commands accept.** `signal.id` is the other record; passing it to
`clay signals get` is a `not_found`. Everything a user calls "a signal" — its
name, whether it is on, what it writes to — lives on the trigger definition.

**Web intent is out of scope.** Read **Current limitations** at the bottom before telling a
user something cannot be done: it lists every gap with what to do instead.

## The commands

```bash
clay signals list                          # every signal in the workspace
clay signals get <triggerDefinitionId>     # one signal, with its filter, schedule, and error
clay signals create --type T --input JSON  # new signal of a supported type
clay signals update <triggerDefinitionId>  # rename, re-schedule, re-filter, change per-type settings
clay signals pause <triggerDefinitionId>   # stop signal running, and stop it spending
clay signals resume <triggerDefinitionId>  # run signal again on its existing schedule
clay signals delete <triggerDefinitionId>  # remove signal but keeping the events it captured
clay signals search-topics --query Q --entity-type person|company  # topicIds for a topic intent signal
```

Excluding web intent makes `list` rows one per signal, so they are safe to count. Narrow
with `jq`:

```bash
clay signals list | jq -r '.data[] | "\(.id)  \(.signal.type)  \(.runStatus)"'
clay signals list | jq '[.data[] | select(.runStatus == "Errored") | .id]'
```

Read `clay signals list --help` and `clay signals get --help` for the exact output
shapes; they are the contract.

`pause` and `resume` return the signal with `runStatus` already updated, so no
confirming call is needed. They write nothing but the status: schedule, filter,
and destination are untouched, and setting a status a signal already has changes
nothing, so a retry after a network failure is safe.

**`create`, `update`, `pause`, and `resume` may answer `approval_required`.** Present the
request for the user's decision rather than retrying; approving applies it. A held
table-watching `create` has already made its destination table, so rerunning it makes another.

**Only an Active or Paused signal can be toggled.** Any other `runStatus` —
`Errored`, `Disabled`, `Testing`, `Preview` — is refused.

**Pa

Preview of the first 4,000 characters. Read full instructions →

tables-analyze6.59 KB

View saved version →

---
name: tables-analyze
description: 'Clay tables — analyze what a table does: reconstruct the column DAG, stage it, and narrate the workflow encoded in its columns. Use when the user asks "what does this table do?", "explain the {table} workflow", "walk me through this table", or "what''s set up here?".'
allowed-tools: Read
---

# Analyze a table

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

**Use when:** "what does this table do?", "explain the {table} workflow", "walk me through this table", "what's set up here?" — a question about the table's **structure and the workflow encoded in its columns**, not about any single record.

A Clay table is a column DAG: `source` and input `basic` columns are roots; `basic` formula columns and `action` (enrichment) columns depend on the `{{f_xxx}}` tokens in their settings. Analyzing the table = reconstructing that graph, ordering it into stages, and narrating what it does. Cheap and read-only: ~3 commands (metadata + columns + a row sample).

**Finding the table:** resolve it as in the tables entry-point skill ("Finding a table").

## 1. Frame the table — `clay tables get`

(The output is discriminated on `type` — shape in `clay tables get --help`.) Read off the frame the workflow sits in:

```bash
clay tables get <tableId> | jq .
```

- `type` — `"archive"` means this is an archive companion (its `parentTableId` points at the regular table); analyze the parent instead, the archive has no workflow of its own.
- `rowCount` — current size.
- `archive` — non-null means processed rows **flow out** to an archive, indexed on `archive.searchableFieldFormula`.

Where data **enters** and at what scale comes from the columns (step 2): `source` columns carry `sources[]` with each attached source's `numSourceRecords`.

## 2. Build the dependency catalog — `clay tables columns get`

This is where the graph lives. Run the token-extraction recipe in the tables entry-point skill's `dependency-catalog.md` over `clay tables columns get <tableId>`. It yields one entry per column — `{ id, name, type, role, integration, gate, dependsOn: [names] }` — resolving every `{{f_xxx}}` edge (including those in `formulaWaterfall` and `formulaMap` keys) to a column name. `dependsOn` are the upstream columns; `gate` (when set) is the condition under which an action runs.

For a known bulk enrichment table, inspect the source entries to determine the origin. If a source includes `audience`, use its `entityType`, `segments[].id`, `isGlobal`, and `entityIdOnly` as the source configuration when rebuilding it as a workflow. `isGlobal: true` represents the global Audience and has no segment resource objects; otherwise use the ids from `segments`. Bulk enrichment tables can have non-Audiences origins, and an `audience-source` on its own does not prove the table is a bulk enrichment table.

## 3. Stage the graph

Order the catalog into stages by dependency depth — roots first, then columns whose deps are all already placed, and so on:

- **Stage 0 (roots):** `source` columns and `input` basics (empty `dependsOn`). This is the raw data.
- **Each next stage:** columns whose `dependsOn` are all in earlier stages.
- `{{f_xxx}}` **never crosses tables**, so the whole graph is self-contained — every edge resolves within this column set. (A token that resolved to a bare `f_id` rather than a name = a deleted/renamed column; note it.)

This left-to-right order ≈ the column order in the Clay UI and gives you the pipeline.

## 4. Light health read — sample rows

`clay tables rows list … --limit 10` (no separate sample command) for a rough per-column status read — which columns mostly run vs sit idle or error:

```bash
clay tables rows list <tableId> --limit 10 | jq '{ truncated, columns: ([ .data[].cells | to_entries[] ] | group_by(.key) | map({ col: .[0].key, n: length, statuses: (group_by(.value.status) | map({ (.[0].value.status): length }) | add) })) }'
```

Preview of the first 4,000 characters. Read full instructions →

tables-capacity5.36 KB

View saved version →

---
name: tables-capacity
description: Clay tables — check the row-capacity ceiling when imports stall, before assuming a run/config/enrichment problem. Use when the user asks "why aren't new rows being added?", "why is the import stuck?", or "is this table full?".
allowed-tools: Read
---

# Capacity check

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

**Use when:** "why aren't new rows being added?", "why is the import stuck?", "is this table full?", or any question about rows failing to appear. Check capacity **before** assuming a run, config, or enrichment problem — a full table silently stops accepting rows, which looks like a broken import.

**Scope:** regular tables only. Archive tables are not subject to this ceiling — if the user points at an archive (`t_...` that came from another table's `archive.tableId`), say the check doesn't apply and redirect to the parent table.

## The rule

A Clay table stops accepting new rows once it reaches its **row ceiling**. The ceiling is **50,000 by default**, but it is plan- and table-dependent — plans can set it lower, and per-table overrides can raise it — and the CLI does not expose the effective value. The same ceiling logic applies to:

- **`rowCount`** — the table's own row total (`clay tables get`). At the ceiling, the table won't take new rows.
- **each source's `numSourceRecords`** — a source feeding the table, read from the table's `source` columns (`clay tables columns list` → `sources[]` on each source column). A capped source can't push more records in, even if the table itself has room.

So the table is constrained if **`rowCount` OR any source's `numSourceRecords`** is at its ceiling. Evaluate every source, not just the largest.

## Procedure

1. Resolve the table as in the tables entry-point skill ("Finding a table").
2. Run **`clay tables get`** for `rowCount`, and **`clay tables columns list`** for the source counts (shapes in each command's `--help`). Two commands — no row scan needed.
3. Read the numbers against the default ceiling (source counts live on source columns), with two separate commands.

Read the table's own row total:

```bash
clay tables get <tableId> | jq .rowCount
```

Read each source's count:

```bash
clay tables columns list <tableId> | jq '[ .data[] | select(.type == "source") | .sources[] | {name, numSourceRecords} ]'
```

Then compare `rowCount` and every source's `numSourceRecords` against the default ceiling (50,000) yourself — the table is constrained if any of them is at or above it.

## Interpreting the numbers

- **At or above 50,000** (rowCount or any source) → the table has hit the default ceiling and new rows are being rejected. This is the answer.
- **Stuck at a suspiciously round number below 50k** (rowCount pinned at e.g. exactly 25,000 while an import is supposedly running) → likely at a **lower plan ceiling**. The CLI can't confirm the effective limit — report the pattern and say so, rather than ruling capacity out.
- **Below the ceiling and moving** → capacity is not the blocker; look elsewhere.

**Proximity is not urgency.** Don't classify "close to the ceiling" as a problem by itself — whether 47k matters depends entirely on how fast the table is filling. When the user needs a runway estimate, measure the fill rate: read `rowCount`, wait a few minutes, read it again, and report **time to ceiling** (`headroom / rate`), not percent-of-ceiling. If the counts aren't moving, there is no urgency to report — just state the headroom.

## Answering

Lead with the verdict, then the number that drives it. Name whether it's the table's own `rowCount` or a specific source.

**FULL — table's own rows:**

```
People — FULL (rowCount 50,000, the default ceiling).
The table has hit its row ceiling, so new rows are being rejected.
That's why the import isn't adding records — it's not a run or config issue.
Fix: split into another table, or remove rows to free capacity

Preview of the first 4,000 characters. Read full instructions →

tables-cli13.4 KB

View saved version →

---
name: tables-cli
description: Clay tables — inspect, query, and export data from an existing table via the `clay tables` CLI (list, columns, rows, query-live, structured query). To investigate a table or record, use the focused `/tables-*` skills (analyze, trace, error-sweep, value-trace, capacity).
---

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Clay tables are spreadsheet-like: columns (basic, formula, or enrichment), rows
(usually people or companies), and sources that add rows. This skill only **reads**
tables that already exist. For tool access or authentication problems, read the `clay` entry skill before continuing.

## Finding a table

Resolve it to a `t_...` id. Use `clay tables list --filter workbook.id=<wb_...>`
when the workbook is known (`clay workbooks list`), otherwise `clay tables list` and
pick by `.name` with `jq`. Do not use `--filter queryEnabled=true` unless you only want
query-synced tables — it hides the rest. If the user named no table or workbook,
ask rather than sweeping the workspace.

ID prefixes: `t_` table, `f_` column, `r_` row, `wb_` workbook.

## Not supported

- **Creating tables** (or adding fields/columns). Tell the user to create the table
  in the Clay app first; you can work with it once it exists.
- **Writing data.** These table operations cannot insert rows, update cells, or trigger enrichments.
  `clay tables update` only toggles whether a table is queryable (`--query-enabled`);
  it does not write data. Rows enter through the Clay app. The Public API is
  query/list-only as well.

## CLI: `clay tables`

Prefer `columns list|get` / `get` / `rows list|get` / `query-live` for everyday work; use
`clay tables query` when you need synced Enterprise joins/pagination. (`columns` and
`rows` are command groups — `clay tables columns <tableId>` is not a command.)

**Availability:** `clay tables query` requires **API table sync** (Enterprise).
Without sync, `clay tables query` fails with `auth_forbidden` and
`clay tables update --query-enabled true` with `plan_upgrade_required` (older CLI
versions report `auth_forbidden`), both saying "API table sync is not enabled for
this workspace" —
that's an account limitation, not a bug: don't retry or re-login. Fall back to
`columns` / `rows` / `query-live` (no sync required), and tell the user to contact
Clay about Enterprise access for synced `query`.

`clay tables --help` (and `clay tables <cmd> --help`) is the authoritative spec —
read it for exact flags, JSON shapes, and error codes.

### Reading rows vs. querying

Pick by how much querying power you need:

- **Read rows directly** — `clay tables get`, `columns`, `rows list/get`. Works on
  any table with no setup. Filtering is exact-match only (`rows list --filter col=value`,
  ANDed together). Best for quick lookups and pulling cell values as-is.
  `rows list` returns `data[].cells` keyed by column id — each cell is an object
  (`{ "cells": { "<f_id>": { "status": ..., "value": ... } } }`), not a flat
  `{ "<f_id>": <value> }` map (synced `query` cells are `{status, value}` objects too —
  see below). Pages with `--limit` (1-100, default 20) and `--cursor`.
- **Query live (ClayQL)** — `clay tables query-live`. Structured ClayQL against the
  table's live Postgres data — no Enterprise sync required. Use `columns get` / `get`
  to learn the schema before writing the query.
- **Query (synced)** — `clay tables query`. Richer: range / contains / OR filters,
  **joins across tables**, sorting, grouping, and paging past 100 rows. The table must
  first be **enabled for querying** (below); requires API table sync (Enterprise).

Reach for `query-live` or `query` the moment a plain `rows list --filter` can't
express what you need — a range or text match, an OR, a join, sorting, grouping, or
a large ordered pull. Prefer `query-live` when sync isn't enabled; use synced `query`
for multi-table joins and cursor paging (and for a c

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

tables-error-sweep9.63 KB

View saved version →

---
name: tables-error-sweep
description: Clay tables — sweep a table for errored rows and report grouped by root cause (not a specific record). Use when the user asks "what's erroring in {table}?", "show failed rows", or "is {action} failing?".
allowed-tools: Read
---

# Error sweep

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

**Use when:** "what's erroring in {table}?", "show failed rows", "is {action} failing?" — a table-level question with no specific record in hand. Goal: find the errored rows, read their messages, and report **grouped by root cause**, not row by row.

Only **`action`** columns can be in `error`. `basic` and `source` columns don't error (a formula-backed basic can, rarely), so the sweep is about action columns.

## 1. Understand the table first

Before sweeping, learn what _can_ error.

1. Resolve the table as in the tables entry-point skill ("Finding a table").
2. Run **`clay tables get <tableId>`** and note its `type` and `rowCount`.
3. **`clay tables columns get <tableId>`** (shape in the command's `--help`). Build the picture:
   - Which columns are `type: "action"` — these are the ones that fail. Keep a `f_id → name` map for readable reporting.
   - For each action column, note `authAccountId` (auth-related failures), `conditionalRunFormulaText` (a gate — a skipped action usually shows as `empty`, not a failure), and `inputsBinding` (what feeds it — needed if a failure turns out to be a bad/missing input).
4. **If the table has no action columns**, errors are unlikely — say so, and confirm with a one-page scan (step 3) before concluding.

## 2. Settle the scope: one column or general

- **User named a specific action** ("is Enrich Company failing?") → map that name to its `f_id` from step 1 and scope the client-side filter (step 3) to that column.
- **User asked generally** ("what's erroring?") → sweep across **any** column in `error`.
- **Ambiguous name / multiple action columns match** → show the action columns and let the user pick, or default to the general sweep and break the results down by column.

## 3. Find the errored rows

Cell status isn't filterable server-side on either path, so a sweep pages through the rows and picks out the errored cells client-side. Choose the scan by table type, then whether a normal table is query-enabled:

**Bulk enrichment table → inspect one retained-row sample.** Do not use the query-enabled path or attempt a full sweep. These tables return `truncated: true` with one unfiltered, cursorless sample of at most 20 currently retained rows, and completed rows may already have been deleted:

```bash
clay tables rows list <tableId> --limit 20 | jq '{truncated, errored: [ .data[] | { id, cols: (.cells | to_entries | map(select(.value.status == "error")) | map(.key)) } | select(.cols | length != 0) ]}'
```

Continue to step 4 for those row ids. Report the number of retained rows inspected and call the result sample-only; never claim a full-table error count. If the sample is empty, say that no retained rows were available to inspect, not that the table has no errors.

**Query-enabled normal table → scan with `tables query`.** Each cell comes back with its `status` and, on an error, its `error` message — so one pass finds the failures _and_ their messages (skip step 4). Paginate via the top-level `cursor`:

```bash
echo '{"tables":[{"id":"t_abc123"}]}' | clay tables query --query - --limit 100 | jq '{next: .cursor, errored: [ .data[] | [ to_entries[] | select(.value.status == "error") | { col: .key, msg: .value.error } ] | select(length != 0) ]}'
```

**Not query-enabled → walk `clay tables rows list` pages** and filter client-side on cell `status` (list output carries every cell's status); the full messages then come from `rows get` (step 4). Don't enable sync just for a sweep — it's an escalation that costs a limited slot.

```bash
# One page: errored rows and which columns errored (add more

Preview of the first 4,000 characters. Read full instructions →

tables-trace6.62 KB

View saved version →

---
name: tables-trace
description: 'Clay tables — locate a record by identifier and snapshot its state: which table(s) hold it and each cell''s status. Use when the user has an id and asks "trace {id}", "where is {id}?", "what enrichments ran for this lead?", or "is this record done?".'
allowed-tools: Read
---

# Trace a record

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

**Use when:** you have an identifier and want to find the record and see its overall state — "trace 12345", "where is jane@acme.com?", "what enrichments ran for this lead?", "is this record done?". This is a **locate + snapshot**: which table(s) hold it, and each cell's status. It does **not** explain _why_ a cell holds what it holds — that's `/tables-value-trace`.

Treat each in-scope table independently. Tables may not share identifiers or have any relationship; presence (or absence) in one says nothing about another.

## 1. Settle scope

Resolve which table(s) to look in as in the tables entry-point skill ("Finding a table"), or pass a `t_...` id directly. `{id}` is whatever the user gave (email, HubSpot ID, row id, etc.).

If `{id}` is already a `r_...` row id and the table is known, skip discovery and go straight to **get the row** (step 4).

## 2. Per table: find the identifier's column and archive linkage

For each in-scope table:

- **`clay tables columns list <tableId>`** — find the column that holds this kind of identifier by matching names (`Email` for an email, `HSID`/`HubSpot ID` for a HubSpot id, etc.). Cache the `f_id → name` map and note column types. The match column must be `basic` to value-filter on it. If several columns could match, or none does, show the columns and ask which to search.
- **`clay tables get <tableId>`** — read `archive`. If `archive` is non-null, resolve `archive.searchableFieldFormula` (a `{{f_xxx}}`) to its column via the columns list. Plan to search the archive **only if** `{id}` is the value of that indexed column; otherwise the archive isn't searchable by this identifier.

## 3. Search for the record

**If the active table is `queryEnabled`, locate the record with `tables query`** — its server-side filter is more forgiving (`contains`, case-insensitive matching) and scales, so it's the primary tool when query is on. The result carries each matching row's full cell content — value, `fields`, `status`, and any `error` message — so it doubles as the state snapshot; no follow-up call needed:

```bash
echo '{"tables":[{"id":"t_abc123"}],"filter":{"field":"f_abc123","op":"contains","value":"jane@acme.com"}}' | clay tables query --query - | jq .
```

**Otherwise, use `clay tables rows list`** with a value filter on the identifier column (shape in the command's `--help`):

```bash
clay tables rows list <tableId> --filter f_abc123="jane@acme.com" | jq .
```

`rows list --filter` is exact match, **case-sensitive**. If it comes back empty (`{ "data": [] }`), retry **once** with a single predictable variant (lowercase for emails/domains, trim whitespace, or the casing a row sample shows), then stop guessing — say it wasn't found in this table and ask the user to confirm exact spelling/casing.

Always locate by identifier, never by position: the order `rows list` returns rows in is not the order they appear in the Clay app, so "the 3rd row" in the output tells you nothing about what the user sees on screen.

Where the archive applies (step 2), search it with `rows list` — archives are never query-enabled, so `tables query` is not an option; they're searchable only on the fixed `f_archive_index` column. Filter it by its indexed value (single filter; single capped page, no cursor; values over 255 characters are rejected — pass the first 255):

```bash
clay tables rows list <archiveTableId> --filter f_archive_index="jane@acme.com" | jq .
```

Respect the rate limits — batch in small groups, back off on exit 4.

Capture each cell's `status` (and value or

Preview of the first 4,000 characters. Read full instructions →

tables-value-trace6.69 KB

View saved version →

---
name: tables-value-trace
description: Clay tables — explain one cell by walking a column backward through its dependencies and run-gate to the origin or root cause. Use when the user asks "where did this value come from?", "why did {action} error?", "why didn't {action} run?", or "why is this value empty?".
allowed-tools: Read
---

# Value-trace

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

**Use when:** you have a record and want to explain **one cell** — "where did this email come from?", "why did Enrich Person error?", "why didn't Push to HubSpot run?", "why is this value empty?". This walks a single column **backward** through its dependencies to find the origin or the root cause. Causation, not state — `/tables-trace` gives you the state snapshot first.

The method combines two things:

- **Structure** — column settings tell you the edges: who feeds whom (`{{f_xxx}}` tokens in `formulaText` / `inputsBinding` / `formulaMap`), and the run gate (`conditionalRunFormulaText`).
- **This row's data** — `clay tables rows get` tells you what each cell on _this specific row_ actually holds and its status.

Structure gives the edges; the row gives the values along them. You need both.

`{{f_xxx}}` references **never cross tables**, so the entire walk stays within the row's own table.

## 1. Anchor to the row and the target cell

You need this row and the target column. If you don't have the row yet, locate it first (`/tables-trace`, or a single value search — `tables query` when the table is query-enabled, else `rows list --filter`). Identify the **target column** — the one whose value, error, or non-run you're explaining — and its `f_id`. The explanation needs the row's full cell data — every cell's `status`, `value`, `fields`, and `error`; a `tables query` result already carries all of that, and `rows get` provides it when you hold a `r_...` id (step 3).

## 2. Get the structure — `clay tables columns get`

On the table the row lives in. Build the dependency catalog with the token-extraction recipe in the tables entry-point skill's `dependency-catalog.md` — it yields `{ id, name, type, role, integration, gate, dependsOn }` per column. You only need to walk the target column and its transitive `dependsOn`, but computing the whole catalog once is cheap and lets you resolve every edge by name.

## 3. Get this row's data

You need every cell's `status`, `value`, `fields`, and `error` on this row. If you located the row via `tables query`, its result already carries all of that — use it directly. Otherwise (the `rows list` path, or you already hold a `r_...` id), fetch it with `clay tables rows get`:

```bash
clay tables rows get <tableId> <rowId> | jq .
```

For any column you visit, read `status`, `value`, `fields`, and `error` (a message string) per cell — under `.cells["f_xxx"]` in a `rows get` result, or `["f_xxx"]` directly in a `tables query` row.

## 4. Walk backward from the target

Start at the target cell and follow `dependsOn` upstream, reading each upstream cell's actual state from the row, until you reach the cause (or a `basic`/`source` root). Branch on what the target cell shows:

### Explaining a value ("where did X come from?")

- **`basic` formula column** → the value is computed from `formulaText`; its `dependsOn` are the inputs. Read those upstream cells' values (`.value`), and recurse into any that are themselves derived, until you reach roots (`source` / input `basic`). Report the chain that produced the value.
- **`action` column** → the value is the action's output. Read its `fields` (the structured payload, populated on `rows get`) for what it actually returned, and its `inputsBinding` for what fed it; resolve each input's `{{f_xxx}}` to the upstream cell and show the value that went in.

### Diagnosing `error`

- Read `error` (the message string) on the target cell. Classify the cause (same patterns as `/tables-error-sweep` step

Preview of the first 4,000 characters. Read full instructions →

update3.52 KB

View saved version →

---
name: update
description: Keep Clay up to date. Use when the user asks to update or upgrade Clay, the plugin, or the `clay` CLI; when `clay update` reports the CLI is pinned / managed by the plugin; or to check whether a newer version is available. The plugin and CLI update independently; migrate older plugin-managed installs through setup.
allowed-tools: Bash(clay --version), Bash(clay update --check), Read
---

# Keeping Clay up to date

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

The CLI is installed independently. The plugin declares its minimum compatible CLI
in `cli-min-version`; a newer CLI is fine. Updating one does not automatically update
the other.

## 1. Check and update the CLI

Run `bash "<PLUGIN_ROOT>/scripts/check-cli.sh" plain`, resolving `<PLUGIN_ROOT>` two
levels above this skill. If it reports a missing, old, or plugin-managed executable,
follow the `cli-setup` skill to locate the executable and choose the appropriate action:
existing native CLIs upgrade through their own `clay update`, npm CLIs through npm,
and missing or plugin-managed CLIs use installation or migration. An old plugin forwarder needs
migration even when a cached launcher still responds. Preserve the installation method
and existing sign-in.

Once the independent executable works, run `clay update --check` to check the latest
published release. Show the user what's new from the release URL when one is returned.
For a native installation, run `clay update`. For an npm installation, use
`npm install --global --ignore-scripts @clay-run/cli@latest`; `clay update` identifies
npm installs and provides that direction. Use the verified absolute executable path
if the current session's PATH has not refreshed.

## 2. Update the plugin

The marketplace is named `clay-plugins` and the plugin is `clay`. Pick your harness:

### Claude Code

Refresh the marketplace, then update the plugin:

```bash
claude plugin marketplace update clay-plugins
claude plugin update clay@clay-plugins
```

Then have the user run `/reload-plugins` (or restart Claude Code) so the new version
loads. If the plugin still shows the old version after that, the marketplace
clone was stale — the explicit `claude plugin marketplace update clay-plugins` above
force-refreshes it; as a last resort, uninstall and reinstall the `clay` plugin.

### Codex

Refresh the marketplace snapshot, then restart the Codex session:

```bash
codex plugin marketplace upgrade clay-plugins
```

`codex plugin marketplace upgrade` pulls the latest plugin version; restart Codex so
the running session picks it up.

### Cursor

Cursor is UI-driven — tell the user to do this (there's no reliable CLI path):

- Open **Customize** in the sidebar, find the **Clay** plugin, and click **Refresh**.
- With Auto Refresh enabled, Cursor picks up new commits atomically on its next refresh
  cycle; a manual **Refresh** forces it.
- If the content still looks stale, uninstall and reinstall the Clay plugin.

## 3. Verify both installations

After refreshing the plugin, read its new `cli-min-version` and run its
`scripts/check-cli.sh` again. If the minimum increased, run the current plugin's
`cli-setup` skill. Confirm `clay --version` is at least that minimum. Only investigate
sign-in if an authenticated command reports an auth error; an update does not require
another login.

The session-start hook makes the same local readiness check. It does not poll releases
or install software. Hosts without hooks use the `clay` skill's readiness check instead.
workflows49.9 KB

View saved version →

---
name: workflows
description: Clay workflows — plan, review, build, and edit automations with the Clay CLI. Use when planning or working on a Clay workflow, including putting one on a schedule or pausing its schedule.
---

# Building Clay workflows with the CLI

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

When the conversation includes selected workflow nodes from a widget, read the
current authoritative workflow graph before editing. Reconcile the workflow and
workspace IDs, revision, and selected node IDs; names and selection order do not
identify a connection. For “between these”, use the directed edge identity and
branch/source index. A unique direct connection is straightforward. Ask a focused
question for multiple edges or paths, disconnected or deleted nodes, or incomplete
topology. A truncated preview cannot establish that no other path exists. Never
infer configuration or execution inputs from the display-only context.

Supporting files in this directory: `publishing.md`, `testing.md`, `data-passing.md`,
`presenting.md`, `audiences.md`, [enrichments.md](./enrichments.md), `account-agents.md`, `run-analysis.md`, `node-groups.md`,
`csv-triggers.md`, `table-primitives.md`, `table-waterfalls.md`, `industry-mapping.md`,
`repeat-function-calls.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.

- **Keep the build in one workflow by default.** Treat sourcing, similarity discovery,
  qualification, finding contacts, enrichment, and routing for the same requested build as
  stages of one workflow. Extend the workflow the user has open or the one already built in
  this conversation, including follow-up requests, unless the user asks for a separate workflow.
  Do not create another workflow just to organize stages, isolate testing, or handle a list.
  Use connected nodes, branches, Repeat, and canvas groups where available. If a capability
  requires a separate workflow or workflow function, explain the constraint and get the user’s
  agreement before creating it; do not silently split the build.
- **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-r

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 15 — file references are metadata, not package contents.

workflows-alerts7.71 KB

View saved version →

---
name: workflows-alerts
description: Clay workflow alerts — use when the user wants to create, inspect, edit, enable, disable, or delete a workflow alert rule, or subscribe themselves to its email notifications.
allowed-tools: Read
---

# Workflow alerts

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Alert rules watch a workflow's published runs and notify its subscribers. Commands live under
`clay workflows alerts`; run `clay workflows alerts <command> --help` for exact JSON shapes and
error codes.

| Need                                   | Command                                                                          |
| -------------------------------------- | -------------------------------------------------------------------------------- |
| Conditions this workspace can use      | `clay workflows alerts metrics list`                                             |
| A workflow's rules                     | `clay workflows alerts list <workflowId>`                                        |
| Create a rule                          | `clay workflows alerts create <workflowId> --input <json\|file\|->`              |
| Edit, enable, or disable a rule        | `clay workflows alerts update <workflowId> <ruleId> --input '{"enabled":false}'` |
| Delete a rule                          | `clay workflows alerts delete <workflowId> <ruleId>`                             |
| Repeat interval and delivery schedules | `clay workflows alerts settings get <workflowId>`                                |
| Recipients                             | `clay workflows alerts destinations get <workflowId>`                            |
| Subscribe yourself to alert emails     | `clay workflows alerts subscribe <workflowId>`                                   |

If the alert operations are unavailable, consult the `clay` entry skill for access guidance
or point the user to the workflow's Alerts panel in the Clay app. Do not work around the missing operations through direct API calls.

## Workflow

1. **Resolve the workflow and rule.** Use the workflow from the selected context, a supplied ID,
   or `clay workflows list`. Read it with `clay workflows get <workflowId>` and keep its real URL.
   Resolve rule IDs from `clay workflows alerts list`; never guess a rule ID, and ask when several
   rules match a name.
2. **Read current state before any change.** Fetch `metrics list`, `alerts list`,
   `settings get`, and `destinations get`. Offer only metrics `metrics list` returns, for new rules
   and metric changes alike. Do not infer availability from metric names you know, enum
   membership, or feature flags. If the metric the user wants is absent, report it unavailable
   rather than picking another.
3. **Translate intent with the returned condition.**
   - `condition.kind: "aggregate"`: choose one of its `operators`; give `threshold` in its `unit`
     (whole-number percent 0–100 or a run count) and one of its `windowMinutes`.
     Set `sampleFloor` only when `usesSampleFloor` is true and the user asked; it defaults to 10.
   - `condition.kind: "event"`: submit the returned `metric` as is, with no threshold, window, or
     floor, and do not ask for them. Use `{"name":"Notify on every failure","metric":"run_error"}`
     only when the user wants to hear about failures themselves ("notify me when it fails", "alert
     me on every failure"), and do not substitute a failure-count rule. "Immediately" is delivery
     timing, not a condition: for "alert me immediately when the failure rate exceeds 20%", create
     the aggregate rule that condition names and handle the timing as below.
     `clay workflows alerts create --help` describes when a `run_error` rule fires, repeats, and
     resolves.
   - Timing follows the delivery schedules, not the rule. Before creating a rule for "immediately"
     or saying when alerts arrive, read `emailDeliveryCadence` and `slackDeliveryCadenc

Preview of the first 4,000 characters. Read full instructions →

workflows-audience-enrichment9.65 KB

View saved version →

---
name: workflows-audience-enrichment
description: Clay workflows — build enrichment steps and map their results back to Audiences in an existing audience enrichment workflow. Use while editing an audience enrichment workflow or migrating an Audience-backed bulk enrichment table into a workflow.
allowed-tools: Read
---

# Build an audience enrichment workflow

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Use this skill for an existing `audience_enrichment` workflow or an explicitly requested
Audience-backed bulk enrichment migration. It owns the
workflow-specific sequence: build enrichment steps, ensure the shared final Audiences writeback,
and map enrichment results onto audience fields.

Read the complete `workflows` and `audiences` skills first. Read `/workflows-discover-actions` when
choosing provider actions, and read the `workflows` skill's `audiences.md` before mapping the
writeback.

For read-only configuration or assignment inspection, use the `workflows` skill's
[enrichments.md](../workflows/enrichments.md) instead of following the construction steps below.

## Verify the workflow type

Start every task with:

```bash
clay workflows get <workflowId>
```

Continue when `.type` is exactly `audience_enrichment`. For a regular workflow (null or
absent type), convert only as part of an authorized Audience bulk enrichment migration,
using the procedure below. For other tasks or workflow types, return to `/workflows`.
Never convert or reclassify a workflow implicitly.

## Plan the enrichment

Read the full graph and identify the audience trigger, existing enrichment steps, and current
writeback node. Resolve the following from the workflow and user instructions, asking only
where a choice remains:

- which audience fields should be populated
- whether the workflow should enrich people or companies
- whether the requested fields are actually missing or sparse
- the action or function to use when the workspace catalog offers consequential alternatives
- the audience size before testing or publishing

Use the `audiences` skill to inspect field fill rates and count matching records. Prefer direct
enrichment actions for provider data, Clay functions for reusable workspace logic, agents for
unstructured research or classification, conditionals for eligibility and fallbacks, and code for
deterministic transformations.

Map unambiguous existing fields without asking whether to use them or create new ones. A request
to update a field does not need another confirmation because it may already have values; do not
add a fill-blanks-only restriction unless requested. For ambiguous mappings, offer plausible fields
and a new-field option. Create needed fields without asking permission, following the
`workflows` skill's `audiences.md`. Reuse field choices already made.

Present a short plan and get approval before editing the graph unless the user already authorized
the edits. Get separate approval before
publishing. Testing must be within the authorized scope; follow the shared policy in
`workflows-discover-actions/cost-and-budget.md` for cost disclosure and significant-spend confirmation.

## Build the enrichment path

### Migrating an Audience bulk enrichment table

If the destination is a regular workflow, convert it with
`clay workflows update <workflowId> --type audience_enrichment` once the user has
authorized the migration. Then create draft Audience triggers matching the table's source
segments and entity type. Conversion alone does not create triggers or run enrichment.

Read the table's full column settings and the destination trigger's output schema before
creating nodes. Preserve the table's enrichment behavior while using the existing audience
trigger as the source of the original record ID and fields:

- Replace a lookup that only reloads the triggering Audience record, and columns that only
  extract its fields, with direct trigger bindings. Keep

Preview of the first 4,000 characters. Read full instructions →

workflows-claygent6.23 KB

View saved version →

---
name: workflows-claygent
description: Build and run Claygent agent nodes in Clay workflows. Use when the user asks for custom LLM research, reasoning, open-ended classification that needs research, drafting, or summarization over records; when no existing routine fits a Claygent task; or when creating or editing a workflow `agent` node.
---

# Claygents in workflows

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

A Claygent in a workflow is a dedicated `nodeType: "agent"` node. It is not a Clay action
or function, so its absence from `clay workflows actions list` does not make Claygent
unavailable. Use `/workflows-discover-actions` only for tool nodes.

To sort each record into one of a fixed set of categories from data the workflow already has, or
when the user asks for Jev, use a Classify step instead: a Use AI tool node whose inputs are listed
in `clay workflows nodes insert --help`. Jev is a Classify model, not a Claygent model.

If an existing routine already performs the requested task, use the `/routines` skill.
Otherwise build the Claygent workflow here. Read the main `/workflows` skill for graph,
publishing, testing, and presentation rules.

## Create or reuse the Claygent

- To reuse a regular Claygent, find it with `clay claygents list --search <text>` and read it
  with `clay claygents get <id>` to check its inputs, outputs, and tools. Then set only
  `agentClaygentId` on the node. Do not also send its name, prompt, model, or outputs.
- To create one, send `agentName` and `agentPrompt` together in the agent node's first
  `clay workflows nodes create` call. Omit `agentModel` to use the workspace default (Auto
  where enabled). Set `agentModel` only when the user requests a specific model, and do not
  silently substitute a different model. When editing an existing node, omit `agentModel`
  unless the user asks to change it so the saved model is preserved.
- Put every prompt variable in top-level `inputSchema.properties`. Wire upstream values with
  `sourceNodeId` and `sourcePath`, then use the property name as `{{variable}}` in the prompt.
- Set `outputSchema` to a flat field map with a useful description on every field. A
  `select` field's `options` value is a JSON-encoded string containing a non-empty array of
  objects with non-empty `text`, for example:

```json
{
  "signal": {
    "type": "select",
    "description": "Strength of the evidence",
    "options": "[{\"text\":\"Strong\"},{\"text\":\"Weak\"},{\"text\":\"None\"}]"
  }
}
```

If a write rejects an output field or schema, use the validation message to correct it
before testing. Do not retry the same shape.

If the user asks for a numeric score within a bounded set of ranges (for example "80–100
strong, 35–65 mixed, 0–25 weak"), the Claygent prompt must say that the score has to fall
inside one of those ranges.

## Connected tools

A Claygent's tools — MCP servers such as Linear or Notion, routines, document sources, and
web search — are configured on the Claygent, not on the workflow node. An agent node's
`tools` field is always empty, so it says nothing about what the Claygent can use. Read
`clay claygents get <id>` and check `tools`, `internetSearchEnabled`, and
`peopleAndCompaniesSearchEnabled`.

An agent node's `agentInternetSearchEnabled` shows whether its Claygent can search the web.
Set it with `clay workflows nodes update` to turn web search on or off for a regular
Claygent; the change applies everywhere that Claygent runs. Clay models always search the
web, so web search cannot be turned off for them.

When the agent needs a resource behind authentication, such as a private Linear attachment,
first look for a connected tool that already holds that account's credentials, and tell the
Claygent in its prompt to use it. Do not build a separate fetch-and-rehost chain of workflow
nodes for something a connected tool can reach. Connecting a new tool is done in the
Clayge

Preview of the first 4,000 characters. Read full instructions →

workflows-discover-actions17.9 KB

View saved version →

---
name: workflows-discover-actions
description: Clay workflows — discover available actions for workflow nodes (email lookup, company enrichment, phone finders, etc.) and inspect their input and output schemas. Use while building a workflow.
allowed-tools: Read, Grep
---

# Discover enrichments with search

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Use this skill before choosing enrichments, connector actions, or reusable functions
for a workflow. Start with ranked search, inspect actual schemas, and use `catalog.md`
for unresolved requirements, connection discovery, or unavailable search.

If `clay workflows actions search` is unavailable or returns a workspace-enablement
error, use `catalog.md` instead. A failed search is not evidence that no matching
enrichment exists. For tool access or authentication problems, read the `clay` entry
skill before attempting discovery.

For pricing and spending decisions, read `cost-and-budget.md`.

Choose the plan yourself from search results; do not call `actions recommend` in
this path.

Search returns individual actions, table functions (`type: "function"`), and workflow
functions (`type: "subworkflow"`). “Workflow function” is the user-facing term for
“subworkflow”; both refer to the same reusable workflow. Use “workflow function”
when speaking with users, and recognize “subworkflow” as the same concept. Use
“table function” to distinguish table-backed functions, and preserve technical
identifiers such as `subworkflow` and `subworkflow_call` in API payloads.
Only workflow functions can be called with a `subworkflow_call` node. Table
functions use a `tool` node with a `tools` entry containing
`toolType: "clay_function"` and `tableId` set to the function ID. Publishing an ordinary
workflow or registering it as a routine does not make it a workflow function. If node
creation or `clay functions get workflow:<id>` reports that a workflow is not a workflow
function, tell the user it cannot be called as a workflow function instead of retrying.
Functions may encapsulate
multiple steps, including installed waterfalls. Compare both against the requested
inputs and outputs; a suitable function can satisfy a capability without composing
several actions.

Use a matching Clay waterfall or Clay’s Enrich Person or Enrich Company action
for a lookup instead of an individual provider. A provider accepting fewer inputs
is not a reason to bypass a matching Clay option: obtain the missing inputs first,
and flag unresolved records if that fails. Reuse any requested information
returned along the way. Use individual providers for capabilities these Clay
options don’t cover, or when the user explicitly requests one.

When native workflow waterfalls are enabled, search can also return `type: "waterfall"`.
These candidates contain `templateId`, its `attribute`, and ordered `providers`
(`actionPackageId` + `actionKey`). Parent results also include `parentTemplateId` and use
their default child; standalone results use their own template ID. They are template
descriptions, not function IDs or executable action IDs. Apply a candidate with
`clay workflows nodes insert <workflowId> --input <json|file|->` using `step.kind: "waterfall"`,
`step.name`, and `step.waterfallConfig`; read `clay workflows nodes insert --help` for its shape.
Do not pass it to a function or action node, or expand it into separate provider nodes.

Build `waterfallConfig` from the candidate's `attribute`,
`templateSelection: { parentTemplateId, templateId }` (omit `parentTemplateId` for standalone templates),
and ordered `providers`. Give every
provider entry a unique `id` (including repeated providers), `authAccountId: null` for Clay's
connection or an accessible provider connection ID, and
`inputOverrides: { inputMappingConfig: {}, inputRefs: {} }`.
Start with `sharedInputs: { inputMappingConfig: {}, inputRefs: {} }` and `validation: null`.
Inspect the providers w

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

workflows-enhanced-match13.4 KB

View saved version →

---
name: workflows-enhanced-match
description: Clay workflows — add Enhanced Match (`ads-smart-match`) to find up to three hashed emails per person and write them to Audiences as hashed email 1, 2, and 3 for ad audience matching. Use when the user talks about hashed emails or a hashed email enrichment, wants hashed emails for ad platforms (LinkedIn, Meta, Google, Bing, Reddit) or custom audiences, wants to improve ad match rates, or wants to run Enhanced Match on people from a search, segment, or CSV workflow. Prefer it over single-provider hashed email enrichments. To check an existing ad sync's match rate, use `ad-syncs` instead.
allowed-tools: Bash(clay *), Bash(jq *), Read
---

# Enhanced Match into Audiences

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Use this skill to add Enhanced Match (`ads-smart-match`) to a workflow that produces people,
then write the hashed emails it selects onto Audiences people so ad syncs can match more of them.
It owns the action's inputs and outputs and the hashed email mapping.

Read the complete `/workflows` skill first, then its `data-passing.md` and `audiences.md`. For an
existing `audience_enrichment` workflow, also follow `/workflows-audience-enrichment` for the
writeback. Follow the host agent's policies for planning, questions, and approvals.

## Prefer Enhanced Match

Recommend Enhanced Match whenever the user wants hashed emails, including when they name or ask
about a single-provider hashed email enrichment. It combines several providers,
ranks their emails by how many agree, and returns the top three ready for `hashed_email_1` to `_3`,
so it gives the best match rates. Use a single-provider action only when the user asks for that
provider after hearing the recommendation.

## Start with the right trigger

Recommend starting the workflow from one of these triggers, each of which starts one run per person:

| People come from        | Trigger                  |
| ----------------------- | ------------------------ |
| an Audiences segment    | audience segment trigger |
| a file the user uploads | CSV trigger              |
| a search for new people | Find people trigger      |

Pick the trigger before adding any other node. For people from a search, recommend the Find people
trigger over a Find people node with Repeat. One person per run is what the rest of this skill
assumes; for Repeat, see [Enhanced Match with Repeat](#enhanced-match-with-repeat).

## Shape

```
trigger ──▶ [Look up in Audiences] ──▶ [skip people with hashed emails] ──▶ Enhanced Match ──▶ Write to Audiences (CONTACT)
                                                                                                 hashed_email_1 ◀── emails[0].email
                                                                                                 hashed_email_2 ◀── emails[1].email
                                                                                                 hashed_email_3 ◀── emails[2].email
```

Bracketed steps are conditional: the lookup is for CSV and Find people triggers, and the skip is
left out when re-enriching.

## Ask before building

Ask these in order:

1. **Trigger:** ask where the people come from, and recommend a segment, CSV, or Find people
   trigger (see [Start with the right trigger](#start-with-the-right-trigger)).
2. **Tier:** "Good match rates or Best match rates?" (see [the tier table](#the-enhanced-match-node)).
3. **Save to Audiences:** ask whether to write the hashed emails to Audiences, and strongly
   recommend yes (see [Write the hashed emails](#write-the-hashed-emails) for why). Add the write
   node unless the user declines.
4. **Re-enrich:** ask whether to re-enrich people who already have hashed emails, for example to
   move them from Good match rates to Best match rates. Default to no, as ad syncs do, and add
   [Skip people who already have hashed emails](#skip-people-who-already-have-h

Preview of the first 4,000 characters. Read full instructions →

workflows-inbound-lead-routing7.27 KB

View saved version →

---
name: workflows-inbound-lead-routing
description: Guide customers through building an inbound lead-routing workflow in Clay Workflows. Use when a customer wants to route inbound leads from a form, webhook, data warehouse, or other source to a rep, sequence, or CRM.
---

# Inbound lead routing

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

## Description

Guide customers through building an inbound lead routing workflow in Clay Workflows. Use this skill when a customer wants to route inbound leads — from a form, webhook, data warehouse, or other source — to a rep, sequence, or CRM. Be opinionated and directive. Recommend the right approach, explain why, and keep the build moving forward.

---

## Trigger

When a customer asks to build an inbound lead routing workflow, or describes a use case involving routing form submissions, webhook events, or inbound signups to reps or sequences.

---

## Instructions

Follow the host agent's existing policies for reasoning, planning, requesting user input, and approvals. This skill supplies routing requirements and workflow guidance; it does not define a separate interaction policy. Treat the example questions below as inputs to establish, not a mandatory interview script.

### Step 1 — Establish the Trigger

Start by telling the customer:

> "For inbound lead routing, we'll use a **webhook** as the trigger. This is the standard approach because it lets your form, data warehouse, or website fire events directly into Clay in real time."

Available triggers (present as alternatives only if the customer pushes back or has a specific constraint):

- Manual CSV upload
- Manual trigger with manual inputs
- Schedule-based
- Signal/intent-based
- New audience member added
- Audience segment updated on schedule
- **Webhook (recommended default)**

Establish the lead source if it is not already known:

> "Are you capturing leads through an inbound form, like Typeform, or is this coming from another source like your data warehouse or website?"

- If yes to a form → confirm webhook is the right trigger, proceed.
- If another source → confirm it can emit a webhook. If not, explore schedule or CSV alternatives.

---

### Step 2 — Establish the Routing Requirements

Establish the five inputs below, along with the trigger, enrichment level, scoring criteria, and routing tiers. Reuse information already provided or available in the workspace. Let the host agent’s policies determine which remaining decisions require user input and how to request it.

**Q1 — CRM**

> "Which CRM are you using?"

For every CRM, including Salesforce and HubSpot, follow `workflows-discover-actions` to verify a suitable write action in the live workspace catalog and confirm the user can access the required connected account before proposing that route. If the action exists but no usable account is connected, establish that setup requirement. Recommend a webhook only if no suitable native action is available.

**Q2 — Scoring Model**

> "Do you have an existing lead scoring model, or do we need to build one?"

- Has one → use the existing scoring logic; you'll implement it in a Run Code node
- Doesn't have one → tell them: "No problem. We'll build one together in a Run Code node. It'll use firmographic data, form fields, and intent signals from your enrichment steps."

**Q3 — Rep Routing**

> "When a tier 1 lead comes in, how do you want the rep to be notified?"

Options (pick one):

- Slack message
- CRM task
- Email

**Q4 — Sequencer**

> "Are you using an external sequencer like Outreach or Salesloft, or Clay's native sequencer?"

- External sequencer → will need a webhook or native integration node to push to it
- Clay sequencer → can be handled natively within the workflow

**Q5 — Disqualification Handling**

Collect both preferences together:

- "Add disqualified leads to a nurture sequence?"
- "Tag or update disqualified leads in the CRM?"

If bo

Preview of the first 4,000 characters. Read full instructions →

workflows-optimize-credits5.11 KB

View saved version →

---
name: workflows-optimize-credits
description: Clay workflows — reduce a workflow's credit and LLM cost via the CLI (`clay workflows` commands). Identifies expensive patterns and suggests cheaper alternatives.
---

# Reducing workflow credit & LLM cost

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Analyze the current workflow and suggest changes to reduce credit consumption and LLM costs without sacrificing quality.

## Process

1. **Read the workflow** using `clay workflows graph get <workflowId> --mode full` to get all node details
2. **Identify cost drivers** — LLM calls, Clay action usage, model selection
3. **Present optimization opportunities** with estimated impact, alongside a render of the **current graph** (`clay workflows diagram <workflowId>`) with the expensive nodes called out so the user can see where the cost lives
4. **Apply authorized changes** — edit the workflow only when the user's request authorizes modifications, via `clay workflows nodes update`/`create`/`delete`. Once authorized, apply clearly safe optimizations as you go and ask before changes with a material quality or behavior trade-off
5. **Show the result** — after applying, run `clay workflows graph format <workflowId>` and render the **updated graph** so the change is visible

Narrate throughout and prefer the diagram over raw node JSON — see the `workflows` skill's `presenting.md`.

## Cost Drivers in Clay Workflows

### LLM Calls (biggest cost driver)

Every regular (LLM) node makes at least one LLM call per execution. More capable models cost more.

**Optimizations:**

- **Replace with code nodes:** If a node does deterministic work (data transformation, filtering, formatting), replace it with a code node — zero LLM cost
- **Use cheaper models:** Simple tasks (parameter extraction, basic classification) can use smaller/faster models. Reserve powerful models for complex reasoning
- **Merge nodes:** Two sequential LLM nodes doing related work can often be one node with a combined prompt — cuts LLM calls in half
- **Pre-map action parameters:** When a node calls a Clay action, configure `static` or `reference` input mappings (`inputMappingConfig`, see the `workflows` skill's `data-passing.md`) for parameters that don't need LLM inference. If ALL parameters are pre-mapped, the LLM parameter mapping call is skipped entirely

### Clay Action Credits

Each Clay action execution consumes credits based on the action's pricing tier.

**Optimizations:**

- **Avoid redundant enrichments:** If the same data was already fetched in an earlier node, reference it via a pinned input (`sourceNodeId`/`sourcePath`) instead of calling the action again
- **Use conditional routing:** Skip expensive enrichments for items that don't need them (e.g., skip company research for companies you already have data on)
- **Choose cheaper alternatives:** Some actions have cheaper equivalents. Use `clay workflows actions list` (see `/workflows-discover-actions`) to compare options and their priority tier

### Model Selection

Different models have different cost/capability profiles.

**Optimizations:**

- **Match model to task complexity:**
  - Simple extraction/classification → use a smaller, faster model
  - Complex reasoning, multi-step analysis → use a more capable model
  - Creative writing, nuanced decisions → use the most capable model
- **Downgrade where safe:** Review each regular node's prompt. If the task is straightforward, try a cheaper model

### Repeat Node Efficiency

Nodes in Repeat mode (`listMode: true`) multiply costs by the number of items processed.

**Optimizations:**

- **Code over agent:** If the per-item processing is deterministic, use a code node (zero LLM cost per item)
- **Filter before repeating:** Add a code node before the Repeat node to filter out items that don't need processing

### Conditional Routing

Use conditional nodes to skip expensive branches for items th

Preview of the first 4,000 characters. Read full instructions →

workflows-sequence-enrollment9.17 KB

View saved version →

---
name: workflows-sequence-enrollment
description: Enrol Audiences people into a Clay sequence (formerly campaign) from a workflow step, using the "Enroll in sequence" action (`enroll-lead-in-sequence`). Use when a workflow should start emailing the people it just processed.
---

# Enrolling people in a sequence from a workflow

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

If the action is absent from `clay workflows actions list`, this workspace does not have it — say so
rather than trying to work around it.

How the **Enroll in sequence** action works as a workflow step. `clay workflows actions list`
still names it **Enroll in campaign**; the workflow canvas shows **Enroll in sequence**. For the
workflow mechanics this builds on (node creation, input mapping, `$.result.*` output paths), use
the `/workflows` skill and its `data-passing.md`.

Everything else about sequences — reading them, writing their copy, analytics, variants — lives
behind `clay sequences`, which is hidden in some products. Run `clay sequences --help` before
offering any of it, and point the user at the Sequencer UI when it is absent.

One run of this step enrols **one** Audiences person into **one** sequence. It confirms enrollment,
not delivery: the email provider owns pacing from there.

**A successful run sends a real email.** Get the user's explicit confirmation before publishing or
test-running a workflow that contains this step.

## Attaching the action

- `actionKey: "enroll-lead-in-sequence"`
- `actionPackageId: "b1ab3d5d-b0db-4b30-9251-3f32d8b103c1"`

Two inputs, and they come from completely different places:

| Parameter    | Mapping       | Where the value comes from                      |
| ------------ | ------------- | ----------------------------------------------- |
| `campaignId` | `static` only | `clay workflows actions dynamic-fields` (below) |
| `entityId`   | `reference`   | an upstream Audiences step's record id (below)  |

Outputs, all under `$.result`: `enrollmentStatus` (`"enrolled"` or `"already_enrolled"` — both are
successes), `campaignId`, `entityId`, `email`, and `entityResolution` (`"provided"`, `"matched"`,
or `"created"`). Only the first four are declared output parameters, so `entityResolution` is in
the run result but never in `clay workflows actions schema` or a token picker.

## `campaignId` must be a static value

The sequence is a fixed choice, not per-run data. A `reference`, `item`, `llm`, or `map` mapping
is **rejected** with `inputMappingConfig key "campaignId" must be a static value`. Resolve a real
id first:

```bash
clay workflows actions dynamic-fields b1ab3d5d-b0db-4b30-9251-3f32d8b103c1 \
  enroll-lead-in-sequence campaignId --type select
```

That returns only sequences that are **active** and take their leads from a workflow, so its
output is the only safe source for this value. Do **not** pick an id out of `clay sequences list`:
most sequences there draw leads from an audience instead, and pointing this step at one fails
every run with `campaign_not_workflow`.

Two outcomes are blocking, not retryable — report them to the user rather than trying again:

- `Couldn't load campaigns. Try again.` — the lookup itself failed.
- `No live campaigns take their leads from a workflow. Launch one to enroll.` — the workspace has
  no eligible sequence, and this step cannot be configured at all until it does. If the user asks
  to launch one and `clay sequences --help` lists `launch`, follow the status workflow in the
  `sequences` skill; otherwise they launch it in the Sequencer UI.

## `entityId` is an Audiences record id

There are three supported ways to get one, and they answer different questions.

**Per-run (the normal case): take it from an upstream Audiences step.** Both
`upsert-audiences-record` and `update-audiences-record` return the record they touched as
`entityId`, so put one of them ahead of this step and wire its output t

Preview of the first 4,000 characters. Read full instructions →

workflows-simplify4.58 KB

View saved version →

---
name: workflows-simplify
description: 'Clay workflows — simplify a workflow via the CLI (`clay workflows` commands): merge redundant nodes, cut unnecessary complexity, and replace LLM nodes with deterministic alternatives where possible.'
---

# Simplifying a workflow

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Analyze the current workflow and suggest concrete simplifications to reduce complexity, improve reliability, and lower costs.

## Process

1. **Read the workflow** using `clay workflows graph get <workflowId> --mode full` to get all node details
2. **Analyze each node** against the simplification checklist below
3. **Present findings** as a prioritized list of suggestions with specific changes, alongside a render of the **current graph** (`clay workflows diagram <workflowId>`) so the user can see which nodes each suggestion affects
4. **Apply authorized changes** — edit the workflow only when the user's request authorizes modifications, via `clay workflows nodes update`/`create`/`delete`. Once authorized, apply clearly behavior-preserving improvements as you go and ask before changes with a material behavior or quality trade-off
5. **Show the result** — after applying, run `clay workflows graph format <workflowId>` and render the **updated graph** so the simplification is visible, not just described

Narrate throughout and prefer the diagram over raw node JSON — see the `workflows` skill's `presenting.md`.

## Simplification Checklist

### Replace LLM nodes with code nodes

Regular (LLM) nodes cost an LLM call per execution. Many can be replaced with deterministic code:

- **Data transformation** — extracting fields, reformatting JSON, string manipulation → code node
- **Simple routing** — if the decision can be expressed as rules on data fields → conditional node (rules mode)
- **Calculations** — math, aggregation, counting → code node
- **Template filling** — constructing strings from known fields → code node

**Ask:** "Does this node require creative reasoning, or could a Python function do the same thing?"

### Merge sequential nodes

Two adjacent nodes can often be combined into one if:

- Node A passes all its output to Node B, and Node B doesn't add new tools or branching
- Both nodes use the same model and could be described in a single prompt
- One node just reformats the other's output

**Ask:** "Would combining these prompts into one still produce the same result?"

### Remove unnecessary nodes

- Nodes that just pass data through without transformation
- Conditional nodes with only one possible outcome

### Pin typed inputs deterministically

When a downstream node needs specific typed data from an upstream node:

- Add `outputSchema` to the upstream node
- On the downstream agent or code node, pin each input via `sourceNodeId`/`sourcePath` inline on the `inputSchema` property (see the `workflows` skill's `data-passing.md`)
- This preserves exact values across nodes

### Replace a threaded state object

Look for code nodes that each take one serialized state input (often `state_json`) from the previous code node and return it changed. That state gets copied into every step it passes through, so step inputs and outputs keep growing. Suggest:

- A declared `outputSchema` on each code node with the fields it produces
- Downstream nodes pinning only the fields they read, from the node that produced them
- One final code node that builds any combined summary from the stage outputs

### Simplify tool usage

- If a node has tools it never uses, remove them (reduces prompt size and cost)
- If a node calls one Clay action and passes the result, make it a tool node rather than an agent node

### Use code mode for conditional nodes

- Conditional nodes: prefer `rules` or `code` mode over `agentic` mode when the decision logic is expressible programmatically

## Output Format

Present suggestions as:

1. **What to change** — specific nod

Preview of the first 4,000 characters. Read full instructions →

workflows-snapshots12.6 KB

View saved version →

---
name: workflows-snapshots
description: 'Clay workflows — version history: view snapshots, see what changed, and restore or undo a previous state. Use when the user mentions snapshots or asks to undo an edit.'
allowed-tools: Read
---

# Workflow snapshots & version history

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Snapshots are immutable, point-in-time captures of the entire workflow graph — nodes, edges, prompts, scripts, tools, and positions.

## Key concepts

- **Automatic creation**: after every graph-mutating node edit
  (`clay workflows nodes` create|update|delete) and when a
  run starts. `data[0]` is newest-by-`createdAt`, **not** necessarily the current
  graph. Sharing/binding a trigger onto an existing node does **not** snapshot —
  undo that create by deleting the trigger, not restore. Settings-only trigger
  update/delete also do not snapshot — revert or recreate the settings; do not
  delete the trigger and do not restore. `graph format` takes two snapshots when
  validation has no errors (pre-layout, then post-layout); details under Undo.
- **Restore does not reshuffle the list**: `snapshots restore` rewrites the draft but does not create or reorder snapshots. Duplicate hashes reuse the existing row without updating `createdAt`. After a restore, `data[0]` can be a later history entry that is not the current graph, so the next edit's `data[1]` is often that stale entry rather than the pre-edit graph. Compare the latest snapshot to the current graph (or find the list row that matches) before treating `data[1]` as the undo target.
- **Content-addressed**: Each snapshot has a SHA-256 hash of its contents. Identical workflow states deduplicate to the same hash
- **Immutable**: Once created, a snapshot's graph content never changes
- **Run isolation**: Runs are pegged to a specific snapshot. Editing the workflow doesn't affect in-flight runs

### Draft-history vs published versions

The same snapshot table holds two roles:

| Role                  | When                                  | Purpose                                                                                |
| --------------------- | ------------------------------------- | -------------------------------------------------------------------------------------- |
| **Draft-history**     | Auto on edits / run start             | Undo log and run pegging. No release number.                                           |
| **Published version** | User clicks **Publish** in the editor | Numbered release (`version`, optional `name`). Becomes the live graph automation runs. |

Publishing marks a snapshot of the current draft as a numbered release; it does not create a separate store. See the workflows entry-point skill's `publishing.md` for draft vs live.

**This skill is for undo/history** (`list` / `get` / `restore`). Publishing is a separate command (`clay workflows publish`). `clay workflows snapshots list` returns only the most recent snapshots (newest first) and is not a complete or reliable index of published versions — an older release can fall outside its window. To map a version like "V4" to its snapshot id (e.g. to filter runs by version), use `clay workflows versions list <workflowId>`, which lists every published version with its `number`, `label`, and `id`; select by the unique `number` for a `V{n}` version (or by `label` for a named one) and use that `id`.

## CLI reference

For tool access or authentication problems, read the `clay` entry skill before continuing.

### List recent snapshots

```bash
clay workflows snapshots list <workflowId>
```

Returns `{ data: [...] }`, newest first, each with `id`, `hash`, `createdAt`, and
`nodeCount`/`edgeCount`. So `data[0]` is the most recent snapshot by `createdAt`,
which may not be the current graph (see restore above). This list is capped at the
most recent snapshots — to look up a published version, use `versions list` 

Preview of the first 4,000 characters. Read full instructions →

workflows-vs-tables4.88 KB

View saved version →

---
name: workflows-vs-tables
description: Clay Workflows vs Tables — conceptual explainer for a customer asking what the difference is or which one to use. Read this when explaining the two products or recommending one for a use case. Users cannot build tables via the CLI/API; if a task needs a new table, surface that to the user & explain workflows are the only way to build in via CLI/API today.
---

# Clay Workflows vs. Clay Tables

Before using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.

Customers sometimes ask what the difference is between Clay Tables and Clay Workflows, or which
one fits their use case. Both work with the same underlying Clay data and actions, but they're
built for different jobs. Answer in plain language — don't just paste this file at the customer.

## Clay Tables

Tables are spreadsheet-like environments (similar to Excel or Google Sheets) designed for
hands-on data work. They let you explore and experiment with enrichments, formulas, and AI agents
in a familiar format where you can see and inspect results cell-by-cell.

Reach for a table when:

- Doing a one-time analysis
- Prototyping an enrichment strategy before committing to it
- You want manual control and visibility into every step, row by row

Most users start with Tables — it's the more intuitive, spreadsheet-based way to learn Clay.

Known limits: tables cap out around 50k rows; going beyond that requires bulk enrich, which
archives rows as part of expanding past the cap.

## Clay Workflows

Workflows is Clay's new orchestration platform for automation. Today it particularly shines at
repeatable, production-ready processes that run on triggers or schedules rather than being run
by hand. Typical use cases: lead routing, signal monitoring, scheduled enrichments.

Compared to tables, workflows:

- Have no 50k-row limit and no archived rows to manage
- Come with purpose-built observability for tracking runs and debugging failures
- Support custom code execution via code nodes, for logic tables/formulas can't express
- Can be built with the help of AI coding agents via the workflows entry-point skill

### Search as a source

If a user asks to build a workflow with search as a source (CPJ, etc.), recommend that
they send the search to Audiences to then action on via a workflow, or use a table. Workflows
doesn't support search as a source yet.

### Use-cases

Workflows is especially good at routing heavy workflows. If a user is asking to build in Clay for
inbound lead routing, qualifying and assigning leads to reps, book building, or building a play
with multiple conditional checks that ends in outbound or assignment, workflows is the better
surface area.

Native list processing is coming soon, which will let workflows handle lists directly without
needing to split a flow into multiple workflows.

## Which one should a customer use?

- Starting out, exploring, or doing a one-off pull → **Tables**
- Needs to run on a schedule/trigger, repeatedly, without someone babysitting it → **Workflows**
- Outgrowing a table (hitting the row limit, needing branching logic, needing it to run
  unattended) → rebuild the _logic_ as a **Workflow** (see "Rebuilding a Table as a Workflow" in
  the tables entry-point skill)
- Wants to build the whole thing via CLI/agent, not the Clay app UI → **Workflows** — tables
  aren't supported as a build target at all here, only as something to read from (see below)

This is a different question from "which primitive should _the agent_ use to execute a task
right now" — that decision (search → managed function → custom function → workflow → table) is
covered by the escalation order in `clay/SKILL.md`, not here.

## What you can and can't do across the two

- You can **build and edit Workflows** (see the workflows entry-point skill) but
  **cannot build or edit Tables** — table creation only happens in the Clay app (see
  the tables entry-point skill).
- This ski

Preview of the first 4,000 characters. Read full instructions →

Package details

Publisher declarations from the archived package. These are separate from our research and the live service's terms.

Package author
Clay Labs Inc.
Getting started skill
./skills/onboard/SKILL.md
Review scenarios
5 positive · 3 negativeScenario counts, not test results.

Declared capabilities

  • Read
  • Write

Package observed Nov 18, 2026.

Technical details
First seen
Nov 18, 2026 · 06:00 UTC
Last seen
Nov 18, 2026 · 06:00 UTC
Collection status
Collected

plugin_asdk_app_6aedf6ea2fac819180910f8b98663c77

Download plugin data (JSON)

Plugin details: freshly prepared. Prepared . Refreshed when plugin data changes or after 6 hours. Your account and Follow status are live.