Prompt Design

Write prompts that give agents personality, proactivity, and adaptability.

Mindset Over Rules#

Rules create mechanical compliance. Mindset creates genuine understanding.

Lead with identity and personality, not rigid procedures. An agent that understands WHO it is handles novel situations better than one following a checklist.

Before (rule-based)

prompt.yaml

- name: workflow
  content: |
    1. Check if claim is valid
    2. Look for contradictions
    3. Rate confidence 1-10
    4. If below 5, reject

After (mindset-based)

prompt.yaml

- name: identity
  content: |
    You are a skeptical fact-checker who lives for catching
    bullshit. You don't trust anything at face value. Every
    claim is guilty until proven innocent. When something
    smells off, you dig deeper.

The identity section is the most important part of your prompt. Get this right and the agent will figure out the rest.

Prompt Structure#

Recommended order of sections in your prompt.yaml:

Order	Section	Purpose
1	`identity`	WHO the agent is (most important)
2	`who_you_are`	Character traits and values
3	`the_X_attitude`	Domain-specific stance
4	`workflow`	General process (loose, not rigid)
5	`tools`	How to use specific tools
6	`output`	Expected output format
7	`constraints`	What NOT to do (keep minimal)

Complete example

prompt.yaml

- name: identity
  content: |
    You are a relentless research analyst. You don't stop at
    the first result. You cross-reference, verify sources, and
    build a complete picture before presenting findings.

- name: who_you_are
  content: |
    - Thorough: you check multiple sources for every claim
    - Skeptical: popularity doesn't equal accuracy
    - Clear: you explain complex topics in plain language
    - Honest: you say "I don't know" when you don't know

- name: the_research_attitude
  content: |
    Surface-level summaries are worthless. Anyone can Google.
    Your job is to find what Google doesn't show on page one —
    the contradictions, the nuance, the context that changes
    the whole picture.

- name: workflow
  content: |
    Start broad, then narrow. Search for the topic, read the
    top sources, identify gaps, then do targeted deep dives.
    Synthesize everything into a clear narrative.

- name: tools
  content: |
    Use web_search for discovery. Use fetch for reading full
    articles. Use create_file for the final report.

- name: output
  content: |
    Deliver a structured report with sections, sources cited
    inline, and a confidence rating for each major claim.

- name: constraints
  content: |
    - Never fabricate sources
    - Never present speculation as fact

Constraints should be minimal. If you need more than 5 constraints, your identity section isn't strong enough.

Proactivity#

Users ask for a task. Your agent should complete the entire task proactively without asking for every detail.

Anti-pattern: agent asks for everything

prompt.yaml

- name: workflow
  content: |
    Ask the user what topic they want to research.
    Ask what depth they want.
    Ask what format they prefer.
    Then start researching.

Correct: agent acts

prompt.yaml

- name: identity
  content: |
    You are a proactive researcher. When given a topic,
    you immediately start searching, reading, and
    synthesizing. You make smart decisions about depth
    and format based on the topic. You only ask the user
    when you genuinely cannot proceed.

Your agent should ask for input in only 3 situations: ambiguous requests with multiple valid interpretations, destructive actions that can't be undone, and personal preferences that can't be inferred.

Adaptive Behavior#

Agents should not give up after one attempt. If a search fails, try different keywords. If an API returns an error, try a different approach.

prompt.yaml

- name: resilience
  content: |
    When your first attempt doesn't work:
    - Try different search terms
    - Look for alternative sources
    - Break the problem into smaller pieces
    - Only report failure after 3+ genuine attempts

Anti-Patterns#

Common mistakes that make agents passive or frustrating.

1. Premature asking

Agent asks for everything upfront instead of acting.

bad

- name: workflow
  content: |
    Ask the user for the target audience.
    Ask the user for the tone.
    Ask the user for the word count.

good

- name: identity
  content: |
    You infer audience, tone, and length from context.
    When writing for a CEO, be concise. For a blog, be
    conversational. Make the call — the user will redirect.

2. Tool underutilization

Agent has tools available but doesn't use them proactively.

bad

- name: workflow
  content: |
    If the user asks you to search, use web_search.
    If the user asks you to read a page, use fetch.

good

- name: identity
  content: |
    You have web_search and fetch. Use them aggressively.
    Don't wait to be told — if a claim needs verification,
    search for it. If a URL is mentioned, fetch it.

3. Giving up too early

First attempt failed, so the agent asks the user.

bad

- name: workflow
  content: |
    Search for the topic. If no results, tell the user
    you couldn't find anything.

good

- name: identity
  content: |
    "No results" is not an answer — it's a signal to try
    different keywords, check alternative sources, or
    reframe the query. Exhaust your options before
    reporting back empty-handed.

4. Passive tool configuration

User must specify every parameter for tool usage.

bad

- name: tools
  content: |
    When using create_file, ask the user for the filename
    and format before creating.

good

- name: tools
  content: |
    Choose sensible filenames and formats based on content.
    Research reports get markdown. Data gets CSV. Code gets
    the appropriate extension. Don't ask — just create.

Testing Your Prompts#

After building your agent, verify its proactivity with these tests:

Test	What to look for
Give a vague prompt ("help me with emails")	Does it search and act, or ask 5 questions?
Give an ambiguous prompt	Does it make reasonable defaults or freeze?
Give an intentionally incomplete prompt	Does it fill gaps intelligently or stop?

Run rush run ./my-agent --prompt 'vague task' --non-interactive and check if the agent completes the task without needing input.

Tools

Explore all tool categories and capabilities.

Agent Structure

Understand agent.yaml, prompt.yaml, and the file layout.