Agent Prompt Quality Bar Agent Skill

Universal Agent-Prompt Quality Bar

This is the builder's compile check. If no archetype skill matches the user's request, OR if you want a final review pass after picking an archetype, follow these rules to write a great agent system prompt.

A produced agent is good only when it can finish a real run, not when it merely sounds capable.

Required run contract

Before writing the produced system prompt, instantiate this contract for the user's request:

• Trigger / input — what starts the run: a user message, schedule, webhook, file, spreadsheet row, support ticket, document, or event.
• Owned outcome — the one concrete result the agent is responsible for finishing.
• Available capabilities — only the tools, data sources, workflows, agents, or stored skills actually attached or available.
• Missing-capability fallback — what the agent must do when a required integration, credential, workspace, permission, source, or input is absent.
• Done criteria — how the agent proves the job is complete, including tool confirmation, read-back, tests, citations, delivery receipt, or an explicit not-run reason.
• Final response format — the exact receipt, report, draft, diff summary, confirmation, or escalation note the user receives.

Non-negotiable sections

Every produced agent system prompt MUST contain these sections. If any is missing, the agent will underperform.

1. Role and outcome

• One sentence: who the agent is and the _single outcome_ it owns.
• Bad: "You are a helpful AI assistant."
• Good: "You are Acme's Tier-1 Email Triager. You reply to inbound billing and account tickets, or escalate cases that need a human."

2. Trigger and input

• Name what starts a run and what data the agent expects.
• Bad: implicit trigger.
• Good: "A run starts when the user provides a support ticket or a scheduled inbox workflow passes unread tickets to you."

3. Decision rules

• 3–6 bullets stating the defaults the agent uses when the request is ambiguous.
• Replace broad "ask the user" language with explicit choices unless action is impossible or unsafe.
• Bad: "If unsure, ask the user."
• Good: "If the customer didn't specify a region, default to the account's billing country and state that assumption once."

4. Capability awareness

• Describe capabilities only if they are attached or available.
• Phrase them in outcome terms, not internal ids.
• Bad: "Use sheetsTool and emailWorkflow."
• Good: "You can read and update the connected leads sheet, and you can draft follow-up emails."

5. Missing-capability fallback

• Include explicit behavior for missing integrations, credentials, workspace, permissions, or data.
• Bad: agent silently invents success.
• Good: "If spreadsheet access is missing, stop and say: 'I need access to the leads sheet before I can update rows.'"

6. Communication style and final response format

• Tone, length, structure, and exact output shape.
• Bad: "Be friendly and helpful."
• Good: "Return a receipt with: action taken, affected records, status, verification, and next step if any."

7. Refusals and escalations

• What the agent will not do, and what it does instead.
• Always include out-of-scope and missing-capability refusals.
• For real user data or external systems, include destructive-action and privacy/security boundaries.

8. Completion criteria

• An explicit numbered list of conditions that MUST all be true before the agent stops.
• This is the single most important section. It is the #1 reason agents stop mid-task or wander.
• Good:

> Completion criteria — you are NOT done until:

>

> 1. The action was attempted, not merely planned.

> 2. The result was verified by read-back, status code, test output, citation, or tool confirmation.

> 3. Failures are reported with the specific item and reason.

> 4. The final response follows the required format.

> Stop only when all four are true.

9. Worked example

• Include one short input → behavior → final output example.
• The example must demonstrate a complete run, including verification or a clean fallback.
• Do not leave placeholder names or vague "then respond" endings.

Mandatory final audit rubric

Before calling the tool that writes the produced system prompt, verify every item below is true:

• Single concrete outcome: the role owns one job, not a vague domain.
• Named trigger/input: the prompt says exactly what starts a run.
• Capabilities are accurate: the prompt describes only attached/available tools, workflows, agents, data sources, or stored skills.
• Missing integration behavior exists: the prompt has a clean refusal/fallback for absent tools, credentials, permissions, workspace, or source data.
• Completion criteria are verifiable and tool-aware: done means confirmed, read back, tested, cited, delivered, or explicitly not run with a reason.
• Final response format is specified: the user knows what receipt/report/draft/confirmation to expect.
• No placeholders remain: no <...>, "TBD", "TODO", "your company", "policy here", or generic policy gaps.
• No internal terms leak: no builder playbook names, tool ids, schemas, file paths, or implementation jargon.
• No unsupported promises: the prompt never claims the agent can browse, send, edit files, access sheets, run tests, or update accounts unless that capability is attached.
• Refusal path is present: unsafe, out-of-scope, destructive, or unsupported requests have explicit behavior.
• Worked example completes a full run: not just a sample input; it shows the expected action and final output.

If any item fails, revise the system prompt before writing it.

Universal anti-patterns to reject

• No completion criteria. Agent never finishes. Fix: add a numbered "done when" list.
• "Ask the user if unsure." Agent stalls on every request. Fix: state defaults, and ask only when action is impossible or unsafe.
• No scope. Agent drifts into unrelated requests. Fix: explicit in-scope / out-of-scope lists.
• Too many tools. Agent makes worse choices with more options. Fix: attach the minimum.
• Generic identity ("helpful assistant"). Produces generic output. Fix: name a specific outcome.
• No missing-capability fallback. Agent hallucinates success. Fix: state exactly when to stop and what to tell the user.
• Marketing voice in instructions ("be amazing", "delight users"). Untestable. Fix: concrete behaviors.

How to use this skill

If you already activated an archetype skill (coding, spreadsheet, research, customer-support, content-writer, ops-automation, generic-assistant), the archetype's template provides the domain rules. Use this skill as the final compile check.

If no archetype fit and the user's outcome is genuinely novel:

• Draft the run contract.
• Write each required section from scratch.
• Apply the mandatory final audit rubric.
• Reject anything that drifts toward the anti-patterns list.

Cross-references

• coding-agent — for code-writing/editing/review agents.
• spreadsheet-agent — for tabular data agents.
• research-agent — for research-and-report agents.
• customer-support-agent — for ticket / inbox triage agents.
• content-writer-agent — for marketing / blog / social agents.
• ops-automation-agent — for recurring / event-driven internal automation.
• generic-assistant — fallback for general personal helpers.