Source: mattpocock/skills · Maintainer: community: Matt Pocock · License: MIT · Checked: 24 October 2026
What is the wayfinder skill?
The wayfinder skill plans an effort too big for one agent session, such as a greenfield project or a large feature, by charting a map of decision tickets on your issue tracker and resolving them one session at a time. It produces decisions, not code, until nothing is left to decide before someone builds the thing.
It comes from mattpocock/skills, which Matt Pocock describes in the README as "My agent skills that I use every day to do real engineering - not vibe coding." The skill's description reads: "Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear."
The repo's router calls it "the most cognitively demanding flow here." As of 24 October 2026, its skills.sh page listed about 718,000 installs (snapshot, 24 October 2026).
What does it do?
The SKILL.md builds on a small vocabulary:
- Destination. What the end of the map looks like: a spec to hand off, a decision to lock, or a change made in place such as a data migration. You name it first, because it fixes the scope.
- The map. One issue labelled
wayfinder:map. It is "an index, not a store": it lists decisions in one line each and links the tickets that hold the detail. Its sections are Destination, Notes, Decisions so far, Not yet specified and Out of scope. - Decision tickets. Child issues of the map, each a question sized to one 100K token agent session.
- Fog of war. Questions you can tell are coming but can't phrase sharply yet. They sit in Not yet specified until a resolved ticket makes them specifiable. The test is "whether you can state the question precisely now, not whether you can answer it now."
- Frontier. Open, unblocked, unclaimed tickets. A session claims one by assigning it before doing any work, and blocking uses the tracker's native dependency links.
Every ticket carries one of four type labels:
| Type | Mode | Use when | Resolved by |
|---|---|---|---|
grilling |
Human in the loop | The default: talk it through | grilling and domain-modeling skills |
prototype |
Human in the loop | How it should look or behave | prototype skill, linked as an asset |
research |
Agent alone | A fact outside the working directory blocks a decision | A subagent running the research skill |
task |
Either | Manual work blocks a decision, like provisioning access | The agent, or a checklist for you |
The rule for human-in-the-loop tickets is strict: "a grilling agent that answers its own questions has broken this."
How do you install it?
The README gives a plugin route and an editable-files route, and says to pick one per agent so you don't get every skill twice.
Claude Code plugin (whole set, updates itself). The collection is listed in Anthropic's official plugin marketplace:
claude plugin install mattpocock-skills@claude-plugins-official
Plugin skills are namespaced, so it appears as /mattpocock-skills:wayfinder. This is the simplest route, since wayfinder calls four other skills.
Codex plugin. From the README:
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
Editable files with the skills CLI. The command on skills.sh:
npx skills add https://github.com/mattpocock/skills --skill wayfinder
The SKILL.md calls grilling, domain-modeling, prototype and research, and tells you to run /setup-matt-pocock-skills if no tracker is set. The skills CLI accepts --skill more than once:
npx skills add https://github.com/mattpocock/skills --skill wayfinder --skill grilling --skill domain-modeling --skill prototype --skill research --skill setup-matt-pocock-skills
Add -g for all projects. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills. Setup writes a "Wayfinding operations" section describing how your tracker expresses the map, child tickets and blocking; see the setup skill page.
How do you use it?
There are two modes, and in both the skill says "never resolve more than one ticket per session," except research tickets.
Chart the map. Invoke it with a loose idea. It grills you to name the destination, grills again breadth-first to map the frontier, creates the map issue and the tickets it can specify, wires the blocking edges in a second pass, and starts research subagents in parallel. Charting is one session's work. If the breadth-first grill finds no fog, it stops and asks how you want to proceed.
Work through the map. Invoke it with the map's URL or number, plus a ticket if you want a specific one. It loads the map, claims the next frontier ticket, resolves it by type, posts the answer as a resolution comment, closes the ticket and adds a line to Decisions so far. Then it graduates any fog the answer cleared into new tickets.
Example prompts (suggestions, not quotes from the repo):
/wayfinder We want to move our monolith's billing into a separate service. The destination is a spec we can hand to the team./wayfinder https://github.com/<owner>/<repo>/issues/310/wayfinder Work the map in issue 310, ticket "Which queue do we use for invoice events?"/wayfinder Something changed: we now have to support EU data residency. Update the map and the affected tickets.
The skill is user-invoked: disable-model-invocation: true means, per the Claude Code skills docs, "Claude can't invoke the skill on its own."
Wayfinder or grill-with-docs?
The repo's docs for wayfinder call this "by far the most-asked wayfinder question," and the answer is session count.
| You have | Run |
|---|---|
| A well-scoped feature you can settle in one sitting | grill-with-docs, or grill-me without a codebase |
| A project spanning many sessions, route still unclear | /wayfinder |
| A thread where the deciding is already done | to-spec |
| A cleared wayfinder map | to-spec on the map issue, then to-tickets and implement |
Greenfield is not a requirement. The docs say people use it on legacy codebases too, where much of the fog is "what is already true here."
Tips and limits
From the repo's docs, not from testing:
- Scope the destination tightly. One user charted 27 tickets and found the later ones no longer made sense by the thirteenth. Maps scoped to one epic behave better than "implement V1." The docs call wayfinder "prototypemaxxing", not "planmaxxing."
- Watch for code. The plan-only default can be overridden in the map's Notes, which the agent writes. Read the Notes on maps you didn't chart.
- Make prototype choices yourself. One user saw an agent build three UI variations, pick one and close the ticket.
- Parallel grilling repeats questions. Two sessions share no context, so one ticket at a time is the safer default.
- The grilling is heavy. The docs call long questions "the sharpest open complaint." A lower reasoning effort or a plain-language rule in your
CLAUDE.mdcan help. - Public trackers fill up. Local markdown keeps planning tickets off a public tracker, but puts them in your repo.
As of 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub and Socket, and Warn from Snyk (medium risk, audited 7 October 2026). Snyk's finding is third-party content exposure: the skill reads issues and tickets that outsiders may have written. If people outside your team can file issues, read the map's tickets before a run. The skill runs no scripts; it creates and edits issues and pushes research/<name> branches. It is MIT licensed.
Save it in your Kipt library
In Kipt, open Skills and paste the mattpocock/skills repo link into the import box. Kipt shows a list of the repo's skills, so you can take wayfinder with grilling, domain-modeling, prototype and research. Your copies live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Matt Pocock or mattpocock/skills.
Similar skills
- Grill with docs skill: single-session planning, the cheaper choice when the work fits.
- To-spec skill: where a cleared map goes next.
- Prototype skill: resolves wayfinder's prototype tickets.
- Grilling skill: the interview behind every grilling ticket.
- Writing plans skill: Superpowers' skill for turning a spec into a task-by-task implementation plan.