Imported from eliasstravik/gtm-skills (skills/gtm-workflow/SKILL.md). Install upstream with npx skills add eliasstravik/gtm-skills --skill gtm-workflow. Copyright stays with the author.

GTM Workflow

Trigger

Apply this skill when a request concerns a saved workflow: creating, changing, running, scheduling, deploying, upgrading, inspecting, opening its UI, or deleting one, or its table, runs, or diagram.

When creating or changing a workflow that enriches connections or followers and their current companies, load gtm-workflow-enrich-network when installed for that recipe; this skill still owns its lifecycle. Ordinary runs of an unchanged workflow need only this skill.

Show the intent menu only when the user's entire request is /gtm-workflow or /gtm-workflows, with no action or other words. Ask Choose a workflow action. with three choices: Open GTM Workflows, Create a workflow, Manage a workflow, and wait. Manage asks which workflow and action: change, run/test, schedule/deploy, upgrade/repair, or delete. Bare entry performs no creation, execution or deployment.

Open GTM Workflows is already an explicit Open request. Resolve the verified viewer URL and return it immediately using entry links; do not show the intent menu or ask the user to choose Open again. Loading this skill does not turn an explicit request into a bare invocation. Other explicit actions also go directly to their procedure. If Open finds no workspace, explain workspace setup; if the workspace has no workflows, show its empty list.

Scope

This skill owns <workspace>/workflows/, a Vercel Workflow runtime on Nitro copied from templates/ on first use: workflow files, db/tables/, migrations, vercel.json, .env, the local database, runs, diagram pages, and the deployed copy. Runs execute locally against this workspace's own Postgres in data/pg by default; they target the deployed copy when the user asks or the host states there are no local runs, and hosted results are read through the deployed copy's query route. Local Connections uses a trusted component outside workflows/; deployed Connections runs inside the existing private Workflows project. For setup, key discovery, connection changes and component upgrades, read Connections. The remaining workspace files outside workflows/ belong to the other gtm skills.

Inputs

The request; the workspace found by the contract; the ICP or persona whose criteria the workflow copies; references/local.md for commands, keys, and verified facts; references/deploy.md for hosting.

Roles

The user's request authorizes routine code changes and real runs within the configured row and cost caps. State the estimate and proceed; confirmation is reserved for destructive actions under the shared interaction rules. The user connects the workflow project through shared standalone setup or optional gtm-agent setup and chooses the AI backend once per workspace in .env; the agent writes, runs, and reports. Deploy is the push.

Procedure

When persisting enriched people or companies, follow shared profiles for storage, identity, freshness, paid attempts and scoped Data views. Its two phase workers and common budget replace the generic self-fan-out pattern below for multi-phase enrichment. The profile tables are runtime tables in schema gtm; scripts/migrate.mjs migrates them with everything else, and upgrades preserve them.

Talk by the six rules in interaction; reproduce the dialogues. Workflow slugs follow the contract's slug rule; the display name is the doc comment's first line.

For Create, Update and Upgrade, read viewer. Keep a valid business diagram and, for every Data tab, a valid viewer.sharePolicy. Build before saving; missing or mismatched sharing metadata is an authoring error. Preparing a policy makes Data selectable; changing a public link's access still requires an explicit sharing request.

Every save: one sentence on what will change, pull first when origin/main exists, edit through the host's write path, commit on main with a plain-language message, push when a remote exists, verify the commit (and that it reached origin/main when a remote exists), close with what was created, changed, or deleted.

On a host that states there are no local runs: the scaffold deletes env.example instead of renaming it, because the values live in the host's environment; every run targets the deployed copy after the push and after Deploy's readiness check; Upgrade verifies through the deployed diagram page after that check instead of restarting a server. Two rules hold on such a host whatever else the agent does:

