Skip to main content

​
Writing a good task for an agent

An agent can inspect its crew workspace, use assigned skills, and recall permitted agent or crew memory. It does not automatically know your unstated definition of done, a credential you did not assign, or a file that exists only on your laptop.

​
What the agent already has—and what it does not

The exact context depends on the crew and adapter, but a task normally starts with:
  • the repository and files mounted into the crew workspace;
  • the agent’s assigned skills and their SKILL.md instructions;
  • memory the agent is allowed to recall, plus crew-shared memory when the task runs in that crew;
  • the task’s issue, prompt, or routine inputs; and
  • only the credentials and tool capabilities granted to that agent or crew.
It does not start with another crew’s memory, an unassigned credential, an unstated issue attachment, a human’s local filesystem, or permission to change production because the prompt sounds urgent. If one of those is required, say which reference should be attached or which capability must be granted. Do not paste a secret as a workaround. The same distinction applies to memory. “Remember the deployment convention” is incomplete if there are several conventions; “store the reviewed staging deploy convention in crew-shared memory, cite the source file, and say when it should be re-checked” gives the agent a durable fact with a freshness boundary.

​
Include five things

  1. Context: name the repository path, issue, crew memory fact, or skill that matters.
  2. Action: say what the agent should inspect or change, in an order that can be followed.
  3. Constraints: state what must not change, especially generated files, public contracts, or credentials.
  4. Acceptance: name executable checks and observable outcomes.
  5. Handoff: say where the result belongs: a file, issue comment, routine output, or Journal entry.

​
A Crewship-shaped task frame

For a lead, add the delegation boundary: which part may be assigned to a peer, what evidence the peer must return, and what the lead will verify before reporting completion. For a routine, add the retry and waitpoint behaviour so a rerun does not silently duplicate an external action. Memory is context, not a specification. Ask the agent to verify remembered facts when they affect a change. Credentials are capabilities, not instructions; assign only what the task needs and describe safe use without asking the agent to reveal values.