Skip to main content
Different AI models respond better to different prompting styles. This guide covers model-specific techniques and provides ready-to-use prompt refiner skills.
Works everywhere: These prompting techniques apply to both CLI and Factory App.

​
Universal Prompting Principles

These principles work across all models:
Weak: “Fix the bug in auth”Strong: “Fix the login timeout bug where users get logged out after 5 minutes of inactivity. The session should persist for 24 hours.”
Weak: “Add error handling”Strong: “This API endpoint handles payment processing. It currently crashes silently on network errors. Add error handling that logs the error, returns a user-friendly message, and triggers an alert.”
Weak: “Make it faster”Strong: “Optimize the search query. Success criteria: query time under 100ms for 10k records, no change to result accuracy, passes existing tests.”
Weak: “Refactor this code”Strong: “Refactor this code to use the repository pattern. Constraints: don’t change the public API, maintain backward compatibility, keep the same test coverage.”

​
Claude Models (Opus, Sonnet, Haiku)

Claude models excel with structured, explicit instructions and respond particularly well to certain formatting patterns.

​
Key Techniques for Claude

1

Use XML tags for structure

Claude responds exceptionally well to XML-style tags for organizing complex prompts:
<context>
This is a React application using TypeScript and Zustand for state management.
The auth module handles user sessions and JWT tokens.
</context>

<task>
Add a "remember me" checkbox to the login form that extends session duration to 30 days.
</task>

<requirements>
- Store preference in localStorage
- Update JWT expiration accordingly
- Add unit tests for the new functionality
</requirements>
2

Put examples in dedicated sections

When you want specific output formats, show examples:
<example>
Input: "user not found"
Output: { code: "USER_NOT_FOUND", message: "The specified user does not exist", httpStatus: 404 }
</example>

Now handle these error cases following the same pattern:
- Invalid password
- Account locked
- Session expired
3

Use thinking prompts for complex reasoning

For complex decisions, ask Claude to think through options:
Before implementing, analyze:
1. What are the tradeoffs between approach A and B?
2. Which approach better fits our existing patterns?
3. What edge cases should we consider?

Then implement the better approach.
Ready-to-use prompt refiner skills are available in the examples folder. Copy them to ~/.factory/skills/ to use them. Learn more about skills in the Skills documentation.

​
Claude Prompt Refiner Skill

Create ~/.factory/skills/prompt-refiner-claude/SKILL.md: 
---
name: prompt-refiner-claude
description: Refine prompts for Claude models (Opus, Sonnet, Haiku) using Anthropic's best practices. Use when preparing complex tasks for Claude.
---

# Claude Prompt Refiner

## When to Use
Invoke this skill when you have a task for Claude that:
- Involves multiple steps or files
- Requires specific output formatting
- Needs careful reasoning or analysis
- Would benefit from structured context

## Refinement Process

### 1. Analyze the Draft Prompt
Review the user's prompt for:
- [ ] Clear outcome definition
- [ ] Sufficient context
- [ ] Explicit constraints
- [ ] Success criteria

### 2. Apply Claude-Specific Patterns

**Structure with XML tags:**
- `<context>` - Background information, codebase state
- `<task>` - The specific action to take
- `<requirements>` - Must-have criteria
- `<constraints>` - Limitations and boundaries
- `<examples>` - Sample inputs/outputs if helpful

**Ordering matters:**
1. Context first (what exists)
2. Task second (what to do)
3. Requirements third (how to do it)
4. Examples last (clarifying edge cases)

### 3. Enhance for Reasoning
For complex tasks, add:
- "Think through the approach before implementing"
- "Consider these edge cases: ..."
- "Explain your reasoning for key decisions"

### 4. Output the Refined Prompt
Present the improved prompt with:
- Clear section headers
- XML tags where beneficial
- Specific, measurable criteria

## Example Transformation

**Before:**
"Add caching to the API"

**After:**

​
GPT Models (GPT-5, GPT-5.1, Codex)

GPT models excel with clear system-level context and benefit from explicit role framing.

​
Key Techniques for GPT

1

Frame the role explicitly

GPT models respond well to clear role definitions:
You are a senior TypeScript developer reviewing code for a production e-commerce platform.
Focus on: type safety, error handling, and performance.

Review this checkout flow implementation...
2

Use numbered steps for procedures

GPT follows numbered instructions reliably:
Complete these steps in order:
1. Read the current implementation in src/auth/
2. Identify all places where tokens are validated
3. Create a centralized token validation utility
4. Update all call sites to use the new utility
5. Add unit tests for the utility
6. Run the test suite and fix any failures
3

Be explicit about output format

Specify exactly what you want:
Return your analysis as a markdown document with these sections:
## Summary (2-3 sentences)
## Issues Found (bulleted list)
## Recommended Changes (numbered, in priority order)
## Code Examples (if applicable)

