Based on Claude 4.x Best Practices (December 2025)
Sources:
- Nate B. Jones Prompting Playbook 2025
- Anthropic Official Claude 4.x Prompting Guide
- Claude Code Best Practices
ACTIVATION
Manual only. This skill does NOT activate automatically — not even after clarify-spec. The previous auto-chain (clarify-spec -> prompt-architect) was removed because it reinforced a clarification loop.
Manually with Trigger
/prompt-architect [task description]
If a clarify-spec run preceded it and a JSON result is available, prompt-architect can use this JSON — but only if the user explicitly invokes /prompt-architect.
The 4 Beginner Moves (Nate B. Jones)
Move 1: Define the Shape of Output
NOT: Write good code BUT: Produce a TypeScript file with interface X, export function Y
Define concrete artifacts:
- Which files are created/changed?
- What format does the output have?
- What does an example output look like?
Move 2: Give Minimal but Sufficient Context
- Automatically read in relevant files
- CLAUDE.md/AGENTS.md excerpts
- Only what is necessary - no context overflow
- Observe token budget
Move 3: Suggest a Silent Plan
- Claude should plan INTERNALLY before responding
- For Claude 4.5: consider your approach first
- Avoiding think when Extended Thinking is disabled
Move 4: Add a Quick Self-Check
- Evaluator block at the end of the prompt
- Checklist: Format adhered to? Constraints met?
- Before responding, verify: [checklist]
Claude 4.x Specific Patterns
Explicitness + Modifier
NOT: Create dashboard BUT: Create dashboard. Include as many relevant features as possible. Go beyond the basics.
Context + Motivation (WHY explains WHAT)
NOT: NEVER use ellipses BUT: Your response will be read aloud by TTS, so never use ellipses since TTS cannot pronounce them.
Examples beat Adjectives
NOT: Write professionally BUT: Show example output, demonstrate format
XML tags for structure
<output_structure>, ,
Uncertainty Permission
If unsure, state explicitly and ask clarifying question. Reduces hallucinations drastically.
The Contract-Style Template
After analyzing the task, generate this structured prompt:
---BEGIN GENERATED PROMPT---
ROLE and GOAL
You are: [Role based on task type, e.g. Senior TypeScript Developer] Goal: [Concrete success definition in 1 sentence from clarified_task.goal]
CONTEXT
[Automatically collected:]
- Project: [Project name from CLAUDE.md]
- Relevant files: [List with brief content overview]
- Existing patterns: [Extracted from codebase]
- No-Touch Zones: [From clarified_task.scope.no_touch]
CONSTRAINTS
- [Constraint 1 as bullet from clarified_task.constraints]
- [Constraint 2 as bullet]
- [Max 5 constraints]
- If unsure about any aspect: State explicitly and ask for clarification
TASK
[Clear task description from clarified_task.goal + problem_statement]
Success Criteria
- [Criterion 1 from clarified_task.success_criteria]
- [Criterion 2]
- All existing tests must pass
Examples (if examples_needed = true)
Input: [Example input] Expected Output: [Expected output]
OUTPUT FORMAT
<output_structure> [Exact format based on task type:]
- For code: Complete files, no diffs, no placeholders
- For docs: Markdown with headings
- For config: JSON/YAML with comments </output_structure>
VERIFICATION (Self-Check)
Before responding, verify: [ ] Output format followed exactly? [ ] All constraints from CONSTRAINTS section satisfied? [ ] All success criteria from TASK section met? [ ] Uncertain claims marked with [UNCERTAIN]? [ ] No changes to No-Touch Zones?
---END GENERATED PROMPT---
Workflow
Step 1: Analyze input
Accepted:
- JSON or context from a previous clarify-spec run, if the user explicitly invokes /prompt-architect afterwards
- Free-form text description
- Combined with current project context
Step 2: Automatically collect context
- Glob for relevant files
- Read CLAUDE.md/AGENTS.md
- Identify No-Touch Zones
- Extract existing patterns from codebase
Step 3: Fill in template
Fill the contract-style template with:
- Role based on task type (frontend, backend, DevOps, etc.)
- Goal from clarified_task.goal
- Context from project analysis
- Constraints from clarified_task.constraints
- Task from goal + problem_statement
- Output Format based on expected artifacts
- Verification Checklist
Step 4: Present prompt
Show the generated prompt to the user:
Generated Best-Practice Prompt
[Complete prompt here]
Options:
- execute: Execute this prompt now
- adjust: Modify prompt
- copy: Copy prompt to clipboard
- save: Save as template
Step 5: Execution
On execute:
- Use prompt internally
- With quality gates (when /supervisor is active)
- Present result
Example: From vague request to best-practice prompt
Input (from clarify-spec):
{ clarified_task: { goal: Fix PPTX export so AI images reliably appear, problem_statement: Images sometimes missing in PPTX download, scope: { files: [presentationBuilder.ts, chartVisualGenerator.ts], no_touch: [api/analyze.ts] }, success_criteria: [All images appear, Under 500KB, No errors], constraints: [No breaking changes] } }
Output (generated prompt):
ROLE and GOAL
You are: Senior TypeScript Developer specializing in browser-based file generation Goal: Fix PPTX export so AI-generated images reliably appear in downloaded files
CONTEXT
- Project: fabrikIQ Analyzer (Manufacturing AI Platform)
- Relevant files:
- presentationBuilder.ts: PptxGenJS integration, slide generation
- chartVisualGenerator.ts: Gemini image generation, base64 handling
- Existing patterns: Async/await, try-catch error handling
- No-Touch Zones: api/analyze.ts (core analysis)
CONSTRAINTS
- No breaking changes to existing PPTX export functionality
- Images must be compressed to under 500KB
- Maintain existing error handling patterns
- If unsure about any aspect: State explicitly and ask
TASK
Fix the PPTX export to ensure AI-generated images reliably appear in downloads. The current issue: Images sometimes fail to appear in the final PPTX file.
Success Criteria
- All AI-generated images appear in PPTX
- Image file size under 500KB each
- No console errors during download
- Existing tests still pass
OUTPUT FORMAT
<output_structure> Provide complete, modified TypeScript files. No diffs, no placeholders, no partial implementations. Include brief comments explaining key changes. </output_structure>
VERIFICATION
Before responding, verify: [ ] All images will be embedded correctly? [ ] Compression logic handles edge cases? [ ] No changes to api/analyze.ts? [ ] Error handling covers network failures?
Token Efficiency
The generated prompt is optimized for:
- Minimal context (only relevant info)
- Maximum clarity (no ambiguity)
- Self-verification (reduces iterations)
Integration
After clarify-spec
clarify-spec -> User explicitly calls /prompt-architect -> Prompt -> Execution
With /supervisor
prompt-architect -> Prompt -> /supervisor -> Quality Gates -> Result
Standalone
/prompt-architect [Task] -> Prompt -> Execution