Writing Workflow Instructions

Internally still called a playbook.

Great workflow instructions are the difference between an agent that nails the task and one that produces something you throw away. This guide covers the patterns that consistently lead to better results.

Be specific about the output format

Agents do their best work when they know exactly what shape the output should take. Vague instructions produce vague results.

Before (vague):

Analyze the sales data and create a report.

After (specific):

Analyze the Q1 sales data. Produce a report with the following sections:
1. Executive Summary (3-5 bullet points)
2. Revenue by Region (table with columns: Region, Revenue, % Change)
3. Top 5 Deals (ranked by value, include customer name and close date)
4. Risks and Recommendations (2-3 actionable items)

TIP

When you specify a format, the agent has a clear target. Tables, bullet lists, numbered sections, and word counts all help constrain the output into something useful.

Tell the agent who the audience is

The same data looks very different in a board presentation versus a team standup update. Always tell the agent who will read the output.

• "This report is for the VP of Sales who needs a high-level overview."
• "This summary will go to the engineering team and should include technical details."
• "This email is for a customer — keep the tone professional and concise."

Break complex tasks into clear steps

Long, sprawling instructions lead to skipped steps and confused output. Break your workflow into discrete phases that the agent can work through one at a time.

Before (monolithic):

Look at all our support tickets from last week, figure out what the
common themes are, write up a report, and then draft an email to
the team about it.

After (structured):

Step 1: Search the workspace for support tickets created in the last 7 days.
Step 2: Group the tickets by category (bug, feature request, question, other).
Step 3: For each category, identify the top 3 recurring themes.
Step 4: Write a summary report with a table showing category, theme,
        and ticket count.
Step 5: Draft a team email (under 200 words) highlighting the top issues
        and any action items.

INFO

You do not need to use numbered steps — but giving the agent a clear sequence helps it prioritize and avoids skipping parts of the task.

Mention the tools the agent should use

If your task requires specific actions like searching the workspace, creating artifacts, or pulling data from a connected integration, say so explicitly.

• "Use the workspace search to find all documents tagged 'Q1 review.'"
• "Create an artifact named 'Weekly Report — March 2' with the final output."
• "Pull the latest pipeline data from the Stripe connection."

Without these hints, the agent may choose a less effective approach or skip external data entirely.

Use workflow inputs for reusable instructions

Instead of hardcoding values like dates, thresholds, or team names, define workflow inputs — runtime parameters that get filled in each time the workflow runs.

Before (hardcoded):

Analyze Q1 sales data and flag any region below $500K.

After (using inputs):

Analyze sales data for the specified quarter and flag any region
below the revenue threshold.

Inputs: quarter (select: Q1/Q2/Q3/Q4), revenue_threshold (number)

This lets you reuse the same workflow every quarter instead of editing instructions each time. Pencel supports text, number, boolean, select, and date input types.

Set guardrails and output schema

Beyond instructions, workflows have two additional quality controls:

• Guardrails are criteria the output must satisfy — like "report must include at least one table" or "total word count under 500." Pencel checks these after the run completes.
• Output schema defines the structured shape of expected outputs — useful when downstream systems or other workflows consume the results.

TIP

Guardrails catch issues that instructions alone miss. Even well-written instructions can produce off-target output — guardrails give you an automated safety net.

Specify success criteria

Tell the agent what "done" looks like. This prevents it from over-delivering or under-delivering.

Weak criteria	Strong criteria
"Make a good report"	"Report should be under 500 words with at least one table"
"Summarize the data"	"Summarize the top 5 trends, each in 1-2 sentences"
"Draft an email"	"Draft a 3-paragraph email with a clear call to action in the last paragraph"

Write for your execution mode

Workflows have two execution modes, and your instructions should match:

Mode	How to write instructions
Agentic (default)	Describe the goal and constraints. The agent decides the sequence of actions. Good for flexible, judgment-heavy tasks.
Guided	Be precise about each step. Specify which tools to use at each point. Best for regulated, auditable workflows where the exact sequence matters.

Start with agentic mode. Switch to guided when you need exact control or an audit trail that maps step-by-step to your process documentation.

Common pitfalls

Too vague

Instructions like "analyze this" or "look into the data" give the agent no direction. Always answer: analyze what, for whom, in what format?

Too long

If your instructions exceed a few hundred words, consider splitting the work into multiple workflows. You can chain workflows together — one workflow's output becomes the next one's input.

WARNING

Extremely long instructions increase token usage and can cause the agent to lose focus on later steps. If you find yourself writing a full page of instructions, break the work into two or three smaller workflows.

A good workflow: start with freeform instructions, run the workflow a few times, then refine by adding structured steps only where you need precise control or approval gates.

Missing output format

The most common mistake is forgetting to say what the output should look like. Without a format, the agent defaults to free-form prose — which is rarely what you want for business operations.

Assuming context the agent does not have

Your agent only knows what is in its system prompt, active guidelines, memory, and workspace files. If the task depends on background knowledge ("you know our pricing tiers"), make sure that information is in a context file or guideline.

Reference context files by name in your instructions: "Refer to product-catalog.md for current pricing tiers" is much more reliable than assuming the agent will find the right file on its own.

Quick checklist

Before you save a workflow, run through this list:

• [ ] Does the instruction say what format the output should be in?
• [ ] Is the audience or purpose stated?
• [ ] Are complex tasks broken into sequential steps?
• [ ] Are required tools or data sources mentioned?
• [ ] Is the definition of "done" clear?
• [ ] Is the instruction under 300 words (or split into sub-workflows)?
• [ ] Are hardcoded values replaced with workflow inputs where applicable?
• [ ] Are guardrails set for critical quality criteria?

Example: Putting it all together

Here is a complete workflow instruction that follows all of these practices:

You are preparing a weekly operations summary for the leadership team.

1. Search the workspace for all artifacts created in the last 7 days.
2. Group them by category: reports, meeting notes, and action items.
3. For each category, write a 2-3 sentence summary of key highlights.
4. Create a table with columns: Category, Item Count, Key Takeaway.
5. End with a "Priorities for Next Week" section (3-5 bullet points).

Output format: A single artifact named "Ops Summary — [current date]".
Keep the total length under 600 words. Tone should be professional
but accessible — no acronyms without definitions.