optimize-prompt-goal

name	optimize-prompt-goal
description	Optimizes prompts for goal effectiveness - ensures instructions serve the stated goal, prevents missteps, improves efficiency. Use when asked to optimize a prompt for its goal, improve goal alignment, or make a prompt more effective at achieving its purpose.

Optimize Prompt Goal

Iteratively optimize prompt for alignment with stated goal and likelihood of achieving intended outcomes through analysis and verification loops.

Overview

This skill transforms goal-misaligned prompts into effective ones through:

1. Verification First - prompt-goal-verifier checks for issues before any changes
2. Optimization - Apply targeted fixes based on verifier feedback
3. Re-verification - Verify fixes, iterate if issues remain (max 5 iterations)
4. Output - Atomic replacement only after verification passes

Loop: Read → Verify → (Exit if optimal) → Optimize based on feedback → Re-verify → (Iterate if issues) → Output

Key principle: Don't try to optimize in one pass. The verifier drives all changes - if it finds no issues, the prompt is already optimal.

Required tools: This skill requires Task tool to launch the verifier agent. If Task is unavailable, report error: "Task tool required for verification loop." This skill uses TodoWrite to track progress. If TodoWrite is unavailable, track progress internally and proceed without external todo tracking.

Workflow

Phase 0: Create Todo List (TodoWrite immediately)

Create todos tracking workflow phases. Todos represent areas of work that may expand during execution.

Starter todos:

- [ ] Input validation
- [ ] Initial verification
- [ ] (Expand: optimization iterations on ISSUES_FOUND)
- [ ] Output optimized prompt

Phase 1: Input Validation

Mark "Input validation" todo in_progress.

Step 1.1: Parse arguments

Extract input from $ARGUMENTS. Determine if file path or inline prompt.

Step 1.2: Handle input type

Input Type	Detection	Action
File path	Path contains / or \, OR ends with .md, .txt, .yaml, .yml	Read file content
Inline prompt	Does not match file path criteria above	Write to /tmp/prompt-{timestamp}.md

Priority: If input could match both (e.g., text containing /), treat as file path first; if file not found, treat as inline.

Step 1.3: Validate content

• If detected as file path: Attempt to read file using Read tool.
  • If file exists and has content: Use file content
  • If file exists but empty: Error: "Cannot optimize empty prompt. File contains no content: {path}"
  • If file not found: Re-classify as inline prompt and write to temp file
• If inline: Write to temp file, note original was inline
• Error only if no input provided at all: "Usage: /optimize-prompt-goal OR /optimize-prompt-goal "

Step 1.4: Store metadata

• source_path: Source file path (or temp path for inline)
• is_inline: Boolean (affects output messaging)
• original_content: Full prompt text
• original_path: /tmp/goal-original-{YYYYMMDDHHMMSS}-{4-lowercase-alphanumeric}.md (copy of original for verifier comparison)
• working_path: /tmp/goal-optimized-{YYYYMMDDHHMMSS}-{4-lowercase-alphanumeric}.md (modified version)

Mark "Input validation" todo completed.

Phase 2: Initial Verification

Mark "Initial verification" todo in_progress.

Step 2.1: Create working copies

Using Write tool:

1. Copy original content to original_path (untouched reference for verifier comparison)
2. Copy original content to working_path (will be modified)

Step 2.2: Run verifier first (single file mode)

Launch prompt-goal-verifier agent via Task tool BEFORE any optimization:

• subagent_type: "prompt-engineering:prompt-goal-verifier"
• prompt: "Verify prompt goal optimization. File: {working_path}. Check for goal misalignment, misstep risks, failure mode gaps, contradictory guidance, unsafe defaults, unnecessary overhead, indirect paths, and redundant instructions. Report VERIFIED or ISSUES_FOUND with specific details."

Step 2.3: Handle verifier response

• If "VERIFIED": Mark todo completed, proceed directly to Phase 4 (Output) with message: "Prompt is already goal-optimized. No changes needed."
• If "ISSUES_FOUND": Mark todo completed, save the issues list, add "Optimization iteration 1" todo and proceed to Phase 3
• If verifier fails or returns unexpected format: Retry once with identical parameters. If retry fails, report error: "Verification failed - cannot proceed without verifier."

Step 2.4: Display verifier findings

