@jesdi/skills 0.0.31 → 0.0.33

package/README.md

@@ -144,11 +144,12 @@ them afterwards). `external-skills.json` lists them under `forks`.
 
 ### The box set
 
-`external-skills.json` → `sets.box` names the skills the agent-ops box
-receives: `own` from this package, `external` from the pinned upstream.
-`pr` is in the external set and is installed directly from mattpocock/skills.
-agent-ops vendors that set into its claude-home seed with its own refresh
-command; this repo's job is to publish the set and keep the pins resolvable.
+`external-skills.json` → `sets.box.external` names the third-party skills the
+agent-ops box receives from the pinned upstream. `pr` is in this set and is
+installed directly from mattpocock/skills. agent-ops-infra lists the own skills
+of the box (`provision/my-skills.json`) and pins the commit of this file it
+reads (`provision/external-skills.pin`); this repo's job is to publish the set
+and keep the pins resolvable.
 
 ## Authoring skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/implement-spec/ARCHITECTURE.md

@@ -78,7 +78,7 @@ and do not know about the run, except `driver_run.py`, which the three deciding
 ### Work is never dropped
 
 - A role that commits keeps its tree after a timeout or an interrupt; its rerun continues from it.
-- A read-only role (reviewer, correctness, final-reviewer) has no work to keep. When it changes its slot, the
+- A read-only role (reviewer, correctness, final-reviewer, pr-writer) has no work to keep. When it changes its slot, the
   driver restores the slot and runs the review one more time (`Run.read_only`).
 - A slot with uncommitted work of an interrupted or parked ticket is kept for that ticket (`driver_state.kept`).
 - A blocked ticket keeps its slot when the slot is not clean.

package/skills/implement-spec/README.md

@@ -44,7 +44,7 @@ One driver runs in a repository at a time. The driver holds a kernel file lock o
 | `--only ROLE` | Test only. Run one role (`test-writer`, `implementer`, `reviewer` or `correctness`) on the first ticket, with no gate and no merge. |
 | `--help`, `-h` | Print the flags and exit. |
 
-Default timeouts in minutes: explorer 30, test-writer 30, implementer 90, reviewer 45, correctness 30, fixer 60, final-reviewer 60, conflict 30.
+Default timeouts in minutes: explorer 30, test-writer 30, implementer 90, reviewer 45, correctness 30, fixer 60, final-reviewer 60, conflict 30, pr-writer 20.
 
 `run.sh` downloads `uv`, Python 3.13 and `jsonschema` once into `~/.cache/implement-spec`. `IMPLEMENT_SPEC_CACHE_DIR` moves that cache. `IMPLEMENT_SPEC_OFFLINE=1` forbids the download. `run.sh` supports macOS and Linux only, on x86_64 or ARM64, and needs `curl`, `tar` and `sha256sum` or `shasum` for the first download.
 
@@ -81,7 +81,7 @@ Everything is under `.agent/`, which is never committed.
 | `.agent/implement/<NN>/<role>-<K>.json`, `.log`, `.prompt.md` | The report, the log and the prompt of one agent. K is the fix round. |
 | `.agent/implement/<NN>/gate-<sha7>.log` | One gate record: start, commit, status, command, output, exit, the state after the command, end. |
 | `.agent/implement/<NN>/findings-<K>.json` | The merged findings of the review after fix round K. |
-| `.agent/implement/final/` | The same files for the end of run, and `pr-body.md`. |
+| `.agent/implement/final/` | The same files for the end of run, and `pr-body.md`: the pr-writer's body, then the facts of the run. |
 | `.agent/implement/pycache/` | Compiled Python of the gate, kept out of the slots. |
 | `.agent/implement-review.html` | The page with the open questions. |
 | `.agent/implement-answers.json` | The answers: `{"v": 1, "stage": "implement", "submitted": …, "revision": …, "answers": {…}}`. |
