adaptationio/prompt-builder

Prompt Builder

Overview

prompt-builder provides a systematic workflow for creating effective prompts in Claude Code skills. It applies prompt engineering principles, uses proven templates, and validates quality to ensure prompts are clear, specific, actionable, and produce reliable results.

Purpose: Create high-quality prompts for skills, workflows, tasks, and operations

Pattern: Workflow-based (5-step process)

Key Benefit: Transforms vague instructions into precise, effective prompts that Claude can execute reliably

When to Use

Use prompt-builder when:

• Creating new skill instructions
• Writing workflow steps that Claude will execute
• Defining task operations
• Building automation prompts
• Improving existing prompts that produce inconsistent results
• Ensuring prompts follow best practices

Prerequisites

Before building prompts:

• Clear objective: Know what the prompt should accomplish
• Context understanding: Understand the situation where the prompt will be used
• Success criteria: Define what "good output" looks like

Prompt Building Workflow

Step 1: Understand Context

Before writing any prompt, understand the full context.

What to Identify:

1. Goal: What should this prompt accomplish?

   • Create something new?
   • Transform existing content?
   • Analyze and provide insights?
   • Make a decision?

2. Audience: Who will use this prompt?

   • Claude directly (in skill)?
   • Developer building skills?
   • End user interacting with system?

3. Situation: When/where will this prompt be used?

   • Part of sequential workflow?
   • Independent task operation?
   • Conditional branch?
   • Error recovery?

4. Constraints: What limitations exist?

   • Time limits?
   • Output format requirements?
   • Tools available/unavailable?
   • Dependencies on other steps?

5. Success criteria: How do you know it worked?

   • Measurable outcome?
   • Specific format?
   • Validation criteria?

Questions to Ask:

• What problem does this prompt solve?
• What does "success" look like?
• What could go wrong?
• What information does Claude need?
• What should Claude NOT do?

Example Context Analysis:

Goal: Have Claude write a comprehensive guide for a reference file
Audience: Claude (executing skill)
Situation: Step 3 of 6 in skill-building workflow
Constraints: Must be <5,000 words, specific format
Success: Complete guide covering all topics, properly formatted

Common Context Mistakes:

• ❌ Skip context analysis, jump straight to writing
• ❌ Assume context is obvious
• ❌ Don't define success criteria
• ❌ Ignore constraints

Best Practices:

• ✅ Write down context explicitly
• ✅ Identify all constraints upfront
• ✅ Define measurable success
• ✅ Consider edge cases

→ Output: Context analysis document

→ Next: With context clear, define the specific task

Step 2: Define Task Clearly

Transform the goal into a clear, specific, actionable task definition.

Task Definition Elements:

1. Action Verb: What specific action?

   • Good: "Write", "Analyze", "Create", "Transform", "Extract"
   • Avoid: "Handle", "Deal with", "Work on", "Process"

2. Object: What is being acted upon?

   • Be specific: "the authentication module" not "the code"
   • Include type: "markdown file", "Python function", "data structure"

3. Constraints: What limits or requirements?

   • Format: "as a bulleted list", "in JSON format"
   • Length: "under 500 words", "10-15 items"
   • Style: "imperative voice", "technical language"

4. Quality Criteria: What makes output good?

   • Completeness: "covering all edge cases"
   • Accuracy: "matching the specification exactly"
   • Usability: "beginner-friendly explanations"

5. Context References: What information to use?

   • "based on the examples in references/"
   • "following the pattern from Step 2"
   • "using the template below"

Task Clarity Checklist:

• [ ] Action verb is specific and unambiguous
• [ ] Object is clearly identified
• [ ] Constraints are explicitly stated
• [ ] Success criteria are measurable
• [ ] Context references are provided
• [ ] Can be completed without additional questions

Good vs Bad Task Definitions:

❌ Bad: "Update the documentation"

• Vague action, unclear object, no criteria

✅ Good: "Write a Getting Started section for README.md covering installation, basic usage, and first example. Use imperative voice, keep under 300 words, include 2-3 code examples."

• Clear action, specific object, defined constraints and criteria

❌ Bad: "Make the code better"

