Write the Agent brief before adding capabilities.

Start with the job and the person accepting it

Download the fictional brief and the blank outline. Read the completed example before replacing its details with your own. Name who needs the result and who will check it. “Review equipment demand for Tomas before checkout allocation” creates a clearer review relationship than “manage our entire equipment library.”

State what the Agent should receive and return in one sentence. Keep the first role small enough to test from beginning to end. The specification can be written before you configure an Agent, and it should remain understandable to someone who has never opened the editor.

Specify the evidence the task depends on

List required files, source versions, the review range, and timezone. Decide what happens if a file is missing or two sources conflict. In the Pine example, the stock snapshot and reservation rows answer different questions. An unapproved request must not silently become committed demand because its requested quantity is present.

Separate stable references from current work. The overlap and approval rules can travel with the role; this week’s stock counts and reservations belong in the relevant Project. If the task needs a live connection, describe the requirement without treating it as configured. The specification documents intended access; actual account authorization remains a separate step.

Describe a file that a reviewer can inspect

Name the destination Project, filenames, sections, and required source references. A useful output contract makes completion observable. In the sample, allocation-review.md carries overlapping demand and shortage arithmetic, while open-questions.md preserves incomplete return windows. The owner can inspect both instead of relying on an assurance that the task was handled.

Explain how unknown values appear. An explicit missing return time is more accurate than an invented availability promise. Show the arithmetic that can be established and label the remaining coverage incomplete. Keep the file format realistic for the intended reader and check the actual saved output in the acceptance exercise.

Map every proposed component to a reason

Use the method section to distinguish instructions, reference knowledge, Skills, and Tools. Instructions define behavior; knowledge supplies references; a Skill provides a reusable method; a Tool performs an operation. Ask why each proposed component is needed before selecting it in Workspace.

Record connections and approval choices as configuration to review, not effects of this document. Begin with the operations needed for the sample job. The Pine allocation reviewer can be evaluated from supplied files without contacting borrowers or accessing a live inventory system. More available capabilities do not by themselves make the brief more complete.

Put exceptions beside the normal workflow

List external actions that need a separate decision, such as sending a message, approving a purchase, or changing an external record. State when the Agent should stop, ask, or return an incomplete draft. A specification is useful when it explains the difficult case as clearly as the ideal case.

An instruction is not a substitute for reviewing actual tool access and Session approval settings. Configure those deliberately when building the role. If a later task adds unattended work or computer access, revise the brief and acceptance criteria rather than assuming the original draft-review setup covers the new operation.

Finish with examples that can reject the draft

Write a normal case, a missing-input case, and an expected outcome for each. Keep the reviewer reference separate from the task input. The acceptance-test template linked below provides overlapping equipment reservations, a missing return window, and a separately supplied amendment you can use to practice this process.

Review the specification with its owner, then configure and test the Agent. Save the resulting outputs and observations with the brief. When the role changes, record why and repeat the earlier examples. The finished document supports an informed configuration decision; it is not proof that the Agent has already passed its tests.

Try it with a small example.

An illustrative result.

Fictional sample, written to show the expected structure. Your result depends on your inputs and needs review.

Fictional expected specification

Role: equipment-allocation reviewer. Owner Leena; reviewer Tomas.
Inputs: dated serviceable-stock rules, reservation CSV, review range, and timezone.
Outputs: allocation-review.md and open-questions.md in the selected Project.
Method: sum overlapping approved quantities, compare with stock, and separate pending requests.
Evidence: calculations cite stock sources and reservation IDs.
Exception: a missing return time stays unresolved; no later availability promise.
Scope: draft review only; no booking approvals, cancellations, purchases, or external changes.
Acceptance: overlap shortage arithmetic, a missing return window, and a separately supplied approved amendment. No test result has yet been observed.

Before you use the result.

• The brief identifies the job, owner, reviewer, inputs, and saved output.
• Changing Project facts are separated from the reusable method.
• Every proposed capability has a necessary task step.
• Unknowns and external action boundaries are explicit.
• Acceptance cases have expected behavior but no invented results.