DrCatHicks/learning-opportunities: a skill that makes the agent stop and ask

A premise stated before any feature

The README opens with a single line under the title: build your expertise, not just your projects. Everything after that is an argument in service of that sentence.

The mechanism is described as an adaptive dynamic textbook approach that integrates science based expertise building exercises while doing agentic coding. Concretely, after architectural work, Claude offers an optional ten to fifteen minute learning exercise grounded in evidence based learning science. The exercises draw on prediction, generation, retrieval practice and spaced repetition, and the material for each exercise is semi worked examples taken from the user's own project work rather than from a generic curriculum.

The repository metadata is small to match. It is described as a Claude or Codex skill for deliberate skill development during AI assisted coding, the declared language is Shell, the license is CC-BY-4.0, and there are 2,446 stars against 90 forks with 9 open issues. It is not archived, main is the default branch, and the last push was 2026-08-19. There are no releases, no homepage, and no topics. For a repository with almost 2,500 stars, the absence of a topic list and a release history is notable; installation happens through the plugin marketplace commands in the README rather than through versioned artifacts.

Five named risks in agentic coding

The middle of the README is the strongest part of the document, because it states the problem in the language of learning science rather than in the language of developer productivity. The claim is that AI coding tools create specific risks for decreasing user engagement in learning by introducing inefficient learning habits, and then five of them are named.

The generation effect: accepting generated code and decreasing the act of generating your own code skips the active processing that builds understanding. The fluency illusion: clean generated code gets perceived as more understood than it is, and easily accessible knowledge from search promotes an illusion of knowledge and of a more complete mental model than you actually hold. The spacing effect: machine velocity pushes toward constant cramming and long production sessions without the cadence and reflection that support longer term retention.

The fourth is metacognition, meaning fast workflows leave no room to monitor your own learning or develop a schema representation of the material, along with a sense of your own relative expertise when working with something unfamiliar. The fifth is testing and retrieval, since agentic models push toward giving complete answers, which means fewer opportunities to self test or retrieve specific components of new knowledge.

The countermeasures are listed as a mirror image of the five risks: active generation through predictions, explanations and sketches, retrieval practice through check ins, teach it back and self testing, deliberate pauses for spacing and reflection, and explicit metacognition through self assessment and gap identification. The design intent is to interrupt the default pattern by reminding you to invest in reflection, and the README is honest that this introduces a different mode of interaction which will intentionally feel unlike fast fluent agentic coding.

Three packages doing three different jobs

The repository tree is short enough to read in one pass, and the directory names map directly onto the feature list in the README: .agents/, .claude-plugin/, CHANGELOG.md, CLAUDE.md, LICENSE, README.md, learning-opportunities/, learning-opportunities-auto/ and orient/.

The marketplace listing names three components. learning-opportunities is the core learning exercise skill. learning-opportunities-auto is an optional post commit prompting hook. orient is a repo orientation generator.

That third one is easy to skim past and deserves more attention than the README gives it. If you are learning a new repository, you can create an orientation.md file with suggested lessons using the orient skill. The stated approach applies strategies from empirical research on program comprehension and codebase navigation, including how expert developers sample codebases strategically rather than reading exhaustively, and the full source list lives in a bibliography file under orient/skills/orient/resources/. It composes with the core skill: you run orient to be offered two lessons covering the repository's core features, then call learning-opportunities with the orient argument to act on them.

There is also a companion project referenced, Learning-Goal, described as a skill that guides semi structured interactive learning goal setting using Mental Contrasting with Implementation Intentions. It is a separate repository, worth knowing about if your problem is deciding what to learn rather than practicing something you have just built.

Installing through the plugin marketplaces

The repository doubles as a plugin marketplace for both tools, which is why the install commands come first in the README rather than being tucked at the end.

For Codex, adding it from GitHub is a single command:

+codex plugin marketplace add https://github.com/DrCatHicks/learning-opportunities.git
+

For local development from an existing checkout, the same command takes a filesystem path instead of the URL.

Claude Code installation is a three step sequence, since it separates adding the marketplace from installing the plugin from restarting. You add the marketplace with the slash command form of the same address, then run `/plugin install learning-opportunities@learning-opportunities`, then restart Claude Code to activate. The orient plugin installs the same way with `/plugin install orient@learning-opportunities`.

