- Home
- Skills
- Agents & Orchestration
- Walkthrough Buddy
More screenshots
Works with the AI Agents you already use
Walkthrough Buddy
Point it at a PR, folder or whole repo and get one page that takes you from "never seen this code" to making your first change: diagrams, ELI5 analogies, real code linked to exact lines, and tested commands.
Free
Walkthrough Buddy
Example session with this skill installed
walk me through pallets/click PR #3877 so I can make my first change in this area
- Read your context and instructions
- Compiled the walkthrough buddy
Wrote .walkthroughs/click-pr-3877.html: one page, ~12 min read, 4 diagrams, 12 code excerpts and 62 file:line links, all checked against commit 2247b35. Below is a cut-down copy of its text. The real page also has the diagrams, the code excerpts and the quiz.
Parameter.spec: naming a parameter the way the user types it
Click now names options in errors, warnings and help the way users type them: --my-option, not my_option.
Not covered here: tox -e typing/style/docs were not run. Tests ran on one local Python, not the CI matrix.
The big picture
Before this PR, some error messages named an option by its Python name: The option 'my_option' is deprecated. The user never typed my_option. They typed --my-option. The PR adds one property, Parameter.spec, that returns the user-facing spelling, and deprecates human_readable_name.
Like you're five: a coffee shop. The customer writes an order slip (the decls: '-g', '--gluten-free'). The barista turns it into a kitchen ticket (the name: gluten_free). The menu board shows the drink as the customer orders it (the spec: --gluten-free). Before this PR, the barista shouted the ticket number at the customer. Now they read from the menu board.
Where it breaks: an argument has no flag, so its menu-board entry is its name in capitals (
RECIPE).
Worked example (real output)
@click.option("--my-option", deprecated=True)builds an Option._parse_declsderivesname = 'my_option'(src/click/core.py:3486).- User runs
cli --my-option hello. The deprecation branch runs (src/click/core.py:2960). self.specreturns'--my-option'.- stderr:
DeprecationWarning: The option '--my-option' is deprecated.
Test it
- ✅ ran:
python -m pytest tests/test_options.py -k test_spec: 7 passed - ✅ ran:
python -m pytest: 2269 passed, 25 skipped, 1 xfailed in 3.58s - ⚠️ not run here:
tox r -e typing(mypy + pyright)
Recipe: change what users see as a parameter's name
- Pick
spec(messages) orget_help_spec(ctx)(the--helpcolumn). - Edit
Parameter.specat src/click/core.py:2570, orArgument.specat :3932 for arguments only. - Add a case to
test_spec(tests/test_options.py:102). - Grep the tests for the old wording.
test_deprecated_warningasserts on it. - Add a CHANGES.md bullet and a
versionchangedin the docstring.
Watch out: don't call human_readable_name from Click code. It warns, and Click's tests turn every warning into an error (pyproject.toml:86).
Next steps
Answer the 4 check-yourself questions on the page, then try the starter task. It gives the exact test command and what passing output looks like.
Connects securely to your tools. The creator never sees your data.
About this skill
New to a codebase, or stuck reviewing a big PR? Ask your agent "walk me through this" and Walkthrough Buddy writes one page you read once and then make your first change from.
What's on the page
- Big picture: one sentence on what the code (or PR) does, and a before/after diagram for changes
- Diagrams of the real flow: what calls what, following one real request, not a folder tree
- ELI5 analogies for every hard idea, plus where the analogy breaks
- Real code, not made-up snippets: every excerpt is copied from git at a pinned commit and linked to the exact lines
- Read these yourself: a short list of the files and line ranges worth reading, with what to look for
- How to contribute: setup, the exact test command (already run), conventions, a step-by-step recipe for the most common change, and the traps
- Check yourself: a few questions, then a starter task with what "done" looks like
It checks its own work
Before handing the page over, a bundled script compares every snippet against the code, follows every file:line link and renders every diagram. A box at the top of the page says what was checked and what the page did not cover.
ADHD mode
Say "I have ADHD" or "make it easier to read" and the same content comes in short timed parts, with a "do this first" step, a progress bar, Done ticks and one next step at the end.
Works on
- a pull request (
#482or a GitHub/GitLab URL) - a branch, commit or range
- a folder or file (
src/billing) - a whole repo
- an idea ("how payments get retried")
Output is a single HTML page (light and dark), or Markdown if you ask. It's saved to .walkthroughs/ and kept out of git status. Commands run in a throwaway worktree, so your checkout is never touched.
Needs: git, bash, python3. Optional: gh CLI for PR threads, and Chrome/Edge/Brave to check diagrams render.
- Needs the code checked out locally as a git repo. It reads files from git, so it can't work from a pasted diff alone.
- Commands only run if the project can be set up on your machine. Anything it couldn't run is marked "not run here" instead of being claimed.
- Very large repos get a focused page (one main flow and the most-changed areas), not a tour of every module. The page lists what it did not cover.
- Diagram render checks need Chrome, Edge or Brave. Without one, the page says diagrams were not checked.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 10 days ago
- Free with an Agensi account
Requires
Permissions
Shell: runs git, the bundled scripts and the project's own tests, inside a temporary git worktree. Read files: reads the code it explains. Write files: saves the page to .walkthroughs/ and adds that folder to .git/info/exclude. Network: optional, for gh to read the PR description and review comments; the HTML page loads Mermaid and highlight.js from a CDN when opened.