If issues found, show user the verifier's inferred goal and proceed:

Inferred Goal: {goal from verifier response}
Verifier found {count} issues. Proceeding with optimization...

Mark "Initial verification" todo completed.

Phase 3: Optimization Loop (Verifier-Driven)

Mark "Optimization iteration 1" todo in_progress.

Key principle: All fixes are driven by verifier feedback. Do NOT analyze the prompt independently - only fix the specific issues the verifier reported.

For each iteration from 1 to 5:

1. Apply fixes from verifier feedback: For each issue in the verifier's report, apply the Suggested Fix or use Optimization Techniques (see below) to address it. Write optimized version to working_path using Write tool.

   • Only fix issues the verifier identified - do not add your own improvements
   • If Write tool fails: display error "Failed to save optimization iteration {iteration}: {error}" and proceed to Phase 4 using the most recent successfully written version (or original_content if none)

2. Re-verify (comparison mode): Launch prompt-goal-verifier agent via Task tool:

   • subagent_type: "prompt-engineering:prompt-goal-verifier"
   • prompt: "Verify optimization. Original: {original_path}. Modified: {working_path}. Check for goal misalignment, misstep risks, failure mode gaps, contradictory guidance, unsafe defaults, unnecessary overhead, indirect paths, redundant instructions, optimization regressions, and over-optimization. Report VERIFIED or ISSUES_FOUND with specific details."

3. Handle response:

   • If "VERIFIED": mark todo completed, exit loop, proceed to Phase 4
   • If "ISSUES_FOUND" and iteration < 5: mark todo completed, save new issues list, add "Optimization iteration {next}" todo, continue to next iteration
   • If "ISSUES_FOUND" and iteration = 5: mark todo completed with note about unresolved issues, proceed to Phase 4 with warning
   • If verifier fails or returns unexpected format: display error to user, retry the verifier Task call once with identical parameters. If retry fails, proceed to Phase 4 with warning: "Verification incomplete - manual review recommended."
   • If Task tool becomes unavailable during workflow: proceed to Phase 4 with warning: "Verification unavailable - manual review recommended."

Optimization Techniques

Apply these techniques to fix goal optimization issues:

Goal Achievement Fixes

Issue Type	Technique	Example
Goal Misalignment	Remove/rewrite instructions that explicitly contradict the goal statement or produce outcomes opposite to stated success criteria	Remove "format output as JSON" from prompt whose goal is readable explanations
Missing/Vague Goal	Add explicit goal section with verifiable outcomes (e.g., "user receives working code" not "user is satisfied")	Add "Goal: Help users debug code by identifying root causes and suggesting fixes"
Goal Dilution	Establish priority order. If secondary goal conflicts with primary: remove if it undermines primary in most cases, otherwise subordinate with explicit "if conflict, primary wins" clause	"Primary: accuracy. Secondary: speed. If conflict, choose accuracy."
Unmeasurable Success	Add success criteria with verifiable outcomes (actions completed, outputs produced, states achieved)	Add "Success: User can reproduce the fix independently"

Error Prevention Fixes

Issue Type	Technique	Example
Misstep Risk	Add guardrails, clarify scope, require confirmation for destructive actions	"Delete only files in /tmp/, confirm before deleting multiple files"
Failure Mode Gaps	Add explicit handling for common failures	Add "If API unavailable: retry 3x with backoff, then report error"
Contradictory Guidance	Resolve conflict with priority or conditional logic	"Be thorough for complex queries, brief for simple ones"
Unsafe Defaults	Make safe behavior explicit, require opt-in for risky actions	"Default: dry-run mode. Require --execute flag for actual changes"

Efficiency Fixes

Issue Type	Technique	Example
Unnecessary Overhead	Remove steps that don't impact goal achievement	Remove mandatory summary step if summaries aren't consumed
Indirect Path	Remove intermediate steps that don't add information, validation, or safeguards (keep multi-step processes if each step serves a distinct purpose)	Collapse redundant confirmation dialogs into single confirmation
Redundant Instructions	Consolidate repeated guidance into single clear statement	Merge 3 sections saying "be concise" into one

Resolution Strategy

For each issue, follow this decision tree:

Issue detected
    │
    ▼
