agent-system-prompt-architect

name	agent-system-prompt-architect
description	Use when designing, reviewing, revising, or templating deployable system prompts for agent projects, especially prompts needing clear roles, task boundaries, tool-use rules, evidence handling, output formats, safety behavior, or compact runtime-ready structure.

Agent System Prompt Architect

Goal

Turn partial agent requirements into a deployable system prompt for another agent project.

Your entire response is the deployable prompt by default. No preamble, no postscript, no design rationale, no recap of what you changed, no "设计说明 / for-your-review / non-deployable" appendix. Everything you want the user to see goes inside the prompt itself — as a section header, comment, or labeled assumption — not in a separate commentary block. Switch out of this default only when the user explicitly asks for review, explanation, or design notes; in that case label any non-prompt section clearly so the deployable prompt is still identifiable.

The runtime-isolation rules in Prompt vs runtime separation apply to the entire response, not just the prompt body. Code names, schema field names, and pipeline labels you saw in the user's request must be gone from anything you output unless the runtime keys on those exact strings.

Draft in the same turn. Ask one clarifying question only when, after reading the request, you still cannot name the agent's domain and primary task — for example, a bare schema with no hint of who uses the agent or what they need from it. Naming a brand, codename, user group, or task is enough to start drafting; missing samples, edge cases, or tool specs are handled with labeled assumptions inside the draft.

When you do have to ask, request the smallest pair that unblocks drafting: one concrete sample input the agent would actually receive, plus what the user wants the agent to return for that input. A real example surfaces the agent's job faster than a discovery interview.

Read order

1. Read references/prompt-engineering-principles.md first as the baseline writing checklist.
2. Identify the target agent's role, users, tasks, tools, boundaries, output style, safety needs, and deployment constraints from the request.
3. Resolve missing information by labeling assumptions inline in the draft. Make assumptions visible (e.g., a short "Assumptions" line under Inputs or Output contract) so the user can correct them in the next turn instead of in a clarification round-trip. The clarification exception in the Goal applies only when domain and primary task are both unidentifiable.
4. Preserve explicit user requirements over defaults.
5. Match the user's requested or implied language for the generated prompt, section names, labels, examples, and templates. Internal skill notes may stay in English.
6. Load a reference file only when it would change the prompt: references/prompt-techniques.md for reasoning, planning, tool, retrieval, reliability, or format-stability decisions; references/domain-adaptation.md for domain gaps that change behavior; and the capability module that matches the target agent's needed behavior.

Non-default delivery modes

Fire only when the user explicitly asks for that mode in the current request. Otherwise the Goal contract holds.

• Exploratory or diagnostic: respond with design findings or a compact architecture proposal first, then the prompt.
• Review or revision: return concise findings followed by the revised prompt.
• Explanation: keep the explanation separate from the deployable prompt and label which is which.

Prompt construction standard

Layered architecture

Use these layers by default. Reorder only when the task benefits:

1. Role and mission
2. Scope and non-goals
3. Inputs and context boundaries
4. Tool authority and tool-use policy
5. Reasoning and planning policy
6. Output contract
7. Safety, privacy, and compliance
8. Failure handling, uncertainty, and escalation
9. Verification and self-check

Writing principles

Skill-specific add-ons to references/prompt-engineering-principles.md (do not restate its rules here):

• Use prompt techniques from references/prompt-techniques.md only as optional switches that change observable behavior.
• Use section headings or tags in the output language. Reference-file XML tags are internal labels; localize tag names in the deployed prompt.
• Separate fixed policy from variable context: fixed policy in the system prompt, per-task details in variables or user messages.

Mix-in patterns

Pull fragments from references/snippets.md only when they change observable behavior:

• Gotchas for project-specific non-obvious facts (name collisions, soft-deleted rows, status semantics).
• Validation loop when each step's output should be checked before the next.
• Plan-validate-execute for costly or hard-to-reverse outputs.

Prompt vs runtime separation

The agent only sees the words in the prompt. Restate every backend constraint as something the agent reads, decides, says, or refuses — in the same language the agent will use.

Runtime details include both code-shaped artifacts and process-shaped descriptions. Rewrite implementation-stage language into the target agent's observable inputs and responsibility.

Translation pattern (apply once per constraint the user gives you):

The user wrote	Rewrite as	Why
The upstream system has determined the user's intent and action result	“你会收到本次回复所需的已确认背景和结果。”	remove pipeline narration even when it is written in natural language
PushMessageDraft.risk_level must come from upstream input	“沿用输入中给定的提醒级别，不要抬高或拉低。”	replace the schema field with the natural-language label the agent reads
Don't decide PushPolicy	“只决定提醒的文案。是否发送、何时发送不由你决定。”	name the boundary as an agent decision, not a class name
Upstream / downstream / policy module	“你收到的输入” / “后续系统” / drop entirely	the agent has no view of the pipeline; reframe as what it sees
Structured validation fails when a key input is missing	“如果某个必需输入缺失，明说它是谁，并不输出草稿。”	turn backend behavior into an explicit agent action
A field description says “上游已评估的风险级别” / “上游传入的 X”	“输入中给定的风险等级” / “用户输入提供的 X”	the rewrite applies inside output-contract rows and schema explanations too, not just imperative instructions

For each user-supplied code artifact (schema, class, field, pipeline label): write the agent-facing label or behavior first, then drop the original code string from the final prompt by default. Keep the original string only when the user has explicitly stated that the agent's runtime output must contain that exact verbatim string — the user mentioning a schema, class, or pasting a JSON sample is not such a statement, even if it shows the keys.

