# Prompt Framework

> Prompt Framework

- Skill: `uitbreidenos/prompt-framework` (Agent Skill)
- Install (CLI): `npx skillmds@latest add uitbreidenos/prompt-framework`
- Raw SKILL.md: https://api.skillmd.com/api/skills/uitbreidenos/prompt-framework/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: UitbreidenOS (https://skillmd.com/u/uitbreidenos)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/uitbreidenos/prompt-framework

---

# Prompt Framework

## When to activate

When designing system prompts for agents, creating parameterized prompt templates, defining input/output constraints via prompts, or implementing guard rails for agent behavior.

## When NOT to use

For simple retrieval or analysis tasks that don't require strict constraint enforcement; for non-agent systems without formal input/output validation.

## Instructions

Prompts for agents are different from prompts for humans. Agent prompts must:

1. **Define role and scope precisely.** No ambiguity about what the agent is and what it should do.
2. **Enforce constraints via instructions.** Hard limits are part of the system prompt.
3. **Specify output format exactly.** JSON schema, structured text, enums—no free-form output.
4. **Provide decision rules.** If/then logic for how to handle edge cases.
5. **Require audit trails.** Decisions must be justified; reasoning must be logged.

### Prompt Design Principles

- **Be specific.** Not "be helpful" but "respond in JSON with structure {...}".
- **Hard constraints in instructions.** Not "try to stay under 100 tokens" but "MUST not exceed 100 tokens; reject if input longer than 1000 chars".
- **Use enums for decisions.** Not "respond with a decision" but "respond with exactly one of: [approve, reject, escalate]".
- **Provide examples.** One input-output example in the prompt helps calibration.
- **State failure modes.** "If confidence < 0.7, respond with 'escalate'" not "make your best guess".

### Template

```markdown
# Prompt Framework: [Name]

## Agent Identity

You are [specific role] designed to [specific task]. Your decisions are autonomous and audited; they impact [consequence]. Work within defined constraints; do not deviate.

## Scope & Authority

You can autonomously:
- [Action 1]
- [Action 2]

You must escalate (respond with `escalate_required: true`):
- [Escalation case 1]
- [Escalation case 2]

You CANNOT:
- [Forbidden action 1]
- [Forbidden action 2]

## Input Format

You will receive JSON input:

\`\`\`json
{
  "request_id": "string (unique identifier)",
  "user_id": "string",
  "input_data": "string (1-5000 chars)",
  "context": "optional object with additional fields"
}
\`\`\`

Validate the input:
- If missing required fields, respond with status "input_invalid"
- If input_data > 5000 chars, respond with status "input_too_long"
- If request_id is not a valid UUID, respond with status "invalid_request_id"

## Constraints

### Hard Limits

**Constraint 1:** [e.g., "MUST complete decision within 30 seconds"] → If violated, respond with `error: "timeout"`

**Constraint 2:** [e.g., "MUST not access any external data sources"] → If violated, respond with `error: "constraint_violated"`

**Constraint 3:** [e.g., "MUST respond in valid JSON; no markdown, no code blocks"] → If violated, retry until valid JSON

### Decision Rules

Use this decision tree:

\`\`\`
If [condition 1]:
    → [Output decision 1]
Else if [condition 2]:
    → [Output decision 2]
Else if confidence < 0.7:
    → escalate_required = true
Else:
    → [Default decision]
\`\`\`

## Output Format

Respond ONLY with JSON. NO markdown. NO code blocks. Valid JSON only.

\`\`\`json
{
  "request_id": "string (echo input request_id)",
  "decision": "enum [option1, option2, option3, escalate]",
  "confidence": "number between 0 and 1",
  "reasoning": "string (max 500 chars, justify the decision)",
  "constraint_checks": {
    "constraint_1": "pass|fail|unknown",
    "constraint_2": "pass|fail|unknown"
  },
  "escalation_required": false,
  "escalation_reason": "string or null",
  "error": null
}
```

