⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.0.0

prompt-sensei

chengzhongwei@chengzhongwei⭐ 109 stars· last commit 4mo ago· 0 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 109 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

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.

中文说明

Quickstart · FAQ · Privacy · Examples · Advanced setup · Discussions

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:

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:

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:

/prompt-sensei observe

Try improving a rough prompt:

/prompt-sensei improve "fix this test"

Example output:

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 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 styleEnvironments
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 for the Claude Code/Codex hook matrix and trust notes.


Beginner Path

Start with:

/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:

/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.


Commands

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

Essential commands:

/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:

/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 for settings commands, hook setup, Codex examples, and consent scopes.

For direct script checks, see advanced setup.


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 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.

StageMeaningExample
ExplorationStill figuring out the problemwhy is this broken
DiagnosisHave evidence or symptomsexpected /login, actual /dashboard
ExecutionWant implementation or changesimplement this with these constraints
VerificationWant correctness checksfind edge cases and test commands
Reusable workflowWant a repeatable processcreate a code review checklist
ActionShort follow-through directiveok 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:

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. For scoring details, read docs/scoring-rubric.md.


How Do I Know It Helps?

Prompt Sensei does n

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md7.8 KBupstream ↗
    ---
    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
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/chengzhongwei-prompt-sensei.md

// REPO STATS

109 stars
0 open issues
Last commit: 4mo ago