@@ -131,7 +131,7 @@ The end of run starts only when every ticket is merged and every slot is idle. I
 3. **Gate**, then the **final-reviewer** (`prompts/final-reviewer.md`) on the whole range, with the method of the `review-diff` skill. It gets the minor findings of the tickets and the rulings of the operator.
 4. **Fix batch.** Critical and important findings go to one fixer (`prompts/final-fixer.md`). The driver names each of its commits `fix(NN): …` from the ticket in the report. Then the gate, then one scoped review of those commits.
 5. Findings that are open after the second review become questions of kind `final-finding`. There is no third review.
-6. **Push.** With `--push` or `--unattended`, the driver pushes the reviewed tip once, with no force, and opens the PR with `gh`, ready for review. Without them it prints the two tips and the command to run again with `--push`.
+6. **Push.** With `--push` or `--unattended`, the driver pushes the reviewed tip once, with no force, and opens the PR with `gh`, ready for review. The **pr-writer** (`prompts/pr-writer.md`) writes the body with the method of the `pr` skill; the driver puts the facts of the run after it: the ticket-to-commit map, the fix commits, the rulings and the review coverage (`prompts/pr-body.md`). A push stops before any agent when no `pr` skill is next to this skill, in `${CLAUDE_CONFIG_DIR:-~/.claude}/skills` or in `~/.agents/skills`. Without them it prints the two tips and the command to run again with `--push`.
 
 History rules:
 
