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

v1.1 Is Ready!

00:00Hello 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.

00:14There 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.

00:29So, why not? Let's actually freaking merge this thing. And just like that, we have our version 1.1 ready to

to-spec, /to-tickets

00:37go. 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 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 uh 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. The thing that we were creating into PRD wasn't actually a PRD. It was a spec.

01:08A 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 I've wanted to rename it to to spec because that's what we were creating.

01:25We 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. That can be technical. It can be non-technical and it can blend the two. It doesn't really matter.

01:39When 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 uh take to actually enact the spec and create it.

01:56This has been annoying me for a long time and finally it no longer annoys me. It brings me joy. Now one irritating thing about this rename is that you will need to probably delete those skills and read them. This means you'll need to run npx skills add mapco skills.

02:07I'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 tosp spec. You get what I 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.

02:22And once you've done that, you should probably go through a pass through your skills folder and just check that uh no bad ones are still in there. So you want to make sure that you're intentionally grabbing all the right skills. The next

Grilling skill improvements

02:35change is that I've fixed a couple of bugs that people were having with grill me and grill with dogs. 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 d direction to ask questions one at a time.

02:54It was still occasionally just going have multiple questions at once. So I've told it why we don't want uh 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.

03:09Lots 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.

03:38So sometimes it was using the previous phrasing here by just exploring the codebase and grilling 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 codebase 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

Complete development lifecycle flow

04:06issues 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.

04:19So, 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. 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 glossery to kind of understand you better as you go along and also add architectural decision records so you can capture the non-obvious stuff.

04:42The stuff that goes in the grill 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 individual tickets so you can spread the development of it out over multiple agent sessions.

04:58That's the purpose of to 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. Implement the work described by the user in the spec or tickets. Use TDD where possible at pre-agreed seams.

05:16That's a nice one. And run type checking regularly. Single test files regularly. Full test sweep 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 skill for this because it's really simple, right?

05:30It's just mostly relying on the agents prior on its, you know, on the harness kind of teaching it what 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?

05:44At 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.

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 axes. So it does a sub agent for each one of these. The first one is the standards axis.

06:16Does 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.

06:33They'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 PRD

Code review with refactoring smells

06:45or 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. And what I decided to do is Martin Fowler names a bunch of different smells that the agent can identify in bad code.

07:03Refactoring is such an old book, such a well-sighted book that these uh kind of smells are deep in the agent's prior. And so all you need to do is kind of invoke the idea of 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 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

07:36yes I found some message chains I need to remove them I found a middleman 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 improving the quality of my code and it's really cheap to add here.

07:51Just kind of like 10 lines. But,

Introducing Wayfinder for large plans

07:53let'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 other words, it goes here where it may in some situations replace Grill with Docs and it's called Wayfinder.

08:09I will make an entire post, entire video about WFinder, 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 Wfinder 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:31In 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 for one agent session and wrapped in fog.

08:45The 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 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:04A big big 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.

09:24Each one of these decisions is scoped to be the size of an 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.

09:39This 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.

09:53So, we have research, we have grilling, we also have prototype as 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 of the discussion by making a cheap rough concrete artifact to react to an outline rough take UI logic code via the prototype skill.

10:14We'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 be recommending using Wfinder for anything that touches the front end.

10:30The 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.

10:44What 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.

10:58What I've 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 up the next Wayfinder ticket.

11:12It'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

Supporting skills: research and prototype

11:21you'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.

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:45So 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.

11:57This is now model invoked so that Wayfinder can invoke itself and it essentially gives you a choice between logic or state. So, it's either a logic prototype or a UI prototype, and they react quite

TDD skill updates

12:12differently. 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.

12:23the 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 uh 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 particular steps apart from just the order in 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:56And it also splits away uh 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.

13:14So that is

Migration guide and closing thoughts

13:17all 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 npx skills update and grab all of the new ones.

13:30If 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 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 and I hope to be the start of you getting obsessed with Wfinder.

13:51I'm using Wayfinder for literally everything, even non-coding stuff. I've actually been planning my next course with Wfinder and it's really, really good. And in fact, why

AI Coding Crash Course announcement

14:00don't I just show you that course now? This is the AI coding crash course. This is going to be different from the cohorts that I usually run. It's going to be much much cheaper and it's going to be self-paced so you can purchase it anytime.

14:12You 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.

14:25So for senior engineers, it's going to 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 a price yet. I am going to just be adding signups in here and it will be available once I finish filming it.

14:42Maybe in about uh 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 usage just absolutely grow and grow. Everyone tells me I shouldn't show the star count, but it's up to like 160k stars now.

14:56There are 7 million downloads on 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 will see you very