• Links: a dev server or a local build may be started as a check, but nothing it serves is ever posted. The only links a reply may carry are the verified viewerUrl the deployed copy's link route returned after the readiness wait; localhost never appears in a reply.
• Keys: read GET /api/connections through the protected workflow transport for presence and declared usage, including unused services. Use the saved Note as the service name and the exact variable for code, following Connections naming. Direct missing-key entry to the verified connectionsUrl from the private link route. Never collect keys in chat. Saved changes become active after a deliberate deployment; presence does not prove validity.

Conventions the code follows

• Linked result tables: linked data defines the optional data registry property and the read-only People/Companies-style viewer. Register it when users need to browse related records. Its private Data link comes from the same link route. Preserve viewer, data, and intake during upgrades. Sharing is an explicit private-viewer action; it requires a versioned table/column/relationship/row policy described in viewer.

• Step choice: every step is the plainest kind that does the job. Deterministic work (parsing, arithmetic, a fetch, a provider or gateway API call with known inputs, a Slack post) is a plain "use step" function with no model. Judgment over text the workflow already holds (scoring, classifying, extracting, drafting) is a single-shot AI step, generateObject with a schema. An agent stage (runAgent) only when the user names an agent, or the work needs the model to choose its own tool calls as it goes (find the right endpoint, research across pages) and no sequence of plain and AI steps can be written in advance; a stage that would always call the same tools in the same order is those steps instead. When the user asks for an agent where steps would do, say so in one sentence and build what they asked.

