SOURCES

Decisions

1. Use an eval-first workflow before prompt edits. Status: adopted Why: Anthropic explicitly recommends success criteria, tests, and a first draft before prompt engineering, and OpenAI’s prompt optimizer centers graders and annotations.

2. Keep a provider-agnostic base prompt plus model-family adapters. Status: adopted Why: OpenAI, Anthropic, and Gemini each recommend materially different prompting strategies around reasoning, XML tags, examples, and thinking controls.

3. Use markers and tags selectively, not automatically. Status: adopted Why: OpenAI and Anthropic both recommend delimiters for clarity, but over-structuring adds noise and reduces readability.

4. Use a candidate-based optimization loop instead of one linear rewrite. Status: adopted Why: OPRO, ProTeGi, and DSPy all support score-driven search across multiple prompt variants.

5. Keep an explicit optimization log and reflective memory across rounds. Status: adopted Why: Self-Refine and Reflexion both show the value of critique and retained reflection across iterations.

6. Optimize examples, tool rules, and output contracts together with the core prompt. Status: adopted Why: Provider docs and DSPy both treat examples and instructions as first-class levers, not optional decoration.

7. Make prompt compaction and de-duplication a first-class optimization step. Status: adopted Why: OpenAI recommends simple, direct prompts; Gemini explicitly says to avoid passing tokens you do not need; Anthropic frames concision as a context-budget issue.

8. Make context ordering explicit rather than implicit. Status: adopted Why: Gemini and Anthropic both document that long-context prompts perform better when evidence comes before the final query.

9. Inventory stable external context by exact path. Status: adopted Why: AGENTS.md and Codex guidance favor explicit project instruction sources, and path inventories prevent prompts from copying stale docs or using vague “read the docs” pointers.

10. Add External Context to the returned prompt package. Status: adopted Why: another engineer should see which specs, docs, policies, and examples were loaded, referenced, or left out of scope.

Coverage matrix

Description QA

Should trigger

• “Improve this system prompt for our coding agent.”
• “Optimize an agent prompt for Claude.”
• “Rewrite this OpenAI developer prompt.”
• “Port this prompt from GPT to Gemini.”
• “Make this tool-using prompt more reliable.”
• “Tune this prompt wording with a proper eval loop.”

Should not trigger

• “Write a new skill.”
• “Review my pull request.”
• “Fix this bug in the repository.”
• “Summarize this document.”
• “Design a new model architecture.”
• “Tune only the temperature and top-p settings.”

Open gaps

1. Add provider notes for additional families only when the repository has a real downstream need.
2. If this skill starts getting heavy use, add an optional script or eval template for capturing prompt scores across rounds.
3. Re-check provider docs when major model-family updates land, especially around tool use and reasoning defaults.
4. Add durable before/after examples for external context inventories if future prompt changes regress into vague file references.

Stopping rationale

Further retrieval is currently low-yield for this first version. The source pack already covers:

• official prompt guidance from the three major model families most likely to matter in practice
• current optimizer framing from a live prompt-programming framework
• foundational prompt-optimization research for candidate search, critique loops, and reflection memory
• local repository conventions for canonical skill authoring and registration

Changelog

• 2026-04-18: Created the initial prompt-optimizer skill, references, and provenance record.
• 2026-04-18: Added an explicit prompt learnings pass covering compaction, deduplication, and context ordering.
• 2026-04-18: Folded the prompt learnings back into the core shaping and iteration guidance to keep the workflow compact.
• 2026-05-04: Added exact external context inventories, External Context output, concise runtime workflow, and SPEC.md.