# Write the Agent brief before adding capabilities.

Reviewed: 2026-10-18

Canonical: https://clankercloud.ai/templates/agent-specification

Use an Agent specification to connect a repeated job with its inputs, saved output, evidence rules, selected capabilities, and acceptance tests. This template includes a fictional equipment-allocation reviewer and an editable outline. The files are planning material; uploading them does not create an Agent, grant access, or start work automatically.

## What you are working toward

A reviewed Agent specification that can guide configuration and a small acceptance exercise.

## Start with

- One repeated job and an owner who understands it

- An example input packet and a useful saved output

- A reviewer and explicit decisions about external actions

## 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.

## Sample files

Fictional inputs. Download and add to your Project.

- [pine-allocation-agent-brief.md](https://clankercloud.ai/templates/agent-specification-files/pine-allocation-agent-brief.md): Fictional brief for reviewing equipment demand, stock shortages, and missing return windows.

- [agent-specification-outline.md](https://clankercloud.ai/templates/agent-specification-files/agent-specification-outline.md): Editable planning outline; it is not an Agent import format.

## Try this prompt

Copy into a Workspace Session. Opening Workspace does not send it automatically.

```text
Use the fictional Pine Equipment Library brief below to produce agent-specification.md for review. Follow the outline: job and ownership, required inputs, saved output contract, reusable method, proposed knowledge/Skills/Tools, separate connection requirements, allowed actions, exceptions, and acceptance cases. Explain which facts belong in the Project. Do not create or run an Agent, connect accounts, approve reservations, send messages, share, or publish. Mark unspecified details as questions rather than inventing them.

# Fictional agent brief: Pine Equipment Library allocation reviewer
Brief ID: PINE-SPEC-1. Prepared 2026-10-18.
Owner: Leena. Reviewer: Tomas.
Job: review equipment checkout demand against serviceable stock and flag conflicts.
Audience: the internal equipment coordinator, who decides all actual allocations.
Inputs: a dated stock-and-rules file and a reservation CSV with approval status.
Output: allocation-review.md and open-questions.md in the selected Project.
Required sections: source cutoff, overlapping approved demand, shortage arithmetic,
pending requests kept separate, missing return windows, and coordinator questions.
Evidence: cite the stock source and reservation IDs behind every calculation.
Unknowns: missing return times remain unknown; pending requests are not approved.
Allowed work: read supplied records, calculate draft scenarios, and save review files.
Outside scope: approve a request, cancel a booking, notify borrowers, buy equipment,
or change a live inventory system.
Stable method: compare intervals, sum approved quantities, expose missing windows,
show arithmetic, separate pending demand, and verify saved outputs.
Project facts: stock counts, reservation rows, date range, and approved amendments.
Success example: 5 plus 4 approved projectors exceeds stock of 8 by exactly 1.
Difficult example: an approved reservation has no recorded return time.
Response: flag the incomplete window; do not invent a return or promise availability.
Initial rollout: one supervised review; no recurring worker is configured.

```

## Illustrative result

Fictional sample; your result depends on your inputs and needs review.

```text
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 using 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.

## Common questions

### Does the downloaded specification create an Agent?

No. It is an editable Markdown planning document. Use the supported Agent editor to configure the role, review its access, and test the result.

### Where should current stock and reservation facts go?

Keep dated stock snapshots, reservation rows, and approved amendments in the appropriate Project. Keep reusable overlap, evidence, and exception-handling rules in the Agent or a suitable method.

### When is the specification ready?

When its owner can explain the inputs, output, evidence, exceptions, access decisions, and examples that would pass or fail. Configuration and observed testing still come afterward.

## Sources

- [Clanker: create and test a custom Agent](https://clankercloud.ai/learn/build-a-custom-agent)

- [Clanker: knowledge, Skills, Tools, and access](https://clankercloud.ai/learn/agent-knowledge-skills-tools)

- [Clanker: write testable reusable instructions](https://clankercloud.ai/learn/write-reusable-agent-instructions)

- [Clanker Workspace: current product capabilities and availability](https://clankercloud.ai/faq)

## Related

- [Build an Agent you can test, reuse, and hand over.](https://clankercloud.ai/learn/ai-agent-factory)

- [Give the Agent a test with an answer you can check.](https://clankercloud.ai/templates/agent-acceptance-test)

- [Test the work before you reuse the Agent.](https://clankercloud.ai/learn/test-ai-agent-before-reuse)

- [Choose an environment by what the agent must reach.](https://clankercloud.ai/learn/choose-ai-agent-environment)

- [A small packet the next agent can verify.](https://clankercloud.ai/templates/agent-handoff-pack)

- [Give your agents a place to do lasting work.](https://clankercloud.ai/learn/ai-agent-workspace)

[Open Workspace](https://workspace.clankercloud.ai)

[Current pricing and usage](https://clankercloud.ai/pricing)