Building block 3 · The basics
Instructions
Instructions are the house rules for your extension, written in plain words. Charlie always reads a short version, and can open a longer guide when it needs the detail.
What you'd use it for
- Set a firm rule, such as Gmail's "never send, only draft".
- Explain how your tools fit together, or which tool to pick when.
- Keep a long how-to out of the way until Charlie actually needs it.
In your manifest
From the canvas extension, trimmed. The short instructions carry the rules that matter before the first call, and end by pointing to the guide.
"guide": "GUIDE.md", "instructions": "Canvas renders your own HTML in a window; render again with the same slug to update it in place... Before your first render, call read_instructions with guide: \"canvas\"."
The real value is one line of text. It's wrapped here to fit.
What each part means
| Field | What it does |
|---|---|
instructions | Text Charlie reads before every reply. Keep it to rules and a line on when to open the guide. |
guide | The path to a longer text file in your extension folder, such as GUIDE.md. Charlie reads it only when it asks for it. |
topBar.thread.instructions | A small module whose text is given to the chat docked under your extension's top-bar page. See below. |
Always read, or read on demand
Instructions are added to what Charlie reads before every reply. That makes them reliable, and it also means every word costs a little on every turn. Put rules here that must be in front of Charlie before it ever calls your tools.
The guide sits outside that. Charlie opens it with its read_instructions tool, passing guide and your extension name. Charlie won't know to do that on its own, so say in your instructions when to read it, as canvas does.
Detail about one tool's inputs belongs in that tool's description. Instructions are for anything that isn't about a single call.
Instructions for a top-bar chat
An extension with a topBar page can have its own chat docked under that page. That chat gets your extension's instructions, those of any extension in your dependsOn, and then the text from topBar.thread.instructions. Finder uses this to explain its file panes to Charlie. See Surfaces.
Things to know
- Charlie reads instructions once, at startup. Restart Charlie after you change them or the guide.
- A switched-off extension contributes no instructions and no guide.
- Don't write instructions that assume another extension is installed unless you list it in
dependsOn. - The guide path must stay inside your extension folder. If the file is missing or unreadable, Charlie ignores it.
- Thread instructions should be fixed text. Anything that changes from turn to turn belongs somewhere else.
- To see exactly what Charlie was told, open Settings > Instructions.
See it in
Every field, in full: reference: instructions and guide.