The whole flow, end-to-end: the smart zone is the unit of work
TL;DR
Matt Pocock's first actual tutorial for his skills repo answers the
question people kept asking — what sequence do I use these in?
— and in doing so reveals that the pipeline the vault already documents
(grill-with-docs → to-spec → to-tickets → implement → code-review) is
not really a planning methodology at all: it is machinery for
doing work that is bigger than one context window's usable
region. He calls that region the smart zone,
puts it at ~140k, and — this is the load-bearing detail — is running a
model the harness reports as Opus 4.8 (1M context), so he
is deliberately planning against about a seventh of the window he has.
Everything follows from that one limit. The fork after grilling is
decided by it ("we've got 100k of budget here to remove 10 commands —
that seems super easy" → skip steps 2 and 3, go straight to
/implement); /to-spec exists to compress a
46.1k grilling session into a durable artifact when the work
won't fit; a ticket is defined as "the size of a single context
window"; you /clear between tickets. So specs and tickets
are revealed as pure overhead on work that fits the
zone — which is a sharper and more useful rule than "always
spec first." Two other ideas earn their own pages: the skills reach
backends through a repo-local binding document whose
headings are the skill's own verbs
(## When a skill says "publish to the issue tracker" →
write a file under .scratch/), which is why "how
do I make this work with Jira?" is answered "it already does"; and
/code-review runs in spawned sub-agents with fresh
context windows, because "agents are often really bad at
improving code they've just written — they wrote it, so they think
that's fantastic, that's fine." That last one sits in productive tension
with the vault's Cross-Model
Independence, which holds that same-model review is an echo chamber
no prompt can fix.
Concepts introduced
- Context Smart Zone — the usable band of a context window is smaller than the advertised one (~140k against a 1M window here), degrades before it fills, and is what you plan against. It becomes the unit of work: tickets are sized to it, you clear between them, and the entire spec-and-tickets apparatus is what you build only when the job exceeds it.
- Context-Independent Review — a third independence axis alongside rank (Authority-Independent Verification) and lineage (Cross-Model Independence): the reviewer is the same model but its context never contained the authoring, so it has nothing to defend. Cheap, real, and strictly weaker than an uncorrelated checker.
- Repo-Local Capability Binding — the skill names an abstract verb ("publish to the issue tracker"); a repo-local markdown dispatch table keyed by that exact phrase binds it to GitHub, local markdown, Jira, or anything else. Interface/implementation separation where both halves are prose — which is what makes the skills portable, and what makes the binding uncheckable.
Held, not dropped (touched, but not warranting a page yet):
- Ask-Matt: the author packaged as an onboarding oracle. A skill that is "essentially me as a skill," knowing the repo and what you should do first — the tutorial's own recommended entry point ("stop the video now and use one skill"). Interesting as a distribution answer to "nobody reads the README," and adjacent to Curatorial-Voice Learning and Public Skill Adoption. Held pending a second instance of author-as-skill.
- The operator overruling the agent's decomposition. "These three slices are a little bit much — do it in one slice instead." Slicing is presented as agent-proposed, human-ratified; folded into Agent Supervision and Agent Task Graph rather than given a page.
- Install-scope as a team decision. Project skills so a team shares one set and contributes to it together, global for solo work. A governance theme adjacent to Public Skill Adoption; held.
- Blessed vs experimental within one repo. 38 skills split into a public-facing set he has "blessed" and ones he "may delete in future," with a stated main flow and an explicit periphery. Adjacent to Skill Pruning and Minimal Skill Surface; held pending a second source treating the stable-core/experimental-edge split as a design move rather than housekeeping.
- Single vs multi bounded context for domain docs. "Multi-context is if you have a big monorepo and need lots of different bounded contexts… for 99% of people, a single context is going to be fine." Recorded as an observation on Repo-Local Capability Binding; held as a theme.
- Installer friction as an adoption tax. The Vercel
skills.shCLI is "kind of broken," selection is fiddly, and he may ship his own. Real, but a tooling gripe rather than a concept; held.
Key claims
- A context window's usable region ("the smart zone") is smaller than its nominal size, and the usable region is what you plan against. principle — durable: attention degrades before the window fills, so the advertised number is a capacity limit while the smart zone is the quality limit. A bigger window does not repeal it — it widens the gap. → Context Smart Zone
- Size each ticket to one smart zone and clear between them. (best practice) — context: multi-session agent work where a degraded run is expensive to catch late; the cost is a handoff artifact per boundary (the spec and ticket that carry state across the clear), so this is pure overhead on work that fits one zone. → Context Smart Zone / Agent Task Graph
- Decide whether to spec or just build by measuring the work
against the remaining zone — if it fits, skip steps 2 and 3 and
go straight to
/implement. (best practice) — context: the fork after grilling, when ~46k is already spent; the author judged his own demo job to fit and ran spec-and-tickets only for the camera. Contingent on being able to estimate the work's cost, which he does by feel. → Spec-Driven Development / Context Smart Zone /to-specis deliberate context compression: it collapses a 46.1k-token grilling session into a durable document, so the spec is the destination and the tickets are the route. observation — the operator doing on purpose, at a chosen moment, what compaction does automatically at the window edge. → Context Compression / Spec-Driven Development- An agent reviews its own work badly because it authored it — "they wrote it, so they think that's fantastic, that's fine" — so spawn review sub-agents with a clear context window. principle for the failure; (best practice) for the fix — context: any write-then-check stage on one model; nearly free, and it buys freedom from authorship anchoring only, not from shared blind spots. → Context-Independent Review
- Review on two axes against written standards: the diff vs the original spec (catching what the tickets left unspecified or the agent forgot), and the diff vs the repo's own conventions — falling back to Fowler's code smells where a repo documents none. (best practice) — context: a pipeline that already produced a spec as its handoff artifact; a reviewer with no memory of the intent needs the intent supplied. → Context-Independent Review / Leading Words
- Couple skills to abstract operations and bind them to tooling in a repo-local document the agent reads; then "how do I make this work with Jira?" is answered by writing the binding, not by adding an integration. principle — durable: it is interface/implementation separation, and it is the precondition for a skill library being portable at all. → Repo-Local Capability Binding
- A prose binding is unchecked — it fails at agent-interpretation time, not at a type boundary. principle — the standing cost of natural-language interfaces; the flexibility and the absence of a checkable contract are the same property. → Repo-Local Capability Binding
- Keeping skills user-invoked keeps the whole library nearly free in context — measured on screen at 660 tokens for 9 skills, because the descriptions "don't leech their way in" and are "quite short and precise." (best practice) — context: an operator willing to absorb the cognitive load of remembering their own skills in exchange for control and a clean context; a team optimizing for hands-off automation weighs it differently. → Skill Invocation Trigger / Minimal Skill Surface
- The full lifecycle is a fixed pipeline of named skills —
grill-with-docs → to-spec → to-tickets → implement → code-review — and
wayfinderis not in it. observation — the author's own answer to "what is the sequence?"; corroborates the vault's existing pipeline claim and Map-First Planning's positioning of Wayfinder as situational rather than the default entry. → Spec-Driven Development / Map-First Planning - A vague idea is a sufficient input — "it really can be as vague as this; grill-with-docs is going to do the heavy lifting" — and the interview runs in auto mode, not plan mode, ending at shared understanding (~6 questions here, "usually about 20"). (best practice) — context: a stateful repo where the skill can explore code to ground its questions; the vagueness tolerance is bought by the interview, not free. → Step Isolation
- The video states the repo is "up to 162,000 stars" with "7.5
million downloads," that 38 skills were found by the installer, and that
the session ran Claude Code v2.1.197 on "Opus 4.8 (1M context) with
medium effort" with
/contextreporting 660 tokens for 9 skills. observation — the source's claims about external, groundable facts (star and download counts, a named model, version strings, on-screen token figures), recorded as claimed for later verification, not adjudicated here. Note the internal wrinkle worth a check: 38 skills were offered at install but/contextreports 9 — consistent with user-invoked skills not all being counted, but unexplained on screen.
Why this builds on the existing graph
Same author, same system, same pipeline the vault already documents
from his v1.1 release (Skills
v1.1: Wayfinder, the SDLC flow, and naming the artifact right) — so
the dominant stance is builds_on. But it is not a
duplicate, and the reason is a change of altitude: the v1.1 video
documented what the flow is; this one documents what
the flow is for. The five steps were already on the page. The
fact that steps 2 and 3 exist only to survive a ~140k attention ceiling
— and that their own author skips them when the work fits — was not, and
it converts a methodology into a conditional.
- Corroborates Spec-Driven Development's pipeline claim, and sharpens it. The page already holds "the full lifecycle is a fixed pipeline of named skills." This is the same author demonstrating it end-to-end on a real repo — but the demonstration adds the trigger condition (does the work fit the remaining zone?) that turns "spec first" from a rule into a decision. Two sources from one author is corroboration of the pipeline's stability, not independent evidence for its value.
- Corroborates Skill
Invocation Trigger with a measurement. The page argues
user-invocation trades operator cognitive load for a clean agent
context. Here the clean context is quantified — 660 tokens for
9 skills — and the
(user)tag the page records as an observed UI detail is visible again in this palette, from the repo that motivated the claim. - Corroborates Map-First Planning from the negative side. That page positions Wayfinder as a situational on-ramp, not the default. This tutorial — explicitly scoped to the main flow — starts at grill-with-docs and never mentions Wayfinder outside the command palette. The author's own curriculum confirms the positioning his own commit message asserted.
- New below the graph: Context Smart Zone. Both Map-First Planning and Agent Task Graph already invoke the smart zone — "too big for one agent session," "hand each to a fresh context window" — without anywhere naming what it is or why. This is the principle those recipes instantiate, and giving it a page is exactly the pattern→principle lift the vault's ontology asks for: the fresh-window rule stops being a heuristic two pages happen to share and becomes a consequence of a stated limit.
- New beside the graph: Repo-Local Capability
Binding. The vault had this at artifact scale (Agent Task Graph's medium-agnostic
/to-ticketsoutput) but not as the general move. The binding doc is the mechanism Skill Artifact Transfer silently depends on.
The tension worth keeping: Context-Independent Review vs Cross-Model Independence
This is the one place the capture pulls against an existing vault claim, and it is worth stating as a tension rather than resolving.
Cross-Model Independence
holds — sharply, and as a principle — that "a model
cannot be trusted to grade work it authored: its blind spots are
properties of the model, so same-model review is an echo chamber that no
prompt, persona, or adversarial instruction removes." This video
asserts that a same-model, same-lineage sub-agent with a fresh
context window does "a much better job" reviewing — and
structures its whole review stage on that assertion.
Both can hold, because they name different failures. The vault's page is about blind spots (what the model cannot see at all); this video is about authorship anchoring (what the model will not look at because it just produced it). Clearing the context removes the second and leaves the first entirely intact. But the two claims will read as interchangeable to anyone skimming — "don't let it grade its own work" — and they buy very different things at very different prices. The distinction to carry forward: context independence is nearly free and removes commitment; lineage independence is expensive and removes correlation. A fleet that has bought the first and believes it has bought the second is exactly the failure Cross-Model Independence exists to name. Neither source measured its claim; both are held as attributed hypotheses.
Secondary stances: corroborates toward Spec-Driven Development, Skill Invocation Trigger, and
Map-First Planning (same-author,
so weak corroboration); novel for the three new pages.
Illustrated walkthrough
Visual coverage is low confidence
(sampler audit): the largest un-illustrated stretch is ~30
s, and the last third of the video (t≈720 s → end, covering the
real multi-ticket spec, implementation, and code review) is carried
entirely by coverage-floor frames on a fixed 30 s grid
— i.e. sampled by the clock, not by anything changing on screen.
Terminal output and file edits in those windows were not
sampled, and the absence of a frame there is not evidence that
the screen was static; this sampler is known to miss
text-on-solid-background changes, which is most of what a terminal is.
Read the walkthrough below as keyed to the frames I could actually
read.
- t=0:10 — the ask (
f0002). The framing claim: the repo is "up to 162,000 stars," "7.5 million downloads," and has never had a tutorial. The recurring question is "what is the sequence I should use these skills in?" — so this video is deliberately scoped to the main flow: "we're not going to look at the advanced stuff, we're not going to look at the new stuff." - t=2:20 — install (
f0023).npx skills@latest add mattpocock/skills, theskills.shinstaller (from Vercel). The agent-selection list is long — AiderDesk, AstrBot, Autohand, Augment, IBM Bob, Claude Code (.claude/skills), OpenClaw, CodeArts, "↓ 44 more" — withSelected: Amp, Antigravity, Antigravity CLI +11 more. 38 skills found, in two groups: the blessed public-facingmattpocock/skillsand experimental ones he "may delete in future." He is candid that the installer UI "is kind of broken" and he may ship his own. Install scope is a genuine decision: project skills for a team (so everyone shares a skill set and contributes to it together), global for a solo developer; symlink over copy. - t=4:18 — the context bill, measured
(
f0043)./contextonOpus 4.8 (1M context),claude-opus-4-8[1m], 12.5k/1M tokens (1%). Broken out: system prompt 2.2k, system tools 5.3k, memory files 100, Skills: 660 tokens (0.1%) — 9 skills, messages 4.2k. This is the concrete evidence for the user-invoked design (Skill Invocation Trigger): "not many of my skills actually leech their way into the description… the descriptions I have are quite short and precise." A whole library for 660 tokens. - t=5:08 — the binding doc (
f0056). Thesetupskill interviews for the issue tracker: the agent notesgit remotepoints atmattpocock/ai-hero-cliand proposes GitHub ← recommended, Local markdown (.scratch/<feature>/), or Other (Jira, Linear, etc.) — "describe the workflow and I'll record it as prose." The key sentence on screen: "Skills liketo-tickets,triage,to-spec… need to know whether to callgh issue create, write a markdown file under.scratch/, or follow the place you actually track work." This is Repo-Local Capability Binding stated outright. He picks local markdown. - t=12:00 — what setup wrote (
f0165).docs/agents/issue-tracker.md, titled "# Issue tracker: Local Markdown." Conventions: one feature per directory.scratch/<feature-slug>/; the PRD at.scratch/<feature-slug>/PRD.md; issues atissues/<NN>-<slug>.mdnumbered from01; triage state as aStatus:line; comments appended under## Comments. Then the dispatch table itself:## When a skill says "publish to the issue tracker"→ create a file under.scratch/<feature-slug>/;## When a skill says "fetch the relevant ticket"→ read the file at the referenced path;## Wayfinding operations. Sibling filesdomain.mdandtriage-labels.mdare visible in the tree. The skill names the verb; this file binds it. - t=6:54 — Ask Matt (
f0090). Claude Code v2.1.197,Opus 4.8 (1M context) with medium effort. He runsask-matt("essentially me as a skill") with "how do I get started? what is the main flow I should use?" It answers: "Since you have a code base, start at the top of the main flow and walk down it in one unbroken context window" — routing advice that is about session management, not just skill order. He editorializes on its prose ("'defensible' is such an LLM phrase, honestly") while accepting the routing. - t=8:24 — the flow, named (
f0105; restated at t=10:12,f0138). The five-step diagram, and the answer to the whole video: 1 grill-with-docs · 2 to-spec · 3 to-tickets · 4 implement · 5 code-review. Note what is not step 1: wayfinder appears only in the/-palette, never in the main flow — corroborating Map-First Planning's own positioning of it as a situational on-ramp rather than the default entry. - t=8:36 — grilling, and the (user) tag (
f0107,f0139at t=10:22). He kicks offgrill-with-docswith a deliberately vague idea: "I would like to remove most of the internal tooling on this CLI to make it just only public-facing… I want to just take this repo down a notch." His point: "it really can be as vague as this — grill-with-docs is going to do the heavy lifting." Six questions later (he notes his sessions are "usually about 20") there's a plan: delete 10 command files, delete 3 tests, rewire shared modules. He was in auto mode, not plan mode. The palette inf0139shows/grill-me,/grill-with-docs,/grillingeach tagged(user)— the invocation mode surfaced at the command surface, exactly as Skill Invocation Trigger records. - t=10:12 — the fork, and the smart zone
(
f0138). The five-step diagram again, at the decision point. "You now have a fork in the road." If the work fits the remaining window, skip 2 and 3 and say/implement this. His reasoning, verbatim: "I think of my context window as kind of ending or getting significantly dumber around 140k. I think of that as kind of like the smart zone of the LLM. If you go above 140k, you end up with attention degradation, it ends up getting stupider, does weird hallucinations. So I think of having, okay, we've got 100k of budget here to remove 10 commands. That seems super easy." He judges this job does fit — and then does spec-and-tickets anyway, only "in the interest of showing you everything." That aside is the most useful thing in the video: the flow's own author would have skipped two of its five steps. See Context Smart Zone. - t=11:20 —
/to-specas deliberate compression. "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." The spec has a problem statement, solution, user stories, implementation decisions, testing decisions. Its role is stated cleanly: the spec is the destination, the tickets are how we get there. This is Context Compression's job done on purpose by the operator rather than by the harness at the window edge. - t=13:00 —
/to-tickets, and the human overruling the slicing (f0167). Same session, no clear. "Each one of these tickets is supposed to just be the size of a single context window or a single smart zone." It proposes three slices; he rejects the decomposition — "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." The resultingtickets.mdis on screen: "Work the frontier: any ticket whose blockers are all done. This is a single ticket, so just do it," then**What to build:**,**Blocked by:** None — can start immediately, and a scoping principle worth keeping — "The scoping principle is actively used, not audience:edit-commit(an author tool) survives because it is still used, while everything else ininternalis removed." Note the frontier language and blocking edges surviving into a flat markdown file: Agent Task Graph's medium-agnostic artifact. - t=13:06 — the real example (11 sub-issues). He drops the toy case ("this is quite a bad example cuz it's kind of copying the stuff that's in our PRD") for a spec he shipped days earlier: one spec with 11 sub-issues underneath it, each "a single context window session." Each ticket is short — "most of the acceptance criteria is already in the main spec, so this one is just literally what do you build in this session?" The spec holds the standard; the ticket holds only the slice.
- t=14:00 — implement, and clearing between tickets.
/clear, thenimplement this @tickets. The discipline: "you don't say do every single ticket" — implement one, check whether you've hit the smart zone, maybe squeeze one more in, "but usually I would say you clear in between every single ticket." - t=15:30 — review in fresh sub-agents
(
f0172). The implement skill runs typecheck, test, build, verifiesai-hero internal --helpshows onlyedit-commit, then loadsSkill(code-review)and announces: "I'll pin the fixed point and gather the diff, then spawn the two review sub-agents in parallel." Two axes: the diff against the original spec ("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") and against the repo's standards docs, falling back to Martin Fowler's code smells where a repo documents none (Leading Words). The rationale for the sub-agents is the whole of Context-Independent Review: "if you do it in the main agent, the main agent already has written the code, and agents are often really bad at editing or improving code they've just written. Because they wrote it, so they just think, 'okay, that's fantastic, that's fine.' Whereas if you spawn some agents, they're going to have a clear context window and they're going to do a much better job." Both come back green; it commits. - t=16:22 — the recap. "We aligned before we got started. We created 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." And the boundary: "the stuff that isn't in the main flow is stuff that I'm experimenting with" — the main flow is the stable core; everything else in a 38-skill repo is explicitly provisional.