From 8702f3058db8fb2c04e1d6a181749095da752d8b Mon Sep 17 00:00:00 2001 From: Frank Date: Sun, 18 Oct 2026 14:57:20 -0700 Subject: [PATCH] chore: re-sync agent skills to upstream mattpocock/skills Local snapshots dated 2026-09-16; upstream has moved on since. Refreshes 7 SKILL.md files (code-review, diagnosing-bugs, implement, tdd, grilling, handoff, teach): tracker-doc references generalized, CONTEXT.md renamed GLOSSARY.md, implement gains ticket-fetch step + Skill-tool invocation, grilling question wording rule, handoff names the OS temp dir, teach workspace-path resolution + quiz answer-position rules, tdd seam notes. find-skills (vercel-labs) and prototype already current. Skill updates take effect next session (discovery runs at startup). --- agent/skills/code-review/SKILL.md | 8 +++++--- agent/skills/diagnosing-bugs/SKILL.md | 4 ++-- agent/skills/grilling/SKILL.md | 2 ++ agent/skills/handoff/SKILL.md | 2 +- agent/skills/implement/SKILL.md | 6 ++++-- agent/skills/tdd/SKILL.md | 4 ++-- agent/skills/teach/SKILL.md | 4 ++-- 7 files changed, 18 insertions(+), 12 deletions(-) diff --git a/agent/skills/code-review/SKILL.md b/agent/skills/code-review/SKILL.md index e28d7ac..373a4f2 100644 --- a/agent/skills/code-review/SKILL.md +++ b/agent/skills/code-review/SKILL.md @@ -10,7 +10,7 @@ Two-axis review of the diff between `HEAD` and a fixed point the user supplies: Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. -The issue tracker should have been provided to you. If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`. +The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. ## Process @@ -26,14 +26,14 @@ Before going further, confirm the fixed point resolves (`git rev-parse ``` +Word each question so "yes" accepts your recommended answer. + Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one. Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait. diff --git a/agent/skills/handoff/SKILL.md b/agent/skills/handoff/SKILL.md index 2eb98a5..a224edc 100644 --- a/agent/skills/handoff/SKILL.md +++ b/agent/skills/handoff/SKILL.md @@ -5,7 +5,7 @@ argument-hint: "What will the next session be used for?" disable-model-invocation: true --- -Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace. +Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS (`$TMPDIR`, else `/tmp`; `%TEMP%` on Windows) - not the current workspace. Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for. diff --git a/agent/skills/implement/SKILL.md b/agent/skills/implement/SKILL.md index 7a0b11f..bd49e47 100644 --- a/agent/skills/implement/SKILL.md +++ b/agent/skills/implement/SKILL.md @@ -6,10 +6,12 @@ disable-model-invocation: true Implement the work described by the user in the spec or tickets. -Use /tdd where possible, at pre-agreed seams. +If the user passes a ticket reference, fetch it from the issue tracker and state its title before starting. If the reference is ambiguous, ask. + +Call the Skill tool with "tdd" where possible, at pre-agreed seams. Run typechecking regularly, single test files regularly, and the full test suite once at the end. -Once done, use /code-review to review the work. +Once done, call the Skill tool with "code-review" to review the work. Commit your work to the current branch. diff --git a/agent/skills/tdd/SKILL.md b/agent/skills/tdd/SKILL.md index 8fc0867..01eadaa 100644 --- a/agent/skills/tdd/SKILL.md +++ b/agent/skills/tdd/SKILL.md @@ -7,7 +7,7 @@ description: Test-driven development. Use when the user wants to build features TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle: consult them before and during the loop, not after. -When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching. +When exploring the codebase, read `GLOSSARY.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching. ## What a good test is @@ -21,7 +21,7 @@ A **seam** is the public boundary you test at: the interface where you observe b **Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything, so agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case. -Ask: "What's the public interface, and which seams should we test?" +Ask: "What's the public interface, and which seams should we test?" Give each proposed seam a one-line note on what it catches and what it misses. When the shape of that interface is itself in question (how deep the module is, where the seam belongs, what the interface should expose), call the Skill tool with "codebase-design" for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run. diff --git a/agent/skills/teach/SKILL.md b/agent/skills/teach/SKILL.md index c679eec..493fa3b 100644 --- a/agent/skills/teach/SKILL.md +++ b/agent/skills/teach/SKILL.md @@ -9,7 +9,7 @@ The user has asked you to teach them something. This is a stateful request - the ## Teaching Workspace -Treat the current directory as a teaching workspace. The state of their learning is captured in this directory in several files: +Treat the current directory as a teaching workspace. Workspace paths (`./lessons/` and the rest) resolve from the directory `/teach` was run in; only the `*-FORMAT.md` links resolve from this skill's folder. The state of their learning is captured in this directory in several files: - `MISSION.md`: A document capturing the _reason_ the user is interested in the topic. This should be used to ground all teaching. Use the format in [MISSION-FORMAT.md](./MISSION-FORMAT.md). - `./reference/*.html`: A directory of reference materials. These are the compressed learnings from the lessons - cheat sheets, reference algorithms, syntax, yoga poses, glossaries. They are the raw units of learning. They should be beautiful documents which print out well, and are designed for quick reference. @@ -107,7 +107,7 @@ For skill acquisition, difficulty is the tool. Effortful retrieval is what build Each of these should be based on a **feedback loop**, where the user receives feedback on their performance. This feedback loop should be as tight as possible, giving feedback immediately - and ideally automatically. -For quizzes, each answer should be exactly the same number of words (and characters, if possible). Don't give the user any clues about the answer through formatting. +For quizzes, each answer should be exactly the same number of words (and characters, if possible). Vary which position holds the correct answer across questions. Don't give the user any clues about the answer through formatting or order. ## Acquiring Wisdom