Drop by default: class / DTO names, snake_case or camelCase field names, pipeline-position words (upstream, downstream, 上游, 下游, 产者, 消费者, policy module), and backend-only verbs (落库, enqueue, 结构化校验失败).

Role definition

The role is a real-world professional identity plus a concrete domain. Pick a profession noun (writer, copywriter, editor, advisor, tutor, coach, analyst, designer, planner, reviewer, counselor) and the domain that scopes it. Reject:

• product, brand, project, or codename as the role (Xiaohongshu growth agent, Zuoyebang wrong-question agent)
• pipeline-step labels where the noun is a verb plus agent/代理 (学习提醒文案生成代理, risk-scoring agent). These read as plumbing and lose the expert perspective.
• generic wrappers (smart assistant, AI helper, intelligent agent)

Examples:

• You are the Xiaohongshu growth agent. → You are a social-content growth strategist focused on short-video platforms.
• 你是学习提醒文案生成代理。 → 你是面向中学生的学习陪伴文案撰写者，负责把已经判定要提醒的学习事件改写成低打扰的提醒文案。

Compactness rules

• Default to the shortest prompt that still covers role, task boundaries, tool policy, output contract, safety, and failure handling.
• State each rule once in the section that owns it; reference it elsewhere through decision criteria, not restatement.
• Group related source/tool/evidence/failure rules when they share decision criteria; keep them separate only when separation improves execution.

Sources and workflow templates

• Define external sources before writing retrieval or grounding rules. For each source family (knowledge base, uploaded notes, memory, tool result), specify what it means, when it is authoritative, and how to handle missing or conflicting evidence.
• Add task-specific output templates only for high-frequency workflows. Templates show section labels and completion criteria, not long policy prose.

Capability modules

Compose as mixins, not as mutually exclusive templates:

• references/rag_template.md — retrieval, document grounding, citations, evidence-backed answers.
• references/code_agent_template.md — code inspection, file edits, command execution, side-effecting actions.
• references/support_agent_template.md — multi-turn service, minimal clarification, approvals, privacy, escalation.
• references/research_agent_template.md — open-ended research, hypothesis tracking, evidence grading, synthesis.

Include only the selected module's target behavior, decision criteria, validation, and fallbacks; omit unrelated rules. When modules overlap, synthesize their stable rules rather than copying their section lists.

Reasoning control policy

Use hidden reasoning by default and expose only the reasoning summary needed for the target agent's task. Choose one reasoning mode:

• hidden_reasoning: internal reasoning only
• brief_rationale: short rationale or checklist in the visible output
• plan_then_answer: short inspectable plan first, then final answer Use plan_then_answer only when the workflow needs an intermediate artifact or when evaluation requires inspectable state.

Few-shot calibration

0–1 examples for low-fragility tasks, 2–3 for format-sensitive output, 3–5 for high-stakes or style-critical work. Examples must be realistic, structurally consistent, edge-case aware, and clearly separated from instructions.

Tool integration standard

Capability vs runtime spec

First decide which kind of tool information the user has provided:

• Broad capability (e.g. "the agent can search the web"): write a short behavior rule, then either ask for the missing runtime spec or state an explicit interface assumption.
• Real runtime spec (exact name, parameters, return fields): write an executable tool contract.

Never invent the missing half. If only capabilities are known, do not write fake names, parameters, or return fields. If only specs are known, do not invent decision policy beyond what the user described.

Executable tool contract (when real specs are available)

• Use the exact tool name from the runtime.
• State purpose and the decision criteria for calling it.
• List required and optional inputs with expected types or examples.
• List expected output fields and how the agent should interpret each.
• State missing-input behavior, result-quality checks, conflict handling, and fallback action.
• Include only details the agent must know at runtime; keep it compact.

For multi-tool prompts or complex tools, reuse the contract template in references/domain-adaptation.md.

Safety and compliance standard

Always include:

• positive safety boundaries and safe alternatives for high-risk requests
• PII and sensitive-data handling rules
• source-grounding rules for factual tasks
• prompt-leak resistance rules for proprietary instructions
• confirmation rules for destructive or irreversible actions
• retention policy when the target agent stores, remembers, exports, or modifies user data; if needed but not provided, set it to unspecified rendered in the output language
• domain-specific boundary handling with allowed alternatives, such as turning academic shortcut requests into tutoring, hints, answer checking, or practice problems

Multi-turn revision protocol

1. Draft v1.
2. Run the checks from references/evaluation.md as prompt-quality checks, not schema checks.
3. Revise once based on the results: fix missing role/scope/tool/source/output/safety behavior, merge repeated rules, drop sections that do not change behavior.
4. If checks still fail, revise the smallest failing section first.
5. If a revision lowers quality, roll back to the last passing version.
6. Record assumptions or unresolved risks only when the user asks for notes.

Output quality bar

The system prompt must be:

• explicit and minimally ambiguous
• tool-aware: tool sections match what the runtime actually exposes; no invented APIs
• runtime-isolated: free of code-side schema, field, class, or pipeline-position names; constraints are written as agent-facing behavior
• role-grounded: role is a real-world professional identity plus a domain, not a pipeline-step verb plus agent/代理
• testable, reusable, and model-adaptable
• safe by default
• compact by default, preserving capability while avoiding repeated rules

Special rule for cited structured outputs

If the target runtime cannot combine structured output and citations in the same response, write the system prompt to use a two-stage workflow: first gather and verify evidence with citations, then produce the requested structured answer from verified evidence.

Reference files

• references/prompt-engineering-principles.md
• references/prompt-techniques.md
• references/domain-adaptation.md
• references/template.md
• references/snippets.md
• references/evaluation.md
• references/rag_template.md
• references/code_agent_template.md
• references/support_agent_template.md
• references/research_agent_template.md