A prompt that improves itself before it runs

Most requests to an AI agent are one line long. "Analyse this website and give me conclusions." "Write an email to clients who haven't paid." The output is generic because the request is generic: no role, no definition of good, no format. The usual advice is to learn prompt engineering. The faster fix is to make the tool write the brief.

/improve-prompt is a skill for Claude Code — a single Markdown file dropped into a folder. You type your request after the command. It rewrites it as a complete prompt, shows you the rewrite, and only runs it once you say so.

What it does

1. Reads your request and, if you are inside a project, a small amount of context: the project's instructions file and any files you named. Three reads at most — it does not go exploring.
2. Checks for ambiguity. If "analyse this website" could mean UX, SEO, copy or performance, it asks one multiple-choice question. If there is one obvious reading, it does not ask.
3. Rewrites the request as a prompt with a fixed structure: expert role, objective, context, steps, quality criteria, output format, constraints. Same language you wrote in.
4. Shows the rewrite in a code block, with one line explaining the role it picked, and asks: run it, adjust it, or just copy it.
5. On run, executes the improved prompt — and loads a specialised skill first if one fits the task.

What the rewrite looks like

The input:

/improve-prompt write an email to clients who haven't paid

The output, before anything runs:

Act as a senior collections and client retention lead, experienced in B2B communication that is firm but cordial.

Objective: write a payment reminder email that gets the invoice paid without damaging the relationship.

Context: [company and sector], invoice overdue by [N days], [first reminder / second reminder].

Steps:
1. A clear subject line that names the invoice and does not read as a threat.
2. A brief reminder of the amount, invoice number and due date.
3. How to pay, and who to contact if it is already paid or there is a dispute.
4. A cordial close with a specific deadline.

Quality criteria:
- Under 150 words.
- Professional tone, no blame and no over-apologising.
- One single call to action.

Output format: subject line + email body, in English.

Constraints: do not offer discounts or payment plans unless the user asks.

Note the brackets. The skill does not invent your company name or how overdue the invoice is. It leaves a placeholder and asks for the value at the confirmation step — which is also where you catch a wrong role before it costs you a run.

The rules that make it work

• It always delivers a prompt. It never answers with a list of questions — that is what an agent without the skill does, and it is the main failure it was written against.
• One question at most, and only when the answer changes the expert role or the deliverable. A missing URL is not a question; it is a placeholder.
• Nothing runs without passing through the confirmation step.
• If your request is already well written, it says so and changes almost nothing. It organises long requests instead of inflating them.
• It stays in your language and keeps your intent. It does not add requirements you did not ask for.

Install it

1. Download the file below.
2. Save it as ~/.claude/skills/improve-prompt/SKILL.md — the folder name must match.
3. Start a new Claude Code session. The command is available in every project from then on.
4. Type /improve-prompt followed by your request.

The file follows the open SKILL.md format, so the same file works in other agents that read skills from a folder — for Codex, the path is ~/.agents/skills/improve-prompt/SKILL.md. Open it in any editor: it is plain Markdown, and the whole point is that you can change the structure, the rules or the example to match how you work.

A vague request is not a prompting problem. It is a missing brief. This writes the brief, and lets you read it first.