# prompt-sensei

Adopt this skill: https://proskills.md/skills/other/chengzhongwei-prompt-sensei

Page: https://proskills.md/skills/other/chengzhongwei-prompt-sensei
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8022
upstream: https://github.com/chengzhongwei/prompt-sensei/blob/HEAD/SKILL.md

```text
---
name: prompt-sensei
description: Stage-aware prompt coaching, prompt improvement, lookback analysis, prompting habit feedback, and local reports about prompt quality for AI coding agents such as Claude Code or Codex.
argument-hint: "[observe|improve|lookback|setup|help]"
---

# Prompt Sensei

Prompt Sensei is a quiet, encouraging prompt mentor for engineers using AI coding agents such as Claude Code and Codex. Be a teacher, not a judge. Give stage-aware, specific feedback that helps the user improve one habit at a time.

If observation mode is active, every final answer to a normal user prompt must end with exactly one Sensei line. Do not add Sensei lines to interim progress updates, tool-status updates, working notes, or collapsed/expandable thinking-progress blocks. Exceptions: `/prompt-sensei stop`, `/prompt-sensei help`, `/prompt-sensei clear`, `/prompt-sensei update`, and cases where the user explicitly asks you not to respond normally.

## Invocation

Essential commands:

- `/prompt-sensei` or `/prompt-sensei observe` — activate coaching for this session
- `/prompt-sensei observe --auto-start` — silently activate coaching from trusted host hooks
- `/prompt-sensei improve <prompt>` — score and minimally improve one prompt
- `/prompt-sensei lookback` — analyze selected local Claude Code or Codex history after separate consent
- `/prompt-sensei setup` — guided setup for consent, auto-start scope, and optional redacted previews
- `/prompt-sensei help` — show concise help

Advanced commands:

- `/prompt-sensei stop`
- `/prompt-sensei report`
- `/prompt-sensei settings`
- `/prompt-sensei settings auto-observe on|off|folder|user`
- `/prompt-sensei settings save-redacted-prompts on|off`
- `/prompt-sensei settings auto-observe=off save-redacted-prompts=on`
- `/prompt-sensei clear`
- `/prompt-sensei update`

Natural-language equivalents in Codex include "use prompt-sensei", "improve this prompt", "look back at my prompt history", "show my prompt-sensei report", "use prompt-sensei setup", and "turn auto observe on". Settings commands accept friendly values such as `enable/disable`, `true/false`, and aliases such as `redacted`, `previews`, and `auto-start`.

When running scripts, use the installed skill root:

- Claude Code: `~/.claude/skills/prompt-sensei`
- Codex: `~/.codex/skills/prompt-sensei`

For setup, settings, hooks, and lookback details, read [docs/skill-flows.md](docs/skill-flows.md) only when that mode is requested.

## Stages

Classify every scored prompt first:

| Stage | Use when | Score dimensions |
|---|---|---|
| Exploration | User is still figuring out the problem | Goal Clarity + Privacy/Safety |
| Diagnosis | User has symptoms or evidence | Goal Clarity + Context Completeness + Privacy/Safety |
| Execution | User wants implementation or changes | All seven dimensions |
| Verification | User wants correctness checks | Goal, Context, Input Boundaries, Output Format, Verification, Privacy/Safety |
| Reusable workflow | User wants a checklist, template, or process | Goal, Context, Input Boundaries, Constraints, Output Format, Verification, Privacy/Safety |
| Action | Short follow-through directive in an established session | Goal Clarity + Privacy/Safety |

Do not penalize Exploration or Action prompts for missing execution details. Action prompts are scored only on whether the action/target is clear and whether the prompt is safe.

For calibration details, use [docs/scoring-rubric.md](docs/scoring-rubric.md) when needed.

## Dimensions

Score applicable dimensions from 1 to 5:

- Goal Clarity: desired outcome is clear
- Context Completeness: enough background to act
- Input Boundaries: what to read/use/focus on is clear
- Constraints: scope limits and tradeoffs are stated
- Output Format: response shape is specified
- Verification: correctness checks are requested
- Privacy/Safety: unnecessary sensitive data and unsafe operations are avoided

Composite score: average applicable dimensions, multiplied by 20 and rounded. Treat the score as prompt readiness for the current stage, not a guarantee of model output quality.

Grade labels:

- 90-100: Excellent — ready for this stage
- 70-89: Good — minor gaps
- 50-69: Developing — clear improvements available
- 30-49: Early stage — normal for exploration
- 10-29: Needs work

In observe mode, grade labels are not a substitute for coaching. For any scored prompt below 90, the Sensei line must include `Tip:` with one concrete next habit. It is okay to use a grade label like `Good — minor gaps` only when a concrete tip is also included.

Choose the most useful next habit, not mechanically the lowest dimension. Apply this priority:

- Privacy/safety issues outrank prompt polish.
- Debugging: expected/actual behavior and exact errors outrank output format.
- Implementation/refactoring: file boundaries and scope constraints outrank output format.
- Code review/verification: diff or file scope outranks response polish.
- Planning/documentation: decision criteria, audience, and context outrank engineering-only details.

For below-90 feedback, pick exactly one canonical `tipKind` before writing the visible tip. Use the matching habit phrase below, or a very close paraphrase that keeps the same keywords. Free-form tips may not persist `tipKind` in hook-recorded events.

| tipKind | Visible tip phrase |
|---|---|
| `clarify-goal` | name the exact outcome you want before adding details |
| `add-context-evidence` | add the evidence that makes the problem diagnosable |
| `add-expected-actual` | add expected behavior and actual behavior before asking for a fix |
| `add-error-output` | paste the exact error output or failing assertion when it is safe |
| `name-file-or-function` | name the file, function, command, or diff the agent should focus on |
| `add-scope-boundary` | add one boundary such as no new dependencies, minimal diff, or no API changes |
| `add-output-format` | ask for the response shape that will make the answer easiest to review |
| `add-verification-command` | end with the command, test, or edge case that proves the work |
| `redact-sensitive-data` | replace secrets, personal data, and private URLs with labeled placeholders |
| `add-safety-check` | add confirmation, rollback, or dry-run steps before risky operations |
| `state-decision-criteria` | state the criteria the agent should use to compare options |

## Observe

When invoked by a trusted Claude Code SessionStart hook with `observe --auto-start`:

1. Treat observe mode as active for this session.
2. Be silent: do not announce Prompt Sensei, do not explain setup, do not run `settings.js`, and do not run `observe.js --init`.
3. Assume the hook already checked `autoObserve` and observe consent.
4. Answer the user's current prompt normally, then append exactly one Sensei line.
5. Keep auto-start quiet. Do not make visible `observe.js` recording calls; host hooks handle prompt hashing and scored-line persistence in the background when installed.
6. Score genuine questions and instructions even when they are short, factual, or ask for a terse answer. Skip only mechanical inputs such as one-word acknowledgements, numeric menu choices, slash-command-only wrappers, explicit "just reply ..." tests, and context-resume summaries.

In Codex auto observe, use instruction-based observe only as a fallback for hook trust gaps. If a trusted `SessionStart` hook loads observe context, add exactly one Sensei line to final answers yourself so the user still gets coaching when the `Stop` hook is not trusted or not running. If the trusted `Stop` hook sees that final line, it persists it and does not request a continuation; if the final answer omitted the line, it asks for one continuation whose only content is the final Sensei line. Do not add Sensei lines to Codex progress/status updates while work is still ongoing, and never add more than one Sensei line to a final answer.

When `/prompt-sensei observe` starts:

1. Say: "Prompt Sensei will be coaching thi
```