• Subjective, unmeasurable, no direction

✅ Good: "Refactor the authentication function to use async/await pattern, add error handling for network failures, and include JSDoc comments for each parameter."

• Specific improvements, clear criteria, measurable outcome

Task Definition Template:

[ACTION VERB] [SPECIFIC OBJECT] that [QUALITY CRITERIA].

Constraints:
- [Format/Structure requirement]
- [Length/Size requirement]
- [Style/Tone requirement]

Success means:
- [Measurable criterion 1]
- [Measurable criterion 2]
- [Measurable criterion 3]

Use/Reference:
- [Context source 1]
- [Context source 2]

Example Task Definition:

Write a comprehensive dependency management guide that explains identification,
documentation, critical path analysis, and optimization strategies.

Constraints:
- Structure: 4 main sections with subsections
- Length: 600-800 words per section
- Style: Technical but accessible, use examples
- Format: Markdown with code examples

Success means:
- All dependency types covered (hard, soft, none)
- Critical path calculation explained with formula
- Optimization strategies include specific techniques
- Examples demonstrate each concept

Use/Reference:
- Project management best practices
- Task scheduling algorithms
- skill-builder patterns for reference organization

→ Output: Clear task definition with measurable criteria

→ Next: Structure the prompt effectively

Step 3: Structure Prompt

Organize the prompt using proven templates and patterns.

Core Prompt Structure:

[CONTEXT SETTING]
[TASK DEFINITION]
[CONSTRAINTS & REQUIREMENTS]
[OUTPUT FORMAT]
[EXAMPLES (if needed)]
[VALIDATION CRITERIA]

1. Context Setting (1-3 sentences)

Establish the situation and frame the task:

• What role is Claude playing?
• What's the broader goal?
• Why is this task needed?

Example:

You are creating a reference guide for a Claude Code skill. This guide will be
loaded on-demand when users need detailed information about dependency management.
The guide should be comprehensive yet practical.

2. Task Definition (From Step 2)

State exactly what to do:

Example:

Write a dependency management guide covering: identification, documentation,
critical path analysis, and optimization strategies.

3. Constraints & Requirements

List all limitations and requirements:

Example:

Requirements:
- 4 main sections: Identification, Documentation, Analysis, Optimization
- 600-800 words per section
- Include code examples and formulas
- Use markdown formatting with headers, lists, code blocks
- Technical but accessible language

Constraints:
- No external dependencies or libraries
- Must work with generic task structures
- Examples should be realistic but not project-specific

4. Output Format

Specify exact structure expected:

Example:

Format:
# Dependency Management Guide

## 1. Identifying Dependencies
[Content with examples]

## 2. Documenting Dependencies
[Content with templates]

## 3. Critical Path Analysis
[Content with formulas]

## 4. Optimization Strategies
[Content with techniques]

5. Examples (if helpful)

Provide patterns to follow:

Example:

Example dependency documentation:

Task 5: Write API integration (3h) Depends on: Task 2 (auth complete), Task 3 (models defined) Type: Hard (blocking) Rationale: Cannot call API without authentication and data models

6. Validation Criteria

How to verify success:

Example:

Verify the guide:
- [ ] All 4 sections present and complete
- [ ] Each section 600-800 words
- [ ] Code examples in each section
- [ ] Critical path formula included
- [ ] Practical optimization techniques provided
- [ ] Markdown formatting correct

Template Selection Guide:

Workflow Step Prompt:

## Step [N]: [Action Name]

[Step description and purpose]

**What to Do**:
[Detailed instructions]

