How Do You Write a Prompt Spec for an AI Step in a Zap?

How do you write a prompt spec for an AI step in a Zap?

Write a short document that defines the step's job, its exact inputs, the allowed outputs and their format, the rules it must follow, what to do when input is missing, and a set of test cases with expected answers. The prompt itself is only one part. The spec is what keeps the step predictable when inputs get messy.

AI steps are now easy to add to Zapier, Make, or n8n workflows. You drop in a step, write a prompt, map a few fields, and it works on the first test. That ease is the trap. A prompt written in five minutes and tested on one example will behave in surprising ways on the hundredth real input.

A prompt spec takes about an hour. It turns a clever experiment into a component you can trust inside a workflow that touches your CRM or your customers.

What is the difference between a prompt and a prompt spec?

A prompt is the text you send to the model. A prompt spec is the document that explains what the prompt is for, what it receives, what it must return, and how you know it works. The prompt can change as you improve it. The spec is the stable contract that the rest of the automation depends on.

Think of it like any other step in a workflow. A step that writes to HubSpot has a defined input and a defined output. An AI step should be no different. The spec makes that contract explicit, so the steps before and after it can rely on what it does.

It also makes handover possible. Someone who inherits the automation can read the spec and understand the AI step without reverse-engineering a long prompt. I treat it as part of the automation's documentation, alongside the wider one-page spec I write before building any automation.

What should the job statement say?

One sentence that names the task, the input, and the output. For example: "Read a demo request form submission and classify the lead as sales-ready, nurture, partner, or spam." If you cannot write this sentence clearly, the step is probably doing more than one job and should be split into two smaller steps.

Single-purpose AI steps are far easier to test and debug. A step that classifies, extracts a company name, and writes a summary all at once will fail in tangled ways. Three small steps, each with its own spec, fail in ways you can find.

Add one line on why the step exists, too. "So sales-ready leads reach a rep within minutes" tells future maintainers what matters when they have to make a trade-off.

How do you define the inputs?

List every field the step receives, where it comes from, and what it looks like when it is good, empty, or messy. Include the exact field names from the earlier steps in your Zap. Most AI step failures trace back to an input that was empty, truncated, or formatted differently than the prompt assumed.

For each input, note whether it is required. If the company name is required for a good classification, the spec should say what happens when it is missing, rather than letting the model guess.

Keep inputs minimal. Sending the model every available field feels thorough, but it adds noise and cost. Send only what the task needs, and say in the spec why each field is included.

How do you define the output format?

Specify exactly what the step must return: the allowed values, the structure, and the field names. If later steps expect one of four labels, the spec should list those four and nothing else. Ask the model for a structured response, such as a simple JSON object with named fields, so the next step can read it reliably.

Free text is the enemy of automation. A model that sometimes returns "Sales Ready," sometimes "sales-ready," and sometimes "This lead looks sales-ready to me" will break any filter that follows. A strict format, plus a check that the output matches it, solves this.

Include a short reason field in the output when the step makes a judgment. The reason helps humans review edge cases and makes it easier to spot when the model is misunderstanding the task.

What rules and examples belong in the spec?

Write the decision rules in plain language, then add a few examples of correct input and output pairs. Rules tell the model how to decide. Examples show it what good looks like. Both should come from real cases, not invented ones, so they reflect the inputs your automation actually sees.

Rules should be specific. "Mark as spam if the email domain is a known free provider and the message contains no company information" is testable. "Use good judgment about spam" is not.

Examples should include the hard cases, not just the easy ones. A borderline lead, a partner inquiry that looks like a sales lead, a form filled in another language. These are where the model needs the most help.

What should the step do when it is unsure or input is missing?

Define a fallback output for uncertain or incomplete cases, such as a "needs review" label, and route that label to a person. Never let the step invent missing information. A model asked to classify a lead with no company data will produce an answer anyway, and that answer is a guess dressed up as a decision.

The fallback should be one of the allowed outputs, so the rest of the automation handles it cleanly. Downstream, a filter can send "needs review" items to a queue rather than the CRM.

I go deeper on detecting and routing uncertain cases in how to route low-confidence AI classifications to a human. The spec is where you decide which cases qualify.

How do you test the prompt against the spec?

Build a test set of twenty to fifty real inputs with the expected output for each, written by a person. Run the prompt against the full set, compare results, and record every mismatch. Change the prompt only after reviewing the mismatches, then rerun the whole set to make sure the fix did not break other cases.

I keep the test set in Airtable or a Google Sheet next to the spec. Each row holds the input, the expected output, the actual output, and a pass or fail column. Rerunning it after every prompt change takes minutes and prevents silent regressions.

Include the test results in the spec, with the date and the prompt version. That record tells you whether a later change improved or worsened the step.

How do you maintain the spec after launch?

Review it when the step misbehaves, when inputs change, or when you switch models. Add every real failure to the test set so it never recurs. Version the prompt and the spec together, so you always know which prompt produced which results. Treat changes to an AI step with the same care as changes to a CRM write.

Model changes deserve special attention. A prompt tuned for one model can behave differently on another, even within the same provider. Before switching, rerun the full test set and compare.

Keep the spec where the team can find it, and link it from the automation's runbook. If the AI step sits inside a workflow that affects revenue, the guidance in writing a runbook for a Zap that touches revenue applies directly.

What should you do next?

Pick one AI step already running in your automations. Write its job sentence, list its inputs and allowed outputs, and add a fallback for missing data. Then pull twenty real inputs, write the expected outputs by hand, and run the prompt against them. The mismatches will show you exactly what to fix.

Most teams discover that their AI step works well on typical inputs and poorly on a predictable set of edge cases. The spec makes those edge cases visible before customers do.

If you want help writing specs and tests for the AI steps in your GTM automations, reach out. I build and maintain these systems for B2B teams and I am happy to review yours.