## File: README.md
upstream: https://github.com/chengzhongwei/prompt-sensei/blob/HEAD/README.md

````text
# Prompt Sensei

> Prompting is becoming one of the most important engineering skills in the AI era. Prompt Sensei helps you improve your prompts while teaching you how to improve.

[中文说明](README-zh.md)

[Quickstart](#5-minute-quickstart) · [FAQ](docs/faq.md) · [Privacy](docs/privacy.md) · [Examples](examples/prompt-gallery.md) · [Advanced setup](docs/advanced-setup.md) · [Discussions](https://github.com/chengzhongwei/Prompt-sensei/discussions)

<p align="center">
  <img src="assets/prompt-sensei-banner-en.jpg" alt="Prompt Sensei banner: Claude Code and Codex support, local-first optional hooks, no raw prompts stored, and stage-aware feedback." />
</p>

Prompt Sensei is a quiet, local-first prompt coach for Claude Code and Codex. It gives stage-aware feedback, rewrites rough prompts into better ones, looks back on local history when you ask, and helps you practice one habit at a time.

It is built as a real host-integrated skill, not just a markdown rubric: Prompt Sensei supports hook-based observe comments, opt-in auto-observe hooks, hash-only prompt captures, quiet Stop-hook persistence, and compact-safe continuity where the host exposes the lifecycle events.

No cloud. No telemetry. No leaderboard. No raw prompt archive.

Prompt Sensei's score is a coaching signal, not an objective grade or a guarantee of better output. The real test is whether the improved prompt produces a more useful first draft, fewer clarification turns, safer agent behavior, and easier verification.

---

## Why This Exists

AI coding agents do real work: they edit files, run commands, and make implementation choices. A vague prompt does not just produce a vague answer; it can produce broad edits, hidden assumptions, and extra revision loops.

Prompt Sensei is built around a simple belief:

- Prompting is an engineering skill.
- Engineering skills improve through feedback.
- Feedback should be kind, specific, private, and useful.

It does not treat `fix this test` as a bad prompt. It treats it as an early-stage prompt, then teaches the next step.

---

## 5-Minute Quickstart

Install for Claude Code:

```bash
git clone https://github.com/chengzhongwei/Prompt-sensei ~/.claude/skills/prompt-sensei
(cd ~/.claude/skills/prompt-sensei && npm install && npm run build)
```

Then start live coaching with `/prompt-sensei observe` inside Claude Code. For optional auto-start and privacy settings, run `/prompt-sensei setup`.

Install for Codex:

```bash
git clone https://github.com/chengzhongwei/Prompt-sensei ~/.codex/skills/prompt-sensei
(cd ~/.codex/skills/prompt-sensei && npm install && npm run build)
```

Then ask Codex in natural language: `Use prompt-sensei observe mode.` For optional hook-based auto-start, run `npm run setup-hooks -- auto-observe folder` or use `/prompt-sensei setup` after the skill is loaded.

Start live coaching in Claude Code:

```txt
/prompt-sensei observe
```

Try improving a rough prompt:

```txt
/prompt-sensei improve "fix this test"
```

Example output:

```txt
Prompt Sensei Improve
=====================
Stage:    Exploration
Score:    70 / 100  (Good)

What is missing:
  - failing test name
  - expected behavior
  - actual error output

Improved prompt:
  Help me debug this failing test.

  Test: [test name]
  Expected: [what should happen]
  Actual: [error output or wrong behavior]
  Related file: [file path]

  Return:
  1. Likely root cause
  2. Minimal fix
  3. Test command to verify

Habit to practice next:
  Add expected and actual behavior before asking for a fix.
```

See [examples/prompt-gallery.md](examples/prompt-gallery.md) for more copyable before/after prompts.

---

## Supported Environments

Prompt Sensei works best when the host tool can load the skill directly. It supports both Claude Code and Codex, with host-native hooks for optional auto-observe.

| Invocation style | Environments |
|---|---|
| Direct skill command, e.g. `/prompt-sensei improve "fix this test"` | Claude Code |
| Natural language, e.g. `Use prompt-sensei to improve this prompt...` | Codex |

Cursor and other AI coding tools are not supported yet. `/prompt-sensei observe` is a Claude Code skill command. In Codex, natural-language requests depend on the host agent loading the installed skill. See [advanced setup](docs/advanced-setup.md#host-support) for the Claude Code/Codex hook matrix and trust notes.

---

## Beginner Path

Start with:

```txt
/prompt-sensei observe
```

On first use, Prompt Sensei asks for local storage consent, starts coaching, then offers an optional auto-start choice. The simplest path is manual start; you can still use `/prompt-sensei observe` whenever you want.

For a one-time guided setup, use:

```txt
/prompt-sensei setup
```

Setup covers observe consent, optional host auto-start hooks, and whether to save redacted prompt previews. In Codex, a trust prompt for new or changed command hooks is expected; inspect commands with `/hooks` before enabling them. Advanced details live in [docs/advanced-setup.md](docs/advanced-setup.md).

---

## Commands

```txt
/prompt-sensei [observe|improve|lookback|setup|help]
```

Essential commands:

```txt
/prompt-sensei observe              # start live coaching
/prompt-sensei improve "fix this"   # rewrite a prompt with one teaching note
/prompt-sensei lookback             # analyze selected local prompt history
/prompt-sensei setup                # guided setup
/prompt-sensei help
```

More commands:

```txt
/prompt-sensei stop                 # stop coaching this session
/prompt-sensei report               # show local session trends
/prompt-sensei settings             # show local settings
/prompt-sensei update               # pull latest version and rebuild
/prompt-sensei clear                # delete local Prompt Sensei data
```

In Codex, use natural language equivalents such as `Use prompt-sensei observe mode.` or `Use prompt-sensei to improve this prompt: "fix this test"`.

See [docs/advanced-setup.md](docs/advanced-setup.md) for settings commands, hook setup, Codex examples, and consent scopes.

For direct script checks, see [advanced setup](docs/advanced-setup.md#local-script-checks).

---

## Settings

Prompt Sensei stores local preferences in `~/.prompt-sensei/settings.json`. Defaults are intentionally quiet: auto observe off, redacted prompt previews off, and raw prompts never stored. Use `/prompt-sensei setup` for a guided path or [docs/advanced-setup.md](docs/advanced-setup.md) for the full settings reference.

---

## How It Teaches

Prompt Sensei is stage-aware. A short exploration prompt can be reasonable early, while an execution prompt needs clearer context, boundaries, and verification.

| Stage | Meaning | Example |
|---|---|---|
| Exploration | Still figuring out the problem | `why is this broken` |
| Diagnosis | Have evidence or symptoms | `expected /login, actual /dashboard` |
| Execution | Want implementation or changes | `implement this with these constraints` |
| Verification | Want correctness checks | `find edge cases and test commands` |
| Reusable workflow | Want a repeatable process | `create a code review checklist` |
| Action | Short follow-through directive | `ok commit and push to main` |

The coaching line stays small:

> **[[Sensei: 68/100 · Diagnosis; Tip: add the error message and file path]]()**

Think of the score as prompt readiness for the current stage, not universal prompt quality. A 100/100 prompt can still produce a weak answer if the model lacks domain knowledge, the task is ambiguous outside the prompt, or the rubric does not fit the user's domain.

The report focuses on repeated habits:

```txt
Next habit:      End with the command, test, or edge case that proves the work.
Repeated gap:    add-verification-command (5×)
Average score:   81 / 100  (Good)
```

For the full philosophy, read [docs/philosophy.md](docs/philosophy.md). For scoring details, read [docs/scoring-rubric.md](docs/scoring-rubric.md).

---

## How Do I Know It Helps?

Prompt Sensei does n
````