**Inputs**: [What's available from previous steps]
**Outputs**: [What this step produces]
**Next**: [Where to go next]

Task Operation Prompt:

## Operation [N]: [Operation Name]

[Operation description]

**When to Use**: [Trigger conditions]
**Prerequisites**: [What's needed]
**Steps**: [How to execute]
**Validation**: [How to verify success]

Analysis Prompt:

Analyze [object] to [goal].

Context:
[Relevant background]

Analysis dimensions:
1. [Aspect 1]: [What to examine]
2. [Aspect 2]: [What to examine]
3. [Aspect 3]: [What to examine]

Output format:
[Structure of analysis]

Provide specific examples and evidence for each dimension.

Creation Prompt:

Create [object] that [criteria].

Specifications:
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

Structure:
[Format/organization]

Example: [Pattern to follow]

Validation: [Success criteria]

→ Output: Structured prompt following template

→ Next: Add context and examples

Step 4: Add Context & Examples

Enhance the prompt with necessary background and patterns.

Types of Context to Add:

1. Background Information

Provide essential knowledge:

• Technical concepts Claude should understand
• Domain-specific terminology
• Related patterns or principles
• Historical context (why this way?)

Example:

Background: Critical path is the longest sequence of dependent tasks
determining minimum project duration. Tasks on the critical path have
zero slack - any delay extends the project. Non-critical tasks have
slack and can be delayed without affecting completion.

2. Reference Materials

Point to existing resources:

• Templates to follow
• Previous examples
• Style guides
• Technical specifications

Example:

Reference: See examples/medirecords-integration/ for a similar two-phase
workflow pattern. Follow the same structure of planning phase → implementation
phase with validation steps between.

3. Constraints & Boundaries

Define what NOT to do:

• Scope limitations
• Excluded options
• Anti-patterns to avoid
• Error conditions

Example:

Do NOT:
- Include project-specific details
- Assume external tools/libraries
- Use placeholders like "TODO" or "FILL IN"
- Skip validation steps
- Create files outside specified directory

4. Examples & Patterns

Show concrete instances:

Good Examples - What success looks like:

Example of good dependency documentation:

Task 7: Implement error handling (2h)
  Depends on: Task 5 (API integration complete)
  Type: Hard (must handle API errors)
  Impact: Blocks Task 9 (testing), Task 10 (deployment)
  Critical path: Yes (on critical path)
  Rationale: Cannot test or deploy without proper error handling

Bad Examples - Common mistakes:

Example of poor dependency documentation (DON'T DO THIS):

Task 7: Error stuff (2h)
  Depends on: Maybe task 5?

This is vague, unclear type, no rationale, doesn't help scheduling.

Before/After - Improvements:

Before: "Update the database code"
After: "Refactor database query functions to use parameterized queries
preventing SQL injection, add connection pooling for performance, and
implement retry logic for transient failures."

5. Success Patterns

Describe characteristics of good output:

• Quality indicators
• Completeness checks
• Style markers
• Validation approaches

Example:

High-quality dependency analysis includes:
✅ Every task has dependencies listed (even if "none")
✅ Dependency types specified (hard/soft/none)
✅ Rationale explains WHY the dependency exists
✅ Critical path is identified and marked
✅ Parallel opportunities are noted
✅ Risk areas highlighted

Context Organization:

Place context strategically:

• Before task: Background, definitions, principles
• During task: Templates, formats, examples to follow
• After task: Validation, success criteria, next steps

Context Amount Guidelines:

Too little context:

• Claude makes assumptions
• Output varies widely
• Requires follow-up questions

Too much context:

• Overwhelms the task
• Dilutes key requirements
• Slows processing

Right amount:

• Sufficient for reliable execution
• Focused on task-relevant info
• Examples demonstrate patterns
• Validation criteria clear

Context Checklist:

• [ ] Background explains WHY
• [ ] Examples show HOW
• [ ] Constraints define boundaries
• [ ] Validation ensures quality
• [ ] References available if needed

→ Output: Enhanced prompt with context and examples

→ Next: Refine and validate quality

Step 5: Refine & Validate

Polish the prompt and verify it meets quality standards.

Refinement Process:

1. Clarity Check

Read through as if you're Claude:

• Is every instruction clear?
• Are terms defined?
• Is the sequence logical?
• Are transitions smooth?

Clarity Improvements:

• Replace vague terms with specific ones
• Break long sentences into shorter ones
• Use active voice ("Write X" not "X should be written")
• Add connective words (Then, Next, After, Before)

2. Completeness Check

Verify nothing is missing:

• [ ] Context provided?
• [ ] Task clearly defined?
• [ ] All constraints listed?
• [ ] Output format specified?
• [ ] Examples included (if needed)?
• [ ] Validation criteria given?

3. Specificity Check

Ensure precision:

• Numbers exact ("15 items" not "several items")
• Formats detailed ("JSON with keys X, Y, Z" not "JSON format")
• Actions specific ("Extract function names" not "Look at the code")
• Criteria measurable ("Under 500 words" not "Brief")

4. Consistency Check

Verify alignment:

• Terms used consistently throughout
• Examples match specifications
• Constraints don't contradict
• Validation matches requirements

5. Conciseness Check

Remove unnecessary words:

• Eliminate redundancy
• Combine similar points
• Remove filler phrases
• Keep focus tight

Before: "In order to create the file, you should write content that includes..." After: "Write a file containing..."

Validation Criteria:

Quality Dimensions:

1. Clarity (1-5): Can Claude understand without questions?

   • 5: Crystal clear, no ambiguity
   • 3: Mostly clear, minor confusion possible
   • 1: Vague, requires clarification

2. Specificity (1-5): Are requirements precise?

   • 5: All details specified exactly
   • 3: Key details specified, some inference needed
   • 1: High-level only, lots of guessing

3. Completeness (1-5): Is everything needed present?

   • 5: All context, examples, criteria included
   • 3: Basics present, some gaps
   • 1: Missing critical information

4. Actionability (1-5): Can Claude execute immediately?

   • 5: Ready to execute, no preparation needed
   • 3: Mostly ready, minor prep needed
   • 1: Requires significant additional work

5. Reliability (1-5): Will it produce consistent results?

   • 5: Same prompt → same quality output every time
   • 3: Generally consistent, occasional variation
   • 1: Highly variable output

Target: All dimensions ≥4 for production prompts

Validation Questions:

Clarity:

• Could a different person understand this prompt the same way?
• Are there any ambiguous words or phrases?
• Is the sequence of steps logical and clear?

Specificity:

• Are all measurements/quantities exact?
• Are formats precisely defined?
• Are examples specific and concrete?

Completeness:

• Does Claude have all information needed?
• Are edge cases covered?
• Are validation criteria provided?

Actionability:

• Can Claude start immediately?
• Are all dependencies available?
• Is the first action clear?

Reliability:

• Would this produce the same output twice?
• Are there subjective terms that vary?
• Are success criteria objective?

Testing Strategies:

1. Dry Run: Execute mentally step by step
2. Peer Review: Have someone else read it
3. Actual Test: Try the prompt with Claude
4. Iteration: Refine based on results

Common Issues & Fixes:

Issue: Prompt produces varying output Fix: Add more constraints, specify format exactly, provide examples

Issue: Claude asks clarifying questions Fix: Context incomplete, add background information

Issue: Output doesn't match expectations Fix: Success criteria unclear, make validation explicit

Issue: Prompt too long (>1000 words) Fix: Move details to references, keep core prompt focused

Issue: Assumes knowledge Claude doesn't have Fix: Add background section, define terms, provide context

Final Checklist:

Before using the prompt:

• [ ] Read aloud - does it flow naturally?
• [ ] Check all dimensions ≥4
• [ ] Verify examples match specs
• [ ] Confirm validation is measurable
• [ ] Test with Claude if possible
• [ ] Document any assumptions

→ Output: Refined, validated, production-ready prompt

Best Practices

Prompt Engineering Principles

1. Clarity First

• Use simple, direct language
• Define technical terms
• Break complex tasks into steps
• Use examples to clarify

2. Be Specific

• Exact numbers, not ranges (unless necessary)
• Precise formats, not general descriptions
• Specific actions, not vague requests
• Measurable criteria, not subjective

3. Provide Context

• Explain why the task matters
• Give relevant background
• Reference related materials
• Define scope boundaries

4. Show Examples

• Good examples (what to emulate)
• Bad examples (what to avoid)
• Before/after (how to improve)
• Edge cases (how to handle)

5. Enable Validation

• Measurable success criteria
• Objective quality indicators
• Checkable outputs
• Clear pass/fail

6. Think Iteratively

• Start simple, add detail
• Test and refine
• Learn from results
• Improve over time

Prompt Patterns

Instruction Pattern:

Do [action] to achieve [goal].
Include [elements].
Follow [format].

Analysis Pattern:

Analyze [object] for [aspects].
Consider [dimensions].
Provide [output type].

Creation Pattern:

Create [object] with [properties].
Use [template/pattern].
Ensure [quality criteria].

Transformation Pattern:

Transform [input] into [output].
Apply [rules/changes].
Maintain [constraints].

Quality Indicators

High-Quality Prompts:

• ✅ One clear objective per prompt
• ✅ All constraints explicit
• ✅ Examples demonstrate patterns
• ✅ Validation criteria measurable
• ✅ Context sufficient but not excessive
• ✅ Language precise and unambiguous

Low-Quality Prompts:

• ❌ Multiple conflicting objectives
• ❌ Implicit assumptions
• ❌ No examples or validation
• ❌ Vague success criteria
• ❌ Missing context
• ❌ Ambiguous language

Common Mistakes

Mistake 1: Vague Task Definition

Problem: "Make the code better"

• Subjective, unmeasurable, no direction

Fix: "Refactor the authentication module to use async/await, add input validation, and document each function with JSDoc comments"

• Specific changes, clear criteria, measurable

Mistake 2: Missing Constraints

Problem: "Write a guide"

• No length, format, audience specified

Fix: "Write a 500-word beginner-friendly guide in markdown format covering installation, basic usage, and first example"

• Length specified, audience clear, format defined

Mistake 3: No Examples

Problem: Instructions only, no patterns shown

• Claude guesses at style/format

Fix: Include 2-3 examples demonstrating the pattern

• Claude sees what "good" looks like

Mistake 4: Unclear Success Criteria

Problem: "Create good documentation"

• "Good" is subjective

Fix: "Create documentation covering all public APIs, with description, parameters, return values, and usage example for each"

• Objective, checkable, measurable

Mistake 5: Too Much Context

Problem: 2000-word background before 1-sentence task

• Obscures the actual task

Fix: Brief context (2-3 sentences), then task, then references to detailed background

• Focused, actionable, with optional depth

Mistake 6: Assuming Knowledge

Problem: "Implement the standard pattern"

• Assumes Claude knows which pattern

Fix: "Implement the Repository pattern: create interface IRepository<T>, implement with generic class, use dependency injection"

• Explicit about what "standard pattern" means

Integration with Other Skills

With skill-builder-generic

Use prompt-builder to create high-quality prompts for skill instructions

• Each workflow step is a prompt
• Each task operation is a prompt
• Reference guides include prompt examples

Flow: skill-builder → prompt-builder → improved skills

With planning-architect

Use prompt-builder to create clear prompts in skill plans

• Plan includes example prompts
• Workflow steps defined as prompts
• Validation includes prompt quality

Flow: plan skill → build prompts → validate prompts

With review-multi

Use prompt-builder as validation criteria for prompt quality

• Review checks prompt clarity
• Review verifies specificity
• Review ensures validation criteria

Flow: create skill → review prompts → refine prompts

Quick Reference

The 5-Step Workflow

1. Understand Context: Goal, audience, situation, constraints, success
2. Define Task: Action verb + object + constraints + criteria
3. Structure Prompt: Template + format + organization
4. Add Context: Background + examples + boundaries
5. Refine & Validate: Clarity + completeness + specificity + test

Quality Checklist

• [ ] Clear action verb and specific object
• [ ] All constraints explicitly listed
• [ ] Success criteria measurable
• [ ] Context provides necessary background
• [ ] Examples demonstrate patterns
• [ ] Format/structure specified
• [ ] Validation criteria included
• [ ] Language precise and unambiguous
• [ ] All dimensions score ≥4
• [ ] Tested (if possible)

Key Principles

• Clarity First: Simple, direct, unambiguous
• Be Specific: Exact requirements, precise criteria
• Provide Context: Background, examples, boundaries
• Enable Validation: Measurable, objective, checkable

---

For detailed guides on prompt engineering principles, templates, and examples, see the references/ directory.

For automated prompt validation, use scripts/validate-prompt.py.