Skip to content

feat(pages): agents offer a page when their output has a reader - #7759

Merged
harshithmullapudi merged 2 commits into
mainfrom
keep-the-skill.md-offer-sectio
Sep 29, 2026
Merged

harshithmullapudi merged 2 commits into
mainfrom
keep-the-skill.md-offer-sectio

Conversation

@harshithmullapudi

@harshithmullapudi harshithmullapudi commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

Links

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 asked section 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 description so 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.

Written for commit bdd3408. Summary will update on new commits.

Review in cubic

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.

The page skill only loaded when someone already knew to ask for a page,
so the feature's cold start depended on the user discovering it first.
Teach the skill to offer unprompted when an agent finishes output that
has a reader and wants a link, bounded on both sides so it cannot become
a nag: stay quiet for ordinary replies, treat a turned-down offer as a
standing preference for the session, and skip the offer when the user
asked for a page outright.

Supersedes the starters and empty-state preview from #7729. Starters
belong in the page header's Create menu, where orgs that already have
pages can reach them too, rather than in an empty state only a first-time
org ever sees.
@coderabbitai

coderabbitai Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 16d68098-696d-43cd-9184-a48d851fa424

📥 Commits

Reviewing files that changed from the base of the PR and between 403f642 and bdd3408.

📒 Files selected for processing (1)
  • plugins/superset/skills/page/SKILL.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.


📝 Walkthrough

Walkthrough

The page skill now includes teammate-facing work among the outputs that can prompt a page offer. It defines when to offer publication, how to handle acceptance or refusal, and when not to offer.

Changes

Page skill offer guidance

Layer / File(s) Summary
Proactive page offer guidance
plugins/superset/skills/page/SKILL.md
The skill description lists output types that may prompt a page offer. The guidance specifies how to make one offer, handle acceptance or refusal, and avoid offering for ordinary replies, file edits, direct page requests, or work with a declined offer.

Priority: ➖ Normal

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to bdd34

The skill now offers pages for specified shareable work while waiting for consent and preserving the existing publication guidance. No actionable merge risk was identified.

Architecture Summary

Architecture risk: 🔵 Low · up to bdd34

The change affects 1 system.

