Prompt Coach

A UserPromptSubmit hook that watches every prompt you send Claude Code and coaches you toward better prompting habits — definition-of-done, scoped references, guardrails, verification, and more. As of v0.34 the coach is a collaborator: when a rule fires, Claude reads your prompt in context and rewrites it with the fix baked in, at the top of its response. Rules quietly graduate once you consistently apply them, so the coach fades as your prompts improve.

Graduated to a stable 1.0.0 release on 2026-07-28 after clearing its own bar — nightly use across dozens of repos with rules mastered per repo. Development continues on the stable line (next: an eval harness for measured per-rule precision, and a Java MCP server).

Install

/plugin marketplace add alexmond/alexmskills
/plugin install prompt-coach@alexmskills
/reload-plugins

That’s it. No separate channel, no extra configuration. Restart the session so the UserPromptSubmit hook registers. Then just prompt Claude normally — the coach analyzes every prompt in the background and steps in when a rule matches.

Quick start

What you’ll see when a rule fires

The coach is a collaborator, not a nagger. When a rule fires, Claude rewrites your prompt with the improvement baked in — rendered as a block at the very top of its response:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💬 prompt-coach — I read your prompt as:

    "in src/auth/login.js, update handleLogin() to reject empty
     password submissions with a 422 and a 'password required'
     message. Keep the existing test suite green."

Changes:
  [1] Named the file + function (was: 'the login flow')
  [2] Made the behavior explicit + added a guardrail

Sources: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#be-clear-and-direct

Reply "yes" to proceed, "no" for original, or "edit" to change something.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Your reply on the next turn — yes / no / edit — is the accept/reject signal; Claude answers your prompt normally either way. The Sources line carries the full clickable doc URL so you can jump to the Anthropic guide section behind the rule (toggle with show_source_urls).

On a clean prompt you instead get a compact one-line liveness heartbeat:

✓ prompt-coach · clean prompt · closest to mastery: no-verify-loop 2/3 demonstrated

This is informational, not praise — a heartbeat that also shows your progress toward the next mastery. It’s specific (v0.41.1): it names the rule involved rather than a bare count — you used <rule> (2/3 toward mastery) when the clean prompt demonstrated a technique, closest to mastery: <rule> … for the practicing rule nearest graduation, or watching for: <rule> otherwise. Rules graduate to "mastered" once you’ve demonstrated the good technique min_demonstrations times (default 3) with no recent relapse — see earned mastery — then the next dormant rule activates. When a rule masters you get a 🎓 congratulation.

The slash commands

Command When to use

/prompt-coach:analyze

"Is this prompt any good?" Runs the full 42-rule catalog against a pasted prompt or your last N logged prompts, with a coached rewrite / pattern report.

/prompt-coach:stats

"How am I doing?" Health dashboard: prompts analyzed, emit rate, top-fired rules, mastery status.

/prompt-coach:mastery

"Which rules mastered, which need reset?" Per-rule breakdown with well-tested / barely-tested / untested analysis + close-to-mastery.

/prompt-coach:dashboard

"Show me everything in a browser." Launches the local web dashboard — stats, mastery, live config editor, the Prompt Library, and the ranked Sources tab.

/prompt-coach:config

"Change my settings." Verbs: show / set / describe / options / mastery / sources / paths / analyze / library / dashboard / diff / export / reset.

/prompt-coach:library

"Show me a prompt for X." Matches your task to the closest gold-standard template from Anthropic’s Claude Code Prompt Library.

/prompt-coach:help

"What are my options?" Compact live-config card + command list + say-it cheatsheet.

/prompt-coach:report-issue

"The coach was wrong." Files a redacted GitHub issue (first-5-words + structural signature only).

/prompt-coach:analyze in depth (on-demand analysis)

The passive hook is quiet by design — it only checks the handful of active rules. But the skill carries the whole prompting-knowledge catalog, so /prompt-coach:analyze (or "analyze this prompt: <text>") points it at a prompt on demand for a complete read across all 42 rules:

  • A specific prompt — every rule that fires (with tier, the fix, and a clickable doc URL) plus a rewritten prompt.

  • Your recent history (--last N) — reads this repo’s coach log, runs the full catalog on the last N prompts, and reports your clean rate, the top recurring rules, and one habit to focus on next.

$ …/config.py analyze "fix it and make it better and faster"
── prompt analysis ─────────────────────────────────────
  7 rule(s) fired (full catalog):
    · L1 vague-reference — Vague reference
    · L1 no-definition-of-done — No definition of done
    · L1 improve-without-metric — Improve without a metric
    · L2 no-verify-loop — No verify loop
    · L4 implicit-goal — Action without goal
    · L4 unbounded-iteration — Loop without stopping condition
    …

Read-only — it never touches mastery, config, or state.

Say-it phrases (natural language)

Claude edits your config file — or runs the right command — when you say any of these:

On / off:

  • "disable prompt-coach" — full silence in this scope (enabled: false)

  • "enable prompt-coach" — turn it back on

  • "coach pause 10" — temporary silence for the next 10 prompts

Analyze / docs / files:

  • "analyze this prompt: <text>" / "analyze my last 20 prompts" — full-catalog coaching on demand

  • "open the docs for <rule>" — open the Anthropic guide section in a browser

  • "show me the skill folders" — list the plugin’s folders, state files, and runnable scripts

Per-rule + praise:

  • "coach off <rule-id>" — permanently disable one rule

  • "coach on <rule-id>" — re-enable it

  • "disable praise" — silence encouragement, keep coaching

Bug reporting:

  • "coach that was wrong" — flag the PRIOR prompt for /prompt-coach:report-issue

First-day tweaks

To fully disable the coach in this repo or globally:

"disable prompt-coach"

If you’re being coached too often:

"show me prompt-coach mastery"        # dashboard of practicing vs mastered rules
"coach off <rule-that-keeps-firing>"  # permanent silence per rule
"coach pause 10"                      # silence everything for 10 prompts

Companion skill: log-review

For cross-repo analytics of coach activity, say "log review" or "daily review". That invokes the standalone log-review skill at ~/.claude/skills/log-review/ (redacted-by-default output, safe to paste anywhere).

What it watches for

The catalog ships 42 rules across 6 tiers (L1 6 · L2 4 · L3 11 · L4 5 · L5 11 · L6 5), each with a mirroring positive detector (42 total) so mastery is earned by demonstration. Behavior is tuned by 37 configuration keys (see the full table).

Only six rules are active at a time (max_active_rules, default 6) — lower tiers dominate, and as a rule masters, the next dormant rule activates in its place. When all rules in a tier master, the next tier’s rules take their place. A single prompt can trip several rules at once; the collaborator block surfaces every one it confirms, so you get more than one suggestion when more than one applies.

The L5 tool-native tier is where the coach routes you to a Claude Code affordance the prompt is implicitly asking for. Alongside plan mode, task lists, parallel agents, roles, panels, and Workflow fan-out, v0.48 adds routing to the orchestration commands:

  • no-scheduler-for-recurring → a recurring clock/calendar task ("every morning…", "nightly…", "at 9am…") should be registered once with /loop --interval <cron> (CLI) or /schedule (cloud/web routine), not re-run by hand.

  • no-loop-for-polling → "poll until healthy", "retry until green", "monitor until it drains" is a bounded self-paced /loop with the observed state as its stopping condition (plus a max-attempts / backoff so it actually exits).

  • no-goal-for-outcome → a target end-state ("get the build green", "make all tests pass") is a /goal <condition> handoff — Claude iterates and self-evaluates against a checkable condition instead of you steering each edit.

Because these are distinct prompt shapes, a prompt like "every morning, keep retrying the deploy until it’s green" can legitimately surface more than one of them together.

The full per-rule reference — what each rule catches, a ✗ bad → ✓ good example, and its sources — lives on the rule catalog page.

How it renders (v0.38: collaborator-only)

Rendering is always inline — the coach block is the opening of Claude’s response. There is a single master switch and a small set of behavioural knobs; there is no "mode" or "voice" to pick.

Key What it does

enabled

Master switch. false = the hook returns immediately, fully silent (default: true)

ack_clean / ack_ratio

The ✓ liveness heartbeat on clean prompts, and its rate (1 = every clean prompt)

show_source_urls

Full clickable doc URLs in the coach block’s Sources line (default: true)

pause_until_prompt

Skip until the global prompt counter passes this

disabled_rules

Array of rule ids to permanently silence

v0.38 removed the earlier nudge_style modes (both / silent / log-only), the voice_preset / voice_source knobs, and the anti-habituation config, along with the entire hand-written nudge path. Under collaborator mode Claude writes each rewrite fresh, so there is no preset to pick and no repeated text to habituate to.

Everything about which rules fire, how mastery is earned, and how the coach fades — the acceptance loop, precision gating, decaying mastery — is on How it adapts to you. Every configuration key, the command surface, and the local dashboard are on Configuration & dashboard.

Quality gate

The plugin ships a release test harness — make test-coach (or python3 plugins/prompt-coach/scripts/test-harness.py). Fifteen checks drive the real hook and config surface in throwaway directories: clean→ack, rule→collaborator block with clickable URLs, show_source_urls toggle, enabled=false silence, mastery→🎓 congrats, the analyze command (single + history), sources/paths --open, and a marketplace-validity check. Run it after every change.

Future — Java MCP server

The current Python + UserPromptSubmit hook is CLI-only. A Java MCP server is planned so the coach can run in claude.ai chat, aggregate telemetry across users, and support persistent per-user state. The prerequisite is real training data from many users (not a single maintainer’s log). The report-issue command already produces training-data-shaped payloads.

The living design spec lives in the repo at plugins/prompt-coach/docs/java-mcp-spec.md — MCP surface, canonical rule catalog format, data model, privacy model, and migration path.

Design notes

  • Fast filter, then Claude. Rules are regex + short-window checks — cheap, deterministic, ~10 ms — and identify candidate rules. When one fires, Claude does the situated rewrite in the same response it was already going to send, so there’s no extra API call or latency.

  • False positives are cheap. Cooldowns prevent pestering; graduation rewards consistent clean prompts even in the face of an over-eager rule; and Claude can veto a candidate rule when context resolves it.

  • Sources are diverse. Each rule cites 2+ sources drawn from Anthropic prompt-engineering docs, Claude Code best practices, OpenAI’s prompt guide, Simon Willison’s notes, and academic work (Wei et al. 2022 on CoT, Brown et al. 2020 on few-shot, Schulhoff et al. 2024 on prompt patterns).

  • Stable. Graduated from prompt-coach-beta to a 1.0.0 release on 2026-07-28; development continues on the stable line.

Read next