Skip to main content
skill CX Codex

openai-prompt-engineer — Claude Code skill for prompt design

The openai-prompt-engineer skill helps draft and refine prompts for GPT-5 and other language models. Use it to shape instructions, choose a prompting method, and specify the response format.

MIT 211 installs ★ 236 updated 2026-01-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jamesrochabrun/skills --skill openai-prompt-engineer -a claude-code
Open on GitHub

What openai-prompt-engineer does

The skill guides you through writing prompts from scratch or revising existing ones. It covers how to define a task, constraints, and output format, then choose an approach for the work: examples for pattern matching, or staged requests for larger tasks. Its model-specific guidance includes structured instructions for GPT-5 and XML formatting for Claude.

It also discusses chain-of-thought, few-shot and zero-shot prompting, plus testing a prompt and revising it based on the result. This is guidance for prompt design, not a model runner, so you still need to apply the suggestions to your own request. The skill supports Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.

What it helps with

  • draft a prompt for a new task
  • make model instructions and output format clearer
  • choose a prompting method for a complex request
  • spot weaknesses in an existing prompt

Example prompts for the agent

  • Help me write a GPT-5 prompt to review code for security issues and return the findings in Markdown.
  • Revise this prompt so the model returns structured XML with its findings.
  • Choose an approach for classifying text and show how to include examples in the instructions.

How to install openai-prompt-engineer

1Skills CLI (Vercel)

npx skills add jamesrochabrun/skills --skill openai-prompt-engineer -a claude-code

2Manually: put the files in place

~/.claude/skills/openai-prompt-engineer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/openai-prompt-engineer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about openai-prompt-engineer

How do I install openai-prompt-engineer in Claude Code?

Run npx skills add jamesrochabrun/skills --skill openai-prompt-engineer -a claude-code. The skill file is at ~/.claude/skills/openai-prompt-engineer/SKILL.md.

What does openai-prompt-engineer do?

It helps you draft and refine prompts, with guidance on choosing a structure and technique for the task. The recommendations cover GPT-5 and Claude.

Which prompting techniques does the skill cover?

It discusses chain-of-thought, few-shot and zero-shot prompting, structured output, and progressive disclosure.

Source text

SKILL.md · MIT
---
name: openai-prompt-engineer
description: Generate and improve prompts using best practices for OpenAI GPT-5 and other LLMs. Apply advanced techniques like chain-of-thought, few-shot prompting, and progressive disclosure.
---

# OpenAI Prompt Engineer

A comprehensive skill for crafting, analyzing, and improving prompts for OpenAI's GPT-5 and other modern Large Language Models (LLMs), with focus on GPT-5-specific optimizations and universal prompting techniques.

## What This Skill Does

Helps you create and optimize prompts using cutting-edge techniques:
- **Generate new prompts** - Build effective prompts from scratch
- **Improve existing prompts** - Enhance clarity, structure, and results
- **Apply best practices** - Use proven techniques for each model
- **Optimize for specific models** - GPT-5, Claude-specific strategies
- **Implement advanced patterns** - Chain-of-thought, few-shot, structured prompting
- **Analyze prompt quality** - Identify issues and suggest improvements

## Why Prompt Engineering Matters

**Without good prompts:**
- Inconsistent or incorrect outputs
- Poor instruction following
- Wasted tokens and API costs
- Multiple attempts needed
- Unpredictable behavior

**With optimized prompts:**
- Accurate, consistent results
- Better instruction adherence
- Lower costs and latency
- First-try success
- Predictable, reliable outputs

## Supported Models & Approaches

### GPT-5 (OpenAI)
- Structured prompting (role + task + constraints)
- Reasoning effort calibration
- Agentic behavior control
- Verbosity management
- Prompt optimizer integration

### Claude (Anthropic)
- XML tag structuring
- Step-by-step thinking
- Clear, specific instructions
- Example-driven prompting
- Progressive disclosure

### Universal Techniques
- Chain-of-thought prompting
- Few-shot learning
- Zero-shot prompting
- Self-consistency
- Role-based prompting

## Core Prompting Principles

