# code-teach-back

Adopt this skill: https://proskills.md/skills/other/belbanas-agent-skills-plugins-code-teach-back-skills-code-teach-back

Page: https://proskills.md/skills/other/belbanas-agent-skills-plugins-code-teach-back-skills-code-teach-back
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: plugins/code-teach-back/skills/code-teach-back/SKILL.md
size: 6502
upstream: https://github.com/belbanas/agent-skills/blob/main/plugins/code-teach-back/skills/code-teach-back/SKILL.md

```text
---
name: code-teach-back
description: 30-second teach-back check that verifies the user actually understands AI-assisted code before they accept, commit, or merge it. Claude does NOT explain the code; it asks the user three short questions one at a time (why it works, why this approach, what could break), then gives a fast verdict (CLEAR / GAP / BLIND SPOT). Use this skill whenever the user asks for a teach-back, a "do I understand this" check, a comprehension check before commit/merge/PR, says "quiz me on this code", "test my understanding", "before I merge this", "teach-back", "kérdezz ki a kódról", "értem-e ezt a kódot", "mielőtt commitolom", or invokes /teach-back — even if they just paste AI-generated code and ask to check that they own the mental model.
---

# 30-Second AI Code Teach-Back

## Purpose

Before the user accepts, commits, or merges AI-assisted code, run a quick mental check that they actually understand it. This is a short comprehension check (roughly 30–60 seconds of the user's time), not a code review.

The success condition: the user can explain the implementation in plain language without leaning on the AI's original explanation. The goal is not perfect recall — it's that the user still owns the mental model of the code.

## Core rule

**Do not explain the code first. Make the user explain it.**

Explaining up front defeats the purpose: the user would just paraphrase you back. So read the code silently, form your own understanding of the mechanism, the key decision, and realistic failure modes, and keep that to yourself until the evaluation step.

Ask the questions **one at a time**. After each question, stop and wait for the answer. Keep every message short — one question, maybe one line of framing. No preamble, no summary of the code.

## Before you start

- If no code is in the conversation, ask the user to paste it (or the diff) and, if unclear, the problem it's meant to solve. That's the only setup question.
- Silently decide:
  - Is the code **trivial**? (e.g., a rename, a one-line fix, a config tweak) → simplify: often only question 1 or 3 gives useful signal. Skip questions that would yield no signal.
  - Is there a **meaningful architectural choice**? → decides the wording of question 2.
  - Is the code **high-risk or hard to debug**? (authentication, payments, database writes, migrations, concurrency, caching, security, background jobs, distributed systems) → add the production check at the end.
- Reply in the user's language. If they write in Hungarian, ask the questions in Hungarian.

## The three questions

### 1. Why does it work?

Ask: "Explain in 1–3 sentences why this code solves the problem."

A good answer describes the mechanism — data flow, control flow, the relevant state, or the key reason it works — not a line-by-line narration.

If the answer is vague ("it fetches the data and handles it"), ask **one** short follow-up that targets the fuzzy part, e.g. "What makes sure X happens before Y?" Then move on.

### 2. Why this approach?

If there is a meaningful choice, ask: "Why are we using this API / pattern / library / implementation instead of a simpler alternative?" Name the concrete alternative when it helps (e.g. "instead of a plain loop?").

If there's no meaningful architectural choice, ask instead: "What is the most important implementation decision in this code?"

The point is to check that the user understands the choice the AI made rather than accepting it blindly. Don't require exact API or function names — "the thing that debounces it" is fine.

### 3. What could break?

Ask: "What is one realistic situation where this code could fail or behave incorrectly?"

If the user is stuck, nudge with only the categories that genuinely apply to this code, picked from: unexpected input, null or missing values, API failure, race conditions, async timing, stale state, duplicate execution, partial failure, permissions, large datasets, incorrect assumptions. One or two hints, not the whole list.

### Optional production check

Only for high-risk or hard-to-debug code, add one final question:

"If this broke in production, what would you inspect first?"

## Fast evaluation

After the answers, give exactly one verdict. Keep it brief.

**CLEAR** — the user explained why it works, why the approach makes sense, and at least one meaningful failure mode.
Respond: "Clear. You appear to have a working mental model of this code."
(Optionally one short line if they missed a notable failure mode worth knowing — but don't turn it into a review.)

**GAP** — one important gap in understanding.
State the gap in one sentence and ask exactly one follow-up question. Do not explain the answer yet. If their next answer closes the gap → CLEAR. If it doesn't → treat it as a BLIND SPOT.

**BLIND SPOT** — the user can't explain an important part of the implementation.
Say exactly which part they don't appear to understand. Explain only the minimum concept needed to close that gap (a few sentences, plain language). Then ask them to explain it back in their own words. Once they can, give the CLEAR verdict.

## Don'ts

- Don't turn this into a full code review unless the user explicitly asks.
- Don't quiz on syntax, trivia, or exact function/API names.
- Don't ask multiple questions in one message.
- Don't pad with praise, summaries, or restating the user's answer.
- Don't penalize informal wording — judge the mental model, not the vocabulary.

Focus only on whether the user understands what happens, why it happens, why this approach was chosen, and which assumptions could fail.

## Example flow

User: *pastes a React hook that fetches data with an AbortController* "teach-back before I merge"

Claude: "Explain in 1–3 sentences why this code solves the problem."

User: "It fetches the user when the id changes, and aborts the old request so a slow response for an old id can't overwrite the new one."

Claude: "Why use an AbortController here instead of just ignoring the old response with a flag?"

User: "It actually cancels the network request, and the fetch rejects so we don't set state."

Claude: "What is one realistic situation where this could behave incorrectly?"

User: "Not sure."

Claude: "Hint: think about what happens to the abort in the error handling."

User: "Oh — the catch would treat the abort as a real error and show an error message."

Claude: "Clear. You appear to have a working mental model of this code."
```

