mattpocock/skills: A complete AI Coding workflow, end-to-end

Introduction and overview

00:00Hello friends. It occurs to me that I've never actually put together a proper tutorial for my skills repo. At the time of recording, this repo is up to 162,000 stars. We have 7.5 million downloads, and I've never made a tutorial for it. I get questions all the time like, "What is the sequence I should use these skills in?

00:17How should I install them? How should I set them up?" So, this video is going to be a walkthrough of the main flow you use when you're using these skills. We're not going to look at the advanced stuff. We're not going to look at the new stuff really.

00:26We're just going to focus on the main flow, the stuff you need to get started. To walk you through this, I'm going to be using one of my work repos, which is the AI Hero CLI. This is the command line interface that drives a lot of my uh exercises that I use on my courses.

00:40I've never actually set up my skills to work with this repo, so now is a great chance. If you want to set up my skills on a brand new project, you just do this, except you do it in an empty directory. So, it works the same whether you're using a brownfield codebase or a greenfield codebase.

00:53I'm going to open

Installing the skills repo

00:54up the command line interface here and I'm going to type npx skills at latest add mapco/skills. This assumes a couple of things. It assumes that you've got NodeJS installed. This npx comes from NodeJS and it runs the skills.sh command line installer from Versel.

01:13What this basically does is it installs a GitHub repo of skills called map pog skills and it can walk through a few uh setup questions here. It first says it needs to install the following packages. Yes, that seems fine to me. And then it did a couple of things and we now have a long list of all the skills that we could install.

01:32It found 38 skills here, which is a lot. And you can see if I scroll up and down, they're in two groups. We've got the Matt PCO skills and then we've got other skills. So, the Matt PCO skills are the ones that I have blessed as the skills that I think are good enough to be public facing.

01:46The other ones are ones that I'm experimenting with right now and may delete in future. What I recommend you do is you go to the top here and you can kind of go up and down. It's kind of broken, I have to say. And if you press space here, and you should see that if you scroll up, okay, they're now all selected.

02:03You press space, and then you press return, and now uh you've selected all of the official skills. I'm not terribly happy with Versel's CLI here, so I may change it in future or maybe even just ship my own. But uh for now that's as good as it gets.

02:18One thing that is good is that it will set up your skills to work with any agent. So I use claude code, but you can go down here and sort of just select the ones that you want. I'm using space to select. I think by default if I zoom out a touch then it supports all of these universal ones up here.

02:35So cursor, codeex, client, etc. But anything that uses like clawude skills such as claude code then you need to set up yourself. So, I'm going to press return here, and it should now be configured to set up my skills for claw code. The installation scope defines where your skills are installed, whether they're installed just in the current directory or whether they're global.

02:54This will depend on what your team's conventions are. If you're working in a team, I would say that project skills are the right way to go. That way, everyone is using the same skill set on every project, and it means that you can contribute to the skills together and make those decisions together.

03:08But global is fine if you're just a solo developer working on your own stuff like I am. So I'm going to press return here. Install it in my home directory. And I'm going to choose sim link as the recommended way. The choice here is whether you copy it to the agents folder as well as the uh claude folder.

03:25And it's kind of not a nice way to do it. Sim link is just the nice easy way to do it. So I wouldn't even make a decision here. Just choose sim link. So it now gives you a summary of all the things that you're installing here. There seems to be an alert on socket about to spec.

03:38I'll take a look at that later. But yes, we can proceed with installation. And it's now installed all of the skills. This means then that I can run Claude inside here or whatever your agent is. And I'm going to create a new. So I'm just going to say hello to get out of this agents view here.

03:52Now depending on the harness you're using, this will show up in different ways. But on Claude Code, I can press forward slash. And I now see that I have a few skills available to me. I have grill me, grilling, wfinder, grill with docks, etc.

04:06Loads of stuff. Now the difference between my skills and lots of other skills repos that are out there is my skills are mostly user invoked. That means that if I run context here lot not many of my skills actually leech their way into the description and the descriptions I have are quite short and precise.

04:24So that means that even though we've downloaded all of my skills, the skills only take up 660 tokens here. So very very light in terms of context

Running setup and configuration

04:34load. So okay, we got the skills. Now what we have to do is we have to run setup map poclls and this will do a few things. My skills rely on some uh configuration inside the repository and this does a few things for you. The first thing is it means you need to use an issue tracker.

04:52We're going to be saving um specs. We're going to be saving tickets and we need to save them somewhere. You've got kind of an infinity of choices here. You can use GitHub, you can use local markdown, or you can literally use anything. The way that the skill works is that it looks at your local configuration.

05:09And so you can set it up for Jira, you can set it up for linear. And the way you do that is you just tell the agent what you want to set it up for, and it will go and set it up for it. I just want to emphasize that people ask me all the time, how do I make my skills work with Jira, work with beads, work with linear?

05:23It already does. All you need to do is just run setup map pco and just say set it up with Jira. Except I don't want to set it up with Jira. I'm just going to set it up with local markdown please. So that's fine by me. The next question to answer here is about triage labels.