### 1. Be Clear and Specific
**Bad:** "Write about AI"
**Good:** "Write a 500-word technical article explaining transformer architecture for software engineers with 2-3 years of experience. Include code examples in Python and focus on practical implementation."

### 2. Provide Structure
Use clear formatting to organize instructions:
```
Role: You are a senior Python developer
Task: Review this code for security vulnerabilities
Constraints:
- Focus on OWASP Top 10
- Provide specific line numbers
- Suggest fixes with code examples
Output format: Markdown with severity ratings
```

### 3. Use Examples (Few-Shot)
Show the model what you want:
```
Input: "User clicked login"
Output: "USER_LOGIN_CLICKED"

Input: "Payment processed successfully"
Output: "PAYMENT_PROCESSED_SUCCESS"

Input: "Email verification failed"
Output: [Your turn]
```

### 4. Enable Reasoning
Add phrases like:
- "Think step-by-step"
- "Let's break this down"
- "First, analyze... then..."
- "Show your reasoning"

### 5. Define Output Format
Specify exactly how you want the response:
```xml
<output_format>
  <summary>One sentence overview</summary>
  <details>
    <point>Key finding 1</point>
    <point>Key finding 2</point>
  </details>
  <recommendation>Specific action to take</recommendation>
</output_format>
```

## Prompt Engineering Workflow

### 1. Define Your Goal
- What task are you solving?
- What's the ideal output?
- Who's the audience?
- What model will you use?

### 2. Choose Your Technique
- **Simple task?** → Direct instruction
- **Complex reasoning?** → Chain-of-thought
- **Pattern matching?** → Few-shot examples
- **Need consistency?** → Structured format + examples

### 3. Build Your Prompt
Use this template:
```
[ROLE/CONTEXT]
You are [specific role with relevant expertise]

[TASK]
[Clear, specific task description]

[CONSTRAINTS]
- [Limitation 1]
- [Limitation 2]

[FORMAT]
Output should be [exact format specification]

[EXAMPLES - if using few-shot]
[Example 1]
[Example 2]

[THINK STEP-BY-STEP - if complex reasoning]
Before answering, [thinking instruction]
```

### 4. Test and Iterate
- Run the prompt
- Analyze output quality
- Identify issues
- Refine and retry
- Document what works

## Advanced Techniques

### Chain-of-Thought (CoT) Prompting

**When to use:** Complex reasoning, math, multi-step problems

**How it works:** Ask the model to show intermediate steps

**Example:**
```
Problem: A store has 15 apples. They sell 60% in the morning and
half of what's left in the afternoon. How many remain?

Please solve this step-by-step:
1. Calculate morning sales
2. Calculate remaining after morning
3. Calculate afternoon sales
4. Calculate final remaining
```

**Result:** More accurate answers through explicit reasoning

### Few-Shot Prompting

**When to use:** Pattern matching, classification, style transfer

**How it works:** Provide 2-5 examples, then the actual task

**Example:**
```
Convert casual text to professional business tone:

Input: "Hey! Thanks for reaching out. Let's chat soon!"
Output: "Thank you for your message. I look forward to our conversation."

Input: "That's a great idea! I'm totally on board with this."
Output: "I appreciate your suggestion and fully support this initiative."

Input: "Sounds good, catch you later!"
Output: [Model completes]
```

### Zero-Shot Chain-of-Thought

**When to use:** Complex problems without examples

**How it works:** Simply add "Let's think step by step"

**Example:**
```
Question: What are the security implications of storing JWTs
in localStorage?

Let's think step by step:
```

**Magic phrase:** "Let's think step by step" → dramatically improves reasoning

### Structured Output with XML

**When to use:** Working with Claude or need parsed output

**Example:**
```
Analyze this code for issues. Structure your response as:

<analysis>
  <security_issues>
    <issue severity="high|medium|low">
      <description>What's wrong</description>
      <location>File and line number</location>
      <fix>How to fix it</fix>
    </issue>
  </security_issues>
  <performance_issues>
    <!-- Same structure -->
  </performance_issues>
  <best_practices>
    <suggestion>Improvement suggestion</suggestion>
  </best_practices>
</analysis>
```

