prompt-author

name	prompt-author
description	Design a single high-quality prompt — the innermost layer an agent reads. Use when a Smithers <Task>'s prompt (its .mdx body or inline string) is vague, ambiguous, or underperforming and you want to tighten the instruction, role, constraints, examples, and output contract before reaching for harness or workflow changes.

Prompt Author

This skill covers one layer only: the prompt: the text a single agent reads, the innermost ring of the layered model (prompt → context → harness → workflow → backpressure; see skills/context-engineer/SKILL.md). When the graph is fine but a step keeps producing weak or off-target output, fix it here, not in the workflow.

When to reach for it

• A <Task>'s output is vague, wrong-shaped, or inconsistent run to run, or the agent ignores a constraint, invents a format, or stops short of the goal.
• You're tempted to add a retry/reviewer to paper over a prompt that never said clearly what "done" looks like.

Skip it when the real problem is missing context, wrong tools/permissions, or a missing review gate: those are outer layers (context-engineer, the harness in agents.ts, the workflow graph).

What makes a strong prompt

1. One clear instruction, in plain imperative voice: no instruction soup, goal-based beats step-by-step.
2. Role / framing when it changes behavior ("You are an independent reviewer who can reject the diff"); skip it when it's decoration.
3. Explicit constraints: must-nots and bounds, no dead code, no magic numbers, don't touch file X, stay under N changes.
4. Examples for format- or taste-sensitive work: one good and one bad example teaches more than a paragraph of rules.
5. Decomposition for multi-part work: a numbered checklist of what to verify or produce, so nothing gets silently dropped.
6. Success criteria / finish line: "done" as checkable conditions (e.g. "existing tests pass; new tests prove per-account limits; reviewer approves"), with a cap and fallback for any "keep going until…".

The Smithers angle: prompts are .mdx a <Task> renders

Prompts live as .smithers/prompts/*.mdx (JSX prompt components), imported into a workflow as a tag:

import ReviewPrompt from "../prompts/review.mdx";
<Task id="review" output={outputs.review} agent={reviewer}>
  <ReviewPrompt diff={ctx.output("implement").patch} />
</Task>

The .mdx body is the prompt; props inject context. Keep it focused on instruction, constraints, and criteria: let the workflow supply variable context.

Critical: end the prompt before the output schema, never with your own JSON spec. A <Task> with an output={outputs.x} Zod schema gets a **REQUIRED OUTPUT** block auto-appended to the prompt's end; the parser reads the last JSON object in the response, so a hand-written "return JSON like {…}" fights the injected block and confuses it.

• Do describe what each field means in prose if it's non-obvious; let the schema describe the shape.
• Don't wrap the agent in conflicting format rules ("write a report" plus a JSON schema): the schema wins, so phrase the body so its result is the JSON.

Agents with native structured output skip the injected block; a prompt that defers to the schema works in both modes.

Tighten-and-verify loop

Edit the .mdx, re-run with --hot true so wording changes apply on the next frame without losing finished tasks, then attach a schemaAdherence scorer (or a small smithers eval suite) to confirm the new prompt holds the format:

bunx smthrs up workflow.tsx --hot true --input '{"prompt":"…"}'
bunx smthrs scores <run-id>     # did schema adherence improve?

See skills/smithers/SKILL.md for the runtime/CLI surface and docs/llms-core.txt ("Good Smithers prompts are goal-based") for the canonical prompt examples.