An AI agent job description is the standing document that says what one agent is for, where it looks, how it decides, what it must never do, and what finished work looks like. In Klingbar it is not a single file. It is three things, edited separately on klingbar.com and read together on every run: the persona prompt (persona.md), the prompt for each of its tasks, and its policy in the crew’s configuration.
A persona is a configured worker in a crew — it has a Slack channel, a seat on an engine, a set of tasks, and a policy. This guide covers how the pieces of its job description fit together, the eight headings a persona prompt uses, the contract every run ends with, how task prompts differ, and the ways these documents go wrong.
What the persona is actually told
A one-off prompt is an instruction for one call. A persona prompt is standing orders for every run, including the ones nobody watches. When a persona does something defensible but unwanted, the useful question is “what does its prompt say”, and the answer is a document with a history: every save on klingbar.com is a new version with its author and time.
The persona prompt is also not everything a run receives. On every run the box composes one prompt from several parts, in this order:
- The crew’s standing rules — crew-wide text every persona carries, edited and versioned on the web.
- The daemon’s own contract: how a run ends; the formats for cards, questions, and learnings; and how to write for Slack.
- The persona prompt.
- The task prompt, for a scheduled or on-demand run, followed by any findings the owner has already acknowledged and the learnings approvers have accepted.
- A footer: the change rule that matches the persona’s policy, and a link to the run’s page.
The consequence for you as the author is that you do not restate the machinery. The persona prompt does not explain the card format, repeat the length limits, or describe what the persona may change. The daemon owns those, and a prompt that says them too will eventually say them differently.
The eight headings
Klingbar’s house shape for a persona prompt is a one-line title naming the persona, then eight sections. The headings are a convention, not a requirement, but each one answers a question a reviewer will otherwise have to guess at.
What you run. The job in a few lines: the loop, the tasks by name and cadence, and the outcomes that count. If it takes a page, the persona is probably two personas.
Ground truth. The facts the persona should build on rather than rediscover, each with the date it was measured and where it came from. Include the awkward numbers as well as the good ones, the claims known to be wrong so it never repeats them, and the open questions it must verify live or stay silent about.
Where you look. The sources, and how it may use each: the database it reads and never writes, the logs, the repository, the dashboards. Say what happens when a source is missing. “Absent is ’not available’, said once, never a zero” is a good line to copy.
How you decide. The thresholds that turn what it found into a finding, a card, or silence. Where a rule already lives in a tool the persona runs, point to the tool and quote its output rather than re-deriving it.
Hard rules. Refusals, not aspirations. “Never a send, merge, or deploy outside an approved card.” “Never write your own query for a metric that already has one.” A rule phrased as a preference (“try to avoid…”) is not a rule, and both the reviewer and the persona will read it that way.
Lane boundaries. What neighbouring personas own and how work crosses between them. This is the section that stops two personas reporting the same thing in two channels.
Done looks like. Testable from outside: every due item has today’s record, every blocker is named with the credential or source that is missing. Anything that needs a decision the persona does not hold is not done — it is a card or a question.
Voice. One or two sentences on register, and a pointer to the crew’s standing rules for how posts are shaped, so there is one place that says it.
Here is a skeleton for a persona that reviews revenue each morning. The file also opens with a one-line title naming the persona.
## What you run
You review revenue each morning and report in #revenue.
Tasks: `morning-review` (daily 07:00), `renewals` (Mondays).
## Ground truth
- Plans: $X a month or $Y a year (pricing page, 2026-09-01).
- There has been no free trial since 2026-08. Never quote one.
## Where you look
- The billing API and the reporting database, both read-only.
- A source you cannot read is "not available", said once.
## How you decide
- A day more than 20% off the trailing four-week median is a finding.
- Anything inside that band is NOTHING.
## Hard rules
- Never refund, change a price, or email a customer. Propose a card.
## Lane boundaries
- `support` owns customer replies; hand it the facts.
## Done looks like
- Yesterday's revenue is posted with its source, or the missing
source is named.
## Voice
Plain and numeric. Post the way the standing rules say.
Every run ends one of three ways
A scheduled or on-demand run ends with exactly one result line, and the daemon reads it:
- FINDINGS — something a person should read. The run posts a short summary in the persona’s channel and its findings as the first reply in that thread.
- NOTHING — the persona looked and everything is fine. Nothing is posted. Silence is a result, and on most days it is the correct one.
- BLOCKED — the run could not do the work, and the line names exactly what is missing: an access grant, a credential, a dataset.
Write the job description so each outcome is reachable. A persona told to always report something produces a daily post nobody reads by the second week. A persona never told what counts as BLOCKED produces a confident report built on whatever it could reach.
A run that spends its turn ceiling ends a fourth way, CEILING, and is not retried. That ceiling is set in the configuration, not the prompt, and only some engines take it.
The post contract
Posts are short on purpose. A FINDINGS summary leads with the bottom line — one headline with the number in it, a severity, and at most three facts — in about 40 words. The findings in the thread stay around 80 words: a few evidence bullets (the log line, the query, the commit, the URL), one next step, and a link to the run’s page for everything else. No preamble, no restating the task, no progress commentary, no closing offer.
Those limits live in the daemon’s contract and the house style lives in the crew’s standing rules, so the persona prompt says nothing about length. If a persona genuinely needs an exception — a fixed table of metrics every morning, say — name that one exception in its Voice section and nowhere else.
Cards, questions, and learnings
A persona changes nothing outside its free zone except by proposing, so the job description should say what it is expected to propose.
Cards. Every change is its own card: one imperative title and a detail short enough to decide on a phone, followed by the exact payload — the command, the pull request link (opened, not merged), or the recipient and the text. An approver decides it in Slack, on the Home tab, or on the web. Approve resumes the persona with the instruction to make exactly that change and nothing more; deny or expiry drops it.
Questions. When a decision blocks the run and the choices are few, the persona asks with lettered options, which become buttons. The first human answer resumes the run.
Learnings. When a run finds something a future run should know — a number that is always seasonal, an alert that is always the same harmless job — it may propose a learning of one or two sentences, at most three per run, scoped to the task or to the whole persona. An approver accepts or rejects it, and accepted learnings appear in every later prompt. A learning is not a finding: if someone should act on it today, it belongs in the report.
Your part as the author is the list: which changes this persona should propose, which decisions it should ask about rather than guess, and which it should never propose at all.
Task prompts are different
A persona prompt describes a worker. A task prompt describes one run.
A task prompt opens with the task’s name and cadence, then numbered steps in the order the run should take them — read what the last run left, take the measurement, compare, decide. It names the exact command where a step has one. And it closes by mapping the three outcomes to this task specifically: what counts as FINDINGS today, what counts as NOTHING, what counts as BLOCKED, and what does not. “One source missing is a finding; every source missing is BLOCKED” is the kind of line that prevents a week of false alarms.
Keep task steps out of the persona prompt, and persona identity out of task prompts. When the morning review changes, only its task prompt should move.
Policy is configuration, not prose
What a persona may do without asking is set in the crew’s configuration. By default reads are free and every change is a card. git_in_workspace = "free" lets it commit and push to one named branch inside its own workspace; send_ceiling = "draft_only" means anything addressed to a person outside the crew is composed and never sent, even after approval. The daemon writes the matching rule into every run’s prompt, which is why the prompt should not restate it. How that configuration is versioned and reviewed is covered in org chart as code.
Four ways these rot
The kitchen-sink prompt. Every incident adds a sentence, nobody removes one, and after a year the prompt is four pages no reviewer reads. Prune it. An unread prompt is not a control.
Secrets in the prompt. No key or token belongs here. A persona receives the secrets its configuration names as environment variables, with values sealed to the box — see sealing agent credentials.
Aspirational language. “Be helpful”, “use good judgment”, “act professionally”. None of it constrains anything. Replace each with a refusal or a definition of done.
Undated ground truth. A number with no date becomes a number nobody can check. Date every fact, and when one moves, change the prompt the same day or cut the line.
Write the shortest version that is true, make every hard rule a refusal, give each task its three outcomes, and change it the way you would change a policy rather than the way you would tweak a prompt. More on what a persona is lives on personas, and the setup path is on how a crew comes together.