Skip to main content
By the end of this page you will have a task that validates, is saved as a private revision, and has been attempted once by a model so you can see whether it works. You need a signed-in CLI (0.1.29 or newer) and, for the debug run, an OpenRouter key. The example throughout the task guides is expense-audit: a task that gives the agent a folder of expense claims and a reimbursement policy and asks it to list the claims that break the policy.

​
1. Decide the outcome and the check

Write two sentences before touching the CLI: what the agent must produce, and how a verifier will decide it is right without trusting the agent. For expense-audit, the agent writes flagged.json naming each non-compliant claim and the rule it broke, and the verifier compares that file with a private answer key. If you cannot state the check, the task is not ready. A task whose only evidence is the agent saying it is done cannot be scored.

​
2. Choose a starter and initialize

Init writes the required structure with explicitly unfinished placeholders:
  • README.md is the task description the agent reads and the judge’s input.
  • workspace/INSTRUCTIONS.md and the rest of workspace/ hold what the agent may read.
  • droyd_env.json declares the runtime, budgets and a one-line theme statement.
  • expense_audit/taskset.py and toolset.py define the task rows, the agent’s tools and the reward.
  • expense_audit/data/expected.json is where the private answer key goes.
  • seeds/world.json is the registry of people and organizations; it starts empty.
  • AUTHORING.md is local guidance and is never uploaded.
To study a complete worked example instead, run droyd task init ledger-example --example ledger-forensics in a separate folder. Examples are reference material; do not copy their answers into your task.

​
3. Replace the scaffold

Write the real task description in README.md and the operating instructions in workspace/INSTRUCTIONS.md. Put the expense claims and the policy document under workspace/. Fill in the theme statement in droyd_env.json. Every TODO must go; a placeholder that raises or returns zero reward is not a finished task. Install the Droyd skill in the task folder so your coding agent can help with the rest:

​
4. Author the verifier

The verifier lives in your task package and never ships to the agent. Keep the answer key in expense_audit/data/expected.json, load it in the reward function, and compare it with what the agent produced. For repository tasks, put independent checks in hidden_tests/; they run against a fresh checkout with the agent’s changes applied, so the agent’s own test output is never the score. Remove the placeholder exceptions and unconditional failures as you complete each part. Review the agent-visible files for anything that leaks the answer, such as a filename or a comment.

​
5. Validate and save a revision

Validation checks layout, file roles, sizes and the manifest. It does not run anything. Push saves an immutable private revision and returns the task id; it starts no compute and is not a submission. If validation fails, the response names the check and the file. Placeholder content, a missing role, an oversized file, or a dependency declared without a lock file are the usual causes. Fix and rerun.

​
6. Make a first debug run

A debug run attempts your pushed revision with a model from Droyd’s catalog and records a trajectory for each rollout. Read the trajectories before you read the scores: a run that solved the task by finding the answer in a README, or that failed because an instruction was ambiguous, tells you what to change next. Debug runs are billed as runtime plus your OpenRouter usage, and they are never official measurements. Success: you have a validated task, a saved revision, and at least one trajectory you have read. Aim for a task that a strong model solves sometimes but not always.

​
Next steps

In active developmentTask authoring is in active development. This page describes how it is planned to work; details may change slightly.