prompt-improve

Files (3)

• SKILL.md
• review.md
• stats.sh

SKILL.md (first lines)

# Improve Prompt

Take a raw, ugly prompt, rewrite it into a sharp one **in the context of this project**, show the rewrite, then carry it out.

## Steps

1. **Read the raw prompt** — everything the user passed after the skill name.

2. **Ground it in the project.** Spend a *cheap* pass on the context that actually changes the rewrite — not a full audit:
   - What is this repo? (README, manifest, top-level dirs)
   - Which files/areas does the prompt touch? Name them.
   - Existing conventions or utilities the task should reuse.

   Stop as soon as you know enough to rewrite well. Don't boil the ocean.

3. **Rewrite the prompt.** A good rewrite makes the implicit explicit:
   - **Goal** — one sentence, unambiguous.
   - **Scope** — what's in, what's out.
   - **Concrete anchors** — real file paths, function names, commands found in step 2.
   - **Constraints & success criteria** — how we'll know it's done.

   Cut filler. Preserve the user's actual intent — improve it, don't redirect it.
   The rewrite is text an agent executes — apply [STYLE.md](../../STYLE.md)'s
   procedural rules (one instruction per sentence, condition before
   instruction) instead of one dense semicolon-chained paragraph.

4. **Show it.** Print exactly:
   ```
   Improved prompt:
   <the rewrite>

   Why: <one line — what was vague and what you pinned down>
   ```

5. **Log it.** Append one JSON line to `~/.claude/prompt-improve/runs.jsonl`
   (create the dir/file if missing) using the Bash tool:
   ```bash
   mkdir -p ~/.claude/prompt-improve
   printf '%s\n' '{"date":"YYYY-MM-DD","raw":"...","improved":"...","note":"..."}' \
     >> ~/.claude/prompt-improve/runs.jsonl
   ```
   The log lives outside the repo (uncommitted) and feeds the review — see
   [review.md](review.md).

6. **Execute** the improved prompt — actually do the work. Run any other skill
   that applies.

## Guardrails

- If the raw prompt is already clear, say so and run it as-is (still log it).
- If grounding reveals the prompt rests on a wrong assumption (file doesn't
  exist, feature already present), surface that *before* executing — a better
  prompt isn't a wrong one made fluent.
- Never invent file paths or APIs in the rewrite. Anchors must be ones you
  verified in step 2.

## Getting better over time

Every run is logged to `~/.claude/prompt-improve/runs.jsonl`. Run a review
whenever you see fit — it reads that log, judges which rewrites helped, and
proposes edits to this very file. Instructions: [review.md](review.md).

From Esequiel378/skills, MIT.

More from Esequiel378/skills