@@ -174,6 +174,7 @@ Every report has `status` (`DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCK
 | correctness | `prompts/correctness.md` | the same as the reviewer | `mutations` is optional. |
 | fixer | `prompts/fixer.md` | `green`, `ticket` | With DONE: one commit or more. |
 | final-reviewer | `prompts/final-reviewer.md` | `findings` | None. |
+| pr-writer | `prompts/pr-writer.md` | `body`; `commits` is empty | None. |
 | fixer of the final review | `prompts/final-fixer.md` | `green`; `commits` is a list of (`sha`, `ticket`) | Each new commit on the branch is in `commits`, with a ticket of the run. |
 | conflict | `prompts/conflict.md`, `prompts/rebase-conflict.md` | none | With DONE: one commit or more. No locked file may change. |
 

package/skills/implement-spec/driver_agents.py

@@ -18,10 +18,10 @@ from pathlib import Path
 SKILL = Path(__file__).resolve().parent
 # Minutes per role.
 TIMEOUTS = {"explorer": 30, "test-writer": 30, "implementer": 90, "reviewer": 45, "correctness": 30, "fixer": 60,
-            "final-reviewer": 60, "conflict": 30}
+            "final-reviewer": 60, "conflict": 30, "pr-writer": 20}
 PROVIDERS = {"anthropic": ("claude", ("low", "medium", "high", "xhigh", "max")),
              "openai": ("codex", ("minimal", "low", "medium", "high", "xhigh"))}
-READ_ONLY = ("reviewer", "correctness", "final-reviewer")
+READ_ONLY = ("reviewer", "correctness", "final-reviewer", "pr-writer")
 # A process group is here only while its leader is not reaped: then no other process can have its id.
 LIVE: set[int] = set()
 STOPPED = False

package/skills/implement-spec/driver_final.py

@@ -41,6 +41,14 @@ ROUNDS = 2  # the full review and the scoped one after the fix batch
 REVIEW_DIFF = driver_agents.SKILL.parent / "review-diff" / "SKILL.md"
 
 
+def pr_skill() -> Path | None:
+    """The SKILL.md of the pr skill, which the PR body follows: next to this skill, else in the skill folder of the
+    Claude home or of the shared home of Codex and OpenCode."""
+    claude = Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude")
+    homes = (driver_agents.SKILL.parent, claude / "skills", Path.home() / ".agents" / "skills")
+    return next((home / "pr" / "SKILL.md" for home in homes if (home / "pr" / "SKILL.md").is_file()), None)
+
+
 def _has_origin() -> bool:
     return git(".", "remote", "get-url", "origin").returncode == 0
 
@@ -51,6 +59,9 @@ def precondition_errors(push: bool) -> list[str]:
     if not REVIEW_DIFF.exists():
         errors.append(f"{REVIEW_DIFF} is missing: the final review runs through it; install the review-diff skill "
                       "next to implement-spec")
+    if push and not pr_skill():
+        errors.append("the pr skill is missing: the PR body follows it; install it with "
+                      "`npx skills add mattpocock/skills --skill pr`, or run without --push and --unattended")
     if push and not _has_origin():
         errors.append("the repository has no origin remote: --unattended and --push push the PR branch to origin; "
                       "add the remote, or run without them to stop before the push")
@@ -401,8 +412,8 @@ def _name(run: Run) -> str:
     return next((line[2:].strip() for line in lines if line.startswith("# ")), run.pr)
 
 
-def _body(run: Run, final: dict, tickets: list[Ticket]) -> str:
-    """The PR body: the ticket-to-commit map, the fix commits, the rulings and the review coverage."""
+def _facts(run: Run, final: dict, tickets: list[Ticket]) -> str:
+    """The end of the PR body: the ticket-to-commit map, the fix commits, the rulings and the review coverage."""
     titles, tip = {ticket.number: ticket.title for ticket in tickets}, final["reviewed"]
     fixes = git(".", "log", "--reverse", "--format=- %h %s", f"{final['tidied']}..{tip}").stdout.strip()
     rulings = driver_decisions.rulings(run.state.read()["run"]["questions"])
@@ -413,10 +424,28 @@ def _body(run: Run, final: dict, tickets: list[Ticket]) -> str:
         "scoped": f"{final['tidied']}..{tip}" if fixes else "not needed"})
 
 
+def _write_body(run: Run, final: dict, tickets: list[Ticket]) -> Path:
+    """Write the PR body: what the pr-writer wrote with the method of the pr skill, then the facts of the run. A body
+    written for the reviewed tip is kept, so a PR that failed to open costs no second agent."""
+    body, tip = OUT / FINAL / "pr-body.md", final["reviewed"]
+    if final["body"] == tip and body.is_file():
+        return body
+    method, facts = pr_skill(), _facts(run, final, tickets)
+    if not method:
+        raise Blocked("the pr skill is missing: the PR body follows it; install it with "
+                      "`npx skills add mattpocock/skills --skill pr`")
+    values = {**_prompt_values(run), "start_sha": tip, "range": f"{final['onto']}..{tip}",
+              "gate": str(OUT / FINAL / f"gate-{tip[:7]}.log"), "pr_skill": str(method), "facts": facts}
+    with during("the PR body"):
+        report = run.read_only(FINAL, ".", run.pr, tip, lambda: run.agent("pr-writer", FINAL, ".", values))
+    body.write_text(f"{report['body'].strip()}\n\n{facts}")
+    run.state.update(lambda state: state["run"]["final"].update(body=tip))
+    return body
+
+
 def _open_pr(run: Run, final: dict, tickets: list[Ticket]) -> str:
     """Open the PR, ready for review, and return its URL."""
-    body = OUT / FINAL / "pr-body.md"
-    body.write_text(_body(run, final, tickets))
+    body = _write_body(run, final, tickets)
     made = subprocess.run(["gh", "pr", "create", "--base", final["base"], "--head", run.pr, "--title", _name(run),
                            "--body-file", str(body)], capture_output=True, text=True, stdin=subprocess.DEVNULL)
     if made.returncode:

package/skills/implement-spec/driver_state.py

@@ -26,7 +26,8 @@ def _ticket() -> dict:
 def _final() -> dict:
     """The end-of-run record before it starts. Every key is here, so a reader uses [] and a wrong name fails."""
     return {"skipped": "", "recovery": None, "tidied": None, "onto": None, "base": None, "commits": {},
-            "reviewed": None, "round": 0, "open": [], "batch": None, "green_gates": [], "pushed": None, "pr": None}
+            "reviewed": None, "round": 0, "open": [], "batch": None, "green_gates": [], "pushed": None, "body": None,
+            "pr": None}
 
 
 class State:
@@ -44,6 +45,8 @@ class State:
                 "revision": uuid.uuid4().hex, "pr_branch": pr_branch, "gates": 0, "stops": 0, "agents": [],
                 "questions": [], "start": git(".", "rev-parse", f"refs/heads/{pr_branch}").stdout.strip(),
                 "landed": [], "final": _final()})
+            for key, value in _final().items():  # a run of an older driver lacks the newer keys
+                state["run"]["final"].setdefault(key, value)
             tickets = state.setdefault("tickets", {})
             for number in numbers:
                 tickets.setdefault(number, _ticket())

package/skills/implement-spec/models.json

@@ -6,5 +6,6 @@
   "correctness": ["openai/gpt-astra@medium", "claude-opus-5@medium"],
   "fixer": ["claude-opus-5@medium"],
   "final-reviewer": ["openai/gpt-astra@medium", "claude-opus-5@medium"],
-  "conflict": ["claude-opus-5@medium"]
+  "conflict": ["claude-opus-5@medium"],
+  "pr-writer": ["claude-opus-5@medium"]
 }

package/skills/implement-spec/prompts/pr-writer.md

@@ -0,0 +1,31 @@
+# PR writer
+
+Spec: {spec}
+Tickets: {tickets}
+PR branch: {pr_branch}, at commit {start_sha}
+Range: {range}
+Gate record of the driver for {start_sha}: {gate}
+PR method: {pr_skill}
+Facts of the run, which the driver puts after your body:
+{facts}
+
+Write the body of the PR of the range with the method of the pr skill in the file above: its sections, in its order. Read the spec, the tickets and the range first. The gate record and the tests of the range are the execution-based evidence; you cannot take screenshots. Do not repeat the facts of the run: the driver puts them after your body.
+Do not commit. Leave the branch and the tree as you found them.
+
+Write one JSON report at {report} that matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns", "body"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "maxItems": 0},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}},
+    "body": {"type": "string", "minLength": 1}
+  }
+}
+```
+
+Never run `git stash`, never reset, and never check out another branch: worktrees share one stash and one ref store.

package/skills/implement-spec/tests/conftest.py

@@ -16,6 +16,18 @@ def ticket(number, blocked="None (can start immediately)", touches="`demo/x.py:
     return f"# {number}: Ticket {number}\n\n**Blocked by:** {blocked}\n\n**Seam:** {seam}\n\n**Touches:** {touches}\n\n- [ ] It works\n"
 
 
+@pytest.fixture(scope="session", autouse=True)
+def pr_skill(tmp_path_factory):
+    """The Claude home of every test, module rigs included, has the pr skill, which the PR body follows. Rigs copy
+    os.environ."""
+    home = tmp_path_factory.mktemp("claude-home")
+    (home / "skills/pr").mkdir(parents=True)
+    (home / "skills/pr/SKILL.md").write_text("---\nname: pr\n---\n")
+    with pytest.MonkeyPatch.context() as patch:
+        patch.setenv("CLAUDE_CONFIG_DIR", str(home))
+        yield home / "skills/pr/SKILL.md"
+
+
 @pytest.fixture
 def repo(tmp_path, monkeypatch):
     """A clean git worktree with .agent ignored; returns a writer for the ticket set."""

package/skills/implement-spec/tests/test_cli.py

@@ -13,7 +13,8 @@ RUN = SKILL / "run.sh"
 GIT = ["git", "-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false"]
 TOOLS = ("sh", "uname", "dirname", "readlink", "git", "env", "mktemp", "curl", "tar", "gzip", "mv", "rm", "mkdir",
          "sha256sum", "shasum", "cat", "chmod", "ln", "date", "basename")
-ROLES = ("explorer", "test-writer", "implementer", "reviewer", "correctness", "fixer", "final-reviewer", "conflict")
+ROLES = ("explorer", "test-writer", "implementer", "reviewer", "correctness", "fixer", "final-reviewer", "conflict",
+         "pr-writer")
 NONE = "None (can start immediately)"
 
 

package/skills/implement-spec/tests/test_final.py

@@ -263,10 +263,10 @@ def test_a_rerun_after_the_tidy_runs_no_agent_no_gate_and_sends_no_ticket_back(s
     assert all(stop_lines(now.out))
 
 
-def test_the_push_rerun_pushes_once_opens_the_pr_with_map_and_rulings_and_runs_nothing(story):
+def test_the_push_rerun_pushes_once_opens_the_pr_with_map_and_rulings_and_runs_only_the_pr_writer(story):
     rig, before, now = story.rig, story.again, story.pushed
     assert now.code == 0, rig.output()
-    assert (now.calls, now.gates, now.tip) == (before.calls, before.gates, before.tip)
+    assert (now.calls, now.gates, now.tip) == (before.calls + 1, before.gates, before.tip), "only the pr-writer runs"
     assert rig.pushes() == [f"refs/heads/feat/csv {now.tip}"] and ref(rig.origin, "refs/heads/feat/csv") == now.tip
     (pr,) = rig.prs()
     assert "--draft" not in pr["argv"]

package/skills/implement-spec/tests/test_tidy.py

@@ -66,7 +66,7 @@ def stray(rig, text="by hand"):
 
 # ---------------------------------------------------------------- the story: local stop, rerun, push
 
-def test_a_local_run_stops_before_the_push_and_a_push_rerun_pushes_and_opens_the_pr_once(tmp_path):
+def test_a_local_run_stops_before_the_push_and_a_push_rerun_pushes_and_opens_the_pr_once(tmp_path, pr_skill):
     rig = Inside(tmp_path, THREE, FINAL_MODELS)
     rig.run(plan())
     assert rig.code == 0, rig.out + "\n".join(rig.ledger())
@@ -95,7 +95,11 @@ def test_a_local_run_stops_before_the_push_and_a_push_rerun_pushes_and_opens_the
     (pr,) = rig.prs()
     assert pr["argv"][:10] == ["pr", "create", "--base", "main", "--head", "feat/csv", "--title", "csv spec",
                                "--body-file", ".agent/implement/final/pr-body.md"]
-    assert [f"- {nn}: {row['sha'][:7]} {TITLES[nn]}" for nn, row in zip(order, rows)] == pr["body"].splitlines()[4:7]
+    assert pr["body"].startswith("## Summary\n\nCSV export.\n\n## Tickets\n"), "the pr-writer's body, then the facts"
+    assert [f"- {nn}: {row['sha'][:7]} {TITLES[nn]}" for nn, row in zip(order, rows)] == pr["body"].splitlines()[8:11]
+    (writer,) = rig.final_calls("pr-writer")
+    assert f"PR method: {pr_skill}\n" in writer["prompt"]
+    assert "Facts of the run, which the driver puts after your body:\n## Tickets" in writer["prompt"]
     assert "## Rulings\n\nNone.\n" in pr["body"] and "Scoped review after the fix batch: not needed" in pr["body"]
     assert f"Pushed feat/csv at {tip} to origin." in rig.out and "PR: https://github.example/pull/1" in rig.out
     assert f"feat/csv is pushed at {tip[:7]}; its PR is https://github.example/pull/1." in rig.out
@@ -103,7 +107,7 @@ def test_a_local_run_stops_before_the_push_and_a_push_rerun_pushes_and_opens_the
 
     rig.run(plan(), "--push")
     assert rig.code == 0 and len(rig.pushes()) == 1 and len(rig.prs()) == 1, "a second push rerun sends nothing"
-    assert (len(rig.calls()), len(rig.gates())) == (calls, gates)
+    assert (len(rig.calls()), len(rig.gates())) == (calls + 1, gates), "the one agent of the pushes is the pr-writer"
 
 
 def test_the_final_review_does_not_start_while_a_ticket_is_not_merged_and_the_ledger_says_so_once(tmp_path):
@@ -493,6 +497,24 @@ def test_without_the_review_diff_skill_every_repository_stops_before_any_agent(t
                        "review-diff skill next to implement-spec\n")
 
 
+def test_a_push_without_the_pr_skill_stops_before_any_agent_and_a_local_run_does_not_need_it(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path / "home"))
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path / "empty-claude-home"))
+    rig = Inside(tmp_path, ONE).run(plan(), "--push")
+    assert rig.code == 3 and not rig.calls(), rig.out
+    assert rig.out.startswith("the pr skill is missing: the PR body follows it; install it with ")
+
+    rig.run(plan())
+    assert rig.code == 0 and not rig.final_calls("pr-writer"), rig.out
+
+    (tmp_path / "home/.agents/skills/pr").mkdir(parents=True)
+    (tmp_path / "home/.agents/skills/pr/SKILL.md").write_text("---\nname: pr\n---\n")
+    rig.run(plan(), "--push")
+    assert rig.code == 0 and len(rig.prs()) == 1, rig.out
+    (writer,) = rig.final_calls("pr-writer")
+    assert f"PR method: {tmp_path}/home/.agents/skills/pr/SKILL.md\n" in writer["prompt"]
+
+
 def test_without_an_origin_the_run_ends_reviewed_and_a_push_is_refused_at_the_start_and_after_the_tidy(tmp_path):
     rig = Inside(tmp_path, ONE, remote=False).run(plan())
     assert rig.code == 0, rig.out

