trailhead charts a large project as a shared map on GitHub Issues, then works its tickets one at a time until the way to the destination is clear. This skill is the entry point: bare /trailhead runs smart entry (detect the repo state and propose the next move); a verb runs that verb's engine. Everything lives on the Issues; the repo holds code only.
Load first, in order
Before doing anything, load <skill base>/../_shared/load-first.md and follow it: the shared-core load contract (the six core files, in order, then the effective config). <skill base> is this skill's base directory (Claude Code prints it as Base directory for this skill: when the skill loads; on another host, the directory holding this SKILL.md): resolve the path to an absolute path and open it with the Read tool on that absolute path. Never cd into a skills directory and never read a relative path from the shell (a cd compound followed by a read is denied by the search guard). The same rule covers every later ../_shared/... or references/... path in this skill: resolve it against the base directory to an absolute path before reading. _shared/ is a sibling of this cluster's own directory (at ../_shared/), never a child of it; its absence from a listing of the cluster dir is expected, not a missing core.
Routing: verb to engine
The first word of the arguments is the verb; the rest is the text or a ticket number. /trailhead <verb> and /trailhead:<verb> are equivalent.
- No verb to smart entry (below): this skill handles it directly.
- A verb to hand off to the skill that owns it, passing the whole argument string. The skill-split migration (map #53) lands the cluster skills one at a time. The chart cluster is built (#59):
new, adopt, ticket, inbox, and grill route to the trailhead-chart skill (call the Skill tool with skill name trailhead-chart and arguments <verb> <rest>). The work cluster is built (#60): work, quick, pause, resume, split, and auto route to the trailhead-work skill (call the Skill tool with skill name trailhead-work and arguments <verb> <rest>). The view cluster is built (#61): map, dashboard, and whiteboard route to the trailhead-view skill (call the Skill tool with skill name trailhead-view and arguments <verb> <rest>). The capture cluster is built (#62): bug, todo, idea, seed, and note route to the trailhead-capture skill (call the Skill tool with skill name trailhead-capture and arguments <verb> <rest>). The manage cluster is built (#63): config, update, prune, and audit route to the trailhead-manage skill (call the Skill tool with skill name trailhead-manage and arguments <verb> <rest>). The panel verb routes to no skill: it is answered by the trailhead mod on Claude Code 2.1.287+ (/trailhead:panel opens or closes the live map panel), and where no mod answers, say in one line that the panel is not available in this session. Then carry out the target skill's instructions.
- Unrecognised verb to treat the whole string as
idea (route to trailhead-capture as idea <text>).
The namespaced /trailhead:<verb> commands reach their target skill directly through their own command wrapper; this routing table only covers the bare /trailhead <verb> form.
Smart entry (bare /trailhead)
With no verb, detect the repo state and propose, do not dead-end:
- No map to offer chart (
/trailhead:new) or adopt (/trailhead:adopt); or point at /trailhead:whiteboard if the repo has loose trailhead:whiteboard tickets but no map.
- Map present with a workable frontier to route to work. Bare
/trailhead:work takes one ticket to act on, but present the frontier as a set to choose from when its tickets are mutually independent, never a crowned first-listed (see Frontier order carries no priority in ../_shared/substrate.md).
- Map present but its frontier is empty (everything left is gated or still fog, or the map is complete-except-gated) to lay out the sensible moves as a short list, and always include
/trailhead:quick "<text>" right after /trailhead:map as the way to open and do a new discrete piece of work off the map now (an existing loose ticket is worked anchored on /trailhead:work <n>, with /trailhead:quick <n> as the lighter alternative), alongside /trailhead:map for the full view, /trailhead:whiteboard when loose work waits, /trailhead:new to chart the next map, the captures (todo / idea / bug / seed) for new work, and graduating a fog line into a ticket when it is sharp enough.
Self-heal the pinned dashboard before proposing: ensure the repo's trailhead:dashboard index exists and is pinned. Ensure the label, then create + pin only if missing, re-pin if the pin was dropped, and never rewrite the body on this render (the dashboard model is in ../_shared/substrate.md; the exact gh commands live in the substrate cookbook, at ../_shared/substrate-commands.md). So a repo that adopted trailhead before the dashboard existed gets one on the next bare /trailhead.
First-time config offer (once per project). When a project has a map but no .trailhead/config.json yet, put an explicit two-way choice to the user and wait for their pick: (a) accept as-is (continue on the current or proposed values, which writes an empty {}), or (b) run /trailhead:config to configure everything through the guided menu (models / design / TDD / ...). Always name both paths and let the user choose; never silently take one. You may show the values you would default to, but frame the close as this binary: do not pre-fill the config keys and ask for an open-ended inline edit, and do not interview the user key-by-key inline (that is /trailhead:config's job). Ask this only once: running config writes the file, and accept as-is writes an empty {}, so once .trailhead/config.json exists it is never offered again (a {} file means "reviewed, using defaults"). The same offer is made at the end of chart / adopt. It fires on the bare /trailhead and when setting a project up, never in the middle of working a ticket.
Every verb is also a namespaced command (/trailhead:new, /trailhead:work, /trailhead:bug, ...) so typing /trailhead lists them all in the picker; they delegate to their owning skill.