### Progressive Disclosure

**When to use:** Large context, multi-step workflows

**How it works:** Break tasks into stages, only request what's needed now

**Example:**
```
Stage 1: "Analyze this codebase structure and list the main components"
[Get response]

Stage 2: "Now, for the authentication component you identified,
show me the security review"
[Get response]

Stage 3: "Based on that review, generate fixes for the high-severity issues"
```

## Model-Specific Best Practices

### GPT-5 Optimization

**Structured Prompting:**
```
ROLE: Senior TypeScript Developer
TASK: Implement user authentication service
CONSTRAINTS:
- Use JWT with refresh tokens
- TypeScript with strict mode
- Include comprehensive error handling
- Follow SOLID principles
OUTPUT: Complete TypeScript class with JSDoc comments
REASONING_EFFORT: high (for complex business logic)
```

**Control Agentic Behavior:**
```
"Implement this feature step-by-step, asking for confirmation
before each major decision"

OR

"Complete this task end-to-end without asking for guidance.
Persist until fully handled."
```

**Manage Verbosity:**
```
"Provide a concise implementation (under 100 lines) focusing
only on core functionality"
```

### Claude Optimization

**Use XML Tags:**
```
<instruction>
Review this pull request for security issues
</instruction>

<code>
[Code to review]
</code>

<focus_areas>
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication bypasses
- Data exposure risks
</focus_areas>

<output_format>
For each issue found, provide:
1. Severity (Critical/High/Medium/Low)
2. Location
3. Explanation
4. Fix recommendation
</output_format>
```

**Step-by-Step Thinking:**
```
Think through this architecture decision step by step:
1. First, identify the requirements
2. Then, list possible approaches
3. Evaluate trade-offs for each
4. Make a recommendation with reasoning
```

**Clear Specificity:**
```
BAD: "Make the response professional"
GOOD: "Use formal business language, avoid contractions,
address the user as 'you', keep sentences under 20 words"
```

## Prompt Improvement Checklist

Use this checklist to improve any prompt:

- [ ] **Clear role defined** - Is the AI's expertise specified?
- [ ] **Specific task** - Is it unambiguous what to do?
- [ ] **Constraints listed** - Are limitations clear?
- [ ] **Format specified** - Is output structure defined?
- [ ] **Examples provided** - Do you show what you want (if needed)?
- [ ] **Reasoning enabled** - Do you ask for step-by-step thinking (if complex)?
- [ ] **Context included** - Does the AI have necessary background?
- [ ] **Edge cases covered** - Are exceptions handled?
- [ ] **Length specified** - Is output length clear?
- [ ] **Tone/style defined** - Is the desired voice specified?

## Common Prompt Problems & Fixes

### Problem: Vague Instructions
**Before:**
```
"Write some code for user authentication"
```

**After:**
```
"Write a TypeScript class called AuthService that:
- Accepts email/password credentials
- Validates against a User repository
- Returns a JWT token on success
- Throws AuthenticationError on failure
- Includes comprehensive JSDoc comments
- Follows dependency injection pattern"
```

### Problem: No Examples (When Needed)
**Before:**
```
"Convert these variable names to camelCase"
```

**After:**
```
"Convert these variable names to camelCase:

user_name → userName
total_count → totalCount
is_active → isActive

Now convert:
order_status →
created_at →
max_retry_count →"
```

### Problem: Missing Output Format
**Before:**
```
"Analyze this code for problems"
```

**After:**
```
"Analyze this code and output in this format:

## Security Issues
- [Issue]: [Description] (Line X)

## Performance Issues
- [Issue]: [Description] (Line X)

## Code Quality
- [Issue]: [Description] (Line X)

## Recommendations
1. [Priority 1 fix]
2. [Priority 2 fix]"
```

### Problem: Too Complex (Single Shot)
**Before:**
```
"Build a complete e-commerce backend with authentication,
payments, inventory, and shipping"
```

**After (Progressive):**
```
"Let's build this in stages:

Stage 1: Design the authentication system architecture
[Get response, review]

Stage 2: Implement the auth service
[Get response, review]

Stage 3: Add payment processing
[Continue...]"
```

