sanity-io/shape-your-agent

Shape Your Agent

An optional, conversational workflow for creating a system prompt for an AI agent that uses the Sanity Context MCP server. This is for users who control the system prompt in their agent setup.

Don't have access to the system prompt? Skip this skill entirely. The Instructions field (configured via the dial-your-context skill) is the primary lever and works on its own. A minimal system prompt like "You are a helpful agent." combined with good Instructions field content scores 80%+ in our evaluations.

Before You Start

What the system prompt is for

The system prompt defines agent behavior — who it is, how it talks, what it refuses to do. Think of it as the agent's personality and policy manual.

What the system prompt is NOT for

These are handled elsewhere — don't duplicate them:

| Concern | Handled by | | ---------------------------------- | -------------------------------------- | | Content schema, field meanings | Instructions field (Dial Your Context) | | Query patterns, data relationships | Instructions field (Dial Your Context) | | GROQ syntax and guidance | MCP auto-provides | | Response formatting rules | MCP auto-provides |

Duplicating these in the system prompt creates conflicts. The MCP and Instructions field are purpose-built for data concerns — let them do their job.

The golden rule: less is more

Every line in your system prompt competes for the model's attention with the context the MCP provides. An over-engineered prompt can actually degrade answer quality. Start minimal. Add rules only when you have a concrete scenario that needs one.

---

How to run this session

This is a conversation, not a form. Ask questions, listen to the answers, and adapt. Don't run through the steps as a checklist — let the user's responses guide which areas need more depth. Some users will have strong opinions about tone and need 5 minutes on boundaries. Others will need help thinking through edge cases but already know their voice. Follow the energy.

---

Step 1: Understand the Use Case

Start by answering these questions:

1. Who uses this agent? (customers, internal team, developers, general public)
2. What setting? (support chat, docs site, internal tool, sales assistant)
3. What problem does it solve? (answer product questions, troubleshoot issues, find content)
4. What's the user's typical state? (exploring, stuck, evaluating, frustrated)

These answers drive every decision that follows. A support agent for frustrated customers needs different rules than a docs assistant for developers.

Step 2: Define Behavior

Choose concrete positions on each axis:

Tone: Professional / Casual / Friendly / Technical

• Bad: "Be friendly and professional"
• Good: "Use a warm, first-name tone. No corporate jargon. Write like a knowledgeable coworker, not a press release."

Verbosity: How much detail by default?

• Bad: "Be concise but thorough"
• Good: "Lead with a 1-2 sentence answer. Offer to elaborate. Never open with more than 3 sentences before getting to the point."

Technical level: Match the audience.

• Bad: "Adjust to the user's level"
• Good: "Assume the user knows JavaScript and REST APIs. Don't explain what an API key is. Do explain Sanity-specific concepts like GROQ projections."

Step 3: Set Boundaries

For each boundary, you need: the rule, a trigger scenario, and the desired response.

What to refuse:

• Example: "If asked to write or modify content in the dataset, explain that you're a read-only assistant and point them to the Sanity Studio."

What to redirect:

• Example: "For billing or account questions, say: 'I can help with product questions, but for billing please contact [email protected].'"

Guardrails:

• Example: "Never mention competitor products by name. If asked to compare, describe our capabilities without naming alternatives."
• Example: "Don't quote specific pricing. Say 'Check our pricing page at [url] for current plans.'"

When information isn't found:

• Example: "If the query returns no results, say so honestly. Suggest 2-3 related topics you can help with. Never fabricate an answer."

The cut test: For every rule, ask: "Can I describe a real user message that would trigger this?" If not, cut the rule. Untriggerable rules are dead weight.

Step 4: Draft the Prompt

Assemble your answers into a prompt. Use this structure:

You are [role] for [company/product].

## Voice
[2-3 concrete tone/style rules]

## Boundaries
[Only rules that passed the cut test]

## When you don't know
[Specific fallback behavior]

That's it. Most agents need 200-400 words here, not 1500.

Example: E-commerce Support Agent

You are a customer support agent for Acme Store.

## Voice
- Warm and conversational. Use the customer's first name if provided.
- Keep answers short — lead with the answer, then explain if needed.
- No marketing language. Don't upsell or promote products unprompted.

## Boundaries
- Never process returns, refunds, or order changes. Direct customers to [email protected] for order issues.
- Don't quote exact shipping times. Say "typically 3-5 business days" and link to the shipping policy page.
- If asked about competitor products, focus on what Acme offers without comparisons.
- Don't share internal inventory numbers. Say whether something is "in stock" or "currently unavailable."

## When you don't know
- Say "I don't have that information" directly. Don't hedge or speculate.
- Suggest related topics you can help with.
- For urgent issues, direct to live support at [email protected].

This is ~150 words. It covers role, voice, boundaries, and fallback behavior. Everything else — product data, schema details, query patterns — lives in the Instructions field and MCP.

Step 5: Review & Iterate

Test your prompt against real scenarios:

1. Write 5-10 questions your users would actually ask. Include at least 2 edge cases (something off-topic, something you want refused).
2. For each boundary rule, write the question that triggers it. Verify the agent handles it correctly.
3. Try removing rules one at a time. If the agent still behaves correctly without a rule, that rule was unnecessary. Cut it.
4. Check for conflicts with the Instructions field. If both the system prompt and Instructions field address the same concern, remove it from the system prompt. The Instructions field wins for data concerns.

Signs your prompt is too long

• The agent ignores some rules (attention dilution)
• Answers feel generic or templated (over-constrained)
• The agent repeats phrasing from the prompt verbatim (parroting)

Signs your prompt is too short

• The agent's tone is inconsistent across conversations
• Users get answers to questions that should be refused
• The agent speculates when it should say "I don't know"

---

Quick Reference

System prompt checklist

• [ ] Role is defined in one sentence
• [ ] Tone rules are concrete (not "be professional")
• [ ] Every boundary has a trigger scenario
• [ ] Fallback behavior is specified
• [ ] No overlap with Instructions field content
• [ ] Under 500 words (aim for 200-400)
• [ ] Tested against 5+ real user questions

The separation principle

| Layer | Controls | Example | | ---------------------- | ------------------------- | -------------------------------------------------------------- | | System prompt | Agent behavior | "Never quote exact pricing" | | Instructions field | Data guidance | "Products are in the 'product' type with a 'price' field" | | MCP | Query mechanics | GROQ syntax, response formatting | | System prompt | Communicating uncertainty | "Say 'I don't have that information' and suggest alternatives" | | Instructions field | Recovery tactics | "If product search returns empty, try support-article type" |

Each layer has its job. Don't cross the streams.