05:38So there are a set of labels that the skill relies on to communicate information about the tickets that it produces. It's not really that important here. So I'm just going to accept the defaults. You can look at the docs on the triage skill if you want to learn more.

05:51So defaults is fine. The next one is about the domain documentation. So my skills like to have a little bit of docs, a context.md file and an ADR inside the repo. And it's basically asking if it's going to be a single context or a multicontext.

06:07I think single context is the way to go here. Multicontext is if you have a big monor repo and you need lots of different uh bounded contexts within it. But for 99% of people, single context is going to be fine. All right. So it's gone ahead and written a few things here.

06:25The first thing it's written is inside clawude.mmd. It's added a few little links here. So this is the new stuff. It's just linking to the issue tracker docs, linking to the triage labels and linking to the domain docs. And each of these are at uh docs agents domain issue tracker.

06:42So we can see here that it's going to save all of the issues and specs inside a scratch file. So with that, our setup for this repo is

Getting started with Ask Matt

06:52complete. And so you might be thinking, how do I get started? Well, before we get started, I'm going to show you one more really cool thing. You can, if you're following along, just stop the video now and use one skill. You can use the ask Matt skill.

07:03This ask Matt skill is essentially me as a skill. It knows everything that is needed about the skills repo and what you should do first. So we can say, ask Matt, how do I get started? I want to make some code changes here. What is the main flow I should use?

07:18I can now submit that and see what it says. By the way, I'm using Whisper Flow as my transcription. So, here we go. It's saying the main flow idea to ship. Since you have a codebase, start at the top of the main flow and walk down in it in one unbroken context window.

07:32So, it's very um kind of really telling you how to use your sessions as well. I really believe that being conscious about the context window that you're using, the tokens that you're using is essential to using AI. Well, it says you should start with grill with docs.

07:49It interviews you to sharpen the idea and because you're in a repo, it's stateful. It records what it learns in context.md and ADRs. This is where you turn I want to change X into a crisp defensible plan. Defensible is such an LLM phrase. Honestly, can you settle every open question just by talking?

08:03If a question needs a runnable answer, then you can use prototype, which I've done a video about on it. Bridged in and out of by handoff. If not, skip this. Once you've done the interviewing grill with docs, you can either go straight to the implement skill or if it needs multiple sessions to go through, then you can go to to spec and to tickets.

08:21Let me make

Main workflow explained

08:24this a little bit clearer for you. The default flow looks like this. You start with grill with docs and this interviews you based on the idea that you want to

Grill with docs interview session

08:31produce. For instance, if I clear out of ask Matt, uh, of course, I could go and ask follow-ups here, use it as a tutorial itself, but let me just show you. I'm going to say grill with docs. And I'm going to kick it off with an idea. I'm going to say I would like to remove most of the internal tooling on this CLI to make it just only public facing.

08:49There's a lot of croft here. I want to just take this repo down a notch. It really can be as vague as this. You don't need to do too much here. Grill with Docs is going to do the heavy lifting by asking you a bunch of follow-up questions. It's going and exploring a bunch of code here.

09:01And by the way, I'm using Claude Code. I'm using Opus 4.8 on medium effort. But you really don't have to use the same setup as me. these skills are being used by a bunch of different people, bunch of different harnesses, different models, different effort levels.

09:15And we can see it's already asked the first question here. So, it's gotten a clear map of the entire repo. It's looking at the internal namespace with 11 subcomands. So, this is what a grilling session looks like. You go through all of the questions until you feel or you and the agent feel that you've reached a shared understanding.

09:32I'm going to do that now and then I'll check in with you once I'm done. Okay, it didn't end up taking too long. We ended up with what, six questions. That's not very much for a grilling session. Usually mine end up being about sort of 20 questions depending on the size of it.

09:45But we've ended up with a decent plan. We're going to delete uh 10 command files, delete three tests, rewire shared modules. And all I did here was I just answered questions until it said, "Okay, we've walked the whole tree. We've reached a shared understanding.

10:00Let me lay out the plan." Notice here I wasn't using plan mode for this. I was actually in auto mode in claw code which is kind of like

Creating specs and tickets

10:08the default mode and you now have a fork in the road. If you think that this work is going to be big enough that it will need multiple agent sessions then you can skip numbers two and three here and go straight into implement. The way you would do that is you would just say uh forward slashimplement this.

10:24And in this case I do think that is what we should do. I've still got about um I think of my context window as kind of like ending or getting significantly dumber at around the 140k mark. I think of that as kind of like the smart zone of the LLM.

10:42If you go above 140K, you end up sort of with, you know, attention degradation. It ends up getting stupider, does weird hallucinations. So, I think of having like, okay, we've got 100K of budget here to remove 10 commands. That seems super easy.

10:55Definitely something, you know, we can definitely do that. So this is what I would usually do. I would just say implement and then I would leave it, let it run and it would finish the work. However, in the interest of showing you everything, I'm going to pretend that this work is going to take more than one session that I've maybe run out of context window in the current or run out of smart zone in the current window and I'm going to need to spread this out over multiple context windows.