Can fix be inferred from prompt context?
    │
    │  Check these sources in order:
    │  1. Prompt's stated goal/purpose
    │  2. Existing patterns in the prompt
    │  3. Domain conventions (conventions typical for the prompt's subject area -
    │     e.g., API prompts follow REST conventions, code review prompts follow
    │     software engineering practices)
    │  4. Sensible defaults in priority order: (1) safety - confirm destructive actions,
    │     (2) completeness - handle errors and edge cases, (3) clarity - explicit over implicit
    │
    ├─ YES (at least one source provides clear guidance)
    │       → Apply inferred fix directly
    │       Examples:
    │       - Misstep risk in file deletion → infer safe defaults from prompt's cautious tone
    │       - Missing goal in code review prompt → infer "identify bugs and improvements"
    │       - Redundant instructions → consolidate using prompt's existing style
    │
    └─ NO (no source provides clear guidance, or sources conflict)
           → Make conservative fix: add safeguards, clarify ambiguity, document assumptions

Never ask user to clarify goal - always infer and proceed.

Phase 4: Output

Mark "Output optimized prompt" todo in_progress.

Step 4.1: Apply changes

After optimization complete (verification passed or max iterations reached):

• For file input: mv {working_path} {source_path} (atomic replacement)
• For inline input: Keep at working_path, report location to user

Step 4.2: Display results

If verification passed:

Optimized: {path}
Iterations: {count}
Status: Goal-optimized

Inferred Goal: {goal statement}

Changes applied:
- {List each fix as a separate bullet, prefixed with category: "Goal Achievement:", "Error Prevention:", or "Efficiency:". Combine multiple fixes of same category into one bullet if they modify the same section or address the same issue type.}

If verification failed after 5 iterations:

Optimized with warnings: {path}
Iterations: 5
Status: Some issues may remain

Inferred Goal: {goal statement}

Unresolved issues:
- {list from last verification}

Review the changes manually.

If already optimized (VERIFIED on first check):

Prompt is already goal-optimized. No changes needed.

Inferred Goal: {goal statement}

Mark "Output optimized prompt" todo completed. Mark all todos complete.

Key Principles

Principle	Rule
Verify first	Always run verifier before any optimization; maybe prompt is already optimal
Verifier-driven	Only fix issues the verifier identifies - no independent analysis or improvements
Track progress	TodoWrite to track phases; expand todos on iteration
Preserve intent	Don't change what prompt is trying to do; only fix issues the verifier flagged
Verification required	Never output without verifier checking
Atomic output	Original untouched until optimization complete. For file input, original is replaced with optimized content after all iterations (even if warnings remain).

Edge Cases

Scenario	Handling
No input provided	Error: "Usage: /optimize-prompt-goal OR /optimize-prompt-goal "
File not found	Re-classify as inline prompt and write to temp file
Empty file	Error: "Cannot optimize empty prompt. File contains no content: {path}"
Already optimized	Verifier returns VERIFIED on first check → Report: "Prompt is already goal-optimized. No changes needed."
Initial verifier fails	Retry once; if still fails, Error: "Verification failed - cannot proceed without verifier."
Re-verification fails	Display error, retry once; if retry fails, output with warning: "Verification incomplete - manual review recommended."
Severely misaligned	Make best effort over 5 iterations; output with warnings
Very large prompt (>50KB)	Process normally as single unit; no special handling needed
Task tool unavailable	Error: "Task tool required for verification loop."
Write tool fails	Display error, proceed to output with most recent successful version or original_content

Example Usage

# Optimize a prompt file for its goal
/optimize-prompt-goal prompts/code-reviewer.md

# Optimize inline prompt
/optimize-prompt-goal You are a helpful assistant. Be concise but thorough. Do your best.

# Optimize a skill file
/optimize-prompt-goal claude-plugins/my-plugin/skills/my-skill/SKILL.md

Example Output

Optimized: prompts/code-reviewer.md
Iterations: 2
Status: Goal-optimized

Inferred Goal: Help developers identify bugs, security issues, and improvement opportunities in code

Changes applied:
- Goal Achievement: Added explicit goal section (was missing); removed "format as markdown tables" instruction (didn't serve goal); added success criteria
- Error Prevention: Added failure handling for empty input and large files
- Efficiency: Consolidated 3 redundant "be thorough" statements into one