Agent Prompt Author

Agent Prompt Author

Prompt work fails for four reasons, in descending order of frequency:

1. The prompt was never the bottleneck. Most requests to improve a prompt should end here.
2. The rule lives in a layer that cannot enforce it. Prose is a request; hooks are a gate.
3. Rules written for an older model are still firing.
4. The revision loop has no external verifier, so it optimizes readability instead of behavior.

Skipping to "write a better rule" is the default failure mode of this task.

Precondition

Always name the route. Routing is done from what the user said and never needs the artifact.

Do not diagnose from description alone. What needs the artifact is the FINDING. Route D is the one exception — a prompt that does not exist yet has no text to ask for. On every other route, before you produce a finding, get:

• The actual artifact text, or the assembled context if the artifact is templated.
• One concrete failure — the input, what happened, what should have happened.
• For Route E, the previous version too. Regression is invisible without a diff.
• Which model families the artifact must run on. If more than one, read references/portability.md alongside your route — several rules invert.

If the user describes a symptom without producing the artifact, name the route, then ask for it once, plainly. A diagnosis built on a description of a prompt is a guess about a class of prompts, not a finding about theirs.

Route

Match the request, then read only that route's file.

Length routes to A, not B. Line count is a rule-count problem, and Route A step 2 measures it — no eval set required.

B and F are not the same question. F asks whether the prompt is built correctly and needs nothing but the text. B asks whether it performs and is unanswerable without cases. When someone says "review this" with no eval set, they are asking for F; offering them B is how this skill dead-ends.

A cross-model symptom is a modifier, not a route. "Works on Claude, not on GPT" reads like non-compliance and pulls toward A. It usually isn't. Route on what they are asking to do — delete a rule is E, optimize or explain a score drop is B, write something new is D — then read references/portability.md alongside that route, because several of its rules invert. A bare behaviour difference with no ask attached is B: you cannot tell whether the prompt is the bottleneck on either model until you have measured on both.

Read references/evidence.md only when a user challenges a claim or asks for sources.

Route C — wrong artifact class

Context files and product prompts take opposite policies. Name which one this is, then redirect.

For context files, point to /doctor, path-scoped rules, and gotchas-over-conventions. This skill does not cover them.

Verification — applies to every route

A single context window cannot audit its own prompt. Self-preferential bias is strongest precisely when a model judges output against a rubric. If verification matters, it runs in a separate context with an agent whose job is to refute, not confirm.

Three failure modes to design against:

• Agentic laziness — declares done after partial progress. A single pass over 200 rules covers maybe 140.
• Self-preferential bias — prefers its own results, worst under rubric judging.
• Goal drift — original constraints lost across turns, especially after compaction.

Grading ≠ ranking. One output against a fixed rubric: a single judge emitting 0.0–1.0 plus pass/fail. Many candidates against each other: pairwise tournament beats absolute scoring.

Narrow gates backfire. Adding a static-analysis check to an iterative loop raised latent degradation from 12.5% to 20.8% — the model optimizes to the gate and you stop looking. A check must cover the property you actually care about.

Output contract

Return, in this order. Never a silent full rewrite.

ROUTE      A — enforcement. Rule is present but competing.

FINDING    orchestrator.md carries 23 live rules in one scope. The
           "always cite sources" rule sits at #19. Compliance at this
           count is ~30% before any conflict is considered.

DELTAS     1. Move rules 14–23 to references/citation-policy.md,
              loaded on the cite path only.  [count 23 → 13]
           2. Merge rules 4 and 11 — both constrain output length,
              4 says "concise", 11 says "at least three paragraphs".
              Kept 11; 4 was unmeasurable.

REMOVED    Rule 7 ("do not hallucinate"). Failed the counterfactual:
           no session in the log shows it preventing anything, and
           the model has no observed failure it guards.

UNVERIFIED Rule 16 kept on judgment. Looks obsolete for this model
           generation, but it guards a tail case the eval set does
           not sample. Flagged, not cut.

If Route B returned a flat landscape, the FINDING is the whole answer. Say the prompt is not the bottleneck and stop. Recommending prompt work the evidence says won't help is worse than declining.

Shelf life

Optimization effects are strongly model-specific: the same task went from 6/6 optimizers beating zero-shot on one model to 1/6 on another. Base models keep absorbing the scaffolding these techniques were built to discover. Re-run Route B after every model update.

The standing question for any existing prompt is not what rule is missing but what can I stop doing.

Written August 2026 against the Claude 5 generation — Opus 5, Sonnet 5, Fable 5. Every number in this skill is sourced in references/evidence.md. Re-check the numbers against a current model before treating them as thresholds.