diegosouzapw 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
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:
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
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
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
<!-- 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
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
- Use [Authorize] on all non-public endpoints
- Validate input with FluentValidation
- Return Problem() for errors (RFC 7807)
---
## 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)