Agent skill

when-optimizing-prompts-use-prompt-architect

Comprehensive framework for analyzing, creating, and refining prompts for AI systems using evidence-based techniques

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/dnyoussef/when-optimizing-prompts-use-prompt-architect

SKILL.md

Prompt Architect - Evidence-Based Prompt Engineering

Overview

Comprehensive framework for analyzing, creating, and refining prompts for AI systems (Claude, GPT, etc.). Applies structural optimization, self-consistency patterns, and anti-pattern detection to transform prompts into highly effective versions.

When to Use This Skill

  • Creating new prompts for AI systems
  • Existing prompts produce poor results
  • Inconsistent AI outputs
  • Need to improve prompt clarity
  • Applying evidence-based prompt engineering
  • Optimizing agent instructions
  • Building prompt libraries

Theoretical Foundation

Evidence-Based Techniques

  1. Chain-of-Thought (CoT): Explicit reasoning steps
  2. Self-Consistency: Multiple reasoning paths
  3. ReAct: Reasoning + Acting pattern
  4. Program-of-Thought: Structured logic
  5. Plan-and-Solve: Decomposition strategy
  6. Role-Playing: Persona assignment
  7. Few-Shot Learning: Example-based instruction

Prompt Structure Principles

[System Context] → [Role Definition] → [Task Description] →
[Constraints] → [Format Specification] → [Examples] → [Quality Criteria]

Phase 1: Analyze Current Prompt

Objective

Identify weaknesses and improvement opportunities

Agent: Researcher

Step 1.1: Structural Analysis

javascript
const promptAnalysis = {
  components: {
    hasSystemContext: checkForContext(prompt),
    hasRoleDefinition: checkForRole(prompt),
    hasTaskDescription: checkForTask(prompt),
    hasConstraints: checkForConstraints(prompt),
    hasFormatSpec: checkForFormat(prompt),
    hasExamples: checkForExamples(prompt),
    hasQualityCriteria: checkForCriteria(prompt)
  },
  metrics: {
    length: prompt.length,
    clarity: calculateClarity(prompt),
    specificity: calculateSpecificity(prompt),
    completeness: calculateCompleteness(prompt)
  },
  antiPatterns: detectAntiPatterns(prompt)
};

await memory.store('prompt-architect/analysis', promptAnalysis);

Step 1.2: Detect Anti-Patterns

javascript
const antiPatterns = [
  {
    name: 'Vague Instructions',
    pattern: /please|try to|maybe|possibly/gi,
    severity: 'HIGH',
    fix: 'Use imperative commands: "Analyze...", "Generate...", "Create..."'
  },
  {
    name: 'Missing Context',
    pattern: absence of background info,
    severity: 'HIGH',
    fix: 'Add system context and domain information'
  },
  {
    name: 'No Output Format',
    pattern: absence of format specification,
    severity: 'MEDIUM',
    fix: 'Specify exact output format (JSON, markdown, etc.)'
  },
  {
    name: 'Conflicting Instructions',
    pattern: detectContradictions(prompt),
    severity: 'HIGH',
    fix: 'Resolve contradictions, prioritize requirements'
  },
  {
    name: 'Implicit Assumptions',
    pattern: detectImplicitAssumptions(prompt),
    severity: 'MEDIUM',
    fix: 'Make all assumptions explicit'
  }
];

const foundAntiPatterns = antiPatterns.filter(ap =>
  ap.pattern.test ? ap.pattern.test(prompt) : ap.pattern
);

await memory.store('prompt-architect/anti-patterns', foundAntiPatterns);

Step 1.3: Identify Missing Components

javascript
const missingComponents = [];

if (!promptAnalysis.components.hasSystemContext) {
  missingComponents.push({
    component: 'System Context',
    importance: 'HIGH',
    recommendation: 'Add background info, domain knowledge, constraints'
  });
}

if (!promptAnalysis.components.hasExamples) {
  missingComponents.push({
    component: 'Examples',
    importance: 'MEDIUM',
    recommendation: 'Add 2-3 examples showing desired behavior'
  });
}

// ... check other components

await memory.store('prompt-architect/missing', missingComponents);

Validation Criteria

  • All 7 components checked
  • Anti-patterns identified
  • Missing components listed
  • Severity assigned to issues

Hooks Integration

bash
npx claude-flow@alpha hooks pre-task \
  --description "Analyze prompt structure and quality" \
  --complexity "medium"

npx claude-flow@alpha hooks post-task \
  --task-id "prompt-analysis" \
  --output "analysis-report.json"