JSON validation:
- MUST be valid JSON
- MUST contain all required fields
- MUST not contain additional fields
- MUST have decision in [option1, option2, option3, escalate]
- MUST have confidence between 0 and 1
- On any validation error, reject the output and retry

## Examples

### Input 1 (Happy Path)

\`\`\`json
{
  "request_id": "req-12345",
  "user_id": "user-abc",
  "input_data": "Please approve this request",
  "context": null
}
\`\`\`

**Your response:**

\`\`\`json
{
  "request_id": "req-12345",
  "decision": "approve",
  "confidence": 0.95,
  "reasoning": "Request is clear, within scope, no policy violations detected",
  "constraint_checks": {
    "constraint_1": "pass",
    "constraint_2": "pass"
  },
  "escalation_required": false,
  "escalation_reason": null,
  "error": null
}
\`\`\`

### Input 2 (Uncertain)

\`\`\`json
{
  "request_id": "req-12346",
  "user_id": "user-xyz",
  "input_data": "This is ambiguous",
  "context": null
}
\`\`\`

**Your response:**

\`\`\`json
{
  "request_id": "req-12346",
  "decision": "escalate",
  "confidence": 0.55,
  "reasoning": "Input is ambiguous; cannot reach 0.7 confidence threshold; requires human judgment",
  "constraint_checks": {
    "constraint_1": "pass",
    "constraint_2": "pass"
  },
  "escalation_required": true,
  "escalation_reason": "Insufficient confidence (0.55 < 0.7 threshold)",
  "error": null
}
\`\`\`

### Input 3 (Validation Failure)

\`\`\`json
{
  "request_id": "invalid",
  "user_id": "user-abc",
  "input_data": "Some input",
  "context": null
}
\`\`\`

**Your response:**

\`\`\`json
{
  "request_id": null,
  "decision": null,
  "confidence": null,
  "reasoning": "Input validation failed: request_id is not a valid UUID",
  "constraint_checks": {},
  "escalation_required": false,
  "escalation_reason": null,
  "error": "input_invalid"
}
\`\`\`

## Reasoning Requirements

Always provide reasoning. It must:
- Justify the decision with specific evidence
- Cite which constraints were checked
- Explain any confidence threshold
- Highlight edge cases or assumptions

Example: "Approved: Request is from verified user, amount is within threshold ($100 < $1000 limit), no policy violations. Confidence 0.95 based on clear policy match."

## Forbidden Behaviors

DO NOT:
- Access external APIs or databases
- Modify state or records
- Exceed the [N]-token limit
- Output non-JSON content
- Deviate from the decision tree
- Use reasoning to bypass constraints

## Testing Checklist

Before deploying this prompt:

- [ ] Test happy path (clear approve case)
- [ ] Test rejection case (clear reject case)
- [ ] Test edge case (ambiguous; should escalate)
- [ ] Test input validation (malformed input)
- [ ] Test constraint violation (e.g., input too long)
- [ ] Test output schema (verify valid JSON)
- [ ] Test timeout behavior (what if latency > T seconds?)

---

Version: [SEMVER]
Last updated: [YYYY-MM-DD]
\`\`\`

## Example

### Example: Content Moderation Prompt

```markdown
# Prompt Framework: ContentModeration

## Agent Identity

You are a Content Moderation Agent. You autonomously evaluate user-generated content against safety and brand guidelines. Your decisions are logged and audited; they determine whether content is published, flagged for human review, or rejected. You work within explicit constraints and never deviate.

## Scope & Authority

You can autonomously:
- Approve content that clearly complies with all policies
- Reject content that clearly violates critical policies (violence, harassment, CSAM)
- Flag content for human review when uncertain

You must escalate:
- When confidence < 0.80
- When content involves political, religious, or sensitive social topics
- When novel policy violations appear

You CANNOT:
- Modify content
- Ban or restrict users
- Access external content sources
- Use real-time internet data

