{"id":103343,"plugin_id":"plugin_asdk_app_6aedf6ea2fac819180910f8b98663c77","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-18T06:19:21.281Z","digest":"da053ddbd5f07db88f65a06f1f868b04fcec7d3b82b1b71dd3714e2ffc2f278e","against":null,"payload":{"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.","included_files":[],"name":"workflows-audience-enrichment","skill_md_contents":"---\nname: workflows-audience-enrichment\ndescription: 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.\nallowed-tools: Read\n---\n\n# Build an audience enrichment workflow\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\nUse this skill for an existing `audience_enrichment` workflow or an explicitly requested\nAudience-backed bulk enrichment migration. It owns the\nworkflow-specific sequence: build enrichment steps, ensure the shared final Audiences writeback,\nand map enrichment results onto audience fields.\n\nRead the complete `workflows` and `audiences` skills first. Read `/workflows-discover-actions` when\nchoosing provider actions, and read the `workflows` skill's `audiences.md` before mapping the\nwriteback.\n\nFor read-only configuration or assignment inspection, use the `workflows` skill's\n[enrichments.md](../workflows/enrichments.md) instead of following the construction steps below.\n\n## Verify the workflow type\n\nStart every task with:\n\n```bash\nclay workflows get <workflowId>\n```\n\nContinue when `.type` is exactly `audience_enrichment`. For a regular workflow (null or\nabsent type), convert only as part of an authorized Audience bulk enrichment migration,\nusing the procedure below. For other tasks or workflow types, return to `/workflows`.\nNever convert or reclassify a workflow implicitly.\n\n## Plan the enrichment\n\nRead the full graph and identify the audience trigger, existing enrichment steps, and current\nwriteback node. Resolve the following from the workflow and user instructions, asking only\nwhere a choice remains:\n\n- which audience fields should be populated\n- whether the workflow should enrich people or companies\n- whether the requested fields are actually missing or sparse\n- the action or function to use when the workspace catalog offers consequential alternatives\n- the audience size before testing or publishing\n\nUse the `audiences` skill to inspect field fill rates and count matching records. Prefer direct\nenrichment actions for provider data, Clay functions for reusable workspace logic, agents for\nunstructured research or classification, conditionals for eligibility and fallbacks, and code for\ndeterministic transformations.\n\nMap unambiguous existing fields without asking whether to use them or create new ones. A request\nto update a field does not need another confirmation because it may already have values; do not\nadd a fill-blanks-only restriction unless requested. For ambiguous mappings, offer plausible fields\nand a new-field option. Create needed fields without asking permission, following the\n`workflows` skill's `audiences.md`. Reuse field choices already made.\n\nPresent a short plan and get approval before editing the graph unless the user already authorized\nthe edits. Get separate approval before\npublishing. Testing must be within the authorized scope; follow the shared policy in\n`workflows-discover-actions/cost-and-budget.md` for cost disclosure and significant-spend confirmation.\n\n## Build the enrichment path\n\n### Migrating an Audience bulk enrichment table\n\nIf the destination is a regular workflow, convert it with\n`clay workflows update <workflowId> --type audience_enrichment` once the user has\nauthorized the migration. Then create draft Audience triggers matching the table's source\nsegments and entity type. Conversion alone does not create triggers or run enrichment.\n\nRead the table's full column settings and the destination trigger's output schema before\ncreating nodes. Preserve the table's enrichment behavior while using the existing audience\ntrigger as the source of the original record ID and fields:\n\n- Replace a lookup that only reloads the triggering Audience record, and columns that only\n  extract its fields, with direct trigger bindings. Keep formulas that transform those fields.\n- Only carry over a related-company lookup when a downstream enrichment or writeback uses\n  its output and that value is not already available from the trigger. Preserve user lookups\n  that retrieve different records or implement additional filtering.\n- Pin each required value on the consuming code or tool node using an `inputSchema` property\n  with the trigger's `sourceNodeId` and the exact `sourcePath` from its output schema. For\n  example, a trigger exposing `fields.Name` supplies `sourcePath: \"$.fields.Name\"`; this may\n  differ from the Audience field ID `name`. A nested expression like `{{fields.id}}` does not\n  replace an explicit upstream binding. Read `/workflows`'s `data-passing.md` for the writable shape.\n- In code, read the pinned input by its property name with `context.get_input`. On the final\n  writeback, pin the original record ID from the trigger and the transformed value from the\n  enrichment node, then reference those input names in `inputMappingConfig`. Read each node\n  back and confirm its source bindings survived before running.\n\nUse the shared writeback procedure below for the table's final Audience update. Do not copy\nthe table's source-record lookup or legacy writeback action into a separate update path.\n\nBuild from the existing audience trigger. Preserve the trigger and any existing\n`upsert-audiences-record` node.\n\nUse `clay workflows actions list` and `clay workflows actions schema` to choose and configure each\nenrichment. Never guess action input names, output paths, credentials, or provider availability.\nPut cheap eligibility checks before paid actions. When an enrichment can miss, use the user's\nchosen fallback or conditional path rather than silently writing a blank value.\n\nUse the general `workflows` skill for node creation, insertion, data passing, and branch wiring.\nDo not manually create or reconnect the final audience writeback while building intermediate\nsteps.\n\n## Ensure and configure the final writeback\n\nAfter the enrichment graph is structurally complete, run:\n\n```bash\nclay workflows ensure-audience-writeback <workflowId>\n```\n\nThis command calls the same server-side helper as the audience enrichment editor. It creates or\nreuses exactly one `upsert-audiences-record` node, validates its entity type, and reconnects every\neligible terminal route. Do not reproduce that topology change with manual node or edge edits.\n\nRead the returned node before updating it. Preserve its tool identity and static `entityType`, then\nconfigure its `inputMappingConfig` with `clay workflows nodes update` using the writable shape from\n`clay workflows nodes get`.\n\nDiscover destination fields with:\n\n```bash\nclay audiences fields list --entity-type people\nclay audiences fields list --entity-type companies\n```\n\nFollow the `workflows` skill's `audiences.md` for the complete mapping shape. In particular:\n\n- set `lookupFields|selectedLookupFields` to the static array `[\"id\"]`\n- bind `lookupFields|id` to the audience trigger record id: use `$.fields.id` when the trigger\n  output schema contains a `fields` object, otherwise use `$.id`; inspect the trigger output schema\n  and never guess the path\n- do not replace the record-id lookup with email, LinkedIn URL, phone, or domain; those aliases are\n  for generic or net-new audience upserts where an existing audience record id is unavailable\n- include every destination id in `recordFields|selectedRecordFields` and provide its matching\n  `recordFields|<id>` binding\n- when the user wants a field cleared, set\n  `recordFields|writeMode|<id>` to the static value `always_write_including_blanks` and map that\n  field to an upstream value; `null`, `\"\"`, or a missing value clears it only when explicit Audiences clears\n  are enabled for the workspace (`enable-audiences-clear-field-command`)\n- bind enrichment outputs from their declared `$.result.<outputPath>` paths; never invent paths\n\nRead the writeback node again after updating it and confirm the mappings persisted. If explicit-clear\navailability is unknown, do not promise a clear. After execution, read the record back before reporting\nsuccess; a successful step alone does not prove the field cleared.\n\n## Validate, test, and publish\n\nFinish an audience enrichment workflow in this order:\n\n1. Run `clay workflows ensure-audience-writeback <workflowId>`, read the returned node, and confirm\n   its mappings persisted.\n2. Validate the graph with the available workflow tools and show the resulting diagram.\n3. Resolve the segment id from the workflow's existing `audience_segment` trigger. Do not search\n   for audience entities or records to decide what to publish or run. If the workflow has no\n   `audience_segment` trigger, stop this completion sequence and use the general `workflows`\n   testing guidance; do not alter its triggers.\n4. Explain the likely credit exposure and get approval for a credit-consuming test.\n5. Test 10 segment records from the current draft by default:\n\n   ```bash\n   clay workflows runs test <workflowId> --audience-segment <segmentId> --limit 10\n   ```\n\n   Use a different limit only when the user requests or approves it.\n\n6. Wait for the run to finish. Inspect both the enrichment output and the final Audiences update.\n   If mappings need correction, correct and validate them, then return to step 4 and get renewed\n   approval before another credit-consuming test.\n7. Get separate approval, then publish the tested draft with\n   `clay workflows publish <workflowId>`.\n\nWhen the user asks to **publish and run** an `audience_segment` workflow, publish first, then test 10\nrecords from the version just published with `--audience-segment <segmentId> --limit 10 --live`.\nDo not substitute an entity lookup, a record search, or a plain manual run for the requested segment\nrun. Later edits remain draft-only until the workflow is published again.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}