Phase 2: Structure Optimization

Objective

Reorganize prompt for logical flow and clarity

Agent: Coder (Prompt Specialist)

Step 2.1: Apply Template Structure

javascript
const optimizedStructure = {
  systemContext: {
    domain: extractDomain(prompt),
    background: generateContextualBackground(),
    constraints: extractOrInferConstraints(prompt)
  },
  roleDefinition: {
    persona: definePersona(task),
    expertise: listRequiredExpertise(),
    perspective: defineWorkingPerspective()
  },
  taskDescription: {
    primary: extractPrimaryTask(prompt),
    secondary: extractSecondaryTasks(prompt),
    scope: defineScope(),
    outOfScope: defineWhatNotToDo()
  },
  constraints: {
    required: extractRequirements(prompt),
    forbidden: extractProhibitions(prompt),
    optional: extractPreferences(prompt)
  },
  formatSpecification: {
    outputFormat: specifyFormat(),
    structure: defineStructure(),
    examples: []
  },
  qualityCriteria: {
    success: defineSuccessCriteria(),
    validation: defineValidationMethod(),
    metrics: defineMetrics()
  }
};

await memory.store('prompt-architect/structure', optimizedStructure);

Step 2.2: Build Optimized Prompt

markdown
# System Context
${optimizedStructure.systemContext.background}

Domain: ${optimizedStructure.systemContext.domain}
Constraints: ${optimizedStructure.systemContext.constraints.join(', ')}

# Role
You are ${optimizedStructure.roleDefinition.persona} with expertise in:
${optimizedStructure.roleDefinition.expertise.map(e => `- ${e}`).join('\n')}

Your perspective: ${optimizedStructure.roleDefinition.perspective}

# Task
Primary objective: ${optimizedStructure.taskDescription.primary}

${optimizedStructure.taskDescription.secondary.length > 0 ?
  'Secondary objectives:\n' + optimizedStructure.taskDescription.secondary.map(t => `- ${t}`).join('\n') : ''}

Scope: ${optimizedStructure.taskDescription.scope}
Out of scope: ${optimizedStructure.taskDescription.outOfScope.join(', ')}

# Constraints
MUST: ${optimizedStructure.constraints.required.map(r => `- ${r}`).join('\n')}
MUST NOT: ${optimizedStructure.constraints.forbidden.map(f => `- ${f}`).join('\n')}
PREFER: ${optimizedStructure.constraints.optional.map(o => `- ${o}`).join('\n')}

# Output Format
${optimizedStructure.formatSpecification.outputFormat}

Structure:
${optimizedStructure.formatSpecification.structure}

# Quality Criteria
Success is defined as:
${optimizedStructure.qualityCriteria.success.map(s => `- ${s}`).join('\n')}

Validation method: ${optimizedStructure.qualityCriteria.validation}

Step 2.3: Add Progressive Disclosure

javascript
// For complex prompts, use hierarchical structure
const progressivePrompt = {
  essential: generateEssentialInstructions(),
  details: generateDetailedGuidance(),
  advanced: generateAdvancedTechniques(),
  examples: generateExamples(),
  troubleshooting: generateTroubleshootingGuide()
};

// Structure with collapsible sections
const enhancedPrompt = `
${progressivePrompt.essential}

<details>
<summary>Detailed Guidance</summary>
${progressivePrompt.details}
</details>

<details>
<summary>Advanced Techniques</summary>
${progressivePrompt.advanced}
</details>

<details>
<summary>Examples</summary>
${progressivePrompt.examples}
</details>
`;

Validation Criteria

  • All 7 components present
  • Logical flow established
  • Progressive disclosure applied
  • Clear hierarchy visible

Script Template

bash
#!/bin/bash
# optimize-structure.sh

INPUT_PROMPT="$1"
OUTPUT_PROMPT="$2"

# Analyze structure
ANALYSIS=$(npx claude-flow@alpha agent-spawn \
  --type researcher \
  --task "Analyze prompt structure: $(cat $INPUT_PROMPT)")

# Optimize
OPTIMIZED=$(npx claude-flow@alpha agent-spawn \
  --type coder \
  --task "Restructure prompt based on analysis: $ANALYSIS")

echo "$OPTIMIZED" > "$OUTPUT_PROMPT"

npx claude-flow@alpha hooks post-edit \
  --file "$OUTPUT_PROMPT" \
  --memory-key "prompt-architect/optimized"

Phase 3: Apply Evidence-Based Techniques