​
GPT Prompt Refiner Skill

Create ~/.factory/skills/prompt-refiner-gpt/SKILL.md: 
---
name: prompt-refiner-gpt
description: Refine prompts for GPT models (GPT-5, GPT-5.1, Codex) using OpenAI's best practices. Use when preparing complex tasks for GPT.
---

# GPT Prompt Refiner

## When to Use
Invoke this skill when you have a task for GPT that:
- Requires a specific persona or expertise
- Involves procedural steps
- Needs structured output
- Benefits from explicit examples

## Refinement Process

### 1. Analyze the Draft Prompt
Review for:
- [ ] Clear role/persona definition
- [ ] Step-by-step breakdown (if procedural)
- [ ] Output format specification
- [ ] Concrete examples

### 2. Apply GPT-Specific Patterns

**Role framing:**
Start with "You are a [specific role] working on [specific context]..."

**Numbered procedures:**
Break complex tasks into numbered steps that build on each other.

**Output specification:**
Be explicit: "Return as JSON", "Format as markdown with headers", etc.

**Chain of thought:**
For reasoning tasks, add: "Think through this step by step."

### 3. Structure the Prompt

**Effective order for GPT:**
1. Role definition (who/what)
2. Context (background info)
3. Task (what to do)
4. Steps (how to do it, if procedural)
5. Output format (what to return)
6. Examples (optional clarification)

### 4. Output the Refined Prompt
Present with:
- Clear role statement
- Numbered steps where applicable
- Explicit output requirements

## Example Transformation

**Before:**
"Review this code for security issues"

**After:**
You are a senior security engineer conducting a security audit of a Node.js payment processing service. Context: This service handles credit card transactions and communicates with Stripe’s API. It runs in AWS ECS. Task: Review the code in src/payments/ for security vulnerabilities. Steps:
  1. Check for proper input validation on all endpoints
  2. Verify secrets are not hardcoded or logged
  3. Review authentication and authorization logic
  4. Check for SQL injection and XSS vulnerabilities
  5. Verify proper error handling that doesn’t leak sensitive info
Output format: Return a security report in markdown with:
  • Critical: Issues that must be fixed before deployment
  • High: Significant risks that should be addressed soon
  • Medium: Improvements to consider
  • Recommendations: General security enhancements
For each issue, include:
  • File and line number
  • Description of the vulnerability
  • Recommended fix with code example

​
Gemini Models

Gemini models handle long context well and work effectively with structured reasoning.

​
Key Techniques for Gemini

1

Leverage long context

Gemini can handle extensive context—don’t be afraid to include more background:
Here's the full module structure for context:
[include relevant files]

Based on these patterns, implement a new service that...
2

Use reasoning levels effectively

Gemini supports Low and High reasoning. Use High for:
  • Architecture decisions
  • Complex debugging
  • Multi-step planning
Use Low for:
  • Straightforward implementations
  • Code generation from specs
  • Routine refactoring

​
Model Selection Strategy

Match the model to the task:
Task TypeRecommended ModelReasoning Level
Complex architectureOpus 4.5Medium-High
Feature implementationSonnet 4.5 or GPT-5.1-CodexMedium
Quick edits, formattingHaiku 4.5Off/Low
Code reviewGPT-5.1-Codex-MaxHigh
Bulk automationGLM-4.6 (Droid Core)None
Research/analysisGemini 3 ProHigh

​
Creating Your Own Prompt Refiner

For team-specific needs, create a custom prompt refiner: 
---
name: prompt-refiner-team
description: Refine prompts using our team's conventions and project context.
---

# Team Prompt Refiner

## Our Conventions
- We use the repository pattern
- All services have interfaces defined first
- Tests use our custom test utilities from @/test-utils

## Checklist for Prompts
1. [ ] References relevant existing code
2. [ ] Specifies which layer (API, service, repository)
3. [ ] Mentions related tests to update
4. [ ] Includes acceptance criteria

## Template
Context: [What exists, what module/layer] Task: [Specific action] Patterns to follow: [Reference existing similar code] Tests: [What tests to add/update] Done when: [Acceptance criteria]

​
Quick Reference Card

​
Claude (Opus/Sonnet/Haiku)

  • ✅ XML tags for structure
  • ✅ Context before instructions
  • ✅ Examples in dedicated sections
  • ✅ “Think through…” for reasoning

​
GPT (GPT-5/Codex)

  • ✅ Role framing (“You are a…”)
  • ✅ Numbered step procedures
  • ✅ Explicit output format
  • ✅ “Step by step” for reasoning

​
Gemini

  • ✅ Extensive context inclusion
  • ✅ Low/High reasoning levels
  • ✅ Structured output requests

​
Next Steps

Setup Checklist

Complete power user configuration

Token Efficiency

Reduce costs while maintaining quality