Your AI Teammate's Guidance window is a system prompt — treat it like one

English Forum Asana AI
,
1

A few weeks ago I posted a step-by-step breakdown of how we built our first AI Teammate to automate ocean shipment tracking. That post covered the mechanics: the project structure, the custom fields, the Teammate configuration.

This is a short follow-up about a conceptual mistake we made that I suspect is common.

What we got wrong

When we built the Cargo Clerk, we filled the Guidance window with ~4,000 characters of hyper-specific instructions to perform a single, detailed task. It worked — the Teammate performed exactly as specified — but we had hard-coded it to a single function, limiting its value.

The Guidance window was a monolithic SOP. One Teammate, one job, forever.

A conversation with Michael Saunders this week made me realize that wasn’t going to work at scale. We’d made an architecture mistake: the Guidance window is the system prompt. Tasks are the user prompt.

Reframing the Teammate

If you’ve worked with any LLM API, this is obvious in hindsight. System prompt defines the agent’s identity and boundaries. User prompt delivers the specific instruction. They serve different functions and should carry different content.

In Asana AI Teammates, the same split applies:

  • Guidance window → role definition (who the agent is, what it’s accountable for, how it responds)

  • Tasks / task descriptions / SOP references → function instructions (what to do, step by step, for this specific job)

Here’s roughly what our Cargo Clerk’s Guidance window is going look like next week, after stripping out the function-specific content:

You are the Cargo Clerk for Ideal Security. You track inbound shipments and answer team questions about them.

Your job:
- Monitor all active POs and inbound shipments from origin to warehouse
- Maintain current status: ETD, ETA, vessel, port, customs, delivery
- Flag delays and exceptions proactively
- Answer shipment questions with specificity — dates, vessels, ports, not approximations

Your limits:
- You don't place orders, modify POs, or make supplier commitments
- If data is missing, say what is known and what isn't — don't speculate

How you respond: Lead with current status. Be brief if things are on track. If not, state the issue and the next update point. No padding.

The function-specific instructions — the ones that used to crowd the Guidance window — move into the assigned task, a task template, or a standing SOP task that gets referenced.

Why this matters

Three practical benefits:

  1. Gets around the 4,000-character limit. The Guidance window is a constrained space. Task descriptions are not.

  2. One Teammate, multiple functions. Assign different tasks, different SOPs, different templates — same underlying agent.

  3. Faster iteration. You can test variations of a function prompt quickly, in parallel, without touching the Guidance window at all.

The anthropomorphic analogy: it’s exactly like onboarding a human. You define someone’s role broadly when you hire them. Then you train them on each specific function — separately, over time, using job aids and SOPs. You wouldn’t cram every procedure they’ll ever need into the job description.

We did the equivalent of that. Now we’re unwinding it.

Where we are now

Next week we’‘ll be testing a broader role definition in the Cargo Clerk’s Guidance window and moving the function-specific instructions into tasks and task templates. We’ll report back.

Has anyone else run into this? Curious whether the monolithic-Guidance-window mistake is common, or whether we just missed something obvious in the documentation.

9 Likes