Objective

Incorporate proven prompt engineering methods

Agent: Researcher + Coder

Step 3.1: Add Chain-of-Thought

markdown
# Chain-of-Thought Enhancement

Before providing your final answer, think through the problem step by step:

1. **Understand**: Restate the problem in your own words
2. **Analyze**: Break down into components
3. **Reason**: Work through the logic
4. **Synthesize**: Combine insights
5. **Conclude**: Provide final answer

Format your response as:
<thinking>
[Your step-by-step reasoning]
</thinking>

<answer>
[Your final answer]
</answer>

Step 3.2: Add Self-Consistency

markdown
# Self-Consistency Pattern

Generate 3 independent solutions to this problem using different approaches:

Approach 1: [Method 1]
Approach 2: [Method 2]
Approach 3: [Method 3]

Then compare the solutions and select the most robust answer, explaining why it's superior.

Step 3.3: Add ReAct Pattern

markdown
# ReAct (Reasoning + Acting) Pattern

For each step in your process:

**Thought**: [What you're thinking]
**Action**: [What you're doing]
**Observation**: [What you learned]

Repeat this cycle until the task is complete.

Example:
Thought: I need to understand the data structure
Action: Analyze the schema
Observation: It's a relational database with 5 tables
Thought: I should check for relationships
Action: Examine foreign keys
Observation: Tables are connected via user_id

Step 3.4: Add Few-Shot Examples

javascript
const examples = [
  {
    input: '[Example input 1]',
    reasoning: '[How to approach it]',
    output: '[Expected output 1]'
  },
  {
    input: '[Example input 2]',
    reasoning: '[How to approach it]',
    output: '[Expected output 2]'
  },
  {
    input: '[Example input 3 - edge case]',
    reasoning: '[How to handle edge case]',
    output: '[Expected output 3]'
  }
];

const fewShotSection = `
# Examples

${examples.map((ex, i) => `
## Example ${i + 1}

**Input**: ${ex.input}

**Reasoning**: ${ex.reasoning}

**Output**:
\`\`\`
${ex.output}
\`\`\`
`).join('\n')}