package/skills/implement-spec/tests/test_walk.py

@@ -66,6 +66,8 @@ if role in ("reviewer", "correctness", "final-reviewer") and "report" not in ste
     proofs = [dict(test=r.split()[1], file="demo/export.py", line=1, red=r) for r in reds]
     step = dict(step, stdout="".join(r + "\\n" for r in reds), report=dict(
         status="DONE", commits=[], files=[], concerns=[], findings=[], mutations=proofs))
+if role == "pr-writer" and "report" not in step:  # an unscripted pr-writer writes one section
+    step = dict(step, report=dict(status="DONE", commits=[], files=[], concerns=[], body="## Summary\\n\\nCSV export."))
 for name in step.get("touch", []):
     (rig / "sig" / name).touch()
 for name in step.get("wait", []):

package/skills/pr-visual-diff/SKILL.md

@@ -45,7 +45,7 @@ file as JSON:
 | `deviceProjects` | the config's `projects` (default to a desktop + a mobile project) |
 | `baseBranch` | the repo's default branch (`main`/`master`; `git symbolic-ref refs/remotes/origin/HEAD`) |
 | `packageManager` | infer from lockfile: `pnpm-lock.yaml`→pnpm, `package-lock.json`→npm, `yarn.lock`→yarn, `bun.lockb`→bun |