11:16So I'm going to call to spec here instead. So instead of writing implement this, I'm going to say to spec here and that's it. What this is going to do is it's going to take all of the discussion that I've had, all of this 46.1K tokens, and it's going to compress it into a document that we can use later.

11:33This is where our issue tracker comes in. So, this issue tracker, we're just going to use local markdown files. And so, it's just going to spit out the spec into a local directory. This spec is going to be the destination that we're heading to over this multi- sprint.

11:47In other words, this is what we're going to end up with. This is the description of everything of how it's going to look at the end. And then the tickets is the description of how we're going to get there. Okay, we can see it's been uh written and published to the issue tracker.

12:00If I open this up, we can see it is in here. So, it's very nice and detailed. It's got a problem statement, a solution, a bunch of user stories, implementation decisions, testing decisions, a lot of stuff here. And this is going to be really useful because we'll be able to compare this at the end to make sure that our implementation matched the spec.

12:18So, now that we've got the spec, I'm going to go into the same session. Not going to change sessions here. And now I'm going to say two tickets. And this is where it will basically try to turn the spec into an implementation plan. Each one of these tickets is supposed to just be the size of a single context window or a single smart zone.

12:37And if we look here, we can see that it's kind of given us three tickets here. So three slices. I think that these three slices are a little bit much. I actually think it can be done in one slice. do it in one slice instead. And so it's now put this in a file.

12:55So it's put the ticket in tickets.md. Now, this is quite a bad example because it's kind of copying the stuff that's in our product requirements document. So let me show you an actual real example. Here is a spec that I implemented a couple of days ago to remove a bunch of stuff from a repo.

13:08So I'm on a real removal spree recently. And you can see that this is the spec and underneath it, it has 11 subissues. So 11 tickets underneath it and each of these tickets, so this is a very detailed spec. Each of these tickets is a single context window session.

13:26So if we click into here, we can see it's just pretty short. Most of the acceptance criteria is already in the main spec. And so this one is just literally what do you build in this session. So that's number session one, then session two, then session three.

13:42You can see that how this breaks down a huge chunk of work into manageable pieces that the agent can then go and do. However, here we are

Implementation and code review

13:52left with a single manageable piece. So what I'm going to do is I'm going to clear the context here. Now we have everything we need so that we can just run a bunch of agents to tackle this problem. So I can clear the context and then I'm just going to say at tickets here and before that I'll say forward slashimplement this.

14:11So now because we have the spec that decides where we're going and the tickets that decide how we get there. The agent has everything it needs and we're ready to implement. Now when you're doing this by hand, the idea is that you then implement each ticket one by one.

14:26So you don't say do every single ticket. You say okay we go and implement then we see if we've hit the smart zone. If we haven't maybe we can squeeze in one more ticket here. But usually I would say you clear in between every single ticket.

14:40Then once you've done all of the implementation, you've got your full thing all implemented, then you can go and code review and do the final check against the spec. We can see here it really was a very small piece of work actually. It's only 42.7K and it's now about to as part of the implement run the code review.

14:58As part of the implement script, it goes and runs all the type check, runs the build. Um, it's doing even more verification, checking AI hero internal help, shows only edit commit, and it's gone and loaded the code review skill. This reviews based on two axes.

15:13First, it compares the work done against the original spec. This is really useful when you've done a huge chunk of work and the agent might have forgotten things in tickets or the tickets might have been unspecified. Doing a final pass means you actually nail everything.

15:30And then it also checks against the standards documentation that you've got in your own repo. In this repo, we don't really have any coding standards documented anywhere. But if it doesn't detect any, then it uses some classic ones kind of from Martin Fowler.

15:41So it looks at code smells, tries to figure out if there's any bad stuff. Doing these in sub agents is really important because if you do it in the main agent, it means that the main agent already has written the code. And agents are often really bad at editing code or improving code they've just written because they've wrote it.

16:00So they just think, "Okay, that's fantastic. That's fine." Whereas if you spawn some agents, then they're going to have a clear context window and they're going to do a much better job reviewing the code. Okay, we can see that uh both came back.

16:10So cross checked every acceptance criterion against the spec. It checked everything against the standards. And cool, we're good to go. And it's now committed against the current branch. Beautiful.

Workflow recap and newsletter

16:23So that is our flow complete. We aligned before we got started. We created some spec and tickets in order to make sure it worked over multiple sessions. We then implemented it. And the implement skill itself used the code review. This is the main flow that all of my work runs through.

16:38And the stuff that isn't in the main flow is stuff that I'm experimenting with, stuff that I'm improving. I'm always trying to get this loop faster, better, easier to run. And for that, if you're interested in that, then you should check out my newsletter for these skills.

16:51This YouTube channel is a great place to be for subscribing to understanding more about the skills, but really the good stuff is on the newsletter. If you want on the day updates when I ship new skills, when I add updates to um kind of that you need to keep updated with, then this is the place to be.

17:06But thank you so much for watching. Hopefully this tutorial gives you an idea on how to get set up with the skills and what the main flow is supposed to be. Thanks for watching. Happy skilling and I will see you very