Now apply the same pattern to: [ACTUAL INPUT]
`;

Step 3.5: Add Constraint Framing

markdown
# Constraint-Based Optimization

This task requires balancing multiple constraints:

1. **Quality**: Must meet 90% accuracy
2. **Speed**: Must complete in < 2 seconds
3. **Resources**: Memory usage < 100MB
4. **Safety**: No external API calls

When these constraints conflict, prioritize in this order: Safety > Quality > Speed > Resources

If you cannot satisfy all constraints, explicitly state which ones are violated and why.

Validation Criteria

  • CoT reasoning added
  • Self-consistency pattern included
  • Examples provided (2-3)
  • Constraints clearly framed

Memory Pattern

bash
npx claude-flow@alpha hooks post-edit \
  --file "enhanced-prompt.md" \
  --memory-key "prompt-architect/techniques-applied"

Phase 4: Validate Effectiveness

Objective

Test prompt performance and measure improvement

Agent: Researcher

Step 4.1: Define Test Cases

javascript
const testCases = [
  {
    id: 'test-1',
    type: 'typical',
    input: '[Common use case]',
    expectedOutput: '[What should happen]',
    successCriteria: '[How to measure success]'
  },
  {
    id: 'test-2',
    type: 'edge-case',
    input: '[Unusual scenario]',
    expectedOutput: '[How to handle]',
    successCriteria: '[Validation method]'
  },
  {
    id: 'test-3',
    type: 'stress',
    input: '[Complex/ambiguous input]',
    expectedOutput: '[Robust handling]',
    successCriteria: '[Quality threshold]'
  }
];

await memory.store('prompt-architect/test-cases', testCases);

Step 4.2: Run A/B Tests

javascript
async function runABTest(originalPrompt, optimizedPrompt, testCases) {
  const results = {
    original: [],
    optimized: []
  };

  for (const testCase of testCases) {
    // Test original prompt
    const originalResult = await testPrompt(originalPrompt, testCase.input);
    results.original.push({
      testId: testCase.id,
      output: originalResult,
      score: scoreOutput(originalResult, testCase.expectedOutput),
      meetsSuccessCriteria: evaluateCriteria(originalResult, testCase.successCriteria)
    });

    // Test optimized prompt
    const optimizedResult = await testPrompt(optimizedPrompt, testCase.input);
    results.optimized.push({
      testId: testCase.id,
      output: optimizedResult,
      score: scoreOutput(optimizedResult, testCase.expectedOutput),
      meetsSuccessCriteria: evaluateCriteria(optimizedResult, testCase.successCriteria)
    });
  }

  return results;
}

const abTestResults = await runABTest(originalPrompt, optimizedPrompt, testCases);
await memory.store('prompt-architect/ab-test-results', abTestResults);

Step 4.3: Calculate Metrics

javascript
const metrics = {
  original: {
    avgScore: calculateAverage(abTestResults.original.map(r => r.score)),
    successRate: calculateSuccessRate(abTestResults.original),
    consistency: calculateConsistency(abTestResults.original)
  },
  optimized: {
    avgScore: calculateAverage(abTestResults.optimized.map(r => r.score)),
    successRate: calculateSuccessRate(abTestResults.optimized),
    consistency: calculateConsistency(abTestResults.optimized)
  },
  improvement: {
    scoreImprovement: 0, // calculated below
    successRateImprovement: 0,
    consistencyImprovement: 0
  }
};

metrics.improvement = {
  scoreImprovement: ((metrics.optimized.avgScore - metrics.original.avgScore) / metrics.original.avgScore * 100).toFixed(2) + '%',
  successRateImprovement: ((metrics.optimized.successRate - metrics.original.successRate) / metrics.original.successRate * 100).toFixed(2) + '%',
  consistencyImprovement: ((metrics.optimized.consistency - metrics.original.consistency) / metrics.original.consistency * 100).toFixed(2) + '%'
};

await memory.store('prompt-architect/metrics', metrics);

Validation Criteria

  • Test cases defined (3+ cases)
  • A/B testing completed
  • Metrics calculated
  • Improvement demonstrated

Script Template

bash
#!/bin/bash
# validate-prompt.sh

ORIGINAL="$1"
OPTIMIZED="$2"
TEST_CASES="$3"

# Run A/B tests
RESULTS=$(npx claude-flow@alpha agent-spawn \
  --type researcher \
  --task "A/B test prompts: original='$ORIGINAL' optimized='$OPTIMIZED' tests='$TEST_CASES'")

# Calculate improvement
METRICS=$(echo "$RESULTS" | jq '.improvement')

echo "Improvement Metrics:"
echo "$METRICS" | jq '.'

# Store results
npx claude-flow@alpha hooks post-task \
  --task-id "prompt-validation" \
  --metrics "$METRICS"

Phase 5: Refine Iteratively

Objective

Continuous improvement based on validation results

Agent: Coder

Step 5.1: Analyze Failures

javascript
const failures = abTestResults.optimized.filter(r => !r.meetsSuccessCriteria);

const failureAnalysis = failures.map(failure => {
  const testCase = testCases.find(tc => tc.id === failure.testId);

  return {
    testId: failure.testId,
    testType: testCase.type,
    expectedOutput: testCase.expectedOutput,
    actualOutput: failure.output,
    gap: analyzeGap(testCase.expectedOutput, failure.output),
    rootCause: identifyRootCause(failure, optimizedPrompt),
    recommendedFix: suggestFix(rootCause)
  };
});

await memory.store('prompt-architect/failure-analysis', failureAnalysis);

Step 5.2: Apply Refinements

javascript
let refinedPrompt = optimizedPrompt;

for (const analysis of failureAnalysis) {
  switch (analysis.rootCause.type) {
    case 'MISSING_CONSTRAINT':
      refinedPrompt = addConstraint(refinedPrompt, analysis.recommendedFix.constraint);
      break;
    case 'AMBIGUOUS_INSTRUCTION':
      refinedPrompt = clarifyInstruction(refinedPrompt, analysis.recommendedFix.clarification);
      break;
    case 'INSUFFICIENT_EXAMPLES':
      refinedPrompt = addExample(refinedPrompt, analysis.recommendedFix.example);
      break;
    case 'MISSING_EDGE_CASE_HANDLING':
      refinedPrompt = addEdgeCaseGuidance(refinedPrompt, analysis.recommendedFix.guidance);
      break;
  }
}

await memory.store('prompt-architect/refined-prompt', refinedPrompt);

Step 5.3: Re-validate

javascript
const revalidationResults = await runABTest(optimizedPrompt, refinedPrompt, testCases);

const improvementFromOptimized = {
  scoreImprovement: calculateImprovement(
    metrics.optimized.avgScore,
    calculateAverage(revalidationResults.optimized.map(r => r.score))
  ),
  successRateImprovement: calculateImprovement(
    metrics.optimized.successRate,
    calculateSuccessRate(revalidationResults.optimized)
  )
};

// If refined version is better, adopt it
if (improvementFromOptimized.scoreImprovement > 5) {
  console.log('✅ Refinement successful. Adopting refined version.');
  finalPrompt = refinedPrompt;
} else {
  console.log('✅ Optimized version is sufficient.');
  finalPrompt = optimizedPrompt;
}

await memory.store('prompt-architect/final-prompt', finalPrompt);

Step 5.4: Generate Documentation

markdown
# Prompt Optimization Report

## Original Prompt
\`\`\`
${originalPrompt}
\`\`\`

## Final Prompt
\`\`\`
${finalPrompt}
\`\`\`

## Changes Applied
${changesApplied.map(change => `- ${change}`).join('\n')}

## Performance Metrics

| Metric | Original | Optimized | Improvement |
|--------|----------|-----------|-------------|
| Avg Score | ${metrics.original.avgScore} | ${metrics.optimized.avgScore} | ${metrics.improvement.scoreImprovement} |
| Success Rate | ${metrics.original.successRate}% | ${metrics.optimized.successRate}% | ${metrics.improvement.successRateImprovement} |
| Consistency | ${metrics.original.consistency} | ${metrics.optimized.consistency} | ${metrics.improvement.consistencyImprovement} |

## Test Results
${testCases.map(tc => `
### ${tc.id} (${tc.type})
- **Expected**: ${tc.expectedOutput}
- **Original Result**: ${getResult('original', tc.id)}
- **Optimized Result**: ${getResult('optimized', tc.id)}
- **Status**: ${getStatus('optimized', tc.id)}
`).join('\n')}

## Recommendations
${generateRecommendations(finalPrompt)}

Validation Criteria

  • Failures analyzed
  • Refinements applied
  • Re-validation completed
  • Documentation generated

Memory Pattern

bash
npx claude-flow@alpha hooks session-end \
  --session-id "prompt-architect-${TIMESTAMP}" \
  --export-metrics true \
  --summary "Prompt optimized with ${IMPROVEMENT}% improvement"

Success Metrics

Quantitative

  • Score improvement > 20%
  • Success rate > 85%
  • Consistency score > 0.8
  • All test cases pass

Qualitative

  • Clear structure
  • No anti-patterns
  • Evidence-based techniques applied
  • User satisfaction with outputs

Common Patterns

Pattern 1: Role-Based Optimization

markdown
You are an expert ${domain} specialist with ${years} years of experience.
Your expertise includes: ${expertise_list}
You approach problems by: ${methodology}

Pattern 2: Constraint-First Design

markdown
# Constraints (Read First)
MUST: ${required_constraints}
MUST NOT: ${forbidden_actions}
OPTIMIZE FOR: ${optimization_targets}

# Task
[task description with constraints in mind]

Pattern 3: Format-Driven Output

markdown
Your output MUST follow this exact structure:

\`\`\`json
{
  "analysis": "...",
  "recommendations": [...],
  "confidence": 0.XX
}
\`\`\`

Do not deviate from this format.

Integration Examples

With Agent Creation

javascript
// Use prompt architect to optimize agent system prompts
const agentPrompt = await optimizePrompt({
  role: 'backend-developer',
  domain: 'Node.js API development',
  constraints: ['RESTful design', 'security-first', 'test-driven'],
  outputFormat: 'production-ready code'
});

With SPARC Workflow

bash
# Optimize specification prompts
npx claude-flow@alpha skill-run prompt-architect \
  --input "sparc-spec-prompt.md" \
  --output "optimized-spec-prompt.md"

# Use optimized prompt in SPARC
npx claude-flow@alpha sparc run spec-pseudocode \
  --prompt-file "optimized-spec-prompt.md"

Memory Schema

javascript
{
  "prompt-architect/": {
    "session-${id}/": {
      "analysis": {},
      "anti-patterns": [],
      "missing": [],
      "structure": {},
      "techniques-applied": [],
      "test-cases": [],
      "ab-test-results": {},
      "metrics": {},
      "failure-analysis": [],
      "refined-prompt": "",
      "final-prompt": ""
    }
  }
}

Skill Completion

Outputs:

  1. final-prompt.md: Optimized prompt ready for use
  2. optimization-report.md: Detailed analysis and results
  3. ab-test-results.json: Performance comparison data
  4. prompt-library-entry.md: Cataloged for reuse

Skill complete when metrics show >20% improvement and all test cases pass.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results