Write instructions your Agent can prove it followed.

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.

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 it with a small example.

Before you use 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.