Changed systems: plugins

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — plugins (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in plugins/superset/skills/page/SKILL.md: The skill description adds teammate-facing outputs as a reason to use the page skill and directs the agent to offer a page after producing specified shareable work, in addition to responding to direct requests.
  • observed — Modified behavior in plugins/superset/skills/page/SKILL.md: Adds guidance to offer publication for specified reader-facing outputs, give one concise offer, and wait for the user’s decision. It says to publish on acceptance, not publish or repeat the offer after a decline, stay quiet for ordinary replies and file edits, and skip the offer for direct page requests.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title uses conventional commit format and clearly summarizes the main change: agents offer a page for reader-facing output.
Description check ✅ Passed The description explains what changed, why it changed, scope boundaries, testing performed, and out-of-scope items. It does not explicitly confirm every checklist item, but the required information is…
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches 💡 1
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
🛠️ Fix failing CI checks 💡
  • Commit to this branch
  • Create a new PR

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

  • ✅ Neon database branch

Thank you for your contribution! 🎉

@harshithmullapudi
harshithmullapudi merged commit a395d30 into main Sep 29, 2026
19 of 20 checks passed
Kitenite added a commit that referenced this pull request Oct 1, 2026
* docs: weekly update for PRs merged 2026-09-23 to 2026-09-30

Source of truth: live Notion SOP "Weekly Docs Update (automation SOP)".
Window: merged:>=2026-09-23 (139 PRs). PRs through the morning of 09-23
were covered by #7771.

Changes
- Pages: no auto-open on publish (#7790); page links and URL links split
  into their own settings (#7916, #7962, #7946); Listening agents menu with
  per-row stop and Add listening agent (#7724, #7820, #7919); globe on the
  Share button (#7766); Report on public pages (#7886); agents offer a page
  (#7759). Files: pages.mdx, cli/cli-reference.mdx.
- Settings moves: Links replaced by Browser and Files & Editor (#7916,
  #7962). Files: editor.mdx, terminal-integration.mdx, customization.mdx.
- Editor: inline rename and drag to move (#7692), Auto Save (#7693, #7916),
  open and save files outside the workspace (#7897, #7982), Copy as Markdown
  (#7591), per-pane error screen (#7983). File: editor.mdx.
- Terminal copy follows Ghostty's whitespace rules (#7868).
  File: terminal-integration.mdx.
- Agents: UFO (#7898); GPT-6 Astra, Sonnet 5.5, retiring GPT-5.5, retired
  GPT-5.4/5.3 Codex (#7783, #7894, #7935). Files: agent-integration.mdx,
  cli/cli-reference.mdx.
- Host: superset start --daemon --auto-update and update-lock permission
  errors (#7735, #7952). Files: cli/host-server.mdx, cli/cli-reference.mdx.
- Removed the mcp CLI section and the Connected Service Plugins section:
  #7776 made plugins/mcp internal, the Plugins page is staff-flagged, and
  apps/docs/AGENTS.md keeps internal commands out. Files: skills.mdx,
  cli/cli-reference.mdx.
- Slack page unfurls and details panel (#7817, #7821, #7914, #7957).
  File: use-with-slack.mdx.
- Workspaces: instant creation with background naming (#7518); recoverable
  project deletion (#7896). File: workspaces.mdx.
- Shortcuts: prev/next workspace includes Pinned and wraps (#7851); ⌘B
  collapses the sidebar to a rail (#7964). File: keyboard-shortcuts.mdx.
- Ship controls and open-in button moved to the right sidebar strip (#7958).
  Files: diff-viewer.mdx, use-with-ide.mdx.

Deliberately skipped
- Cloud workspaces/environments/sandboxes (flag-gated, AGENTS.md rule):
  #7784 #7795 #7824 #7840 #7844 #7845 #7847 #7849 #7850 #7858 #7861 #7863
  #7874 #7911 #7913 #7918 #7922 #7931 #7932 #7937 #7956 #7961 #7969 #7981
  #7637 #7794 #7789 #7838 (its CLI docs already shipped in the PR).
- Staff-only plugins: #7912 Sentry plugin, #7716, #7727, #7955.
- Already documented in their own PRs: #7917, #7921.
- Removed feature never documented: #7796 Google Calendar triggers.
- Agents chip remove/revert/default-off, never documented: #7870 #7871 #7872.
- Billing/backend policy with no docs surface: #7947, #7812, #7786, #7792,
  #7798, #7761, #7948, #7949, #7951, #7827.
- Reverted security trio: #7828 #7829 #7830 (reverted by #7834).
- Fixes restoring expected behavior: #7683 #7696 #7707 #7743 #7751 #7756
  #7764 #7765 #7781 #7788 #7791 #7823 #7825 #7833 #7837 #7852 #7857 #7860
  #7864 #7865 #7869 #7873 #7897-covered #7903 #7938 #7980 #7943 #7964-chrome.
- Mobile (no docs page): #7746 #7747 #7748 #7749 #7750 #7782 #7793 #7810
  #7814 #7816 #7889 #7968.
- Marketing, internal docs, CI, version bumps: #7651 #7744 #7752 #7771 #7774
  #7776-infra #7777 #7785 #7811 #7818 #7822 #7826 #7834 #7884 #7885 #7895
  #7909 #7933 #7934 #7942 #7944 #7965 #7966.

Validation: bun run --cwd apps/docs typecheck, bun run lint:fix,
bun run lint (exit 0), Vale on 13 changed files (0 errors, 0 warnings),
git diff --check.

* chore: log weekly docs update follow-ups

* docs: tighten review findings in the weekly update

Only the page creator can stop or add listening agents. On focus change also
saves on window blur, and Auto Save pauses on conflicts. Taken-down pages do
not unfurl. Model picker coverage matches agent-models.ts.

This branch was previously deployed

1 inactive deployment
preview — bdd3408c Deployed Sep 29, 2026 by harshithmullapudi via Deploy Admin #10535
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant