How to Write a Job Spec for an AI Agent (Treat It Like a New Hire)

Most agents fail on the brief, not the model

Anthropic's engineers once told their own research agents to "research the semiconductor shortage." One agent went off to study the 2021 auto chip crisis, two others ran the same searches on 2025 supply chains, and nobody divided the work.

Same model, same tools. The only thing missing was a brief.

Their fix, in their write-up of the system, was to give every agent an objective, an output format, guidance on which tools and sources to use, and clear task boundaries. That list should look familiar to anyone who has hired a person. It is a job description.

This is the core skill of the role described in What Is a Marketing Engineer?. A marketing engineer does not get value from agents by hunting for better words; they get it by writing down the job the way a good manager would.

A new hire asks. An agent guesses.

Below is the eight-line spec, how to train an agent the way you would train a hire, where corrections go so they stick, and two specs from systems we run ourselves. Copy the template and you can brief your first agent this afternoon.

The eight lines

Greg Isenberg makes the same argument in his episode on the marketing engineer role: write each agent's brief as if you were hiring someone. His list covers the data and where it lives, when the agent runs, what it filters out, the output, what good looks like, what needs a human, the metric, and where results get written.

We compress that into eight lines and call it the Day-One Spec, because each line answers a question a new hire would ask on their first morning. If a line is blank, the agent fills it with a guess.

Line 1, the job, is one sentence with an outcome in it, not a task. "Write LinkedIn posts" is a task. "Turn each customer call into two posts a sales lead would forward" is a job.

Lines 2 and 3 are the inputs and the trigger: exactly which files, accounts or APIs, and whether it runs on a schedule or when something happens. Line 4 is the limits, the line most briefs skip: what to drop, what it may never touch, what it may spend, and when to stop and hand back.

Line 5 is the output and its address, a file path or a channel, never "in the chat." Line 6 is examples of good and bad work, two or three of each. Line 7 is what needs a person's yes, and line 8 is the one number that says the agent did its job, plus the file where corrections live.

Why a spec beats a clever prompt

The companies that build the models say this plainly. Anthropic's prompting guide tells you to think of Claude as a brilliant but new employee who lacks context on your norms and workflows, and says the more precisely you explain what you want, the better the result.

OpenAI's practical guide to building agents gives the same advice from the other side. Build agent instructions from documents you already have, such as operating procedures and scripts, break them into small steps, make every step a specific action, and write down what to do in the edge cases.

That last part is where marketing agents usually break. What should happen when a lead has no company name, when a post is in Spanish, when the ad account returns nothing on a Sunday?

OpenAI's own Agents SDK defines an agent as a model with instructions, tools and optional guardrails. Your spec is the instructions, and lines 2 and 4 decide the tools and the guardrails.

There is a limit, and Anthropic names it. Its guide to context engineering warns against packing a prompt with brittle if-then rules and recommends a small set of diverse, canonical examples instead.

That is why line 6 is examples, not more rules. Three good outputs and three bad ones teach tone, length and judgment faster than a page of instructions.

The same goes for the tools an agent is given. Anthropic's engineers suggest describing each tool the way you would to a new hire, spelling out the formats and terms you would otherwise assume everyone knows.

Train it the way you would train a hire

Nobody hands a new hire the company card on day one. You start them on small tasks, watch the work, correct it, and widen the job as trust builds.

Isenberg describes agent training the same way, and the model companies agree. OpenAI's guide says human review matters most early in a deployment and names two triggers for handing control back to a person: the agent has failed too many times, or the action is sensitive, irreversible or high-stakes.

In practice that gives you three stages. In week one, a person reads every output before anything happens.

In week two, the person reads a sample, plus every output that touches a customer or money. From week three, the agent runs alone on low-risk work and still stops at line 7.

Promote the agent on evidence, not a feeling. Anthropic's guide to agent evals says 20 to 50 simple tasks drawn from real failures is a great start; keep them, rerun them after every change to the spec, and move to the next stage only when they pass.

Limits are part of training too. The security group OWASP calls the failure mode excessive agency: too many tools, too many permissions, too much autonomy. A memo writer does not need write access to the ad account, and an outbound drafter does not need the send button.

For a fuller test plan, How to Evaluate AI Agents covers golden sets and why one passing run proves very little.

Memory and corrections: every mistake becomes a line

The difference between an agent that improves and one that repeats itself is where the corrections go. If a fix lives only in a chat, it disappears when the chat closes.

Write corrections to a rules file the agent reads on every run. In Claude Code that is CLAUDE.md, loaded at the start of every session; Anthropic recommends keeping each file under 200 lines and writing rules concrete enough to verify.