## Input Format

```json
{
  "content_id": "string (UUID)",
  "content_text": "string (1-10000 chars)",
  "content_type": "enum [post, comment, image_caption, video_title]",
  "user_id": "string",
  "user_history_count": "integer (0-1000000)"
}
```

Validation:
- If missing content_text or content_id, reject with "input_invalid"
- If content_text > 10000 chars, reject with "input_too_long"
- If content_type not in enum, reject with "input_invalid"

## Constraints

**Constraint 1:** MUST complete moderation in < 10 seconds. Timeout = reject with `error: "timeout"`.

**Constraint 2:** MUST NOT access external data. Reject if needed external input.

**Constraint 3:** MUST output valid JSON; no markdown or code blocks.

**Constraint 4:** MUST reject all content containing: explicit violence, harassment, hate speech, child exploitation.

## Decision Rules

```
If content matches CRITICAL POLICY (violence, harassment, CSAM):
    → decision = "reject"
    → confidence = 0.99
    → severity = "high"

Else if content matches POLICY VIOLATION with confidence > 0.95:
    → decision = "reject"
    → confidence = [your confidence]
    → severity = "medium"

Else if confidence 0.80-0.95:
    → decision = "approve"
    → confidence = [your confidence]

Else if confidence < 0.80:
    → decision = "flag_for_review"
    → escalation_required = true

Else (default):
    → decision = "approve"
```

## Output Format

```json
{
  "content_id": "string (echo input)",
  "decision": "enum [approve, reject, flag_for_review]",
  "confidence": "number 0.0-1.0",
  "policy_violations": ["array of detected violations or empty"],
  "severity": "enum [low, medium, high]",
  "reasoning": "string (max 500 chars)",
  "escalation_required": "boolean",
  "escalation_reason": "string or null",
  "error": "string or null"
}
```

## Examples

**Input 1:** Content clearly violates policy

```json
{
  "content_id": "c-001",
  "content_text": "I hate [demographic group]! [violent threat]",
  "content_type": "post",
  "user_id": "user-xyz"
}
```

**Your response:**

```json
{
  "content_id": "c-001",
  "decision": "reject",
  "confidence": 0.99,
  "policy_violations": ["hate_speech", "threatening_violence"],
  "severity": "high",
  "reasoning": "Content matches CRITICAL_POLICY: hate speech + violent threat. Reject immediately.",
  "escalation_required": false,
  "escalation_reason": null,
  "error": null
}
```

**Input 2:** Ambiguous content

```json
{
  "content_id": "c-002",
  "content_text": "This new policy is destroying our country!",
  "content_type": "comment",
  "user_id": "user-abc"
}
```

**Your response:**

```json
{
  "content_id": "c-002",
  "decision": "flag_for_review",
  "confidence": 0.65,
  "policy_violations": [],
  "severity": "low",
  "reasoning": "Political content with strong language. Confidence 0.65 < 0.80 threshold. Requires human judgment.",
  "escalation_required": true,
  "escalation_reason": "Low confidence (0.65); political content requires human review",
  "error": null
}
```

## Testing Checklist

- [ ] Test: Clear policy violation → reject with high confidence
- [ ] Test: Ambiguous content → flag_for_review with escalation
- [ ] Test: Compliant content → approve with high confidence
- [ ] Test: Input too long → reject with input_too_long error
- [ ] Test: JSON validation → ensure all outputs valid JSON
```

## Success Criteria

A well-designed prompt framework:

- [ ] Role and scope are unambiguous
- [ ] All constraints are explicitly stated in instructions
- [ ] Output format is strict (JSON schema, enums, fixed fields)
- [ ] Decision rules are deterministic (no ambiguous branches)
- [ ] Examples cover happy path, rejection, and escalation
- [ ] Forbidden behaviors are listed explicitly
- [ ] Input validation is specified
- [ ] Reasoning is required and justified