## Using This Skill

### Generate a New Prompt

**Ask:**
```
"Using the prompt-engineer skill, create a prompt for:
[Describe your task and requirements]"
```

**You'll get:**
- Structured prompt template
- Recommended techniques
- Example few-shots if applicable
- Model-specific optimizations

### Improve an Existing Prompt

**Ask:**
```
"Using the prompt-engineer skill, improve this prompt:

[Your current prompt]

Goal: [What you want to achieve]
Model: [GPT-5 / Claude / Other]"
```

**You'll get:**
- Analysis of current issues
- Improved version
- Explanation of changes
- Expected improvement in results

### Analyze Prompt Quality

**Ask:**
```
"Using the prompt-engineer skill, analyze this prompt:
[Your prompt]"
```

**You'll get:**
- Quality score
- Identified weaknesses
- Specific improvement suggestions
- Best practices violations

## Real-World Examples

### Example 1: Code Review Prompt

**Task:** Get thorough, consistent code reviews

**Optimized Prompt:**
```
ROLE: Senior Software Engineer conducting PR review

REVIEW THIS CODE:
[code block]

REVIEW CRITERIA:
1. Security vulnerabilities (OWASP Top 10)
2. Performance issues
3. Code quality and readability
4. Best practices compliance
5. Test coverage gaps

OUTPUT FORMAT:
For each issue found:
- Severity: [Critical/High/Medium/Low]
- Category: [Security/Performance/Quality/Testing]
- Location: [File:Line]
- Issue: [Clear description]
- Impact: [Why this matters]
- Fix: [Specific code recommendation]

At the end, provide:
- Overall assessment (Approve/Request Changes/Comment)
- Summary of critical items that must be fixed
```

### Example 2: Technical Documentation

**Task:** Generate clear API documentation

**Optimized Prompt:**
```
ROLE: Technical writer with API documentation expertise

TASK: Generate API documentation for this endpoint

ENDPOINT DETAILS:
[code/specs]

DOCUMENTATION REQUIREMENTS:
- Target audience: Junior to mid-level developers
- Include curl and JavaScript examples
- Explain all parameters clearly
- Show example responses with descriptions
- Include common error cases
- Add troubleshooting section

FORMAT:
# [Endpoint Name]

## Overview
[One paragraph description]

## Endpoint
`[HTTP METHOD] /path`

## Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|

## Request Example
```bash
[curl example]
```

## Response
### Success (200)
```json
[example with inline comments]
```

### Errors
- 400: [Description and fix]
- 401: [Description and fix]

## Common Issues
[Troubleshooting guide]
```

### Example 3: Data Analysis

**Task:** Analyze data and provide insights

**Optimized Prompt:**
```
ROLE: Data analyst with expertise in business metrics

DATA:
[dataset]

ANALYSIS REQUEST:
Analyze this data step-by-step:

1. FIRST: Identify key metrics and trends
2. THEN: Calculate:
   - Growth rate (month-over-month)
   - Average values
   - Anomalies or outliers
3. NEXT: Draw business insights
4. FINALLY: Provide actionable recommendations

OUTPUT FORMAT:
## Executive Summary
[2-3 sentences]

## Key Metrics
| Metric | Value | Change | Trend |

## Insights
1. [Insight with supporting data]
2. [Insight with supporting data]

## Recommendations
1. [Action]: [Expected impact]
2. [Action]: [Expected impact]

## Methodology
[Brief explanation of analysis approach]
```

## Best Practices Summary

### DO ✅

- **Be specific** - Exact requirements, not vague requests
- **Use structure** - Organize with clear sections
- **Provide examples** - Show what you want (few-shot)
- **Request reasoning** - "Think step-by-step" for complex tasks
- **Define format** - Specify exact output structure
- **Test iteratively** - Refine based on results
- **Match to model** - Use model-specific techniques
- **Include context** - Give necessary background
- **Handle edge cases** - Specify exception handling
- **Set constraints** - Define limitations clearly

### DON'T ❌

