Prompt-sensei: Instructions file for Claude Code

Repository Guidance

This project is a local-first prompt-coaching skill for AI coding agents. Keep changes aligned with the product principles: quiet, stage-aware, encouraging, privacy-aware, and useful for engineering workflows.

Documentation Shape

• Keep SKILL.md compact. It should be a runtime router plus core scoring behavior, not a full manual.
• Keep README.md and README-zh.md beginner-friendly. They should explain the happy path, command surface, and privacy promise without embedding long setup flows or hook JSON.
• Move low-frequency or advanced details into focused docs:
  • docs/skill-flows.md for agent-facing setup, settings, hooks, and lookback flow details.
  • docs/advanced-setup.md and docs/advanced-setup-zh.md for user-facing advanced configuration.
  • docs/faq.md for skeptical questions, usefulness claims, support scope, feedback channels, and quick public-facing answers.
  • docs/privacy.md for storage, consent, redaction, deletion, and network behavior.
  • examples/claude-settings.example.json for copyable Claude Code hook JSON.
  • examples/codex-hooks.example.json for copyable Codex hook JSON.
• Prefer short links from SKILL.md and README files to those deeper docs instead of duplicating the same instructions.
• Avoid large inline JSON blocks in SKILL.md or README unless they are essential for first-use comprehension.
• Before adding more than a short paragraph to SKILL.md or README, ask whether it belongs in a reference doc instead.
• As a rough guardrail, try to keep SKILL.md under 250 lines and each README under 325 lines. If a necessary change exceeds that, move supporting detail into docs/.

When Changing Behavior

Treat behavior changes as cross-file changes by default. Before finalizing, do a related-file sweep; do not rely only on the file you initially touched or the checklist below.

• Update SKILL.md when command behavior, scoring behavior, consent, storage, lookback, update checks, or report output changes.
• Update docs/skill-flows.md when setup, settings, hook, or lookback agent workflow details change.
• Update both README.md and README-zh.md for user-facing behavior, install steps, essential command lists, examples, and privacy notes.
• Update docs/advanced-setup.md and docs/advanced-setup-zh.md for user-facing advanced settings, hook setup, Codex sync, or optional storage behavior.
• Update docs/privacy.md for any storage, deletion, or network behavior changes.
• Update docs/scoring-rubric.md when stage formulas, dimensions, flags, tip kinds, tip priority rules, or score labels change.
• Update docs/philosophy.md when product framing changes around scoring, reports, privacy, outcomes, or the teaching model.
• Update docs/faq.md when support scope, privacy posture, usefulness claims, feedback channels, or common adoption objections change.
• Update examples/debugging-journey.md when scoring examples, report style, or recommended prompt patterns change.
• Update examples/prompt-gallery.md when improve-mode examples, copyable before/after prompts, or adoption examples change.
• Update eval/prompts.json when scoring behavior, stage definitions, tip kinds, or teaching expectations change.
• Keep host hook snippets in examples/claude-settings.example.json and examples/codex-hooks.example.json, and reference them from docs. Do not duplicate full hook JSON in SKILL.md or README.
• Keep the public command surface consistent across SKILL.md, README.md, README-zh.md, and examples. The public prompt-rewrite command is /prompt-sensei improve; legacy review/score wording should only appear as a redirect to improve.
• Keep beginner and advanced paths separate: basic observe/improve/lookback should work without hook setup, while optional settings can live in advanced docs.