The argument in one line.
A popular Claude Code skills library was rewritten around one precisely-named workflow — spec, then tickets, then implementation, then two-axis review — plus a new tool for making decisions across projects too large for a single agent session.
Read if. Skip if.
READ IF YOU ARE…
- You already use Claude Code (or a similar coding agent) with a structured skills or plan-mode workflow and want to know what changed in this update.
- You're planning a project too large to fit in one agent session and need a repeatable way to accumulate decisions across multiple sessions.
- You want a cheap, borrowed vocabulary (named code smells) for catching bad patterns during AI-assisted code review.
SKIP IF…
- You've never used an AI coding agent and don't yet have a repo-based workflow for planning or reviewing code.
- You're looking for general video or content-creation advice — this is strictly about software development tooling.
The full version, fast.
This update to a popular open-source Claude Code skills library renames two core files — the old 'PRD' skill becomes 'spec' and 'issues' becomes 'tickets' — because the artifacts they produced were never product requirement documents or GitHub issues specifically, just specs and tickets. It formalizes the main workflow: grill, write a spec, break the spec into tickets, implement each with TDD, then run a two-axis code review checking both coding standards and spec faithfulness, using a vocabulary of code smells borrowed from Martin Fowler's Refactoring. The headline addition is Wayfinder: a tool for planning projects too large for one agent session, storing an evolving map of open questions as linked, typed GitHub issues so decisions accumulate across sessions before condensing into a spec.
Free for members
Chat with this breakdown — free.
Sign in and you get 23 free chat messages on us — ask for the hook, quote a framework, find the exact transcript moment, generate a markdown action plan. Bring your own key when you want unlimited.
Create a free account →Where the time goes.
00:00 – 00:36
01 · Cold open — shipping v1.1
Announces the release and merges the pull request live on screen.
00:36 – 02:33
02 · Renaming to-spec and to-tickets
to-prd becomes to-spec, to-issues becomes to-tickets; explains rationale and warns the rename breaks in-place updates.
02:33 – 04:14
03 · Fixing the grilling skill
Three bug fixes: no more multi-question bursts, a confirmation gate before implementation, and a fact/decision split to stop self-grilling.
04:14 – 05:36
04 · The new five-stage main flow
Names the canonical sequence for the first time: grill-with-docs, to-spec, to-tickets, implement, code-review.
05:36 – 06:12
05 · The implement skill
A deliberately tiny skill: TDD at pre-agreed seams, run checks/tests, code-review, commit.
06:12 – 07:45
06 · Code review: standards, spec, and Fowler's smells
Two parallel sub-agent passes (standards + spec) plus a new vocabulary of named code smells from Refactoring.
07:45 – 11:40
07 · Wayfinder: planning across sessions
A shared map of open questions stored as linked, blocking GitHub issues; ticket types research/grilling/prototype/task.
11:40 – 12:36
08 · Research and prototype skills
Research investigates primary sources via a background agent; prototype builds cheap concrete artifacts to raise discussion fidelity.
12:36 – 13:36
09 · TDD becomes reference-only
Refactoring removed from the loop entirely — now red-green, not red-green-refactor — so an AFK agent can run it unsupervised.
13:36 – 14:04
10 · Wrap-up: how to safely update your skills
Recommends a clean reinstall of skills rather than trusting the in-place updater after this rename.
14:04 – 14:49
11 · Pitch: the new AI Coding Crash Course
A self-paced, cheaper, ungated course announced for both developers and non-developers.
14:49 – 15:11
12 · Sign-off — stars and downloads
Repo stats: roughly 160k GitHub stars, 7M downloads on skills.sh.
Lines worth screenshotting.
- A skill originally called 'to-prd' was renamed 'to-spec' because it was never producing an actual product requirements document — just a specification.
- 'to-issues' became 'to-tickets' because 'issues' biased the workflow toward GitHub and Linear specifically, when the underlying artifact is just a ticket.
- The core workflow now runs five stages in order: grill the user, write a spec, break the spec into tickets, implement each ticket with TDD, then run code review.
- A confirmation gate was added to the planning skill — 'do not enact the plan until I confirm we have reached a shared understanding' — because sessions kept skipping straight to implementation.
- Code review runs two parallel sub-agent passes: one checks the diff against a repo's documented coding standards, the other checks it against the originating spec.
- The code-review skill borrows its vocabulary of bad-code patterns directly from Martin Fowler's Refactoring — mysterious names, duplicated code, feature envy, primitive obsession — because those terms are already deep in a model's training data.
- Wayfinder is built for projects too big for one agent session: it stores open questions as linked GitHub issues with blocking relationships, so no decision gets made before its prerequisite is resolved.
- Wayfinder tickets come in four types — research, grilling, prototype, and task — each deliberately scoped to fit inside a single agent session.
- A prototype ticket exists for one reason: raising the fidelity of a discussion by building something cheap and concrete to react to, rather than debating it in the abstract.
- The TDD skill dropped 'refactor' from its red-green-refactor loop entirely — refactoring now belongs to the code-review stage, not the implementation loop, so one slice of work never gets overloaded.
- The research skill spins up a background agent that investigates a question against primary sources — official docs, source code, first-party APIs — not secondary write-ups, and writes findings to a single markdown file.
- A rename across a shared skills library means you can't just update in place — you need to reinstall via the skills CLI and manually prune any old, now-orphaned skill files from your repo.
A renamed workflow, and a new tool for decisions too big for one session
SKILLS WORKFLOW
The real lesson isn't the rename — it's that a repeatable AI-coding workflow needs an explicit place to make decisions before writing code, and a way to spread that decision-making across more than one sitting.
02Renaming to-spec and to-tickets
- A skill's name should describe what it actually produces — 'to-prd' was renamed 'to-spec' because it never generated an actual product requirements document, just a specification.
- Renaming core files in a shared skills library isn't safe to auto-update — after a breaking rename, reinstall via the skill installer rather than trusting an in-place update, and manually prune orphaned old files.
03Fixing the grilling skill
- If an agent keeps asking multiple questions at once despite an instruction not to, explain why one-at-a-time matters instead of just repeating the rule — reasoning lands better than a bare directive.
- Add an explicit confirmation gate ('do not enact the plan until I confirm shared understanding') if planning sessions keep sliding straight into implementation without a checkpoint.
- Distinguish facts (found by exploring the codebase) from decisions (made by the user) in planning prompts — conflating the two can cause a planning agent to start grilling itself instead of the user.
04The new five-stage main flow
- A repeatable coding workflow runs five stages in order: interview/plan, write the spec, break the spec into tickets, implement each ticket, then code-review it.
- Splitting a spec into individual tickets lets a large piece of work get spread across multiple agent sessions instead of forcing it into one marathon session.
05The implement skill
- An implementation step can be extremely short and still earn its place in a workflow — the value is in it existing as a named stage, not in its complexity.
- Sometimes a workflow step doesn't need to teach the agent anything new; it just needs to exist so people stop asking what the next step is.
06Code review: standards, spec, and Fowler's smells
- Run code review on two independent axes in parallel: does the diff match the repo's documented coding standards, and does it faithfully implement the originating spec?
- Borrowing a well-known vocabulary (Fowler's named code smells) works better than inventing new review heuristics, because the terms are already deep in a model's training.
- Keep a repo's coding standards in their own file, separate from the main agent-instructions file — code review is where they get used, not general context.
07Wayfinder: planning across sessions
- For any project too big for one agent session, store open questions as linked GitHub issues with blocking relationships, so no decision gets made before its prerequisite is resolved.
- Label each planning ticket by type — research, grilling, prototype, or task — so it's obvious at a glance whether it needs the user's input or can run unsupervised.
- This kind of typed-ticket planning generalizes past code: treat any big, foggy decision (even planning a course) as a sequence of small, session-sized tickets.
08Research and prototype skills
- A dedicated research skill should investigate against primary sources — official docs, source code, first-party APIs — not secondary write-ups of those sources.
- Before debating how something should look or behave, build a cheap, rough, concrete prototype to react to — it raises the fidelity of the discussion more than more discussion does.
09TDD becomes reference-only
- Refactoring doesn't belong in the same loop as red-green testing — folding it into code review instead keeps each implementation slice from getting overloaded.
- A TDD skill meant for an unsupervised agent should specify ordering only (red before green, one slice at a time), not a rigid confirm-each-test ritual that assumes a human is watching.
10Wrap-up: how to safely update your skills
- After a breaking rename across a shared library, the safe migration path is a clean reinstall of the specific pieces you want, then a manual pass to delete stale ones.
Terms worth knowing.
- Spec
- A specification document describing what to build — can be technical, non-technical, or both — replacing a file previously (and inaccurately) called a PRD.
- Ticket
- A single scoped unit of implementation work broken out from a spec; the renamed replacement for what used to be called an 'issue'.
- Grilling
- An interview-style planning conversation where an agent asks the user one question at a time to stress-test a plan before building starts, resolving open decisions branch by branch.
- Wayfinder
- A planning tool for projects too large for one agent session; it stores an evolving shared map of open questions as linked, typed GitHub issues that get resolved one at a time.
- Smart zone
- The point at which an agent session has accumulated enough context that output quality starts degrading, even before the context window is fully exhausted.
- AFK task
- A ticket type suited to work an agent can complete unsupervised while the user is away, such as research or routine configuration.
- HITL
- Human-in-the-loop — a ticket type that requires the user's direct input or decision before the agent can proceed.
- Code smell
- A named pattern in bad code — like duplicated logic or an overly primitive data type — used as a review heuristic rather than a hard rule.
Things they pointed at.
00:00toolMatt Pocock's skills repo (skills.sh)
01:45toolnpx skills add matt-pocock/skills
06:43bookMartin Fowler's Refactoring
14:04productAI Coding Crash Course (AIHero)
Lines you could clip.
00:51
“For a long time, I've wanted to rename it to to-spec because that's what we were creating. We were just creating a specification.”
03:16
“Do not enact the plan until I confirm we have reached a shared understanding.”
10:10
“A loose idea has arrived. Too big for one agent session and wrapped in fog.”
12:45
“So it's no longer a red green refactor loop. It's more just red green.”
Word for word.
Read-along
Don't just watch it. Burn it in.
See every word as it's spoken — crank it to 2× and still catch all of it. The same dual-channel trick behind Amazon's Kindle + Audible.
metaphoranalogy
00:00Hello, friends. First video in a while and that is because I've been working on version 1.1 of my skills repo.
00:06It has an astonishing amount of stuff in there. There is an entire new approach to grilling which probably deserves its own video but I'll try and squeeze it in here. There is a bunch of new changes to existing skills including a rename of two main flow skills.
00:22There is just really way too much for me to summarize in this intro, so you're just gonna have to watch the video to find out. We can see the p r is literally ready to merge now, so why not? Let's actually freaking merge this thing.
00:33And just like that, we have our version 1.1 ready to go. Let's start with the two that are probably gonna be most annoying for you and the most like, why did he do this?
00:43And there is this very specific reason that I did it, which is that two skills have been renamed. For instance, two PRD has now been renamed to two spec.
00:53And if we go up one level, then we go to two issues has been renamed to two tickets. The reason I've done this is that this has just been bugging me for a long time.
01:04The thing that we were creating into PRD wasn't actually a PRD. It was a spec. A product requirements document kind of describes more things about the actual product itself, whereas we were allowing things to leak into the PRD that weren't necessarily PRDs.
01:21So for a long time, I've wanted to rename it to to spec because that's what we were creating. We were just creating a specification. Specification is a much broader term that actually entails what we were building, a specification for a thing we want to build.
01:35That can be technical, it can be nontechnical, and it can blend the two. It doesn't really matter. When it came to two issues, two issues always felt like it was biased towards GitHub and Linear that used issues.
01:45But really, we want this to be tickets. You have a spec, and then underneath the spec, you have the tickets that are the journey that you, uh, take to actually enact the spec and create it. This has been annoying me for a long time, and finally, it no longer annoys me.
01:59It brings me joy. Now one irritating thing about this rename is that you will need to probably delete those skills and re add them. This means you'll need to run n p x skills add Matt Pocock skills.
02:10I'm pretty sure that this skills installer won't pick up the rename, so it won't try to update to PRD to turn it into to spec. You get what I mean. And so running this command is the safest way to grab all of these new skills because you get to just pick and choose which ones you want.
02:24And once you've done that, you should probably go through a pass through your skills folder and just check that no bad ones are still in there. So you wanna make sure that you're intentionally grabbing all the right skills.
02:34The next change is that I've fixed a couple of bugs that people were having with Grill Me and Grill With Docs. Both of them rely on this kind of central reference grilling skill that kind of show shows the LLM how to grill a person. I've sharpened up this line here saying asking multiple questions at once is bewildering.
02:52Even with this direction to ask questions one at a time, it was still occasionally just going, have multiple questions at once.
03:00So I've told it why we don't want multiple questions at once. We've also added a confirmation gate on the end. Do not enact the plan until I confirm we have reached a shared understanding.
03:11Lots of people on different models were reporting that the grilling session would just end and then it would just go straight into implementation. So this is just an extra little gate there. Finally, on some situations, it would just grill itself, which is very very odd.
03:25Not something I've noticed or seen in my personal thing, but I I can only get a small subset of how these skills are actually used. So I've basically tried to use a couple of leading words to indicate the difference between facts and decisions. So sometimes it was using the previous phrasing here by just exploring the code base and grilling itself.
03:44This was especially happening with Fable, actually. And so I've decided to make a distinction between facts. So facts that are things you find yourself by exploring the code base and decisions.
03:56So decisions are needed to be made by the user. So just a couple of sentences added, a couple of things changed around, and this has made it a lot more consistent, definitely getting a lot fewer complaints about those weird issues happening.
04:07The next thing to say is that I've added a couple of skills that really just take the process that was primarily a planning process, didn't really hold your hand into implementation, and turn it into a proper software development life cycle.
04:20So many folks ask me what is the flow? What is the main flow you're supposed to use with the skills? And first of all, I mean, this is it.
04:28We have number one, you're supposed to instead of using plan mode, you get an agent to grill you. And it uses these couple of docs to add a glossary to kind of understand you better as you go along and also add architectural decision records so you can capture the non obvious stuff. The stuff that goes in the Grofer docs then goes into a spec as we saw before.
04:49That spec kind of defines the destination where you're going. Then you turn that spec into individual tickets so you can spread the development of it out over multiple agent sessions. That's the purpose of two tickets.
05:02You then implement each one of those tickets with a implement skill. And the implement skill is very, very simple. It just looks like this.
05:09Implement the work described by the user in the spec or tickets. Use TDD where possible at pre agreed seams. That's a nice one.
05:17And run type checking regularly, single test files regularly, full test sweep once at the end. Once done, use code review to review the work, then commit your work to the current branch. I almost didn't make a skill for this because it's really simple.
05:30Right? It's just mostly relying on the agent's priors, its, you know, on the harness, kinda teaching it what to do.
05:36And I didn't honestly think we needed a skill here, but folks kept asking me what's the flow? What's the flow here? And so I figured just an implement skill make it nice and simple right at each stage of the process call this skill.
05:48So that means implement earns its place here because you know, okay, once we got two tickets, then we just got to implement each ticket in a separate coding session. Implement then itself calls code review. And code review, I graduated this out of in progress on version one.
06:03So it's been around for a little bit, but I have made some updates to it in this version two. The theory of the code review skill is that it reviews code on two axis. So it does a sub agent for each one of these.
06:15The first one is the standards axis. Does the code conform to this repo's documented coding standards? So if you've got a coding standards dot m d file somewhere in your repo, then it will read that and check against those.
06:28I generally think that coding standards belong outside of your agents dot m d file. They're supposed to be somewhere separate and the code review point is where they're most useful. And then once you've done the standards, you then go on to the spec.
06:41Does the code faithfully implement the originating issue or PRD or spec? They both run as parallel sub agents and it does a process here where it walks through each part. Now the thing that's cool and new about this skill is that I've been reading Martin Fowler's refactoring again.
06:57And what I decided to do is Martin Fowler names a bunch of different smells that the agent can identify in bad code. Refactoring such an old book, such a well cited book that these kind of smells are deep in the agent's priors.
07:13And so all you need to do is kinda invoke the idea of, okay, mysterious name or duplicated code or feature envy, data clumps, primitive obsession, repeated switches, divergent change, speculative generality, minutes and message change. You see what I mean? Like, these are all deep in the agent's kinda knowledge base and all we gotta do is just really describe them in a sentence.
07:31And what I found is that leads the word or leads the agent to repeat that word back to you and say, yes, I found some message chains. I need to remove them. I found a middleman situation.
07:41I need to fix that. So I tested this for a couple of weeks and it was outrageously useful.
07:46It was really really nice at improving the quality of my code and it's really cheap to add here. Just kind of like 10 lines. But let's go and talk about the one that I'm really really excited about which is a whole new change to the way that we kick off and shape specs.
08:03So the pre spec bit. In other words, it goes here where it may, in some situations, replace grill with docks. And it's called Wayfinder.
08:11I will make an entire post of entire video about Wayfinder, but suffice to say is that I would love for you in situations where you're thinking about using Grille with Docs instead to default to Wayfinder instead. What Wayfinder does is it's designed for situations where you have a ton of stuff that you want to plan, but and too big for one agent session.
08:33In other words, you're gonna blow out of the smart zone of the agent or you might even blow out of the context window of the agent. You need to split it into multiple parts in order to figure out where you're going. A loose idea has arrived.
08:44Too big for one agent session and . The way from here to the destination isn't visible yet. on the repo's issue tracker then works its tickets one at a time until the route is clear.
08:56These maps are saved in GitHub issues. For instance, this is one on the Sand Castle repo where we're doing a spike to think about maybe pulling in the AI SDK as a dependency.
09:06A big, big change. And so you can see there are no decisions that have been made so far. And all of the decisions that need to be made are saved in sub issues.
09:16And these sub issues have blocking relationships. So we can see that no decision can be made here before we make this key decision at the start. Each one of these decisions is scoped to be the size of an agent session.
09:29And we can see that they're labeled as different types here. So for instance, this one is labeled as a research task. So this is really an AFK task for the agent to go off, do some research, and then come back.
09:41This one I think is a research as well. This one is a research task, and this one is a grilling task. So this one needs a grilling session to be done here.
09:50Think these are all grillers. We can see these defined in the ticket types down here. So we have research, we have grilling, we also have prototype as well.
09:59So this is something I've been really advocating for recently is doing more prototyping before you get to a spec. The idea is you raise the fidelity of the discussion by making cheap, rough, concrete artifact to react to, an outline, rough take, stub, UI logic code via the prototype skill. We'll get to that in a minute.
10:16Links to the prototype as an asset. And it says use when how should it look or how should it behave is a key question. And this is essential for almost anything that touches front end code.
10:27So I would definitely be recommending using Wayfinder for anything that touches the front end. The final one here is just tasks. So config that needs to be set up, provisioning access, you know, moving data into the shape, you know, all the sort of boring stuff that doesn't need a grilling decision and can't really be automated by AI.
10:45What you end up with is after all of these tickets are closed, all of that information get saved onto the map with the original tickets as kind of primary sources for what was captured. And you can then take this map and just turn it into a spec in the regular way. What I found that instead of having the kind of anxiety of managing my session with Grill with Docs having to hand off, worry about the smart zone, with Wayfinder, it's kind of all managed for me.
11:10I just get to close a session, open up the next Wayfinder ticket. It's all saved in GitHub, it's collaborative. You can share it across your team.
11:17And once the map is done, once it's complete, you just go to to spec and you're good to go. To support the way finder skill, we have a new research skill, which is very small, very handy for when you just need to do a research session or it kind of influences the model in researching in the right way as well or at least the way that I like.
11:35Spins up a background agent to do the research so you keep working while it reads. Investigate the question against primary sources. Write the findings to a simple markdown file and save it where the repo already keeps such notes match the existing convention.
11:46So this is useful too if you need to do any research. You can just invoke the research skill and you're good to go. The next one, of course, is the prototype, which I've kind of shown off a little bit before.
11:56I don't think I've done a full video on it. This is now model invoked so that way finder can invoke it itself. And it essentially gives you a choice between logic or state.
12:06So it's either a logic prototype or a UI prototype, and they react quite differently. The final change is something that people have been asking for for a while, and I finally decided to pull the trigger on it, which is before in my TDD skill, it would recommend a set of steps for you to follow.
12:23And that was a little bit awkward sometimes. The steps were like, it would confirm what tests it wanted to write with you and then you would, you know, walk it through walk it through. And it didn't fit with most people's idea of how TDD should work, which is you should be able to pass an AFK agent the TDD skill and it should just work.
12:44And so this TDD skill is now reference material only. So it doesn't specify any particular steps apart from just the ordering which you should write tests in, so to do red green refactor. So it just says red before green, one slice at a time.
12:57And it also splits away our refactoring as as not part of the loop. So it's no longer a red green refactor loop.
13:05It's more just red green. I tend to think that putting the refactoring in the code review part is a lot more productive because then you don't overload the implementation.
13:15So that is all of the changes that have come in on the skills. It is a lot of changes. And if you're nervous about missing any of the updates, then I recommend that you clear out all of your skills and do n p x skills update and grab all of the new ones.
13:30If you've made updates to your skills in the meantime, then you can point your clanker at my repo and just say pull down all of the good new stuff, especially pointing at the release notes. The thing I think this release will be remembered for is to spec and to tickets changing because that is just a little bit of friction, but I think good friction because it names it properly.
13:48And I hope to be the start of you getting obsessed with Wayfinder. I'm using Wayfinder for literally everything, even non coding stuff. I've actually been planning my next course with Wayfinder and it's really really good.
13:59And in fact, why don't I just show you that course now? This is the AI coding crash course. This is gonna be different from the cohorts that I usually run.
14:08It's going to be much much cheaper and it's going to be self paced so you can purchase it anytime. You get help from the Discord kind of in the usual way, but it's not gonna be gated like a normal cohort. It is going to be the perfect intro for anyone who's looking to get into AI coding whether you are a developer or whether you are not a developer.
14:27So for senior engineers, it's gonna be a conversion course. For folks who are new to development, it's going to be the way that you can actually get productive using these crazy new tools. I've not announced the price yet.
14:37I am going to just be adding sign ups in here and it will be available once I finish filming it maybe in about August time, I think. But folks, thank you so much for watching.
14:47It's always a pleasure sharing these skills updates with you. It is really cool to see these just absolutely grow and grow. Everyone tells me I shouldn't show the star counts but it's up to like a 160 k stars now.
14:59There are 7,000,000 downloads on skills.sh. It is just bonkers. So thank you so much for enjoying the skills.
15:04I hope they are helping you ship more and ship more productively. And I will see you very soon.
The Hook
The bait, then the rug-pull.
Matt Pocock opens by merging the pull request live: version 1.1 of his widely-used Claude Code skills repo is ready to ship. What follows is a tour of a breaking rename, three quiet bug fixes to the planning skill, and one genuinely new tool — Wayfinder — built for decisions too big to make in a single agent session.
Named ideas worth stealing.
04:14list
The five-stage main flow
- grill-with-docs
- to-spec
- to-tickets
- implement
- code-review
The canonical sequence: interview the user (with glossary + architecture decision records), condense into a spec, split the spec into tickets, implement each ticket with TDD, then code-review on both standards and spec axes.
Steal forAny structured AI-coding workflow, including Joe's own Claude Code sessions on MCN/moderncreator.app work
11:40list
Wayfinder ticket types
- Research (AFK)
- Grilling (HITL)
- Prototype (HITL)
- Task (config/provisioning)
Every open question in a large, foggy project gets typed as one of four kinds of session-sized ticket, so it's immediately clear whether it needs the user or can run unsupervised.
Steal forScoping any multi-session build or planning effort, coding or not
06:12model
Code review's two axes
- Standards axis (repo coding-standards conformance)
- Spec axis (faithfulness to originating issue/spec)
Two parallel sub-agents review the same diff on separate criteria so their findings don't pollute each other's context, then get aggregated.
Steal forAny AI-assisted code review process
How they asked for the click.
VERBAL ASK
14:04product
“It is going to be the perfect intro for anyone who's looking to get into AI coding whether you are a developer or whether you are not a developer.”
Soft pitch woven into the sign-off, framed as a byproduct of using his own Wayfinder skill to plan the course; no hard link or price given yet, just a sign-up mention.
FROM THE DESCRIPTION
PRIMARY CTAWhere the creator wants you to go next.
OTHER LINKSAlso linked in the description.
Visual structure at a glance.
