> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Write good instructions
> Creating good integrations starts with describing what you want it to do
A node's instructions determine what the node does when it runs.
It's important not to write vague or confusing instructions. Clear, well specified instructions are the key to cheap, fast and accurate integrations.
## What do good instructions look like?
Write every [agent node](/concepts/nodes) instruction in four parts.
| Part | What it holds |
| :--------------- | :------------------------------------------------ |
| Goal | One sentence on what this node achieves |
| Ordered steps | The actions, in the order the workflow takes them |
| Edge cases | The variations that the site might throw |
| Success criteria | What the workflow can see when the work is done |
```
Your goal is to submit the consultation form for the current patient:
1. Click "New Consultation"
2. Fill the form fields with the provided data
3. Upload any provided attachments
4. Click "Create"
Edge cases:
- If a modal appears, close it before continuing
- If the page asks for confirmation, accept it
Success criteria:
Once you see the "Consultation Submitted" banner, the task is complete.
```
Success criteria carry more weight than they look like they do. Without one, the workflow has to guess when it is
finished, and a guessing workflow keeps clicking.
Name the button text, the field label, and the banner exactly as the site shows them. The workflow reads the page,
so the words you write and the words it sees should match.
## Size a node right
One node does one subtask. A node that logs in is a node. A node that logs in, searches, and files a report is
three nodes wearing a trenchcoat.
Split a node when:
* The instruction runs past a dozen steps.
* Two halves of the instruction can fail for different reasons.
* You want a different [transition](/concepts/transitions) out of each half.
* One half is stable and the other is fragile.
Keep a node whole when the steps only make sense together — open the modal, fill it, submit it.
Smaller nodes cost you nothing and buy you three things. The failure point is clearer. The instruction is
shorter. Each half gets its own failure path. Read [Workflows are graphs](/concepts/graphs) for how the pieces fit.
## Pass values in
Write `{{.variable_name}}` where a value changes from run to run. The caller supplies the values at run time,
so one workflow serves every case.
```
Navigate to the patient search page:
1. Enter {{.patient_name}} into the search bar
2. Select the matching result
3. Fill in {{.diagnosis}}
4. Click Submit
```
### Naming rules
A variable name:
* Contains letters, numbers, and underscores only
* Contains no spaces, and none of `@`, `-`, or `.`
Valid: `{{.user_name}}`, `{{.email}}`, `{{.api_key}}`
Invalid: `{{.user-name}}`, `{{.my@var}}`, `{{.1st_item}}`
Give a variable the name a person would give it. `{{.patient_name}}` tells the next reader what belongs there.
`{{.p1}}` does not.
How values reach an execution, and how the result comes back
## Templating
Write `{{.variable}}` to drop an input value into an instruction at run time.
Reach into nested JSON with a dot path:
```
User: {{.user.name}} ({{.user.email}})
```
```json theme={null}
{"user": {"name": "Jane Smith", "email": "jane@example.com"}}
```
Keep the instruction one shape. A step that needs to branch is a graph that wants to exist. Build the branches
as nodes, and let transitions choose between them.
## When it goes wrong
Watch an execution, find the step that broke, and change the instruction that owns it.
| What you see | What to change |
| :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| The workflow cannot find an element | Name the element the way the page names it. Add the label, the button text, or the section it sits under. Say what to do when the element is missing. |
| The workflow takes the wrong action | Add the edge case that confused it. Say which of two similar controls to use, and say what not to do. |
| The workflow gets stuck and keeps trying | Add success criteria the workflow can see. Split the node so each half has its own ending. |
| The workflow finishes early | Tighten the success criteria. "The task is complete when the confirmation number appears" beats "when the form is submitted". |
| The execution ends in the wrong outcome | Fix the transition descriptions, not the instruction. The workflow picks a transition by reading them. |
Change one thing, then run it again. Two changes at once hide which one worked.
## Best practices
* **Start simple.** Get the happy path running, then add the edge cases you meet.
* **Write down every variation you see.** An execution that surprised you is an edge case you now know.
* **Name nodes and variables so the graph reads itself.** "Find Patient" beats "Node 3".
* **Test with different input values.** It's important that, when the input data changes, the workflow still runs as expected.
* **Add the failure path.** Every agent node needs a route to an output node if it can fail in any way.
Run the draft, read it, change one thing, publish
Turn what production teaches you into changes
What a node is and what it can do
How the workflow chooses where to go next