The optional automatic prompting package is where platform differences show up. Linux and macOS users can install learning-opportunities-auto alongside the core skill to have Claude consider offering an exercise after each git commit. Windows users can use it too, but the README is explicit that a little setup is required and points to a Windows setup section in that package's own README rather than pretending the path is identical.

Once installed, the skill is invoked as a slash command. Orient runs as `/orient`, or as `/orient showboat` to route through Simon Willison's showboat tool, and the core skill can be called as `/learning-opportunities orient`.

Five exercise shapes and one stubborn prompt

The How It Works section describes the trigger and then the shape of what follows, and the trigger is deliberately loose. You decide what counts as significant work, with the author's suggestions being new files or modules, database schema changes, architectural decisions or refactors, implementing unfamiliar patterns, or any work where you asked why questions during development. The stated key idea is to find a moment in your own flow where a learning opportunity is most beneficial.

When that moment arrives, Claude asks a short question: would you like to do a quick learning exercise on a given topic, about ten to fifteen minutes. If you accept, you get an interactive exercise.

The important detail is what does not happen. The README calls it a key design principle: Claude pauses and waits for your input rather than answering its own questions. The author flags that this can feel frustrating and attributes that to pushing against Claude's default to always provide the full answer. He also notes that you may have to design against those defaults, and invites reports of gotchas and conflicts that generalize, giving the example of having needed to suppress prompt suggestions.

Five exercise types are named. Prediction, observation and reflection asks what you expect to happen, then what surprised you. Generation and comparison asks you to sketch your approach before seeing the implementation. Tracing the path walks execution step by step while you predict each transition. Debug this asks what would go wrong and why. Teach it back asks you to explain the thing. Every one of them puts the answer in your mouth first and the model's answer second, which is the entire mechanism stated as an interface.

Who this is actually for

The README nominates a specific reader: users experimenting with developing discrete projects with agentic coding that involve multiple unfamiliar languages, techniques or architectural patterns. That is a narrower claim than the star count suggests, and it is the honest scope.

The reasoning is that this is not a productivity tool and does not compete on speed. It is for the situation where you are using an agent to work in a part of the stack you do not already know well, which is exactly the situation where the fluency illusion does the most damage. If you are building in a codebase you have read thoroughly and know cold, the interruption has little to add.

Two things to weigh before adopting it. The first is interruption frequency. With the auto package enabled, every git commit becomes a prompt opportunity, and a developer doing twenty small commits an hour will feel that more than they will enjoy it, which is why it ships as optional and separate from the core. The second is licensing. CC-BY-4.0 is a content license chosen for a documentation shaped repository, and it is not the MIT or Apache license most plugin code carries. The source code is available and the README does invite contributions and reports of workflow conflicts, but the terms differ enough from the usual plugin default that they deserve a read.

What is here is a well argued thesis, a small amount of code, and a prompt design that takes the pedagogical claim seriously enough to make the model stop talking.

Editorial conclusion

This repository is small and its entire argument fits in one README, but the argument is a real one. Agentic coding tools make code cheap to produce and understanding expensive to skip, and the gap between those two facts is where expertise stops accumulating. The approach here is to reintroduce friction at the exact moment a developer would otherwise coast: after a new file, a schema change, a refactor, or any point where they asked why. The core skill offers a ten to fifteen minute exercise and then, critically, waits for an answer instead of supplying one. That single design choice is what separates it from a tutorial generator. The three packages cover different needs. The core skill is the exercise engine. The optional auto package hooks into git commit so exercises are offered without being requested, which is the piece that needs extra setup on Windows. The orient package is separate and more interesting for newcomers, since it generates orientation lessons for a repository you are learning rather than exercises about code you just wrote, drawing on research into how expert developers sample a codebase instead of reading it exhaustively. Two practical notes. The repository is licensed CC-BY-4.0 rather than MIT, which is unusual for a code-adjacent plugin and worth reading before you fork it. And it has no releases at all, so installing from GitHub means installing whatever is on the default branch, last pushed on 2026-08-19. Install the core skill first and decide about the automation later, because the automation changes when you are interrupted.

Frequently asked questions

Official sources

1. DrCatHicks/learning-opportunities on GitHub
2. Issues
3. License: CC-BY-4.0
4. README