New Skills! v1.1 brings /wayfinder, /research, /implement, /to-spec, /to-tickets

Hello friends. First video in a while, and that is because I've been working on version 1.1 of my skills repo. It 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

in here. There is a bunch of new changes to existing skills, including a rename of two main flow skills. There is just really way too much for me to summarize in this intro, so you're just going to

have to watch the video to find out. We

can see the PR is literally ready to merge now. So, why not? Let's actually

merge now. So, why not? Let's actually

freaking merge this thing. And just like that, we have our version 1.1 ready to go. Let's start with the two that are

go. Let's start with the two that are probably going to be most annoying for you, and the most like, why did he do this? And there is a very specific

this? And there is a 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. And if we go up one level, then we

spec. And 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

tickets. The reason I've done this is that this has just been bugging me for a long time. The thing that we were

long time. The thing that we were creating in two PRD wasn't actually a PRD. It was a spec. A product

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. So, for a long time

necessarily PRDs. So, for a long time I've wanted to rename it to two spec, cuz 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.

for a thing we want to build. That can

be technical, it can be non-technical, 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 use issues, but 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 take to actually enact the spec and create it. This has been annoying me for

create it. This has been annoying me for a long time, and finally it no longer annoys me. It brings me joy. Now, one

annoys me. It 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 NPX skills add Map Po skills. I'm pretty sure that this

skills. I'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

mean. And so, running this command is the safest way to grab all of these new skills cuz you get to just pick and choose which ones you want. And 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 want to make sure that you're intentionally grabbing all the right skills. The 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. Even

with this direction to ask questions one at a time, it was still occasionally just going to have multiple questions at once. So,

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've reached a shared understanding. Lots 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. Not something I've noticed or seen

odd. Not 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

and decisions. So, sometimes it was using the previous phrasing here by just exploring the code base and grilling itself. This was especially happening

itself. This 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. So, decisions are needed to

decisions. So, 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. The next thing to say

issues happening. The 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.

So, many folks ask me, "What is the flow? What is the main flow you're

flow? What is the main flow you're supposed to use with the skills?" And

first of all, I mean, this is it. We

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

non-obvious stuff. The stuff that goes in the growth for docs then goes into a spec, as we saw before. That spec kind of defines the destination, where you're

going. Then, you turn that spec into

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 to

agent sessions. That's the purpose of to tickets. You then implement each one of

tickets. You then implement each one of those tickets with a implement skill.

And the implement skill is very, very simple. It just looks like this.

simple. It just looks like this.

Implement the work described by the user in the spec or tickets. Use TDD where possible at pre-agreed seams. That's a nice one. And run type checking

nice one. And run type checking regularly, single test files regularly, and full test suite once at the end.

Once done, use code review to review the work, and then commit your work to the current branch. I almost didn't make a

current branch. I almost didn't make a skill for this because it's really simple, right? It's just mostly relying

simple, right? It's just mostly relying on the agent's priors, on its, you know, on the harness, kind of teaching it what to do. And I didn't honestly think we

to do. And 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

simple, right? At each stage of the process, call this skill. So, 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. So, 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

two. The theory of the code review skill is that it reviews code on two axes. So,

it does a sub agent for each one of these. The first one is the standards

these. The first one is the standards axis. Does the code conform to this

axis. Does the code conform to this repo's documented coding standards? So,

if you've got a coding standards.md file

somewhere in your repo, then it will read that and check against those. I

generally think that coding standards belong outside of your agents.md 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. Does the code faithfully implement the originating issue or PR 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

part. Now, the thing that's cool and new about this skill is that I've been reading Martin Fowler's refactoring again. And what I decided to do is

again. And what I decided to do is Martin Fowler names a bunch of different smells that the agent can identify in bad code. Refactoring is such an old

bad code. Refactoring is such an old book, such a well-cited book, that these uh kind of smells are deep in the agent's priors. And so, all you need to

agent's priors. And so, all you need to do is kind of invoke the idea Okay, mysterious name or duplicated code or feature envy, data clumps, primitive obsession, repeated switches, divergent change, speculative generality, message

