Instructions are the biggest thing you control. They tell the Agent what job it's doing, how to do it, and what it must never do. Get these right and everything else gets easier.
Go to Agent → open an Agent → Build → Instructions. The model it runs on sits beside the heading, and the test chat opens from the bar above.
How do I write good instructions?
Write them in blocks. Each block has a title and a body, so a long set of instructions reads as sections instead of one wall of text. Tell the Agent:
- The job, in one sentence
- The steps to follow
- The hard rules, like "never guess at an invoice amount"
- What to do when it gets stuck
Resolve billing questions in one reply. Look up the customer's invoices before answering. If the refund is over $500, hand off to a human instead of promising anything.How do I add and reorder blocks?
Click Add block on a row to add a new block below it. Drag blocks to reorder them. The Agent reads them in the order you see them.
Can the Agent read my files?
Yes, with the Web integration turned on under Build → Integrations. Add files on Build → Knowledge → Files, or drag and paste them straight into the instructions editor.
The instructions hold a link to each file, not the file itself. Web is what the Agent reads a file with when a run needs it, so keep it turned on. Deleting a file under Files also removes its link from the text. Each file there shows which block links to it, its size, and when it was uploaded. Click a file to copy its link or download it.
How do I tell the Agent to use a skill?
Type / in a block and pick a skill. Its name goes into the text as a chip, and the Agent follows that skill when it reaches that step.
The menu lists the skills this Agent has, above the formatting options. A chip with a dashed outline means the skill is no longer on the Agent: add the skill back, or delete the chip.
How do I change the model?
It sits beside the Instructions heading. A model change goes into your draft, so you'll need to publish it.
What are starter prompts?
Suggested first messages, shown when someone starts a new chat with the Agent. Edit them on Manage → Agent settings, or click Generate and Hercules will suggest some based on what the Agent does.
Additional FAQ
Do my edits go live straight away?
No. Your edits save on their own to a draft, and the Agent keeps running the live version until you click Publish. See Versions.
Can I write in Markdown?
Yes. Point at a block, or click into it, and a small toolbar appears at its top right. Click the
Markdown button there. It changes how every block is shown at once, and the instructions
themselves stay the same. Click the Rich text button beside it to go back. In Markdown a skill
chip reads [skill-name](skill:skill-name).
Can I get a deleted block back?
Yes. Deleting a block doesn't ask you to confirm. Press Cmd + Z / Ctrl + Z to undo it, or restore an earlier snapshot of your draft from the version history. See Versions.
Is there a limit on how many blocks I can add?
Yes, there's a cap per Agent. The Add block button stops working once you reach it. Long instructions usually work better split into fewer, clearer blocks anyway.
Where do I describe what the Agent is for?
Manage → Agent settings → Details. The description is a note for you and your teammates. It doesn't change what the Agent does. The tags sit beside it.
How do I know if my instructions are working?
Three ways. Try it in the test chat, run an evaluation against your saved test cases, or let Auto-improve read your run history and suggest fixes.
Can I save with the keyboard?
You don't need to: edits save on their own a moment after you stop typing. Press Cmd + S / Ctrl + S to save right away.
Can my teammates see what I'm writing?
Yes. The draft is shared with the teammates who edit the Agent, and it saves as you go. Your users only ever get the published version. See Versions.