walkthrough
Skill45 starsChanged 52 days agoMITView on GitHub
Deliver an evidence-grounded, one-item-at-a-time walkthrough of a Proqi implementation worktree or one dedicated GitHub pull request, including a live Herdr TUI demonstration when behavior is visual. Use when explicitly invoked with $walkthrough or when the user directly asks to be walked through Proqi work. Continue the active walkthrough when the user replies next.
30 other projects use a version of this.
Adopted by
Most recently taken up by
- udecode/dotaitheir own version, first seen Nov 13, 2026
- pche-broken-artist/forge-of-thoughttheir own version, first seen Nov 10, 2026
- taecontrol/skillstheir own version, first seen Nov 8, 2026
- marnickvda/pop-quiztheir own version, first seen Nov 8, 2026
- command-center-ai/skillstheir own version, first seen Nov 8, 2026
- marnickvda/know-it-alltheir own version, first seen Nov 8, 2026
Used with
Projects with it also use chips, redo and 9 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
udecodeSkillchips
Run the project's suggested-task ledger, the chips. /chips alone brings this session's open tasks up to date: it applies what the ledger helper says, settles stale and split tasks, cards what can start and reports the board, and /chips all also takes the ship-list tasks and the ones no live session owns, and merges duplicate tasks across the board. Use for /chips, /chips offer, start or drop, \"what chips are open\", \"suggest a task for X\", \"update the chips\", \"clean up the chips\", \"which chips are stale\", \"is this chip still worth doing\", \"merge duplicate chips\", at the last hand-back of a run that offered a task, and whenever pstack would file a tracked issue, a follow-up, a reflect Backlog item or an out-of-band PR.
Also in 3 projects that use this
Scylla23Skillredo
Re-run the last routed task one model tier up (haiku → sonnet → opus → fable). User-invoked escalation when the previous result missed. Pass --dry-run to preview without running.
Also in 3 projects that use this
Aetheria-Labs1Skillplan-page
Plan one storefront page from strategy through final copy, section order, proof, offers, template direction, responsive layout, and production asset requirements. Stops at an approved execution-ready specification.
Also in 3 projects that use this
SocialKit-APISkillvideo-transcripts
Extract transcripts from social videos through SocialKit across YouTube, TikTok, Instagram, Facebook, X/Twitter, LinkedIn, and direct video file URLs. Use when the user asks to transcribe, get captions or subtitles, pull the spoken text, or read what a video says, including one video or many at once. Returns full text plus timestamped segments. Not for posting, private accounts, or unrelated website scraping.
Also in 3 projects that use this
MicrosoftSkillcleanup
Also in 3 projects that use this
BlockSkilltest-audit
Invoke whenever writing, changing, reviewing, or sweeping tests in buzz-app. Authoring gate for new tests plus audit workflow for low-value, implementation-coupled, or duplicative tests and the test-only production seams they demand.
Also in 3 projects that use this
Other versions30 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 30
- udecode/plate★ 17ksame name
- udecode/dotai★ 1.2ksame name
- udecode/better-convex★ 452same name
- Mathews-Tom/armory★ 340same name
- smallnest/goal-workflow★ 283same name
- andrew-yangy/gru-ai★ 153same name
- huytd/skills★ 19same name
- wycats/ai-plugin★ 19same name
- wycats/vscode-ai-plugin★ 19same name
- pche-broken-artist/forge-of-thought★ 14same name
20 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- xtask/AGENTS.mdAGENTS.md
- architecture-reviewSkill
- claude-code-reviewSkill
- codex-reviewSkill
- implement-in-worktreeSkill
- proqi-screenshotSkill
- releaseSkill
- proqi-debugSkill
- proqiSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. 0 are common, 17 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 30 edited versions we read keep these.
17
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Ask one focused scope question only when the source cannot be inferred after inspection.
- Distinctive: line 28
Do not edit code, repository documents, GitHub, pull requests, or settings during a walkthrough.
- Distinctive: line 34
Use a checkout that faithfully contains the selected source before presenting item one.
- Distinctive: line 46
If an unmerged demonstration depends on primary-checkout changes that are not represented by a commit or existing linked worktree, pause …
- Distinctive: line 65
Do not visually demonstrate planned or described behavior unless code evidence confirms it exists in the selected revision.
- Distinctive: line 67
If evidence materially changes after the agenda is frozen, explain why and rebuild the agenda instead of silently changing the count or …
- Distinctive: line 95
Never present or leave an extreme split ratio that makes either pane too small.
- Distinctive: line 96
When narrow or shallow responsive testing is required, use only recorded walkthrough-owned disposable geometry, then restore the balanced …
- Distinctive: line 104
Never submit to, rename, focus, or close an unrelated agent pane.
- Distinctive: line 112
If the real TUI cannot be prepared after its documented setup and recovery path, pause on that item and report the blocker.
- Very specific: line 120
Treat every other reply as discussion of the current item.
- Distinctive: line 122
Never show more than one agenda item in a response.
- Distinctive: line 131
Use this compact shape, omitting headings that do not help:
- Distinctive: line 151
Keep an item roughly 100 to 250 words.
- Distinctive: line 159
Stop only processes started by the walkthrough and close only its recorded test panes or tabs.
- Distinctive: line 162
Delete only the exact isolated state directory created by this walkthrough.
- Distinctive: line 169
Never remove a reused implementation worktree.
- Distinctive: line 171
If any ownership check fails, the checkout is dirty, or cleanup is refused, retain the resource and report its exact identifiers and reason.
- Very specific: line 175
After cleanup, report what was stopped and removed, note any retained resource, and end with Walkthrough complete.
“Common” is measured: kept by at least 6 in 10 of the 30 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Walkthrough
Explain and, when appropriate, demonstrate one bounded body of Proqi work one concise item at a time. Resolve the source from context, prepare the complete agenda privately, and reveal only the current item.
Resolve and verify the source
- Infer the source from the request and recent conversation before asking the
user to repeat anything. Support:
- the implementation in the current or named linked worktree; or
- one specified GitHub pull request, open or merged.
- Inspect the applicable
AGENTS.md, branch commits, working-tree state, and complete diff against the verified base. For a pull request, use read-only GitHub queries to verify its base, head, state, and merge commit. - Confirm that claimed shipped work is reachable from
origin/main. Label an open pull request, an unmerged branch, or uncommitted work as unshipped. - Ground every claim in code, tests, snapshots, documentation, or observed behavior. A PR description or ticket is not proof that behavior exists.
- Ask one focused scope question only when the source cannot be inferred after inspection.
Do not edit code, repository documents, GitHub, pull requests, or settings during a walkthrough. Builds, isolated test state, and disposable demonstration resources are the only permitted mutations.
Select the checkout
Use a checkout that faithfully contains the selected source before presenting item one.
- A linked implementation worktree may be reused when it contains the exact selected implementation. Record its initial path, branch, HEAD, status, and Herdr workspace or pane identifiers when available. Never remove it.
- The primary checkout may be used only for work already merged to
mainand present in that checkout. Treat it as source-only for every unmerged change. - For an open PR or other committed unmerged source without a matching linked worktree, fetch the exact head and create a collision-free detached temporary worktree. Record its parent directory, checkout path, and head SHA. Do not create a branch for a walkthrough.
- If an unmerged demonstration depends on primary-checkout changes that are not represented by a commit or existing linked worktree, pause and ask the user to commit them or move them into a dedicated worktree. Never copy, stash, reset, or clean user changes to manufacture a demonstration revision.
This worktree rule applies even when the walkthrough itself is invoked outside Herdr.
Build the private agenda
Build and freeze the complete agenda before presenting the first item. Reveal the total count, but not future item titles.
- Group an implementation or PR into coherent user-facing behaviors, system contracts, or operational changes. Do not make one item per file, commit, test, or implementation phase.
- Classify every item privately as visual or nonvisual. A behavior is visual when the verified revision changes something the user can see or operate in the TUI. Refactors, types, tests, and CI-only changes are nonvisual.
- Do not visually demonstrate planned or described behavior unless code evidence confirms it exists in the selected revision.
- If evidence materially changes after the agenda is frozen, explain why and rebuild the agenda instead of silently changing the count or order.
Require Herdr for visual work
Nonvisual walkthroughs may run anywhere. If the agenda contains any visual
item, require HERDR_ENV=1 before presenting item one. When it is absent, pause
with a concise instruction to resume the walkthrough from a Proqi worktree or
coordinator session inside Herdr. Do not substitute a hidden PTY, prose-only
claim, or newly opened operating-system terminal.
Inside Herdr:
- Load the installed Herdr skill completely when the current harness exposes it, then inspect the installed CLI help as the authoritative command contract. If that companion skill is unavailable, use the Herdr CLI help directly rather than blocking an otherwise capable Claude or Codex worker.
- Reuse the selected implementation workspace when it exists. Otherwise open
the selected temporary worktree as a Herdr workspace. Prefer a disposable
sibling pane in the implementation agent's existing tab so the agent and
live demonstration remain visible together. Use a new tab only when the
current tab cannot retain usable pane geometry or the demonstration genuinely
requires an isolated layout. Never create a new tab merely for convenience.
Address every disposable pane or tab by an explicit ID with
--no-focus, and record every resource created. - Present live walkthroughs only in an ordinary, unzoomed, balanced side-by-side
layout where both the implementation or Codex pane and the demonstration pane
remain simultaneously usable. The Herdr
Zzoom state must not be active. Never present or leave an extreme split ratio that makes either pane too small. When narrow or shallow responsive testing is required, use only recorded walkthrough-owned disposable geometry, then restore the balanced side-by-side layout before showing the result to the user. - Build the exact checkout with
cargo build --locked --bin proqi. Launch its real binary in a disposable pane with a private temporary--state-dir. - Seed only synthetic walkthrough sessions and thoughts. Never inspect or mutate the user's ordinary Proqi state. Disable Herdr integration unless the selected behavior specifically requires it.
- Never submit to, rename, focus, or close an unrelated agent pane. A live integration demonstration that would create an agent session, consume model credentials, submit a prompt, or alter the clipboard requires the user's explicit authorization for that action.
- Prepare the exact visible state before describing the item, and leave it visible while the user inspects or operates it. State what is selected, persisted, pending, or expected after the suggested interaction.
If the real TUI cannot be prepared after its documented setup and recovery path, pause on that item and report the blocker. Do not claim a visual result from deterministic tests alone.
Keep strict pace
- Advance only when the user's entire reply is
next, ignoring case, surrounding whitespace, and terminal punctuation. - Treat every other reply as discussion of the current item. Answer concisely,
keep the same item active, and end with
Say next. - Never show more than one agenda item in a response. Do not add back, skip, or overview controls.
- End each non-final item with
Say next. - For a final visual item, keep the TUI live and end with
Final item. Say next when you are finished inspecting it.The next reply triggers automatic cleanup rather than another agenda item. - For a final nonvisual item, clean any walkthrough-owned temporary checkout
before responding and end with
Walkthrough complete.
Use this compact shape, omitting headings that do not help:
2 / 5 · Smart list continuation
What it means
<concise explanation>
Why it exists
<reason or context>
Try
<one focused interaction, for a visual item>
Expected
<observable and persistence result>
Say next.Keep an item roughly 100 to 250 words. Mention paths, tests, or implementation mechanics only when they materially improve understanding.
Clean up automatically
The user has chosen automatic cleanup; do not ask whether to remove or retain a walkthrough-created environment.
- Stop only processes started by the walkthrough and close only its recorded test panes or tabs. Preserve implementation agents, their panes, and every pre-existing service.
- Delete only the exact isolated state directory created by this walkthrough. Resolve and validate the recorded path before deletion; never use an unresolved variable, glob, repository root, home directory, or broad parent.
- For a walkthrough-created detached worktree, verify that
HEADis still the recorded source and that tracked and untracked status is empty, then remove it with ordinarygit worktree removeand no force. Remove its empty temporary parent afterward. - Never remove a reused implementation worktree. Report its path, branch, and status after stopping walkthrough-owned resources.
- If any ownership check fails, the checkout is dirty, or cleanup is refused, retain the resource and report its exact identifiers and reason. Never force cleanup merely to satisfy the automatic policy.
After cleanup, report what was stopped and removed, note any retained resource,
and end with Walkthrough complete. If the user abandons the walkthrough,
perform the same owned-resource cleanup immediately.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

