Your first enrichment

This walks you through installing the improver plugin and running your first enrichment end to end. By the end you will have taken a one-line, under-specified draft and turned it into a complete, ready-to-use prompt — and you will have seen exactly where the plugin's decisions came from.

Nothing here requires you to already know what improver is; if you want that background first, see What improver is, and why it works this way.

Before you start

You need:

Claude Code installed and working.
A local checkout of the improver plugin (the directory this tutorial lives in).

improver is local-only right now — it is not published to any marketplace, so every step below uses a local path.

Step 1 — Install the plugin locally

From a Claude Code session, point directly at the plugin directory:

claude --plugin-dir /path/to/improver

Or register it as a local marketplace and install from there:

claude
> /plugin marketplace add /path/to/improver
> /plugin install improver@improver

Either way, once installed you have four skills available: improve-prompt, improve-goal, improve-loop, and grade-enrichment. This tutorial uses improve-prompt; the shape is the same for the other two improve-* skills — see How to use each improver skill once you're ready to go further.

Step 2 — Write a rough draft

improver's whole point is that you don't need a polished prompt to start. A single under-specified sentence is enough:

summarize customer feedback

Notice what's missing: which product, what time period, how the feedback arrives, who's reading the summary. You don't need to fill any of that in yourself — that's improver's job.

Step 3 — Run improve-prompt

Invoke the skill with your draft:

/improver:improve-prompt summarize customer feedback

Step 4 — See the enriched output land

improver returns exactly one thing: a single code block containing the complete, ready-to-use prompt. For this exact draft, the plugin's own golden test set records this real enrichment:

<role>You are a customer-insights analyst.</role>
<context>Feedback arrives as free-text survey responses. Which product and time period this covers is unstated — see the question in <task>.</context>
<task>Summarize the recurring themes in the provided feedback. Clarify first: which product and time period should this cover, and roughly how many responses are in scope?</task>
<constraints>Base every theme on at least two distinct responses; quote one representative response per theme; do not speculate beyond the provided text.</constraints>
<output-format>A ranked list of themes, each with a one-sentence summary, a count of supporting responses, and one representative quote.</output-format>

A few things to notice about what just happened:

Nothing was invented. The draft never said which product or time period the summary covers. improver didn't guess — it folded that gap into the <task> section as a question you answer before the prompt actually runs.
The output is structured, not a paragraph. improver defaults to explicit XML-tagged sections (role/context/task/constraints/ output-format) rather than an unstructured rewrite.
The original intent survived. The draft asked for a feedback summary; the enriched prompt still asks for a feedback summary — it's now specific and complete, not redirected into something else.
That's the whole response. No "Changes Made" section, no analysis — just the one code block, ready to paste into whatever will actually run it.

Step 5 — Ask why, if you want to

Every non-trivial change improver makes traces back to a specific, citable research finding — never a restated house style. Try:

/improver:improve-prompt improve this prompt and after the code block, for
each change you make, tell me which research finding backs it: "act as a
lawyer and check this contract"

The answer names a rule id (e.g. explicit-role-setting, structured-sections-default) and resolves it to a full citation — see the rule pack reference for exactly how that resolution works.

What to do next

Try the same walkthrough with improve-goal or improve-loop — the installation and invocation shape is identical, only the target artifact changes. See How to use each improver skill.
If you want to understand why improver treats prompts, goals, and loops as three genuinely different things instead of one generic "task," read What improver is, and why it works this way.
For the exact input/output contract of every skill, the rule pack schema, and the character budgets each artifact kind is held to, see the reference.

FilesExpand file tree

tutorial.md

Latest commit

History