Guide · Agent skill
How to use the Wayfinder Planning Map agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Wayfinder is an agent skill for planning work that is too big for one AI coding session and where the route forward is still unclear. It has the agent set up a shared map of decision tickets on your repo's issue tracker, then resolve those tickets one at a time until the way to the destination is clear. This guide explains what the skill does, how to install it, how to ask for it, and what it needs and touches, so you can decide whether it fits your work.
Wayfinder Planning Mapmattpocock/skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the wayfinder ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one repo. Alternatively, upload it in the Claude apps under Settings, then Capabilities, then Skills.
- 2Set up your issue tracker. Make sure the repo has an issue tracker with native blocking. If none is configured, run /setup-matt-pocock-skills.
- 3Describe the effort and destination. Ask the agent to use the wayfinder skill, and state the large, unclear effort and what finished planning should look like.
- 4Let the agent chart the map. The agent names the destination and creates the map issue labelled wayfinder:map, with child tickets for the open questions.
- 5Resolve tickets one at a time. Work the frontier, taking part in grilling and prototype tickets. Each resolved ticket adds a gist and a link to the map's decisions list.
- 6Stop when the route is clear. The map is done when nothing is left to decide before someone does the work. Hand the resulting spec or decisions to whoever builds it.
What the wayfinder skill makes the agent do
Wayfinder is for efforts that are too large for one agent session and whose path is not yet visible. The agent first names the destination, such as a spec to hand off, a decision to lock before planning, or a change made in place. It then charts the route as a map on the repo's issue tracker and works through the map's decision tickets, recording each answer so later tickets build on it.
The skill is planning by default. Each ticket resolves a decision rather than building a slice of the work, and the map is done when nothing is left to decide. The goal is a clear route to the destination, not the finished thing.
- Map: a single issue labelled wayfinder:map that lists the destination, notes, decisions so far, and sections for unspecified work and out-of-scope work.
- Tickets: child issues of the map, each with a wayfinder:research, wayfinder:prototype, wayfinder:grilling or wayfinder:task label.
- Frontier: the open, unblocked, unclaimed tickets, which are the edge of what is known.
- Ticket types: research (AFK) reads outside sources, prototype (HITL) makes a rough artifact to react to, grilling (HITL) is a conversation with you, and task (HITL or AFK) is manual work needed before a decision.
Install the wayfinder skill in Claude
You can install the skill for yourself across projects, for a single project, or through the Claude apps. The source for this skill is the wayfinder folder in the mattpocock/skills repository under skills/engineering, which is MIT licensed.
To install from the ZIP, download it from this page and unzip it into one of the locations below. Claude Code loads skills from the .claude/skills folder, so the folder that contains SKILL.md should end up inside it.
- Personal install: unzip into ~/.claude/skills/ to make the skill available in every project on your machine.
- Project install: unzip into the .claude/skills/ folder of a specific project to share it with that repo.
- Claude apps: go to Settings, then Capabilities, then Skills, and upload the skill there.
Set up an issue tracker before you start
The skill expects an issue tracker for the repo, ideally one with native blocking relationships between issues. Blocking is what lets the tracker show which tickets can be taken right now. If the repo has no tracker configured, run the companion setup skill /setup-matt-pocock-skills first.
If no tracker is available, the skill falls back to local markdown files. That works, but you lose the visible, shared plan that a tracker gives you.
- Use an issue tracker with native blocking if you can, so the frontier shows up in the tracker's own interface.
- Run /setup-matt-pocock-skills when no tracker has been provided.
- Expect the local-markdown fallback to be less useful for teams.
/setup-matt-pocock-skillsTrigger the skill with a natural request
The skill's frontmatter sets disable-model-invocation to true, so the agent does not pick it up on its own. Name it in your request so the agent loads it. Describe the large, unclear effort and the outcome you want, and say that you want the decisions settled before code is written.
Good requests state the destination. For example, you might ask the agent to use the wayfinder skill to map out how to migrate your data layer to the new storage format and to stop when the route is clear. A vague request such as build the feature usually leads to a planning map that is not what you wanted, so be explicit about wanting decisions rather than delivery.
- Name the skill: ask the agent to use the wayfinder skill for the effort.
- State the destination: say what finished planning looks like, such as a spec or a locked decision.
- Say whether you want code: the skill stops at decisions unless the effort's Notes say otherwise.
Work through the map with the agent
Each session loads the map, orients to the destination, and claims a ticket by assigning it to you before doing any work. Assignment is the claim, so other sessions skip that ticket. Once the ticket is resolved, the answer is recorded and linked from the issue, and the map's decisions list gets a one-line gist that links to the ticket.
Keep an eye on the frontier in your tracker. Human-in-the-loop tickets need you to take part in the conversation, because the agent is not meant to answer on your behalf.
- Let the agent claim a ticket before it starts work, so you can see what is in progress.
- Answer grilling and prototype tickets directly; these resolve only through a live exchange with you.
- Check the Not yet specified section of the map to see the suspected questions still ahead.
What the skill needs and what it touches
Wayfinder needs an issue tracker for the repo, or accepts the local-markdown fallback. It also needs access to the Skill tool, because the agent calls the research, prototype, grilling and domain-modeling skills while it works. The skill does not run scripts, but it does use the network, for example when a research ticket reads documentation or third-party APIs.
Because it uses the network and works through your tracker, review what the agent reads and writes on the issue tracker before you trust a long map to it.
- Runs scripts: no.
- Uses network: yes, mainly for research tickets that read outside documentation or APIs.
- Requires Skill tool access so the agent can call the supporting skills.
- Writes to your issue tracker: the map, its child tickets, labels, assignments and blocking links.
What people use it for
- Planning a large feature so the open decisions are settled before any code is written.
- Mapping a data-structure or library migration, with research tickets on the third-party APIs involved.
- Settling a spec through grilling and domain-modeling conversations before handing it off.
- Laying out a multi-part course or content effort as a shared plan of open questions.
Frequently asked questions
How do I install the wayfinder skill?
Download the wayfinder ZIP from this page and unzip it into ~/.claude/skills/ to use it everywhere, or into a project's .claude/skills/ folder to use it in one repo. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills.
Is the wayfinder skill free to use?
The skill is published under the MIT licence in the mattpocock/skills repository. This guide does not cover pricing for Claude or any issue tracker, so check those services directly.
What do I need to run wayfinder?
You need an issue tracker for the repo, ideally with native blocking relationships. The agent also needs access to the Skill tool so it can call the research, prototype, grilling and domain-modeling skills.
Does wayfinder write code?
By default it does not. It plans by resolving decisions, and it stops when the way is clear, unless the effort's Notes tell the agent to carry execution into the map.
What if I don't have an issue tracker?
The skill falls back to local markdown files. You can still use it, but you lose the shared, visible plan that a tracker provides.
Why won't the agent use wayfinder on its own?
The skill's frontmatter sets disable-model-invocation to true. Name the wayfinder skill in your request so the agent loads it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Wayfinder suits developers and teams who face a large effort with unclear decisions and want those decisions settled, visibly and in order, before building starts. If your task fits in one session, or you simply want the agent to build the feature, pick a more direct workflow instead.
Download the skill