potatoman03/code-comprehension-skill

Overview

This skill quizzes users about AI-generated code to build understanding and improve prompting skills. It tracks edits, creates contextual quizzes tied to specific changes, and can block commits until quizzes are passed. The goal is to help you catch issues and learn the rationale behind generated code before shipping.

How this skill works

The skill records pending changes in a local state file (.claude/quiz-state.json) and generates context-specific multiple-choice questions that reference actual functions, files, and decisions in the code. Quizzes are produced in batch (2–5 questions) for speed, scored against a configurable pass threshold, and the state is updated atomically with stats and history.

When to use it

• After AI code generation to verify you understand the implementation
• Before committing changes to ensure you reviewed potential issues
• When learning a new pattern, library, or codebase (strict mode)
• During code reviews to reinforce knowledge about design decisions
• To keep a record of what was added or changed for future reviews

Best practices

• Enable batch quizzes to answer all questions in one interaction for speed
• Keep .claude/quiz-state.json in .gitignore to avoid committing state
• Set questionsPerQuiz and passThreshold in config to match team goals
• Prefer commit mode for productivity, strict mode for focused learning
• Provide clear prompts when requesting code so questions can reference intent

Example use cases

• You asked the model to add JWT auth—track the change and quiz on login(), refreshToken(), and token expiry behavior
• A UI component was generated—quiz on prop names, responsive behavior, and edge-case rendering
• A DB migration was created—quiz on schema changes, rollback strategy, and constraints
• While iterating, strict mode forces you to answer questions after each generation to reinforce concepts
• Pre-commit hook prevents commits when there are pending quizzes, prompting you to review changes first