# Write instructions your Agent can prove it followed. Reviewed: 2026-09-12 Canonical: https://clankercloud.ai/learn/write-reusable-agent-instructions Give a reusable Agent a narrow job, explicit inputs, an inspectable output, and rules for incomplete information. Test those instructions against both a normal example and a case that should make the Agent ask a question or withhold a conclusion. ## What you are working toward A reusable Agent brief with acceptance criteria and a small evaluation set. ## Start with - One repeatable job you can evaluate yourself - A good example and an incomplete example - The information the Agent may use and actions it may take ## Describe the job as an input and output Start with a sentence you can test: “Given dated project notes and an approved plan, prepare a status update for the client.” This defines the work more clearly than “Be a world-class project manager.” Add the reader, the expected sections, and the decisions the result should help that reader make. Specify the minimum inputs. If the task needs a reporting period and approved milestones, say what happens when either is missing. The Agent can prepare an incomplete draft with open questions instead of inventing dates. A useful instruction distinguishes a missing fact from a fact that can be derived from supplied evidence. ## Separate reusable behavior from Project facts Put the repeatable method, tone, and review checklist in the Agent’s instructions. Put client-specific definitions, current source files, and standing preferences in the relevant Project. Keep one-off revision requests in the Session. This lets the same specialist work on different engagements without carrying one client’s facts into another. Avoid copying an entire historical conversation into the role. Old instructions may contain obsolete deadlines, exceptions, or contradictory requests. Extract the rule you still intend to apply. If two instructions conflict, rewrite them into one clear decision rule instead of expecting the Agent to infer which sentence matters more. ## Replace vague rules with observable behavior The following fictional status-report instructions show how to turn a preference into something a reviewer can verify. Each output test has a corresponding input or exception. These are instructions you write, not built-in enforcement controls or a promise that every generated answer will satisfy them. The exception is as important as the normal case. “Always provide an owner” encourages a completed-looking report; “show Unassigned when the notes give no owner” preserves the information needed to fix the actual project. Design the rule around the decision, not the appearance of completeness. | Weak instruction | Testable replacement | Evidence to inspect | | --- | --- | --- | | Be concise. | Keep the main update under 300 words; list open questions separately. | Word count and separate questions. | | Find the next steps. | List only agreed actions; label suggestions as proposed. | Each action matches a dated note. | | Make it actionable. | Include an owner and date only where stated. | Missing values remain visible. | ## Treat access as a separate configuration Instructions describe how to work. They do not connect an account, grant access to a file, or create a permission boundary by themselves. In My Agents, inspect the knowledge, Skills, and selected Tools that support the job. A drafting Agent needs a different capability set from one that updates another system. Add a Skill when the role benefits from a reusable method; add a Tool when it needs an operation. State the action boundary in the brief, then review the actual capabilities and Session approval mode. Use Ask while evaluating changes. Do not rely on a sentence in the prompt to compensate for unnecessarily broad access. ## Test a normal case and a difficult case Use a small example with a known answer. For a status Agent, include one completed milestone, one blocked task, and one unassigned action. Check source accuracy before judging the tone. A polished report that silently turns a proposed date into a commitment fails the test even if its structure is perfect. Then remove a critical input or add conflicting notes. The Agent should expose the conflict and explain what it can still produce. Record the observed result beside the intended behavior in an ordinary evaluation document. Change one instruction at a time so you can tell which revision improved the outcome. Keep the example inputs unchanged during that comparison; otherwise, a different answer may reflect different evidence rather than improved instructions. ## Keep the role understandable as it evolves Save the improved Agent after checking both examples again. Use Agent version history when you need to restore an earlier setup. Keep a short note explaining a material instruction change and the failure it addresses; that note makes later decisions easier than accumulating unexplained rules. If the instructions grow into a collection of unrelated jobs, split the work into clearer roles or return shared context to the Project. Recheck examples when you change reference files, Skills, or Tools. A role tested for drafting a report has not automatically been tested for sending it, editing a database, or running without supervision. ## Try this prompt Copy into a Workspace Session. Opening Workspace does not send it automatically. ```text Draft instructions for a reusable Project Status Agent. Its inputs are dated notes and an approved plan. Its output is a short update with progress, blockers, decisions, and next actions. Every commitment needs a source. Missing owners or dates stay unresolved. It may draft files but may not send updates or change external systems. Include two test cases and explain what belongs in Project instructions instead. ``` ## Before using the result - Inputs and output have observable acceptance criteria. - Missing information triggers the intended behavior. - Changing Project facts are absent from the reusable role. - Selected capabilities match the role. - Both normal and conflicting examples pass review. ## Common questions ### Can I make my own Agent and share it? Yes. Describe the job in plain English, then customize the Agent’s personality, instructions, knowledge, skills, and tools. Test it privately in Workspace. When it is ready, create a private link so someone can sign in and add a copy, or review and publish a separate version to the Agent Marketplace. [Read more in the FAQ](https://clankercloud.ai/faq#custom-agents) ### What is the difference between an Agent, a Skill, and a Tool? An Agent is the assistant with instructions and selected capabilities. A Skill supplies a reusable method. A Tool performs a reusable operation. Choose only the files, skills, and tools the Agent needs, then test it on one familiar task. [Read more in the FAQ](https://clankercloud.ai/faq#agent-skills) ### How do I control approvals? Session settings include Ask, Notify, and AUTO. Choose Ask when you want to review changes first. AUTO approves all enabled actions, so check the Agent’s access and capabilities before using it. [Read more in the FAQ](https://clankercloud.ai/faq#approval-mode) ## Sources - [Workspace guide: reusable Agents](https://workspace.clankercloud.ai/#page=faq&tab=articles&article=reusable-agent) - [Workspace guide: Session settings](https://workspace.clankercloud.ai/#page=faq&tab=articles&article=first-useful-session) ## Related - [One familiar job. Your own specialist.](https://clankercloud.ai/learn/build-a-custom-agent) - [Give an Agent the right knowledge, method, and operations.](https://clankercloud.ai/learn/agent-knowledge-skills-tools) - [Choose approvals around the actions you intend.](https://clankercloud.ai/learn/choose-approval-mode) [Open Workspace](https://workspace.clankercloud.ai) [Current pricing and usage](https://clankercloud.ai/pricing)