convez.ai
SkillProdutividadeIntermediário
lzfxxx

Shadow Tutor

lzfxxx/shadow-tutor

Aprenda pelo palpite: desafio técnico interativo pós-sessão

Ver no GitHub
BomPluginScore · de 0 a 100

Skill que integra aprendizado interativo dentro de sessões Claude Code/Codex. Após o AI gerar código funcional, identifica a decisão técnica que você provavelmente não consegue explicar, te desafia a prever o motivo antes de revelar, e ensina o conceito direto no seu código.

Instalação

$npx convez-ai lzfxxx/shadow-tutor

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Consolidar compreensão de código gerado por IA
  • Identificar gaps de conhecimento em decisões técnicas
  • Treinar raciocínio antes de revelar a explicação

Veredito

Ferramenta criativa que combate a 'ilusão de produtividade' do code-gen, forçando compreensão real através do conflito cognitivo (aprender errando). Ideal para devs que querem evitar dependência de IA e construir skill genuína.

README

A tradução para o português deste README ainda está na fila.

Shadow Tutor

The AI just wrote code that works — but could you explain it? Shadow Tutor runs inside your own Claude Code or Codex session: after a chunk of AI-assisted work, it picks the one load-bearing decision you most likely can't explain, makes you predict why before it reveals, then teaches the why — including the alternative the AI rejected — on your own code.

CI License: MIT version

English · 中文

Install

npx skills add lzfxxx/shadow-tutor

Then finish some real coding with your agent and type /shadow-tutor (or just say "what should I learn from this?").

# Claude Code plugin marketplace
#   /plugin marketplace add lzfxxx/shadow-tutor
#   /plugin install shadow-tutor@shadow-tutor

# Codex skill-installer, straight from this repo
#   $skill-installer https://github.com/lzfxxx/shadow-tutor

# npx installer (installs into both Claude Code and Codex)
npx shadow-tutor install            # or: npx shadow-tutor install cc | codex

# Clone and run the shell installer
git clone https://github.com/lzfxxx/shadow-tutor && cd shadow-tutor
./install.sh                        # or: ./install.sh cc | ./install.sh codex

The problem

AI coding agents let you ship things that run but that you don't understand. Learning happens in the struggle, and the AI removed the struggle. The result is an ability illusion and permanent dependence: the productive friction where skill is built has been optimized away.

Worse, reading the AI's explanation doesn't fix it — explanations slide off. What sticks is the moment you commit to a guess and discover you were wrong. Shadow Tutor engineers exactly that moment, without destroying your productivity (it's post-session and opt-in).

How it works

You code with the AI as usual → reach a stopping point → /shadow-tutor → it:

  1. Reads your knowledge profile (~/.shadow-tutor/knowledge.json) to skip what you've already shown you know;
  2. Silently picks the one load-bearing decision from this session you most likely don't truly understand — a non-obvious choice, a silently-handled pitfall, never boilerplate;
  3. Shows you the actual line and asks you to predict: why this, and what would break otherwise? — then waits;
  4. Reveals, tailored to your answer: confirms the part you got, teaches the part you missed, and gives you the alternative the AI rejected and why — the judgment you can't get from docs;
  5. Offers an optional 60-second exercise on your own code (if your project has tests, it runs them for real feedback);
  6. Updates your profile, so the next review digs one level deeper instead of repeating itself.

One point, one screen, no grading, no guilt — it's a help tool for developers who want to grow, not an exam. "No idea" is a perfectly good answer: that's the illusion breaking in real time.

What it looks like

From a real session transcript (produced by the eval harness, scored 15/16 by the rubric):

Tutor: Here's a call I made in your ProductList:

const filtered = useMemo(
  () => products.filter((p) => p.name.toLowerCase().includes(query.toLowerCase())),
  [products, query]   // ← this line
);

Before I explain anything — the dependency array has both products and query. Why both? Specifically: if I'd written just [query], the search would still feel like it works when you type. So what exactly would break, and when?

You: (commit to a guess — or say "no idea")

Tutor: (reveals, aimed precisely at where your guess fell short — ending with:) …Every dep you leave off is a value quietly frozen, waiting to bite.

Why it's so simple

When you invoke it in-session, the model already has the whole session in context — its own reasoning, every diff, every rejected option. No log parsing, no adapters, no external API, no separate quota: the review is generated in your current session on the subscription you already pay for. Claude Code and Codex use the identical skill format, so one skills/shadow-tutor/ bundle serves both, zero fork.

The entire product is one high-quality teaching methodology (METHODOLOGY.md) plus a per-user knowledge profile.

Repository layout

skills/shadow-tutor/        # ★ the product — self-contained skill bundle (every installer copies this)
  SKILL.md                  #   entry point: triggers + the predict-before-reveal contract
  METHODOLOGY.md            #   the teaching methodology (change behavior here)
  scripts/knowledge.mjs     #   knowledge-profile read/write/validate (guards against corruption)
scripts/knowledge.test.mjs  # node:test suite (npm test)
eval/                       # teaching-quality regression harness (the measure of success)
  run-eval.mjs              #   simulated-student dialogue: predict → answer → reveal → judge
  rubric.md                 #   what "taught well" means, in 8 scored dimensions
  fixtures/{cc,codex}/      #   recorded sessions (React, Python asyncio, Django ORM)
claude/commands/            # optional /shadow-tutor slash command for Claude Code
plugins/ + .claude-plugin/  # generated Claude Code marketplace layout (node bin/cli.mjs build)
bin/cli.mjs                 # cross-platform installer + plugin builder (npx shadow-tutor install)
install.sh                  # shell installer
docs/dev/                   # maintainer playbooks (eval regression gate, adding fixtures)
taxonomy.yaml               # ~130 junior-concept seed (for profile aggregation)

Development: iterating on teaching quality

The one life-or-death question is "does the exchange actually teach?" The eval harness plays out a real dialogue per fixture — tutor asks the PREDICT question, a simulated imperfect student answers, the tutor reveals tailored to that answer, and a judge scores the whole exchange against the rubric:

npm test                 # unit tests for the knowledge profile
npm run eval:dry         # assemble prompts only, no model calls (saves quota)
npm run eval             # real run via claude -p / codex exec, then rubric scoring
node eval/run-eval.mjs --only useMemo   # one fixture

Current scores: 15.3/16 average across React / Python asyncio / Django ORM fixtures. (Honest limits: n=3, the student and judge are themselves LLMs — this measures the shape of the exchange, not human learning. Real signal needs real users; recorded-session fixtures welcome, see CONTRIBUTING.md.)

Edit skills/shadow-tutor/METHODOLOGY.md, re-run, and check the score didn't drop — that's the whole loop (docs/dev/eval-regression.md).

Design notes

  • Predict-before-reveal is the product. Explaining first throws away the only moment where learning happens — the gap between your committed guess and the truth. Every other choice (one point, one screen, evidence-bound) exists to protect that moment.
  • In-session, hook-free. Post-hoc learning needs no real-time mechanism; the skill rides your normal session. See AGENTS.md for the architecture rationale.
  • Privacy. Reviews and the knowledge profile live under ~/.shadow-tutor/ (not in your project), local by default. No network calls, no telemetry.

Roadmap

  • P1 — optional auto-trigger (a SessionEnd hook / lightweight watcher) for users who want it, kept off the skill's critical path.
  • P2 — richer LOCK exercises (fix-the-injected-bug) + HTML rendering of reviews.
  • P3 — deeper spaced recall across sessions (today: a light "due concept" callback rides each invocation).
  • P4 — independent analysis layer (to mitigate self-review bias) / dashboard / multi-user.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados