Writing Instructions

The instructions you write for a workflow define its behavior — what it should do, how it should do it, and what to avoid. Good instructions are the difference between a workflow that works perfectly and one that’s unpredictable.

Structure of good instructions

A well-written set of instructions typically includes:

What the workflow is — A brief description of its purpose
What it should do — The main task, step by step
How to format output — What results should look like
Edge cases — How to handle unusual situations
What NOT to do — Important constraints and guardrails

Example

Here’s an example of well-structured instructions for a bill tracking workflow:


You are a bill tracking workflow. Your job is to identify bills and invoices
in incoming emails and organize them.
 
**PROCESS:**
 
1. Read the incoming email carefully
2. Determine if it's a bill, invoice, or payment notice
3. If it IS a bill:
   - Extract: vendor name, amount due, due date
   - Add the label "bills"
   - If due within 7 days, also add label "bills-urgent"
4. If it's NOT a bill, take no action
 
**WHAT COUNTS AS A BILL:**
- Invoices with amounts due
- Utility bills (electric, gas, water, internet)
- Subscription renewal notices with payment required
- Credit card statements
- Rent or mortgage statements
 
**WHAT IS NOT A BILL:**
- Marketing emails about "payment methods" or "billing updates"
- Receipts for completed purchases (already paid)
- General account notifications
- Promotional offers
 
**OUTPUT:**
After processing, log a brief summary:
- If bill: "Bill from [Vendor]: $[Amount] due [Date]"
- If not bill: "Not a bill - no action taken"
 
**IMPORTANT:**
- Do NOT archive bills - only label them
- Do NOT send any emails
- When uncertain, err on the side of NOT labeling

Key principles

Be specific

Too vague: “Handle my emails”

Good: “When a new email arrives, check if it’s from a known contact. If yes, keep in inbox. If no, add the ‘unknown’ label and archive.”

Vague instructions produce inconsistent behavior. Specify exactly what you want.

Define edge cases

What happens when:

The email doesn’t fit any category?
Information is missing?
The email is ambiguous?


**EDGE CASES:**
- If amount is unclear, add label "bills-review" for manual check
- If due date is missing, assume 30 days from email date
- If sender is unknown, still process if content clearly indicates a bill

Specify output format

If your workflow generates output (summaries, reports), define the format:


**FORMAT:**
 
Subject: Morning Briefing - [Today's Date]
 
**Today's Schedule**
You have [X] meetings today.
 
- **[Time]** - [Meeting Title]
  [One line of context]
 
**Emails Needing Attention** ([X] emails)
- [Subject] from [Sender] - [What action is needed]

Include constraints

Tell the workflow what NOT to do. This is just as important as telling it what to do:


**NEVER DO THESE:**
- Never delete emails
- Never send emails to external addresses
- Never process emails from @town.com
- Never archive emails from my manager (manager@company.com)

Use headers and structure

Well-organized instructions are easier for your assistant to follow:


**ROLE:**
You are an inbox filtering workflow.
 
**TRIGGER:**
This runs on every incoming email.
 
**PROCESS:**
1. First step
2. Second step
3. Third step
 
**RULES:**
- Rule one
- Rule two

Common patterns

The classifier

For workflows that categorize and route emails:


Classify incoming emails into categories and apply labels.
 
**CATEGORIES:**
- "receipts" - Purchase confirmations, order receipts
- "travel" - Flight, hotel, car rental confirmations
- "newsletters" - Subscribed newsletters and digests
- "alerts" - System alerts, monitoring notifications
- "personal" - Emails from known contacts
 
**PROCESS:**
1. Read the email
2. Determine the most appropriate category
3. Apply the corresponding label
4. Archive if not "personal"

The reporter

For workflows that generate summaries:


Generate a weekly summary of [topic].
 
**GATHER:**
1. Search for relevant emails from the past 7 days
2. Extract key information from each
 
**ANALYZE:**
- Identify patterns and trends
- Note anything unusual or urgent
 
**REPORT:**
Send a summary email with:
- Overview statistics
- Key highlights (3-5 bullet points)
- Items requiring attention
- Links to relevant emails

The watcher

For workflows that monitor and alert:


Monitor incoming emails for [condition] and alert when found.
 
**WATCH FOR:**
- [Specific patterns or keywords]
- [Sender domains]
- [Subject line patterns]
 
**WHEN DETECTED:**
1. Read the full email
2. Extract relevant details
3. Send me an alert email with:
   - What was detected
   - Key details
   - Link to the original email
 
**FALSE POSITIVES:**
Do not alert for:
- [Common false positive 1]
- [Common false positive 2]

What your instructions can reference

Your instructions have automatic access to context that gets filled in at runtime:

Current time — For time-based decisions
Your email address — For identifying your own messages
Account info — Which Gmail account is active
Trigger context — The email, calendar event, or other trigger data

You don’t need to ask for these — they’re automatically available when the workflow runs.

Testing your instructions

Start with approval-required mode — See what the workflow wants to do before it does it
Use manual triggers — Test on specific emails or events
Check the run history — Review the decisions and actions your assistant took
Iterate — Refine your instructions based on what you see

Common mistakes

Too vague: “Be helpful with emails”

No structure: A wall of text is harder for your assistant to follow consistently

Missing edge cases: “Process bills” — but what if the email is ambiguous?

No output format: Workflow generates inconsistent summaries each time

Conflicting rules: “Archive all newsletters” + “Keep important emails in inbox” — what if a newsletter is important?

Tips

Read stock workflow instructions. Export a stock workflow and study its instructions. These have been tested and refined over time.

Ask your assistant to build it. It generates instructions based on your description. Use the result as a starting point and customize from there.

Test incrementally. Start with the basics. Add edge cases and constraints as you see issues in the run history.

Include logging. Tell your workflow to log its reasoning — for example, “Log why you classified each email.” This makes it much easier to understand behavior and fix issues.