-| `spinnerSelector` | the app's loading-indicator selector (search for a spinner/`role="status"`/`aria-busy` component) |
+| `spinnerSelector` | every loading indicator of the app, as one selector list: spinners and skeletons (search for a spinner, `role="status"`, `aria-busy`, a skeleton component, `animate-pulse`), e.g. `.animate-spin, .animate-pulse`. A skeleton left out lets a half-loaded view pass as a good shot |
 
 ### Preconditions gate
 
@@ -77,6 +77,14 @@ compact report: the screenshot file names + pinned URLs, the PR-body
 markdown, and any views it flagged. The main context creates/edits the PR from
 that report — it never reads a PNG.
 
+## Where the capture runs
+
+- **Local** (the default): steps 3–5 below, on this machine.
+- **Remote**: when the session instructions say so (the agent-ops box does),
+  or when this machine cannot start a Playwright browser. A GitHub workflow of
+  the target repo captures both sides and pushes the hidden ref; see "Remote
+  capture". Steps 1, 2 and 6 stay the same.
+
 ## Workflow
 
 ### 1. Map the diff to views, then get the user's go-ahead
@@ -96,6 +104,10 @@ hidden ref on the remote and embed them in the PR. Include the proposed plan: wh
 device projects — default to the config's `deviceProjects`; add more only when
 the change is layout-sensitive. If they decline, create the PR normally and stop.
 