- **Be vague** - "Write something about X"
- **Skip examples** - When patterns need to be matched
- **Assume format** - Model will choose unpredictably
- **Overload single prompt** - Break complex tasks into stages
- **Ignore model differences** - GPT-5 and Claude need different approaches
- **Give up too soon** - Iterate on prompts
- **Mix instructions** - Keep separate concerns separate
- **Forget constraints** - Specify ALL requirements
- **Use ambiguous terms** - "Good", "professional", "better" without definition
- **Skip testing** - Always validate outputs

## Quick Reference

### Prompt Template (Universal)
```
[ROLE]
You are [specific expertise]

[CONTEXT]
[Background information]

[TASK]
[Clear, specific task]

[CONSTRAINTS]
- [Limit 1]
- [Limit 2]

[FORMAT]
[Exact output structure]

[EXAMPLES - Optional]
[2-3 examples]

[REASONING - Optional]
Think through this step-by-step:
[Thinking guidance]
```

### When to Use Each Technique

| Technique | Best For | Example Use Case |
|-----------|----------|------------------|
| Chain-of-Thought | Complex reasoning | Math, logic puzzles, multi-step analysis |
| Few-Shot | Pattern matching | Classification, style transfer, formatting |
| Zero-Shot | Simple, clear tasks | Direct questions, basic transformations |
| Structured (XML) | Parsed output | Data extraction, API responses |
| Progressive Disclosure | Large tasks | Full implementations, research |
| Role-Based | Expert knowledge | Code review, architecture decisions |

### Model Selection Guide

**Use GPT-5 when:**
- Need strong reasoning
- Agentic behavior helpful
- Code generation focus
- Latest knowledge needed

**Use Claude when:**
- Very long context (100K+ tokens)
- Detailed instruction following
- Safety-critical applications
- Prefer XML structuring

## Resources

All reference materials included:
- GPT-5 specific techniques and patterns
- Claude optimization strategies
- Advanced prompting patterns
- Optimization and improvement frameworks

## Summary

Effective prompt engineering:
- **Saves time** - Get right results faster
- **Reduces costs** - Fewer API calls needed
- **Improves quality** - More accurate, consistent outputs
- **Enables complexity** - Tackle harder problems
- **Scales knowledge** - Capture best practices

Use this skill to create prompts that:
- Are clear and specific
- Use proven techniques
- Match your model
- Get consistent results
- Achieve your goals

---

**Remember:** A well-crafted prompt is worth 10 poorly-attempted ones. Invest time upfront for better results.

© jamesrochabrun · MIT · jamesrochabrun/skills

Similar skills

All skills for AI and ML →

From the same set23

The whole set →
reading-teacher reading-teacher turns a prompt into an interactive HTML reading lesson for children aged 1 to 10, from letter sounds to story comprehension. CX Codex +1 291installs anthropic-prompt-engineer Builds new prompts from scratch and refines existing templates for Claude models using official Anthropic prompt engineering guidelines. CX Codex +1 233installs query-expert query-expert is a Claude Code skill for writing, tuning, and debugging SQL and NoSQL queries. It reads EXPLAIN plans and suggests indexes. CX Codex +1 227installs anthropic-architect The anthropic-architect skill reviews project requirements and recommends whether to use Skills, Agents, Prompts, or SDK primitives. Use it to plan an Anthropic-based system. CX Codex +1 219installs releasing-macos-apps The releasing-macos-apps skill guides macOS app releases from version changes and code signing through DMG creation, Apple notarization, and Sparkle updates. CX Codex +1 210installs content-brief-generator The content-brief-generator skill builds structured briefs for articles, docs, landing pages, and other formats. Use it when a writer needs a clear audience, goal, outline, and SEO direction. CX Codex +1 207installs design-brief-generator design-brief-generator is a Claude Code skill that builds structured design briefs. It activates for requests about project requirements, goals, and design planning. CX Codex +1 181installs swift-concurrency A skill for building, reviewing, and refactoring Swift concurrency code. Use it for async/await, actors, isolation, and Swift 6+ migrations. CX Codex +1 151installs

Project sponsors

Companies that keep this analytics open