feat(pages): agents offer a page when their output has a reader
Links
- Linear: SUPER-2187 — Pages need onboarding
- Parity study: Pages onboarding — parity study
- Supersedes: #7729 (this is item 1 of that PR, on its own)
Summary
One file. plugins/superset/skills/page/SKILL.md now tells agents to offer a page
when they finish output that has a reader and wants a link: a change or PR
walkthrough, a comparison, a report or digest, an incident writeup, verification
screenshots. One line, then stop and wait.
The frontmatter description names the unprompted case too, so the skill loads
when an agent finishes reader-facing work rather than only when someone types
"page".
Why
Pages has the hard part working: a teammate pins a comment on a published page,
it routes back to an agent, the agent republishes. The cold start is the
opposite problem. Nothing in the product proposes a page to you, so the feature
only reaches people who already know it exists and think to ask.
The parity study compared this against Claude Artifacts, Claude Code Artifacts
and Plannotator. We scored zero on three rows, all the same failure: nothing
happens until the user already knows what a page is.
The offer is the cheapest fix for that, and the only one that reaches every
surface at once — every agent in every workspace reads this skill, so it needs
no UI, no feature flag, and no locale catalog.
How it is bounded
An offer attached to every reply is noise that trains people to ignore the one
that matters, so the section is fenced on both sides:
- an explicit list of output shapes that earn an offer, not "when it seems useful"
- stay quiet for ordinary replies: a quick fix, a two-sentence answer, a file edit
- one line, then stop and let them answer — never a silent publish, because a
page the user didn't want still lands in the org's list - a turned-down offer is the user's standing preference for the rest of the session
- when the user asked for a page outright, skip the offer and just build it
Putting the restraint in prose beside the trigger is the only place that reaches
every agent reading the skill.
What is deliberately not here
#7729 also carried five named starters in the Pages empty state and a miniature
rendered-page preview. Both are dropped.
The starters were reached only from the empty state, which means only an org
that has never published a page ever sees them — exactly the org least likely to
be in the Pages view in the first place. If we want starters, they belong in the
page header's Create menu, where an org that already has pages can reach them
too. That is a follow-up on top of #7726, not part of this change.
Dropping them also drops the 17 locale catalogs #7729 had to touch, which is
most of why that PR was large.
Testing
bun test packages/agent-setup/src/bundled-skills.test.ts— 92 pass, 0 fail.
This is the gate that matters here: it enforces the Agent Skills spec on every
bundled skill, including the em-dash rule, the frontmatter key allowlist, the
1024-char description cap and the 500-line body budget.- Headroom after this change: description 832 / 1024 chars, body 433 / 500
lines. Both fine, but the body budget is the one to watch next time someone adds
a section to this skill. - No code changes, so there is no typecheck or i18n surface: the diff is one
Markdown file, and none of the added prose is user-facing interface copy.
bun run check:plugins passes ("All plugins are valid and published"), but it does
not actually cover this file, which is worth writing down
because the AGENTS.md note on plugins implies it does. That check iterates the
entries in .agent-marketplace.json, and plugins/superset is not one of them —
it is a bundled plugin, not a marketplace-published one. So no
superset plugins publish --bump patch and no plugin.json bump is needed here,
which matches the last five merged PRs that edited this same file (#7726, #7573,
#7531, #7474, #7312), none of which touched plugins/superset/plugin.json.
Out of scope
Items 4-7 of the parity study remain unbuilt, and #7730 (the reader hint and the
sidebar waiting badge) is closed alongside #7729 rather than landing here.
Summary by cubic
Fixes Pages' cold-start problem by teaching the page skill to offer a page unprompted when an agent finishes output a teammate will read, instead of only responding when someone asks for a page.
- Adds an
### Offer one before you are askedsection with a bounded trigger list: walkthroughs, comparisons, reports or digests, incident writeups, verification screenshots, and long terminal output. - The offer is one line, then the agent stops and waits; a turned-down offer is treated as the user's standing preference for the session, and the skill is skipped when the user already asked for a page outright.
- Updates the frontmatter
descriptionso the skill also loads for unprompted reader-facing work; no other code, UI, or skill files changed. - Verified with
bun test packages/agent-setup/src/bundled-skills.test.ts— the description measures 832/1024 chars and the body 433/500 lines.
Summary by CodeRabbit
- New Features
- The assistant may offer to publish a page after preparing shareable content, such as a report, comparison, walkthrough, incident writeup, or verification evidence. It waits for your answer before publishing, publishes only if you agree, and won’t repeat the offer for the same work. If you decline, the assistant treats that as your preference for the rest of the session. The offer is skipped for ordinary answers, file edits, and requests where you explicitly asked for a page.