+In an unattended session (nobody answers questions, as on the agent-ops box),
+do not ask: run the capture with the plan above and name the plan in the PR
+body.
+
 ### 2. Write the capture spec
 
 Copy `references/capture-spec-template.ts` from this skill into
@@ -133,7 +145,10 @@ That assertion is a backstop, not a substitute for looking: the subagent still
 Reads each PNG after capture — an empty state, error toast, or wrong content
 passes the spinner check but is still wrong. On a genuine failure, fix the spec
 (add mock stubs, a wait for a stable element, or correct the spinner selector)
-rather than shipping a bad screenshot.
+rather than shipping a bad screenshot. A fixed element (a mobile bottom nav, a
+sticky header) is drawn where the viewport was, so in a full-page shot it can
+float over the middle of the page: give such a view `fullPage: false`, or one
+shot per scroll position.
 
 ### 4. Capture "before" (merge base, temp worktree)
 
@@ -239,6 +254,74 @@ cell instead of an image:
 | **Mobile** | _New view_ | ![](<blob-url>?raw=true) |
 ```
 
+## Remote capture
+
+Replaces steps 3–5. The subagent rule above still holds.
+
+The steps run in one shared workflow, `.github/workflows/pr-visual-diff.yml` of
+jesdi/general-skills. Each target repo has a short caller of it, made from
+`references/capture-caller.yml` of this skill, which follows the main branch
+of general-skills: GitHub starts `workflow_dispatch` only in the target repo.
+
+**Precondition.** The default branch of the target repo has the caller,
+`.github/workflows/pr-visual-diff.yml`:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+gh api "repos/$REPO/contents/.github/workflows/pr-visual-diff.yml" --silent
+```
+
+If it does not, take no screenshots. Say in the PR body that the repo has no
+pr-visual-diff workflow, and that `references/capture-caller.yml` of this
+skill, filled from the discovery cache and merged to the default branch, adds
+it. Do not add it in this PR: `workflow_dispatch` runs only from the default
+branch.
+
+**Dispatch.** Push the PR branch first: the workflow checks out commits of
+origin. Write the filled spec of step 2 to a file, and a second copy whose
+`VIEWS` holds only the views that exist at the merge base (none: no Before).
+Then:
+
+```bash
+HEAD_SHA=$(git rev-parse HEAD)
+BASE=$(git merge-base origin/<baseBranch> HEAD)
+SLUG=$(git branch --show-current | tr / -)
+CAPTURE="${HEAD_SHA:0:12}-$(date +%s)"
+gh workflow run pr-visual-diff.yml --ref <baseBranch> \
+  -f capture="$CAPTURE" -f slug="$SLUG" -f head="$HEAD_SHA" -f base="$BASE" \
+  -f after_spec="$(base64 < <after-spec> | tr -d '\n')" \
+  -f before_spec="$(base64 < <before-spec> | tr -d '\n')" \
+  -f projects="<deviceProject>,<deviceProject>"
+```
+
+Leave `before_spec` empty when every view is new. `gh workflow run` prints no
+run id: find the run by its name `pr-visual-diff $CAPTURE` (try for up to a
+minute), then wait for it:
+
+```bash
+RUN=$(gh run list --workflow pr-visual-diff.yml --limit 20 --json databaseId,displayTitle \
+  --jq ".[] | select(.displayTitle == \"pr-visual-diff $CAPTURE\") | .databaseId")
+gh run watch "$RUN" --exit-status
+```
+
+**A failed run.** Read `gh run view "$RUN" --log-failed | tail -80`. Fix the
+spec as in step 3 (a mock stub, a wait, the spinner selector) and dispatch
+once more with a new `CAPTURE`. When the second run fails too, take no
+screenshots and say why in the PR body.
+
+**Read the shots back.** Fetch the hidden ref and look at every PNG, as in
+step 3:
+
+```bash
+git fetch origin "refs/pr-screenshots/$SLUG/$CAPTURE"
+SHA=$(git rev-parse FETCH_HEAD)
+mkdir -p <scratchpad>/shots && git archive "$SHA" | tar -x -C <scratchpad>/shots
+```
+
+A wrong shot is a failed run: fix the spec and dispatch again, under the same
+limit. Then embed with step 6, with `$SHA` in the URLs. The ref stays: it keeps
+the images alive.
+
 ## Adding shots to an existing PR
 
 Same flow; the only differences: diff against the PR's base branch

