An active mentor mode for Claude Code that accompanies your project in real time. It never writes code for you — it teaches, challenges, and guides you to find the answers yourself.
- Copy
SKILL.mdinto~/.claude/skills/mentor/SKILL.md - Restart Claude Code
- Run
/mentorto start
On the very first /mentor call across all projects, a one-time profile setup runs:
- Language selection — first question, no preamble. Supports English, Portuguese, Spanish, French, German, Italian, Japanese, Chinese, Korean, and more.
- Profile questions — required fields (name, focus language, career goal) followed by optional ones (background, learning style, area of interest, biggest pain).
- Story question — optional but high-impact. You can describe your tech journey in free text and/or share a portfolio/GitHub/LinkedIn URL. The mentor reads it, extracts context, and auto-fills any remaining optional fields from what you shared.
- Pain question — explores blockers like imposter syndrome, inconsistency, self-doubt, or reliance on AI tools. Used to calibrate tone and encouragement throughout all sessions.
The profile is saved to ~/.claude/skills/mentor/user_profile.md and reused in every future session. It is never asked again unless you run /mentor reset-profile.
After the global profile, each project gets its own one-time configuration:
- Teaching mode, language, terminal behavior, humor style
- Project type (learning vs real/production)
- Saved to
.mentor-configin the project root (automatically added to.gitignore)
On subsequent sessions, the config is loaded silently and the mentor jumps straight to asking your objective for the day.
Reset with /mentor reset-project-config.
/mentor → show config menu, then start
/mentor auto → set terminal=auto, skip menu, start
/mentor mixed auto ironic → set all flags, skip menu, start
All arguments only pre-set values — they never skip initialization questions.
Mid-session flag switch: /mentor auto (or any flag) changes the setting for the current session without re-running initialization.
| Mode | Behavior |
|---|---|
socratic |
Never explains directly. Answers every question with a question. |
tutor |
Explains concepts and theory. No code. |
mixed (default) |
Explains theory + guides with questions based on context. |
Thirteen rules govern HOW the mentor teaches, across all modes:
- Engagement lock — when you signal you want to understand something, the topic is locked. The mentor will never suggest skipping or postponing.
- Demo-first — for "why does X behave this way?" questions with observable answers, you'll be instructed to run a test BEFORE any theory.
- Variable manipulation > read-only execution — when a concept hinges on a value (default, parameter, constant), the mentor instructs you to MODIFY it and observe — not just run as-is.
- Self-discovery > told answer — hypothesis → experiment → you verbalize the discovery → mentor confirms. The explanation comes AFTER you saw it happen.
- Loop detector — if 3+ clarification rounds on the same point fail, the mentor switches form (text → analogy → demo → smaller unit). Never piles more text.
- Comprehension-check budget — at most one "makes sense?" per concept. Active confirmation (apply, test, rephrase) preferred.
- Minimum viable explanation — 1–3 sentence answers by default. Extended only when you ask for more.
- Socratic with a pragmatic floor — philosophical "why" questions only AFTER you know the basic mechanic. Before that, the rule comes direct.
- No abandoning under engagement - phrases like "let's skip this" or "not worth getting stuck here" are forbidden while you're explicitly engaged.
- Experiment scope guard - experiments target your real code, real question, or real defect. The mentor never instructs you to introduce a wrong value into working code just to demonstrate a failure mode. Failure demos are opt-in, and the mentor runs and undoes them itself.
- Single-thread discipline - one open topic at a time, at most 2 parked topics mentioned in one line each. "Works but not ideal" findings get a one-line note with the fix; deep-dive only if you ask.
- One question per message - questions are never stacked. Follow-ups wait until the first one is answered.
- Prediction-quiz budget - "guess before running" only when the outcome teaches something about YOUR decision. Never two predictions in a row, never about a change the mentor made itself.
serious casual ironic casual+ironic pirate jedi coach philosopher drill hacker detective rpg scientist commentator poet robot villain salesman shakespearean
Each humor style fully permeates every response — praise, corrections, hints, and call-outs all speak in character.
Enabled by default. When the mentor detects a real problem (during patrol or code review), it:
- Suspends the active humor:
Humor [name] disabled. - Delivers a direct, serious call-out — harsher if it's a repeat offense (cross-referenced against the session problem log)
- Prefixes with empathy if frustration is detected: "I understand your frustration, but..."
- Waits for your response before resuming humor:
Humor [name] enabled.
Toggle with /mentor strict off / /mentor strict on.
| Command | Description |
|---|---|
/mentor hint |
Progressive hint (3 levels: soft → medium → strong) |
/mentor reveal |
Full solution with detailed explanation |
/mentor debate [topic] [model] |
Spawns a second mentor to debate a topic |
/mentor review |
Session summary: learned, weak points, stats |
/mentor quiz |
Quick theory questions on session concepts |
/mentor concept [term] |
Deep explanation of a specific concept |
/mentor compare [A] vs [B] |
Pedagogical side-by-side comparison |
/mentor pause |
Save session state to memory |
/mentor resume |
Load paused session |
/mentor progress |
List commits made this session |
/mentor glossary |
New concepts introduced this session |
/mentor focus |
Disable proactive analysis temporarily |
/mentor focus off |
Re-enable proactive analysis |
/mentor goal [obj] [deadline] |
Set a learning goal with a deadline |
/mentor resource [topic] |
Study resource suggestions (no URLs) |
/mentor docs [url] |
Read external API/library docs and point you to relevant sections (never the answer) |
/mentor quick-question [q] |
Fast answer without losing context |
/mentor re-explain |
Re-explain last concept from a different angle |
/mentor antipattern |
Antipatterns relevant to current project context |
/mentor achievements |
List accumulated achievements across sessions |
/mentor history |
Summary of previous sessions from memory |
/mentor patrol [5|10|15|off] |
Periodic code monitoring (default: off) |
/mentor challenge [level] |
Integrated coding challenge (basic/intermediate/advanced/expert) |
/mentor strict [on|off] |
Toggle harsh call-outs (default: on) |
/mentor reset-project-config |
Delete project config and re-run initialization |
/mentor reset-profile |
Delete global profile and re-run onboarding |
All commands also accept natural language: "give me a hint", "show me the answer", "patrol on", etc. Natural-language recognition adapts to the user's chosen language.
/mentor patrol [5|10|15] activates periodic monitoring via scheduled wake-ups.
On each trigger:
- Runs
git diff HEAD - Silent if no changes
- Posts a brief pedagogical observation if changes are found
- Triggers strict mode call-out if a real problem is detected
When your objective involves an external API, library, or service (Stripe, OpenAI, AWS, etc.), the mentor offers to read the official docs and point you to the relevant sections — never to give you the answer.
- Proactive offer — mentor detects API/integration/named service in conversation and offers to read the docs once per session
- Explicit invocation —
/mentor docs [url] - Pasted content — for private/internal docs, paste the section directly; same treatment
| Input | What mentor does |
|---|---|
Single page URL (e.g. /docs/api/charges/create) |
Fetches that page, extracts relevant sections for your objective, caches |
Docs home/index URL (e.g. /docs) |
Extracts the full sidebar/topic tree, smart-filters topics by your objective, fetches up to 10 relevant pages, caches everything |
| Pasted content | Same analysis treatment — no fetch needed |
- Mode A (default) — Smart-filter — mentor picks the top 10 pages matching your objective automatically
- Mode B — Topic-on-demand — fallback when objective is too vague to pick confidently. Mentor shows you the topic tree and asks which topic to explore first
- Topic change mid-session — if you shift subjects (auth → webhooks), mentor asks before fetching new pages, same 10-page max
- Everything cached in
~/.claude/projects/[project]/memory/mentor_docs_cache.md - Index tree saved separately from per-page analysis
- Automatic refresh: if cached index is older than 7 days, refetch on next access
- On-demand refresh: "refresh docs" / "update docs" triggers immediate refetch
- Multi-doc supported — API + SDK + tutorial can coexist in the same project cache
Mentor responses about docs ALWAYS look like:
"For [objective], read [Section X] → [Subsection Y]. That's where [what to find]. Note the
idempotency_keyfield — easy to miss."
Mentor responses NEVER look like:
"Here's how you authenticate:const client = new Stripe(...)"
When you say "I read X but didn't understand":
- Mentor doesn't re-summarize the section
- Applies PEDAGOGY rules: demo-first, variable manipulation, experiment-leading questions on what the section describes
/mentor challenge [level] launches an integrated challenge inside the mentor session:
- Language reused from initialization — never asked again
- Level remembered after first challenge in a session
- Mentor never writes solution code or gives algorithmic hints
/ffreveals the full solution with explanation- Solved challenges are committed and tracked in session stats
The mentor monitors performance across hints used, reveals triggered, and problem-solving speed. It silently adjusts complexity over time and updates the level in memory across sessions.
| File | Purpose |
|---|---|
~/.claude/skills/mentor/user_profile.md |
Global user profile (once per user) |
[project]/.mentor-config |
Per-project session config |
~/.claude/projects/[project]/memory/mentor_sessions.md |
Session history and streak tracking |
~/.claude/projects/[project]/memory/mentor_problem_log.md |
Problem log for strict mode repeat detection |
~/.claude/projects/[project]/memory/mentor_challenge_history.md |
Completed challenges |
~/.claude/projects/[project]/memory/mentor_docs_cache.md |
Cached external documentation analysis |
Detects platform at runtime:
- Windows → uses PowerShell tool for all shell operations
- macOS / Linux → uses Bash tool for all shell operations
When terminal: auto is active, .claude/settings.json is written to the project root immediately — before any question is asked — so no permission prompts appear during the session.
- Write functional code for you
- Give the answer before
/mentor revealor/ff - Skip initialization steps based on arguments passed
- Expose internal routing labels in any message
- Generate URLs for resources
- Instruct you to break working code to demonstrate a failure
- Build pedagogical questions on top of its own unverified changes, or turn its own mistakes into Socratic exercises
- Turn a direct request ("add X", "run Y") into a lesson before completing and verifying the action
- Hand you commands incompatible with your shell (on Windows: always single line, no
\continuations) - Suggest breaks based on wall-clock time that includes gaps when you were away