01 Overview
A Claude Code plugin with six skills, six lifecycle hooks, and zero required configuration. The plugin turns rough prompts into deterministic specs (/improve-prompt, /plan), provides three focused lenses for debugging, refactoring, and reviewing code (auto-invoked by semantic match), and ships a command advisor that ranks the right next command from keyword relevance, your command history, and git state — powering a pre-prompt banner, Stop-hook follow-ups, and a statusline segment that are all surfaced to you only, never fed to the model. Run /prompt-craft:refresh to rebuild the advisor any time. Two additional guardrail hooks (block_secrets, format_on_edit) are opt-in via environment variables; everything else runs immediately after install.
02 Problem & why it's needed
Vague prompts (like "fix the thing" or "add auth") route to improvisation, causing scope creep, work starting before "done" is defined, and hidden assumptions discovered mid-implementation. Without a crisp spec, the same ask runs differently twice and produces no artifact a human can correct up front.
03 Install
Add the plugin marketplace, then install prompt-craft
/plugin marketplace add abhijitbansal/claude-skills/plugin install prompt-craft@claude-skillsOptional: enable guardrails in shell profile or .claude/settings.json
export PROMPT_CRAFT_BLOCK_SECRETS=1 # block reads/edits of .env, *.pem, id_rsa, credentialsexport PROMPT_CRAFT_FORMAT_ON_EDIT=1 # auto-format edited files with black/prettier/gofmt/rustfmt/shfmtGuardrails are off by default. The advisor-driven follow-up surfaces (suggest_next.sh, prompt_hint.sh) are always on and stay silent when nothing applies — and everything they emit is shown to you only, never fed to the model.
Optional: wire the live statusline segment
python3 plugins/prompt-craft/scripts/wire_statusline.py --wireAdds a live "💡 next: /x" segment to your statusline (also run by /prompt-craft:refresh). It atomically updates ~/.claude/settings.json, backs up to settings.json.bak.<ts>, and chains your existing statusLine command. Remove with --unwire.
Optional: opt out of advisor command-history learning
export CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 # advisor stops recording leading /command tokens04 Usability guide
Every capability, how to invoke it, and a concrete example.
/prompt-craft:improve-prompt — turn a rough ask into a deterministic spec
Call this when a user gives a vague, one-line, or fuzzy request like "fix the thing", "improve this", "add auth", or "make it better" with no detail. The skill spends a higher-effort pass to produce a spec no one can misread: restated goal, explicit acceptance criteria (testable conditions), surfaced assumptions to confirm, out-of-scope boundaries, and recommended slash commands. It stops before doing any work — the human resolves assumptions first.
/prompt-craft:plan — decompose a task into a tracked, verifiable plan
Use when the user says "plan this", "break this down", "what's the plan", or gives a multi-step feature or refactor that touches more than one file. The skill produces a plan with an explicit goal, acceptance criteria, per-step decomposition (each step has a one-line verify check), and a TodoWrite list for tracking. The plan is confirmed before execution starts.
/prompt-craft:debug — reproduce, isolate, fix
The debug lens auto-invokes when you report unexpected behavior, a stack trace, a flaky test, or ask "why is this broken". It enforces a disciplined flow: reproduce first (ideally in a failing test), isolate to the smallest code path, form one hypothesis at a time (predict, check), write the failing test (RED), fix to GREEN, confirm the original repro passes. Guessing at fixes without reproducing is the failure mode it prevents.
/prompt-craft:refactor — restructure, no behavior change
The refactor lens auto-invokes when you ask to "clean this up", "extract this", "simplify", "reduce duplication", or "make this readable" on existing working code. It guards the invariant (behavior unchanged) with tests: run the suite GREEN before touching anything, refactor in small reversible steps, re-run after each step, stop at the goal. No bundled feature changes; no opportunistic rewrites of adjacent code.
/prompt-craft:review — find bugs, security issues, and quality problems
The review lens auto-invokes when you say "review this", "check this PR", "look this over before I commit", or "is this safe". It scans a diff or branch for correctness bugs and security issues first (logic, unhandled errors, injection, secrets, auth), then quality (duplication, dead code, naming, oversized functions, missing tests). Every finding is one line: where, what's wrong, how to fix. Results are ranked by severity (CRITICAL/HIGH/MEDIUM/LOW).
/prompt-craft:refresh — rebuild the advisor registry & history profile on demand
Re-scan skills and rebuild the command-advisor registry + history profile on demand; also wires the statusline. Run it after installing new skills or plugins so the advisor knows about them immediately — it rebuilds ~/.claude/prompt-craft/registry.json and profile.json and wires the statusline segment in one step.
05 Command advisor
A command advisor ranks the most relevant next command by combining keyword relevance, your command-history frequency, and git-state context (at most 3 recommendations). It powers the pre-prompt banner, the Stop-hook follow-ups, and the statusline segment. Every surface is user-only — advisor output never enters the model context.
Ranking engine — scripts/advisor.py
advisor.py ranks candidate commands by three signals: relevance (keyword overlap with your prompt and context), frequency (how often you reach for a command, learned from your history), and context fitness (the current git state). It returns at most 3 recommendations per call and degrades gracefully to an empty result if its artifacts are missing — it never raises.
Registry — ~/.claude/prompt-craft/registry.json
The advisor reads candidates from a registry at ~/.claude/prompt-craft/registry.json (file mode 0600, directory 0700), built on session start by registry_freshness.sh. The build scans your repo and global skill directories and merges a hand-curated registry-notes.toml overlay. The registry lives only under ~/.claude/ — nothing is imported from version-controlled repos.
History profile — privacy by construction
Command-history frequency comes from ~/.claude/prompt-craft/profile.json, learned from ~/.claude/history.jsonl. Only the leading /command token of each slash-command turn is recorded — never the prompt text — and the profile is capped at 5000 entries. Opt out entirely with export CLAUDE_CODE_SKIP_PROMPT_HISTORY=1.
User-only surfaces — never in the model context
The advisor drives three surfaces: the pre-prompt banner (prompt_hint.sh), the Stop-hook follow-ups (suggest_next.sh), and the statusline segment (statusline_hint.sh). Each is delivered as a top-level {"systemMessage": ...} or statusline text shown to you only — advisor output never enters Claude's context.
Supporting scripts & refresh on demand
The advisor is built from advisor.py, build_registry.py, learn_history.py, registry_lib.py, and wire_statusline.py. Run /prompt-craft:refresh to rebuild registry.json and profile.json immediately — do this after installing new skills or plugins so the advisor knows about them right away.
06 How it works under the hood
Stop hook: suggest_next.sh — advisor-routed follow-ups, user-only and silent when idle
After Claude finishes a turn (Stop lifecycle event), suggest_next.sh reads the working directory's git state and routes it through the command advisor to rank up to 3 follow-up commands. The recommendations are delivered as a top-level {"systemMessage": ...} shown to the user only — they never enter the model's context. If there are uncommitted changes, it surfaces /prompt-craft:review (check the diff) and /commit (save the work). If the tree is clean but there are unpushed commits, it surfaces /pr (open a pull request). It stays silent on no match and exits 0 outside a git repo or when there is nothing to suggest — it never blocks, never produces noise.
UserPromptSubmit hook: prompt_hint.sh — pre-prompt advisor banner, user-only
Before each prompt is processed (UserPromptSubmit event), prompt_hint.sh asks the command advisor for its single top recommendation and surfaces it as a user-only {"systemMessage": ...} banner. Like every advisor surface, it never feeds the model and stays silent when the advisor has nothing to suggest. Exit 0 always (non-blocking).
SessionStart hook: registry_freshness.sh — keeps the advisor registry fresh
On session start, registry_freshness.sh rebuilds the advisor registry (~/.claude/prompt-craft/registry.json) when it is stale — detected by a repo change, a change in the skill scan-signature, or a new Claude Code version. The rebuild scans repo and global skill directories and merges the hand-curated registry-notes.toml overlay. Non-blocking.
statusLine hook: statusline_hint.sh — live next-command segment
statusline_hint.sh adds a live "💡 next: /x" segment to your statusline, sourced from the advisor's top recommendation, and chains to your existing statusLine command so nothing is lost. Wire it once with python3 scripts/wire_statusline.py --wire (also run by /prompt-craft:refresh); remove with --unwire.
PreToolUse hook: block_secrets.sh — opt-in guardrail blocking secret-looking files
When armed via PROMPT_CRAFT_BLOCK_SECRETS=1, block_secrets.sh intercepts Read, Edit, and Write tools before they touch files. It parses tool_input.file_path and checks the basename against a conservative secret-pattern list: .env, .env.*, *.pem, *.key, id_rsa, id_dsa, id_ecdsa, id_ed25519, credentials, .npmrc, .pypirc. If matched, it exits 2 (blocking the tool) and sends an error message to Claude explaining the guardrail and how to disable it. Otherwise exits 0, allowing the tool. Off by default to respect the zero-config principle.
PostToolUse hook: format_on_edit.sh — auto-format edited files, opt-in and always non-blocking
When armed via PROMPT_CRAFT_FORMAT_ON_EDIT=1, format_on_edit.sh runs after Edit or Write tools complete. It extracts tool_input.file_path and dispatches to the appropriate formatter based on file extension: black for .py, prettier for .ts/.tsx/.js/.jsx/.json/.css/.md, gofmt for .go, rustfmt for .rs, shfmt for .sh. Each formatter is checked for installation (command -v) before running; if not found or if the formatter fails, the hook silently continues (exit 0, no blocking). This ensures the edit itself always succeeds even if formatting is unavailable.
The /improve-prompt pipeline — high-effort reasoning at the spec stage
The skill is tagged with effort: high in its frontmatter, which buys a deeper reasoning pass (via Claude's native effort system) exactly where it pays off: converting ambiguity into a checkable contract. The pipeline: rough prompt → restate intent (not phrasing) → derive testable acceptance criteria → surface assumptions to confirm → emit spec + recommended commands → halt. By stopping after the spec, the human can resolve load-bearing assumptions before a single line of code is written, preventing scope creep and guessing.
Zero-config model: skills work immediately, guardrails are deliberate opt-in
The six skills are active after install with no setup. The advisor-driven hooks (suggest_next.sh on Stop, prompt_hint.sh on UserPromptSubmit, registry_freshness.sh on SessionStart) are always active and stay silent unless there is something to surface — and everything they emit is shown to you only, never fed to the model. The statusline segment is opt-in (one wire_statusline.py --wire step). The two guardrail hooks (block_secrets, format_on_edit) are gated by environment variables (PROMPT_CRAFT_BLOCK_SECRETS, PROMPT_CRAFT_FORMAT_ON_EDIT) that default to 0, keeping them off until explicitly enabled. This respects YAGNI — the plugin ships the high-value half (specs, lenses, advisor follow-ups) and leaves guardrails as an opt-in surface layer for users who need them.
Hook I/O contracts: stdin JSON, exit codes, and output signals
All six hooks receive a JSON event on stdin. The advisor surfaces — suggest_next.sh (cwd / git state) and prompt_hint.sh (the prompt) — emit a top-level {"systemMessage": ...} shown to the user only; it never reaches the model context, and both exit 0 always (non-blocking) and stay silent when the advisor returns nothing. registry_freshness.sh rebuilds the advisor registry on session start when stale. statusline_hint.sh prints a one-line statusline segment and chains to your existing statusline command. block_secrets.sh reads tool_input.file_path, exits 0 to allow or exit 2 to block (with stderr fed to Claude). format_on_edit.sh reads tool_input.file_path, always exits 0 (never fails). All parse stdin defensively via /usr/bin/python3 (matching existing plugin patterns), are bash-3.2 compatible, and pass shellcheck.
07 What's inside
Skills
Hooks
Explore the other plugins
Second Wind
Run Claude overnight; auto-resume after 5-hour limit resets
ios-dev
Build iOS apps, screenshot remotely, release to App Store
core-workflow
Opinionated dev workflow: commit + share + team up
linear-pm
Linear issues → code, branches, PRs — autonomous end-to-end