Isenberg's examples are the right size. An outbound drafter whose openers read as fake gets a new rule in the repo. A content agent that keeps writing bland intros gets three strong samples and three weak ones, and a research agent that asserts things without evidence gets a rule that every insight carries a quote or a link.

Each fix is one sentence. Over a few months those sentences become one of the most useful files you own, because they hold your judgment in a form a machine can follow.

Keep them in your growth repo, versioned, so you can see when a rule was added and why. It is the same idea behind source-of-truth skills: one file holds a fact or a rule, and every agent reads the same file.

Line 8 needs the same care. Pick an outcome, not an activity: an agent graded on messages sent will send more messages, and one graded on qualified replies has to write better ones. Economists call the trap Goodhart's law: a number that becomes a target stops being a good measure.

Spec one: the customer-language scan

Before we write about a topic, we want to know how the people who do the work talk about it. So one of our agents scans 121 practitioner accounts on X for the topic and saves the raw posts for the writer.

Its spec is in the figure. A few lines carry most of the weight.

The limits line caps every run at $0.50, and a typical run costs about $0.02. It also notes that the search words are sent to an outside service, so they never include a client name or anything that identifies us.

The examples line says what good looks like: specific phrases a practitioner would type, such as "quiz funnel", not broad ones such as "marketing". The approval line says the writer decides what gets used, and the output is labelled for what it is: claims by people who often sell a service, not results anyone has checked.

Notice the word missing from the spec: "summarize." The agent saves raw posts because the writer needs people's exact words, and a summary would swap those words for the model's.

It is a small version of the customer truth system, pointed at a public market instead of your own sales calls.

Spec two: the citation checker

The second spec has no AI in it at all, and that is deliberate. Its job is to make sure no article on this site publishes with a citation that does not load.

Before any publish, a short script reads every external link cited in every article file and requests each one the way a browser would. Anything that does not return a working page fails the check, and the publish waits until a person replaces the link.

A few sites refuse scripts but load fine in a real browser. The approval line covers those: a person opens the page, confirms it, and the URL goes on a short list with the date, to be checked again each quarter.

Why write a job spec for a script? Because the spec is about the job, not the worker.

Anthropic's guide to building effective agents says to find the simplest solution that works, which sometimes means no agent at all, and OpenAI's guide says a deterministic solution may be enough. Checking that a link loads needs no judgment. It needs to happen every time.

The eight lines still apply. The limits line says the checker reads and never edits, and the metric line sets the only acceptable number: zero dead links at publish.

The same library runs two more checks before anything goes live: no paragraph longer than three sentences, and no run of eight words copied from a source. Twenty-three articles have gone live since October 13, 2026, with more than 120 drafted behind them.

"Writing all this takes longer than doing the task myself"

For a task you do once, it does. Do not write a spec for it.

The spec pays off on work that repeats: the weekly report, the daily lead check, the research step before every article. A job you do every Monday is fifty-two jobs a year, and the spec gets written once.

Here is what the critics get right. Specs rot when the business changes and nobody updates them, and a spec stuffed with rules turns brittle, the exact failure Anthropic warns about.

The fixes are boring. Keep it to eight lines plus examples, date every rule, and reread the spec whenever the output changes for no reason you can see.

Cost belongs in the spec too, because agents spend more than chat does. Anthropic measured its agents using about four times the tokens of a chat, and multi-agent systems about fifteen times, so a limits line without a budget is unfinished; Controlling AI Token Spend covers how to set one.

Write your first spec this week

Pick one task you did at least three times last month. Choose something with clear inputs and an output you can judge in a minute: a lead list check, a weekly search report, a competitor ad scan.

Write the eight lines in a file, not a chat. Fill line 6 with real examples from your own past work, good and bad, because invented examples teach invented standards.

Run it on last week's inputs, where you already know the right answer. Read every output, count the misses, and turn each miss into one sentence in the rules file.

Then give it a schedule and a stage. Week one, you read everything; if it holds for two weeks, let it run and keep reading whatever touches money or customers.

Where it runs matters less than the spec. In Claude Code the spec can live as a subagent file, with a name, a description of when to use it, the tools it may touch, and the instructions underneath; n8n or a scheduled script take the same eight lines.

Two good first candidates are the Monday growth memo and the outbound signal engine, because both come with an obvious number for line 8.

If you want to learn this on live client work, it is the core of our marketing engineer training. If you would rather hand the build to someone, it is the kind of system our AI automation service builds.

What to read next, and why

What Is an Agent Harness? [explainer]. The spec is the job; the harness is the locks around it. You need both before an agent touches a real system.

Become a Marketing Engineer in 30 Days [plan]. Week three of that plan is building one machine, and a spec is how you start it.

So the simple takeaway is this: if a new hire would have to ask, write the answer into the spec, because the agent will not ask.