chains. You see what I mean? Like, these

chains. You see what I mean? Like, these

are all deep in the agent's kind of knowledge base, and all we got to do is just really describe them in a sentence.

And 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

message chains. I need to remove them. I

found a middle man situation. I need to uh fix that." So, I tested this for a couple of weeks and it was outrageously useful. It was really, really nice at

useful. It 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. So, the pre-spec bit. In

shape specs. So, the pre-spec bit. In

other words, it goes here where it may, in some situations, replace Grill with Docs. And it's called Wayfinder. I will

Docs. And it's called Wayfinder. I will

make an entire post uh entire video about Wayfinder, but uh suffice to say is that I would love for you, in situations where you're thinking about using Grill 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. In other words, you're going to 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, too big

going. A loose idea has arrived, too big for one agent session and wrapped in fog. The way from here to the

fog. The way from here to the destination isn't visible yet. This

skill charts the way as a shared map on the repo's issue tracker, then works its tickets one at a time until the route is clear. These maps are saved in GitHub

clear. These maps are saved in GitHub issues. For instance, this is one on the

issues. For instance, this is one on the Sandcastle repo where we're doing a spike to think about maybe pulling in the AI SDK as a dependency, a big, big change. And so, you can see there are no

change. And so, you can see there are no decisions that have um been made so far and all of the decisions that need to be made are saved in sub-issues. And 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. And we can see that

agent session. And 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. This

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. I

think these are all grillers. We can see these defined in the ticket types down here. So, we have research, we have

here. So, we have research, we have grilling, we also have prototype as well. So, this is something I've been

well. So, 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

spec. The idea is you raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to. An

outline, rough tech stub, UI logic code via the prototype skill. We'll get to that in a minute. Links 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. So, I would definitely

front-end code. So, 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, um 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. What you end up with is after all

by AI. What you end up with is after all of these tickets are closed, all of that information gets 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. I just get to close a session, open

me. I just get to close a session, open up the next Wayfinder ticket. It's all

saved in GitHub, so it's collaborative.

You can share it across your team. And

once the map is done, once it's complete, you just go to to spec, and you're good to go. To support the Wayfinder 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.

Spins up a background agent to do the research so you keep working while it reads. Investigate the question against

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. So 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. I don't think I've done a full video on it. This is now modeling, folks, so that Wayfinder can invoke it itself, and it essentially

gives you a choice between logic or state. So it's either a logic prototype

state. So it's either a logic prototype or a UI prototype, and they react quite differently. The final change is

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, and that was a little bit awkward sometimes. The steps were like,

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.

And so this TDD skill is now reference material only. So it doesn't specify any

material only. So it doesn't specify any particular steps apart from just the order in which you should write tests in, so to do red green refactor. So it's

just says red before green, one slice at a time, and it also splits away refactoring as as not part of the loop.

So it's no longer a red green refactor loop, it'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. So that is

all of the changes that have come in on the skills. It is a lot of changes, and

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 NPX skills update and grab all of the new ones. If you've made updates to your

ones. If you've made updates to your skills in the meantime, then you can just 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 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 cuz it names it properly. And I hope to be the start

it properly. And 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. In fact, why don't I just show you

good. In fact, why don't I just show you that course now? This is the AI coding crash course. This is going to be

crash course. This is going to be different from the cohorts that I usually run. It's going to be much, much

usually run. It'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 going to 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. So, for senior engineers, it's going to be a conversion course. For folks who are new to

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 a price yet. I am going to just be adding sign-ups in here and it'll be available once I finish filming it, maybe in about August time, I think. But folks, thank you so much for watching. It's always a

pleasure sharing these skills updates with you. It is really cool to see the

with you. It is really cool to see the usage just absolutely grow and grow.

Everyone tells me I shouldn't show the star counts, but it's up to like 160K stars now. Uh 7 million downloads on

stars now. Uh 7 million downloads on skills.sh. It is just bonkers. So, thank

skills.sh. It is just bonkers. So, thank

you so much for enjoying the skills. I

hope they are helping you ship more and ship more productively and I'll see you very soon.