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

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

prompts/{agent}.md

templates/{name}.md

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

  .md

  files
• MUST store output format templates in

  templates/

  as

  .md

  files
• 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?

Rules

1. All endpoints return ActionResult<T>
2. Use [Authorize] on all non-public endpoints
3. Validate input with FluentValidation
4. 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)