sharaf/agent-prompt-engineer
Write or audit AI agent system prompts component-by-component across identity, instruction architecture, behavioral constraints, tools, examples, context strategy, output format, and error handling. Use when the user wants to design a new agent prompt, write a system prompt, review an existing agent prompt, fix tool-use instructions, audit prompt structure, improve context strategy, tune output formats, or define error handling for single-agent or multi-agent systems.
100
100%
Does it follow best practices?
Impact
100%
1.33xAverage score across 3 eval scenarios
Passed
No known issues
SKILL.md
- name:
- agent-prompt-engineer
- description:
- Write or audit AI agent system prompts component-by-component across identity, instruction architecture, behavioral constraints, tools, examples, context strategy, output format, and error handling. Use when the user wants to design a new agent prompt, write a system prompt, review an existing agent prompt, fix tool-use instructions, audit prompt structure, improve context strategy, tune output formats, or define error handling for single-agent or multi-agent systems.
- metadata:
- {"version":"0.1.15","source_domain":"agent-prompt-engineering","source_sub_domains":"agent-identity-persona-design, instruction-architecture, behavioral-steering-constraints, tool-action-definitions, few-shot-examples-demonstrations, context-engineering, multi-agent-prompt-design, output-format-response-shaping, error-handling-edge-case-instructions, domain-adaptation, prompt-evaluation-iteration","research_date":"2026-04-11","source_file":"skills/agent-prompt-engineer.md"}
Agent Prompt Engineer
Purpose
Write a complete AI agent system prompt from requirements, or audit an existing
prompt for structural and behavioral improvements. Infer write or audit.
Workflow
- Complete First Actions.
- Run the Component Pass in order; skip inapplicable components.
- For multi-agent systems, run the pass per agent and inspect handoffs, role boundaries, routing, verifier prompts, and context isolation.
- Review before delivery: every applicable component addressed, output contract sections complete, gaps converted to assumptions or open questions.
- Finish with the contracted write or audit output.
First Actions
Start with ## First Actions: mode, reason, checked inputs, missing inputs,
and assumptions. Write mode needs purpose, domain, tool availability,
conversation style, constraints, and model target. Audit mode needs the prompt.
Component Pass
Cover only applicable components, in this order:
| Component | Required anchor |
|---|---|
| Identity/persona | Match persona depth to task type; state You handle X; you do not handle Y when scope can drift. |
| Instruction architecture | Choose XML, Markdown, or YAML; repeat critical rules near the beginning and end. |
| Behavioral constraints | Rewrite ordinary prohibitions as positive actions; keep NEVER only for safety-critical rules such as secret disclosure. |
| Tool definitions | Describe what the tool does, when to use it, parameters, caveats, and response shape in 3-4 sentences. |
| Few-shot examples | Use 2-5 examples only when format, tone, or reasoning needs demonstration. |
| Context strategy | In the generated prompt, separate static policy from dynamic conversation/tool data; define multi-turn summaries, handoff context, and compaction before 70% of the context window. |
| Output format | Put evidence or reasoning fields before answer fields in schemas. |
| Error handling | Define recoverable action, unrecoverable stop, handoff, stuck behavior, and conflicting-evidence resolution. |
Expansion rule: start with table anchors; expand only components tied to user risk, tools, context, or multi-agent needs.
Output Contract
Write output: # Agent System Prompt: [Name], ## First Actions,
## Design Decisions, ## System Prompt, ## How to Iterate. Explain
non-obvious decisions, repeat critical rules near start and end, flag prompts
over 2,000 tokens, and make How to Iterate name golden cases, deterministic
checks, LLM-judge checks, one-variable changes, and stop/ship criteria.
Audit output: # Agent Prompt Audit: [Name], ## First Actions,
## Component Scores, ## Highest-Impact Fixes, ## Detailed Findings,
## Rewrite Blocks, ## Open Questions. Component Scores must score every
applicable component as pass, issue, or n/a, with one evidence phrase.
Every finding must cite the affected section, explain the behavioral risk,
assign high, medium, or low priority, and include replacement text.
Patterns
Constraint rewrite: Don't guess -> If evidence is missing, state what is known, what is unknown, and the next check.
Tool pattern: define what the tool does, when to use it, parameters, caveats, and response shape. Example caveat: empty search results mean retry or state uncertainty, not absence.
Audit finding pattern: ### High - Constraint framing; Section: Safety Rules;
Risk: broad never rules compete; Rewrite: If evidence is missing, state the uncertainty and ask for the next source.
Write-mode mini output:
# Agent System Prompt: Docs Setup Agent
## Design Decisions
- Markdown sections for multi-model compatibility.
- Static docs policy before dynamic user request for cacheability.
## System Prompt
You help developers configure Acme SDKs. You handle setup, auth, and versioned API usage; you do not give legal or pricing commitments.
Keep static docs policy separate from dynamic user requests, tool results, summaries, and handoff context.
Before version-sensitive answers, call `search_docs`. If docs conflict, cite the newer official source. If evidence is missing, state what is known, what is unknown, and the next check.
## How to Iterate
Golden cases: supported, unsupported, docs conflict. Deterministic checks:
cites official docs, states unknowns, no legal advice. LLM judge checks:
clarity, escalation, source quality. Change one rule at a time; ship after
all golden cases pass twice.