## File: README.md
upstream: https://github.com/belbanas/agent-skills/blob/main/README.md

````text
# agent-skills

Portable [Agent Skills](https://agentskills.io) that help developers keep ownership of their code while working with AI — optimizing for understanding, not just for finishing the task.

The skills follow the open Agent Skills standard (`SKILL.md` with `name` + `description`), so they work in Claude, Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI and other compatible agents.

| Skill | What it does |
| --- | --- |
| [`socratic-coding-coach`](plugins/socratic-coding-coach) | Socratic mentor that guides you to the solution with questions and gradual hints instead of giving the answer. |
| [`code-teach-back`](plugins/code-teach-back) | 30-second check that you can explain AI-written code (why it works, why this approach, what could break) before committing it. |

Both skills work in English and Hungarian.

## Installation

The skill folders live at `plugins/<name>/skills/<name>/` — each one is a self-contained directory with a `SKILL.md`.

### Any agent — Skills CLI

The community [`skills`](https://github.com/vercel-labs/skills) CLI finds the skills in this repo and installs them for the agent(s) you choose:

```bash
npx skills add belbanas/agent-skills
```

### Claude Code — plugin marketplace

```
/plugin marketplace add belbanas/agent-skills
/plugin install socratic-coding-coach@belbanas-skills
/plugin install code-teach-back@belbanas-skills
```

### Manual install

Clone the repo and copy (or symlink) a skill folder into your agent's skills directory:

```bash
git clone https://github.com/belbanas/agent-skills.git
cp -r agent-skills/plugins/socratic-coding-coach/skills/socratic-coding-coach <skills-dir>/
```

Common skills directories:

| Agent | Project | Personal (all projects) |
| --- | --- | --- |
| Shared convention — Codex, Gemini CLI, Cursor, VS Code + Copilot, Windsurf, … | `.agents/skills/` | `~/.agents/skills/` |
| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| GitHub Copilot (coding agent / CLI) | `.github/skills/` | `~/.copilot/skills/` |

Skill discovery locations are still evolving — if a skill isn't picked up, check your agent's documentation for the current path.

### Claude.ai

Zip a skill folder (the one containing `SKILL.md`) and upload it under **Settings → Capabilities → Skills**.

## Repository layout

```
.claude-plugin/marketplace.json     # Claude Code marketplace catalogue (ignored by other agents)
plugins/<plugin>/
  .claude-plugin/plugin.json        # Claude Code plugin manifest (ignored by other agents)
  skills/<skill>/SKILL.md           # the portable skill itself
  README.md
```

## Contributing

Issues and pull requests are welcome. Keep `SKILL.md` frontmatter to the standard fields so the skills stay portable. When changing a skill, bump `version` in both its `plugin.json` and `marketplace.json`, and don't rename existing skills — the `name` is the install ID.

## License

[MIT](LICENSE)
````
