Prompt Engineering
Purpose: Write effective prompts for AI coding agents and workflows.
Scope: System prompts, reasoning patterns, guardrails, tool use, agentic workflows.
When to Use This Skill
- •Crafting system prompts for AI agents
- •Implementing chain-of-thought reasoning
- •Building few-shot prompt examples
- •Adding content guardrails and safety filters
- •Configuring tool/function calling patterns
Prerequisites
- •Understanding of LLM capabilities and limitations
- •Access to an AI model endpoint
Decision Tree
code
Writing a prompt?
├─ Simple, well-known task?
│ └─ Zero-shot (just instructions)
├─ Need specific output format?
│ └─ Few-shot (2-3 examples of input → output)
├─ Complex reasoning required?
│ ├─ Step-by-step? → Chain-of-thought ("think step by step")
│ └─ Multi-perspective? → Self-consistency (sample multiple paths)
├─ Agent / tool-use scenario?
│ ├─ Define tool schemas clearly
│ ├─ Add guardrails (what NOT to do)
│ └─ Include error recovery instructions
├─ System prompt for coding agent?
│ ├─ Role + constraints + format + examples
│ └─ Keep under 4K tokens for efficiency
└─ Prompt too long?
└─ Progressive disclosure: load details on demand
Quick Reference
| Pattern | When to Use | Token Cost |
|---|---|---|
| Zero-Shot | Simple tasks, well-known domains | Low |
| Few-Shot | Consistent output format needed | Medium |
| Chain-of-Thought | Multi-step reasoning, debugging | Medium |
| ReAct | Tool use, agentic workflows | High |
| Reflection | Self-correction, quality improvement | High |
System Prompts
Structure
Every system prompt should have four parts:
code
1. ROLE → Who the AI is 2. CONTEXT → What it knows about the situation 3. TASK → What it should do 4. CONSTRAINTS → What it must NOT do
Good Example
text
You are a senior Python engineer reviewing pull requests. CONTEXT: - Project uses FastAPI + SQLAlchemy + pytest - Code follows PEP 8 and uses type hints - Test coverage target: 80%+ TASK: Review the code changes and provide: 1. Security issues (critical) 2. Bug risks (high) 3. Style improvements (low) CONSTRAINTS: - Do NOT rewrite code, only point out issues - Do NOT suggest changes outside the diff - Rate each issue: critical / high / medium / low
Anti-Patterns
| Don't | Do Instead |
|---|---|
| "Be helpful" | "You are a Python code reviewer" |
| "Do your best" | "List exactly 3 issues per file" |
| "Be careful" | "NEVER execute DELETE queries" |
| Long paragraphs | Bullet points and numbered lists |
| Vague instructions | Specific output format with examples |
| Inline prompt strings in code | Load from prompts/{agent}.md file |
| Inline output templates in code | Load from templates/{name}.md file |
File-Based Prompt Management
RULE: ALWAYS store prompts in separate files. NEVER embed multi-line prompts or output templates as string literals in code.
Directory Convention
code
project/
prompts/ # System & agent prompts
assistant.md # One file per agent/role
code-reviewer.md
researcher.md
templates/ # Output format templates
review-report.md # Structured output templates
analysis-summary.md
config/
models.yaml # Model configuration
Prompt File Format
markdown
<!-- prompts/code-reviewer.md --> <!-- Purpose: System prompt for code review agent --> <!-- Model: gpt-5.1 | Max tokens: ~1500 --> You are a senior Python engineer reviewing pull requests. ## Context - Project uses FastAPI + SQLAlchemy + pytest - Code follows PEP 8 and uses type hints - Test coverage target: 80%+ ## Task Review the code changes and provide: 1. Security issues (critical) 2. Bug risks (high) 3. Style improvements (low) ## Constraints - Do NOT rewrite code, only point out issues - Do NOT suggest changes outside the diff - Rate each issue: critical / high / medium / low
Loading Pattern
python
from pathlib import Path
# Load prompt from file
prompt = Path("prompts/code-reviewer.md").read_text(encoding="utf-8")
# Load output template and combine
template = Path("templates/review-report.md").read_text(encoding="utf-8")
full_prompt = f"{prompt}\n\n## Output Format\n{template}"
Rules
- •MUST store all prompts ≥2 lines in
prompts/as.mdfiles - •MUST store output format templates in
templates/as.mdfiles - •MUST NOT embed prompt text as multi-line strings in Python/C#/TS code
- •SHOULD use Markdown format (readable, supports headers/lists)
- •SHOULD name files after the agent role:
prompts/{role}.md - •SHOULD include a comment header: purpose, target model, token estimate
- •MAY use
{variable}placeholders for runtime injection
Why Separate Files?
| Benefit | Explanation |
|---|---|
| Version control | Git diffs show exactly what changed in a prompt |
| Non-dev editing | PMs and prompt engineers edit without touching code |
| A/B testing | Swap prompt files without code changes |
| Reuse | Share prompts across agents, languages, and tests |
| Separation of concerns | Logic (code) vs. content (prompts) stay independent |
Rules
- •All endpoints return ActionResult<T>
- •Use [Authorize] on all non-public endpoints
- •Validate input with FluentValidation
- •Return Problem() for errors (RFC 7807)
code
--- ## Common Mistakes | Mistake | Fix | |---------|-----| | Prompt too long (>2000 words) | Split into system prompt + user prompt | | No output format specified | Add "Respond in this format: ..." | | Contradictory instructions | Review and remove conflicts | | Assuming AI remembers context | Repeat key constraints in each message | | Over-constraining | Allow flexibility for edge cases | | No examples for complex formats | Add 2-3 few-shot examples | | Mixing multiple tasks | One prompt = one task | --- ## Evaluation Checklist Rate your prompt before using it: - [ ] **Clear role**: Does the AI know who it is? - [ ] **Specific task**: Is the desired output unambiguous? - [ ] **Output format**: Will responses be consistent? - [ ] **Constraints**: Are boundaries and safety rules defined? - [ ] **Examples**: Are few-shot examples provided where needed? - [ ] **Reasoning**: Is chain-of-thought requested for complex tasks? - [ ] **Verification**: Does the prompt include self-check steps? - [ ] **Stored externally**: Is the prompt in `prompts/` (not inline in code)? - [ ] **Template separated**: Is the output template in `templates/` (not inline)? --- ## Resources - [OpenAI Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering) - [Anthropic Prompt Engineering](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering) - [Google Prompt Engineering](https://ai.google.dev/docs/prompt_best_practices) - [AgentX Agent Definitions](../../../../.github/agents/) - [AgentX Instruction Files](../../../../.github/instructions/) --- **Related**: [AI Agent Development](../ai-agent-development/SKILL.md) for building agents • [Skills.md](../../../../Skills.md) for all skills **Last Updated**: February 7, 2026 ## Scripts | Script | Purpose | Usage | |--------|---------|-------| | [`scaffold-prompt.py`](scripts/scaffold-prompt.py) | Generate structured prompt template (ROLE/CONTEXT/TASK/CONSTRAINTS) | `python scripts/scaffold-prompt.py --name code-reviewer [--pattern cot] [--with-examples 3]` | ## Troubleshooting | Issue | Solution | |-------|----------| | Prompt too long / context exceeded | Reduce few-shot examples or split into sub-prompts | | Model ignores instructions | Move critical rules to top of system prompt with explicit constraints | | Inconsistent outputs | Add structured output format requirements and examples | ## References - [Cot And Few Shot](references/cot-and-few-shot.md) - [Guardrails And Tool Use](references/guardrails-and-tool-use.md) - [Agentic Patterns](references/agentic-patterns.md)