• Rows come from defaultInput (inline), a provider or API call inside a "use step" function, a table another workflow fills, or an inbound webhook (export const intake = defineIntake({ secretEnv, signature, eventId, toRow }) from lib/intake.ts, registered as intake in workflows/index.ts; POST /api/intake/<slug> verifies the sender's signature over the raw body, drops redeliveries by event id for 30 days, and starts one run with the mapped row); never from a workspace file or local-only data. Input is RowsInput from lib/rows.ts, { rows?, maxRows?, maxSpendUsd? }, each row an object with a required string key, the table's primary key; the workflow's constants are the defaults; the start route merges a POST body over defaultInput, so the limited run is POST { maxRows: 1 }.

• runRows({ rows, table, step, maxRows, maxSpendUsd, estimateUsd, freshForMs, concurrency?, fanOut? }) from lib/rows.ts is the loop; step(row) is a plain async function in workflow scope that awaits "use step" functions in sequence and returns { ...columns, costUsd }. Tables are passed by name and resolved through db/tables/index.ts. Every workflow passes fanOut: { workflow: <its own function>, input, chunkSize }: above that many rows the run only splits the list into child runs of itself, four at a time, each with its exact share of the caps, and adds up their totals, so a list of any size is one run with one result. chunkSize is 100 for a workflow of plain steps and 20 for one with an agent stage: the engine caps a run at 25,000 events and an agent row costs about 100 of them. Cancelling the parent cancels its children.

• Every result table has key, updated_at, cost_usd, error. All database I/O, every cached() and generateObject call happen inside "use step" functions declared as async function name() { "use step"; }, never arrow or method form; every paid or AI step sets name.maxRetries = 0.

• Agent stages: an agent inside a workflow is always runAgent() from lib/agent.ts, called from a plain async function in workflow scope (the stage function, an agent node), never WorkflowAgent directly and never inside a "use step" function; the helper makes every model call and tool call a step, races the time limit against sleep(), cleans the schemas, and returns real cost. Its config is the whole authoring surface: model and reasoning (defaults GTM_MODEL and GTM_REASONING on the project), instructions, skills (names from skills/index.ts, each a text module under skills/), tools (mcp servers by name with url, keyEnv, allow, maxCalls; web.fetch free, a step; web.search executed by AI Gateway (true or "gateway", Exa, any model, no key) or by OpenAI ("openai", openai/* models only), inside the model call rather than as a step, so it cannot be approved or call-limited; custom tools whose execute is a "use step" function), approve (tool names requiring destructive-action confirmation or an explicitly requested workflow review; never add routine approval gates by default; the row waits on a hook and the run's read route lists the request until POST /api/runs/<id>/approve decides it; set timeout in days when approvals may wait), stream (every model and tool event on GET /api/runs/<id>/stream), maxSteps, maxUsd (soft: the agent stops using tools after the call that crosses it and writes up what it has), timeout (a duration string; the row fails), schema (or none for plain text), prompt or messages, and, for anything else WorkflowAgent takes, agent (constructor options: sampling, provider options, prepareStep, prepareCall, callbacks, telemetry, contexts) and call (per-call options: toolChoice, activeTools, transforms). Schemas use nullable fields, never optional ones, and no string formats (z.string(), not .url() or .email()); the description carries the intent. Never pass timeout: or AbortSignal.timeout() to the SDK; never build MCP clients or tools by hand. example-research.ts is the reference.

• A single-shot AI step is generateObject with GTM_MODEL inside a step; anything that uses tools is a runAgent stage. The stage's backend is decided per run from the frozen environment: GTM_AGENT_BACKEND (claude or codex: the author's subscription, one step, this machine only; MCP servers and web tools carry over; codex needs each MCP server's allow list) or the Gateway when unset. A stage that uses custom tools, approve, stream, or messages, and every stage on the hosted copy, runs on the Gateway regardless. backend on a stage overrides the variable for that stage only. No other AI path exists.

• Criteria: export const criteria = \…`holds the ICP or persona text, first line naming it; backticks and${` are escaped. Nothing else from the workspace is deployed; the copy stays until the next Update.

• Doc comment: first line is the title, second paragraph the one-sentence summary; the diagram page reads both.

• Viewer metadata: author literal viewer.businessGraph with stable node IDs, human labels, input/action/decision/output kinds, explanations and meaningful decision edges. Keep provider/caching details in explicit owner fields. Review the diagram against the actual workflow code on Create, Update and Upgrade; preserve viewer.id. See viewer for the schema and validation.

• Where to look: follow entry links after create/change, deploy/upgrade, ordinary runs, and explicit requests. Return the canonical private viewerUrl as Open GTM Workflows. This is separate from issuing an external share grant.

• Connections: read the target inventory before writing a paid or AI step and in every pre-run check. Name a missing connection once and open the trusted Connections form; use its workflow-declared gateway relationship when deciding which key is required. Author literal viewer.connections alongside the business graph. Follow Connections for unknown keys, activation state and safe credential entry.

• Gateways: a paid step that uses a provider found through a gateway tool the host exposes (a data marketplace, an MCP server) calls that gateway from code with the gateway's own key, <GATEWAY>_API_KEY managed through Connections, never the provider behind it. When the gateway's HTTP API is unknown, read its documentation before writing the step; do not guess.

• Engine features are used natively (see local.md): a hook or sleep is a wait node, a child workflow a sub node, a runAgent stage an agent node.

• Reaching people: notify({ kind, text, approval?, target }) from lib/notify.ts posts to the GTM agent's notify route, which posts the text straight to Slack with the agent's bot token and no model call; tell and show are plain posts, ask and handoff open a message whose thread the agent watches, so a person's reply there wakes it. An approval in a stage notifies by itself when GTM_AGENT_URL and GTM_NOTIFY_SECRET are on the workflow project. Where it posts is code: const NOTIFY = { channelId: "C0…" } at the top of the workflow, given as notify: input.notify ?? NOTIFY to each stage and as target to each notify call; posts land top-level in that channel, never in the conversation a run was started from. Per-row news goes through runRows, never a notify call inside the step: notify: { target: input.notify ?? NOTIFY, every: "chunk", line: (row, columns) => … }, where every is row (one post per finished row), chunk (one post per run of rows, so one per child when fanned out; the default to propose) or run (one post with the totals at the end), a count and never a judgment; line returns a string, or { text, blocks } when a row deserves a rich post. notify: false on a stage keeps its approvals silent. The agent project's GTM_NOTIFY_CHANNEL is only the fallback when a workflow names none. A workflow calls the agent only to reach people, never to think.

• Helpers are admitted to lib/ only when a bare SDK call was shown to fail or double-spend; everything else is a native SDK call with a worked example in patterns.

• Routes, bearer GTM_RUN_SECRET: POST /api/run/<slug>, GET /api/run/<slug> (cron, also CRON_SECRET), POST /api/intake/<slug> (no bearer; the sender's signature), GET /api/runs/<id> (status, output, error, and approvals, pending first), POST /api/runs/<id>/approve with { token, approved, reason? }, GET /api/runs/<id>/stream (one JSON event per line while an agent stage streams), POST /api/runs/<id>/cancel, GET /api/link/<slug>. Base: http://localhost:3939 locally, GTM_WORKFLOW_URL for the deployed copy. When GTM_RUN_SECRET is the value host, the host supplies the credential outside the agent's reach and the call sends no Authorization header.

Outputs

workflows/<slug>.ts, its table and migration, registry entries, a vercel.json cron when scheduled, a diagram page, rows in the result table, and, once a project is connected, the deployed copy that every push refreshes.

For queue, provider, MCP, or CLI failures, read runtime reliability before attributing the cause or proposing a retry.

Exceptions

Requires the gtm-workspace skill installed alongside this one; when ../gtm-workspace/SKILL.md is missing, say: install it the same way this skill was installed, with npx skills add eliasstravik/gtm-skills -s gtm-workspace -y (add -g when this skill lives in the global skills directory), then retry. A missing key stops a run before it starts and is named. A production build on Vercel with no DATABASE_URL fails on purpose; report it and say the database is added through the Neon integration, as deploy.md describes. A run on the deployed copy needs a connected project; without GTM_WORKFLOW_URL, say how to connect one as Deploy does (shared standalone setup on a computer with the CLIs signed in; gtm-agent is optional) instead. A workflows/ that contains scripts/gtm.ts is the previous runtime, which this skill neither converts nor upgrades: say so, and offer to set it aside (remove workflows/, which stays in the workspace's history; its deployed copy keeps running until the next push) and scaffold fresh.

QC

• Every workflow has a valid business graph whose labels, branches and results match its actual code. Business behavior changes update metadata in the same change. The metadata build passes; compiler graphs never substitute for missing business metadata.
• Every step is the plainest kind that does its job: no AI step for deterministic work, no agent stage where plain and AI steps in a fixed order would do, unless the user named an agent.
• A one-row test was offered, through the question tool, before the first run of more than one row of a new or changed workflow; a one-row request ran without that question; the cost statement preceded every run.
• The result table has the four fixed columns; paid and AI steps have maxRetries = 0; no cached() or generateObject call sits in workflow scope.
• Every agent stage is a runAgent() call in workflow scope with maxSteps, maxUsd, and timeout set; no WorkflowAgent import, no timeout: option, no AbortSignal.timeout, no .url() or .email() in a schema, no optional fields in an output schema; a new or changed agent stage was tested on one row and the reply named its tool calls, stop reason, and real cost.
• Every workflow passes fanOut with itself, chunkSize 20 when it has an agent stage; a module a workflow imports never reaches the database outside a "use step" function; route-only code lives in *-api.ts files.
• An ordinary Run reply ends with the result and repeats no entry unless its address changed or the user explicitly requested it; a save ends with what was created, changed, or deleted.

References

interactions dialogues; local.md for start, keys, data, schedules, tables, the viewer, the agent stage, fan-out, intake, notify, and the findings ledger; patterns for native SDK calls with worked examples; deploy.md; templates/workflows/example-scores.ts as the reference implementation and templates/workflows/example-research.ts as the agent-stage reference; from gtm-workspace: interaction, contract.