package/skills/pr-visual-diff/references/capture-caller.yml

@@ -0,0 +1,56 @@
+# pr-visual-diff remote capture of this repo. Template of the pr-visual-diff
+# skill (references/capture-caller.yml): copy it to
+# .github/workflows/pr-visual-diff.yml, replace every __PVD_*__ marker with the
+# value of the discovery cache, and merge it to the default branch:
+# workflow_dispatch runs only from there. The steps live in jesdi/general-skills
+# (.github/workflows/pr-visual-diff.yml) and follow its main branch, like every
+# jesdi skill follows its latest release.
+
+name: pr-visual-diff
+run-name: pr-visual-diff ${{ inputs.capture }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      capture:
+        description: 'Unique id of this capture; the last part of the hidden ref'
+        required: true
+      slug:
+        description: 'The PR branch with / as -'
+        required: true
+      head:
+        description: 'Commit captured as After'
+        required: true
+      base:
+        description: 'Commit captured as Before (the merge base)'
+        required: true
+      after_spec:
+        description: 'The filled capture spec, base64'
+        required: true
+      before_spec:
+        description: 'The filled capture spec of the views that exist at base, base64; empty: no Before'
+        required: false
+        default: ''
+      projects:
+        description: 'Playwright projects, separated by commas'
+        required: true
+
+jobs:
+  capture:
+    permissions:
+      contents: write  # only its publish job uses it, to push the hidden ref
+    uses: jesdi/general-skills/.github/workflows/pr-visual-diff.yml@main
+    with:
+      capture: ${{ inputs.capture }}
+      slug: ${{ inputs.slug }}
+      head: ${{ inputs.head }}
+      base: ${{ inputs.base }}
+      after_spec: ${{ inputs.after_spec }}
+      before_spec: ${{ inputs.before_spec }}
+      projects: ${{ inputs.projects }}
+      runner: __PVD_RUNNER__
+      frontend_dir: __PVD_FRONTEND_DIR__
+      specs_dir: __PVD_SPECS_DIR__
+      browsers: __PVD_BROWSERS__
+      node_version: '__PVD_NODE_VERSION__'
+      pnpm_version: '__PVD_PNPM_VERSION__'

package/skills/pr-visual-diff/references/capture-spec-template.ts

@@ -26,7 +26,7 @@ const OUT = process.env.PR_SHOT_DIR;
 const LABEL = process.env.PR_SHOT_LABEL ?? 'after';
 if (!OUT) throw new Error('PR_SHOT_DIR must be set to an absolute output directory');
 
-// Selector for this app's loading indicator. From config: <spinnerSelector>.
+// Every loading indicator of this app, spinners and skeletons. From config: <spinnerSelector>.
 const SPINNER = '__PVD_SPINNER_SELECTOR__';
 
 // Pin device-pixel-ratio to 1 for every project. Device descriptors (iPhone 14,

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-14T03:34:13.674Z",
+  "generatedAt": "2026-10-15T12:44:26.687Z",
   "skills": [
     {
       "name": "backlog",
@@ -46,14 +46,14 @@
     },
     {
       "name": "implement-spec",
-      "version": "0.1.8",
-      "hash": "sha256-cafda530227caa971251cbe0d677f758630f96d6178f75a5e32b93417efe033e",
+      "version": "0.1.9",
+      "hash": "sha256-a2864cb6013ba8ee10af5b597b4376b89507efce8c6acecfbeca5db7389623ea",
       "description": "Implement a specification in code."
     },
     {
       "name": "pr-visual-diff",
-      "version": "0.1.1",
-      "hash": "sha256-c90f308a7529ead883b4c379d034724a33da43e91f2d8ba0f2bdc5d79c894df2",
+      "version": "0.1.2",
+      "hash": "sha256-df10fb424564e7721856a88a9bafeeb077041244faa949711ff92d5490fb7854",
       "description": "Capture before/after screenshots of UI views with Playwright and embed them in a PR. Use this skill whenever creating or preparing a pull request that touches frontend code (components, views, styles, layout, Tailwind classes) — even if the user just says \"open a PR\" or \"create the PR\" after UI work, and especially if they mention screenshots, visual diff, before/after, or \"show what changed\". Also use when the user asks to add screenshots to an existing PR."
     },
     {