Skip to content

The open-source app everyone uses to manage agents at work

feat: add pr-report skill

Dottafbf9d5714f16
diff --git a/skills/pr-report/SKILL.md b/skills/pr-report/SKILL.md
new file mode 100644
index 0000000000..5064b67c09
--- /dev/null
+++ b/skills/pr-report/SKILL.md
@@ -0,0 +1,202 @@
+---
+name: pr-report
+description: >
+ Review a pull request or contribution deeply, explain it tutorial-style for a
+ maintainer, and produce a polished report artifact such as HTML or Markdown.
+ Use when asked to analyze a PR, explain a contributor's design decisions,
+ compare it with similar systems, or prepare a merge recommendation.
+---
+
+# PR Report Skill
+
+Produce a maintainer-grade review of a PR, branch, or large contribution.
+
+Default posture:
+
+- understand the change before judging it
+- explain the system as built, not just the diff
+- separate architectural problems from product-scope objections
+- make a concrete recommendation, not a vague impression
+
+## When to Use
+
+Use this skill when the user asks for things like:
+
+- "review this PR deeply"
+- "explain this contribution to me"
+- "make me a report or webpage for this PR"
+- "compare this design to similar systems"
+- "should I merge this?"
+
+## Outputs
+
+Common outputs:
+
+- standalone HTML report in `tmp/reports/...`
+- Markdown report in `report/` or another requested folder
+- short maintainer summary in chat
+
+If the user asks for a webpage, build a polished standalone HTML artifact with
+clear sections and readable visual hierarchy.
+
+Resources bundled with this skill:
+
+- `references/style-guide.md` for visual direction and report presentation rules
+- `assets/html-report-starter.html` for a reusable standalone HTML/CSS starter
+
+## Workflow
+
+### 1. Acquire and frame the target
+
+Work from local code when possible, not just the GitHub PR page.
+
+Gather:
+
+- target branch or worktree
+- diff size and changed subsystems
+- relevant repo docs, specs, and invariants
+- contributor intent if it is documented in PR text or design docs
+
+Start by answering: what is this change *trying* to become?
+
+### 2. Build a mental model of the system
+
+Do not stop at file-by-file notes. Reconstruct the design:
+
+- what new runtime or contract exists
+- which layers changed: db, shared types, server, UI, CLI, docs
+- lifecycle: install, startup, execution, UI, failure, disablement
+- trust boundary: what code runs where, under what authority
+
+For large contributions, include a tutorial-style section that teaches the
+system from first principles.
+
+### 3. Review like a maintainer
+
+Findings come first. Order by severity.
+
+Prioritize:
+
+- behavioral regressions
+- trust or security gaps
+- misleading abstractions
+- lifecycle and operational risks
+- coupling that will be hard to unwind
+- missing tests or unverifiable claims
+
+Always cite concrete file references when possible.
+
+### 4. Distinguish the objection type
+
+Be explicit about whether a concern is:
+
+- product direction
+- architecture
+- implementation quality
+- rollout strategy
+- documentation honesty
+
+Do not hide an architectural objection inside a scope objection.
+
+### 5. Compare to external precedents when needed
+
+If the contribution introduces a framework or platform concept, compare it to
+similar open-source systems.
+
+When comparing:
+
+- prefer official docs or source
+- focus on extension boundaries, context passing, trust model, and UI ownership
+- extract lessons, not just similarities
+
+Good comparison questions:
+
+- Who owns lifecycle?
+- Who owns UI composition?
+- Is context explicit or ambient?
+- Are plugins trusted code or sandboxed code?
+- Are extension points named and typed?
+
+### 6. Make the recommendation actionable
+
+Do not stop at "merge" or "do not merge."
+
+Choose one:
+
+- merge as-is
+- merge after specific redesign
+- salvage specific pieces
+- keep as design research
+
+If rejecting or narrowing, say what should be kept.
+
+Useful recommendation buckets:
+
+- keep the protocol/type model
+- redesign the UI boundary
+- narrow the initial surface area
+- defer third-party execution
+- ship a host-owned extension-point model first
+
+### 7. Build the artifact
+
+Suggested report structure:
+
+1. Executive summary
+2. What the PR actually adds
+3. Tutorial: how the system works
+4. Strengths
+5. Main findings
+6. Comparisons
+7. Recommendation
+
+For HTML reports:
+
+- use intentional typography and color
+- make navigation easy for long reports
+- favor strong section headings and small reference labels
+- avoid generic dashboard styling
+
+Before building from scratch, read `references/style-guide.md`.
+If a fast polished starter is helpful, begin from `assets/html-report-starter.html`
+and replace the placeholder content with the actual report.
+
+### 8. Verify before handoff
+
+Check:
+
+- artifact path exists
+- findings still match the actual code
+- any requested forbidden strings are absent from generated output
+- if tests were not run, say so explicitly
+
+## Review Heuristics
+
+### Plugin and platform work
+
+Watch closely for:
+
+- docs claiming sandboxing while runtime executes trusted host processes
+- module-global state used to smuggle React context
+- hidden dependence on render order
+- plugins reaching into host internals instead of using explicit APIs
+- "capabilities" that are really policy labels on top of fully trusted code
+
+### Good signs
+
+- typed contracts shared across layers
+- explicit extension points
+- host-owned lifecycle
+- honest trust model
+- narrow first rollout with room to grow
+
+## Final Response
+
+In chat, summarize:
+
+- where the report is
+- your overall call
+- the top one or two reasons
+- whether verification or tests were skipped
+
+Keep the chat summary shorter than the report itself.
diff --git a/skills/pr-report/assets/html-report-starter.html b/skills/pr-report/assets/html-report-starter.html
new file mode 100644
index 0000000000..be6f0550c8
--- /dev/null
+++ b/skills/pr-report/assets/html-report-starter.html
@@ -0,0 +1,426 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <title>PR Report Starter</title>
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link
+ href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=Newsreader:opsz,[email protected],500;6..72,700&display=swap"
+ rel="stylesheet"
+ />
+ <style>
+ :root {
+ --bg: #f4efe5;
+ --paper: rgba(255, 251, 244, 0.88);
+ --paper-strong: #fffaf1;
+ --ink: #1f1b17;
+ --muted: #6a6257;
+ --line: rgba(31, 27, 23, 0.12);
+ --accent: #9c4729;
+ --accent-soft: rgba(156, 71, 41, 0.1);
+ --good: #2f6a42;
+ --warn: #946200;
+ --bad: #8c2f25;
+ --shadow: 0 22px 60px rgba(52, 37, 19, 0.1);
+ --radius: 20px;
+ }
+
+ * {
+ box-sizing: border-box;
+ }
+
+ html {
+ scroll-behavior: smooth;
+ }
+
+ body {
+ margin: 0;
+ color: var(--ink);
+ font-family: "IBM Plex Sans", sans-serif;
+ background:
+ radial-gradient(circle at top left, rgba(156, 71, 41, 0.12), transparent 34rem),
+ radial-gradient(circle at top right, rgba(47, 106, 66, 0.08), transparent 28rem),
+ linear-gradient(180deg, #efe6d6 0%, var(--bg) 48%, #ece5d8 100%);
+ }
+
+ .shell {
+ width: min(1360px, calc(100vw - 32px));
+ margin: 24px auto;
+ display: grid;
+ grid-template-columns: 280px minmax(0, 1fr);
+ gap: 24px;
+ }
+
+ .panel {
+ background: var(--paper);
+ backdrop-filter: blur(12px);
+ border: 1px solid var(--line);
+ border-radius: var(--radius);
+ box-shadow: var(--shadow);
+ }
+
+ .nav {
+ position: sticky;
+ top: 20px;
+ align-self: start;
+ padding: 22px;
+ }
+
+ .eyebrow {
+ letter-spacing: 0.12em;
+ text-transform: uppercase;
+ font-size: 11px;
+ font-weight: 700;
+ color: var(--accent);
+ }
+
+ .nav h1,
+ .hero h1,
+ h2,
+ h3 {
+ font-family: "Newsreader", serif;
+ line-height: 0.96;
+ margin: 0;
+ }
+
+ .nav h1 {
+ font-size: 2rem;
+ margin-top: 10px;
+ }
+
+ .nav p {
+ color: var(--muted);
+ font-size: 0.95rem;
+ line-height: 1.5;
+ }
+
+ .nav ul {
+ list-style: none;
+ padding: 0;
+ margin: 18px 0 0;
+ display: grid;
+ gap: 10px;
+ }
+
+ .nav a {
+ display: block;
+ color: var(--ink);
+ text-decoration: none;
+ padding: 10px 12px;
+ border-radius: 12px;
+ border: 1px solid transparent;
+ background: rgba(255, 255, 255, 0.35);
+ }
+
+ .nav a:hover {
+ border-color: var(--line);
+ background: rgba(255, 255, 255, 0.75);
+ }
+
+ .meta-block {
+ margin-top: 20px;
+ padding-top: 18px;
+ border-top: 1px solid var(--line);
+ color: var(--muted);
+ font-size: 0.86rem;
+ line-height: 1.5;
+ }
+
+ main {
+ display: grid;
+ gap: 24px;
+ }
+
+ section {
+ padding: 26px 28px 28px;
+ }
+
+ .hero {
+ padding: 28px;
+ overflow: hidden;
+ position: relative;
+ }
+
+ .hero::after {
+ content: "";
+ position: absolute;
+ inset: auto -3rem -6rem auto;
+ width: 18rem;
+ height: 18rem;
+ border-radius: 50%;
+ background: radial-gradient(circle, rgba(156, 71, 41, 0.14), transparent 68%);
+ pointer-events: none;
+ }
+
+ .hero h1 {
+ font-size: clamp(2.6rem, 5vw, 4.6rem);
+ max-width: 12ch;
+ margin-top: 12px;
+ }
+
+ .lede {
+ margin-top: 16px;
+ max-width: 70ch;
+ font-size: 1.05rem;
+ line-height: 1.65;
+ color: #2b2723;
+ }
+
+ .hero-grid,
+ .card-grid,
+ .two-col {
+ display: grid;
+ gap: 14px;
+ }
+
+ .hero-grid {
+ margin-top: 24px;
+ grid-template-columns: repeat(4, minmax(0, 1fr));
+ }
+
+ .card-grid {
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ }
+
+ .two-col {
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ }
+
+ .metric,
+ .card,
+ .finding {
+ padding: 18px;
+ background: rgba(255, 255, 255, 0.68);
+ border: 1px solid var(--line);
+ border-radius: 18px;
+ }
+
+ .metric .label {
+ color: var(--muted);
+ font-size: 0.82rem;
+ text-transform: uppercase;
+ letter-spacing: 0.08em;
+ }
+
+ .metric .value {
+ margin-top: 8px;
+ font-size: 1.45rem;
+ font-weight: 700;
+ }
+
+ h2 {
+ font-size: 2rem;
+ margin-bottom: 16px;
+ }
+
+ h3 {
+ font-size: 1.3rem;
+ margin-bottom: 10px;
+ }
+
+ p {
+ margin: 0 0 14px;
+ line-height: 1.65;
+ }
+
+ ul,
+ ol {
+ margin: 0;
+ padding-left: 20px;
+ line-height: 1.65;
+ }
+
+ li + li {
+ margin-top: 8px;
+ }
+
+ .badge-row {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 8px;
+ margin: 18px 0 8px;
+ }
+
+ .badge {
+ display: inline-flex;
+ align-items: center;
+ gap: 8px;
+ padding: 8px 10px;
+ border-radius: 999px;
+ font-size: 0.82rem;
+ font-weight: 700;
+ border: 1px solid var(--line);
+ background: rgba(255, 255, 255, 0.68);
+ }
+
+ .badge.good {
+ color: var(--good);
+ }
+
+ .badge.warn {
+ color: var(--warn);
+ }
+
+ .badge.bad {
+ color: var(--bad);
+ }
+
+ .quote {
+ margin-top: 18px;
+ padding: 18px;
+ border-left: 4px solid var(--accent);
+ border-radius: 14px;
+ background: var(--accent-soft);
+ }
+
+ .severity {
+ display: inline-flex;
+ margin-bottom: 12px;
+ padding: 6px 10px;
+ border-radius: 999px;
+ font-size: 0.78rem;
+ font-weight: 700;
+ text-transform: uppercase;
+ letter-spacing: 0.08em;
+ }
+
+ .severity.high {
+ background: rgba(140, 47, 37, 0.12);
+ color: var(--bad);
+ }
+
+ .severity.medium {
+ background: rgba(148, 98, 0, 0.12);
+ color: var(--warn);
+ }
+
+ .severity.low {
+ background: rgba(47, 106, 66, 0.12);
+ color: var(--good);
+ }
+
+ .ref {
+ color: var(--muted);
+ font-size: 0.82rem;
+ line-height: 1.5;
+ }
+
+ @media (max-width: 980px) {
+ .shell {
+ grid-template-columns: 1fr;
+ }
+
+ .nav {
+ position: static;
+ }
+
+ .hero-grid,
+ .card-grid,
+ .two-col {
+ grid-template-columns: 1fr;
+ }
+
+ .hero h1 {
+ max-width: 100%;
+ }
+ }
+ </style>
+ </head>
+ <body>
+ <div class="shell">
+ <aside class="panel nav">
+ <div class="eyebrow">Maintainer Report</div>
+ <h1>Report Title</h1>
+ <p>Replace this with a concise description of what the report covers.</p>
+ <ul>
+ <li><a href="#summary">Summary</a></li>
+ <li><a href="#tutorial">Tutorial</a></li>
+ <li><a href="#findings">Findings</a></li>
+ <li><a href="#recommendation">Recommendation</a></li>
+ </ul>
+ <div class="meta-block">
+ Replace with project metadata, review date, or scope notes.
+ </div>
+ </aside>
+
+ <main>
+ <section class="panel hero" id="summary">
+ <div class="eyebrow">Executive Summary</div>
+ <h1>Use the hero for the clearest one-line judgment.</h1>
+ <p class="lede">
+ Replace this with the short explanation of what the contribution does, why it matters,
+ and what the core maintainer question is.
+ </p>
+ <div class="badge-row">
+ <span class="badge good">Strength</span>
+ <span class="badge warn">Tradeoff</span>
+ <span class="badge bad">Risk</span>
+ </div>
+ <div class="hero-grid">
+ <div class="metric">
+ <div class="label">Overall Call</div>
+ <div class="value">Placeholder</div>
+ </div>
+ <div class="metric">
+ <div class="label">Main Concern</div>
+ <div class="value">Placeholder</div>
+ </div>
+ <div class="metric">
+ <div class="label">Best Part</div>
+ <div class="value">Placeholder</div>
+ </div>
+ <div class="metric">
+ <div class="label">Weakest Part</div>
+ <div class="value">Placeholder</div>
+ </div>
+ </div>
+ <div class="quote">
+ Use this block for the thesis, a sharp takeaway, or a key cited point.
+ </div>
+ </section>
+
+ <section class="panel" id="tutorial">
+ <h2>Tutorial Section</h2>
+ <div class="two-col">
+ <div class="card">
+ <h3>Concept Card</h3>
+ <p>Use cards for mental models, subsystems, or comparison slices.</p>
+ <div class="ref">path/to/file.ts:10</div>
+ </div>
+ <div class="card">
+ <h3>Second Card</h3>
+ <p>Keep cards fairly dense. This template is about style, not fixed structure.</p>
+ <div class="ref">path/to/file.ts:20</div>
+ </div>
+ </div>
+ </section>
+
+ <section class="panel" id="findings">
+ <h2>Findings</h2>
+ <article class="finding">
+ <div class="severity high">High</div>
+ <h3>Finding Title</h3>
+ <p>Use findings for the sharpest judgment calls and risks.</p>
+ <div class="ref">path/to/file.ts:30</div>
+ </article>
+ </section>
+
+ <section class="panel" id="recommendation">
+ <h2>Recommendation</h2>
+ <div class="card-grid">
+ <div class="card">
+ <h3>Path Forward</h3>
+ <p>Use this area for merge guidance, salvage plan, or rollout advice.</p>
+ </div>
+ <div class="card">
+ <h3>What To Keep</h3>
+ <p>Call out the parts worth preserving even if the whole proposal should not land.</p>
+ </div>
+ </div>
+ </section>
+ </main>
+ </div>
+ </body>
+</html>
diff --git a/skills/pr-report/references/style-guide.md b/skills/pr-report/references/style-guide.md
new file mode 100644
index 0000000000..35158d1adc
--- /dev/null
+++ b/skills/pr-report/references/style-guide.md
@@ -0,0 +1,149 @@
+# PR Report Style Guide
+
+Use this guide when the user wants a report artifact, especially a webpage.
+
+## Goal
+
+Make the report feel like an editorial review, not an internal admin dashboard.
+The page should make a long technical argument easy to scan without looking
+generic or overdesigned.
+
+## Visual Direction
+
+Preferred tone:
+
+- editorial
+- warm
+- serious
+- high-contrast
+- handcrafted, not corporate SaaS
+
+Avoid:
+
+- default app-shell layouts
+- purple gradients on white
+- generic card dashboards
+- cramped pages with weak hierarchy
+- novelty fonts that hurt readability
+
+## Typography
+
+Recommended pattern:
+
+- one expressive serif or display face for major headings
+- one sturdy sans-serif for body copy and UI labels
+
+Good combinations:
+
+- Newsreader + IBM Plex Sans
+- Source Serif 4 + Instrument Sans
+- Fraunces + Public Sans
+- Libre Baskerville + Work Sans
+
+Rules:
+
+- headings should feel deliberate and large
+- body copy should stay comfortable for long reading
+- reference labels and badges should use smaller dense sans text
+
+## Layout
+
+Recommended structure:
+
+- a sticky side or top navigation for long reports
+- one strong hero summary at the top
+- panel or paper-like sections for each major topic
+- multi-column card grids for comparisons and strengths
+- single-column body text for findings and recommendations
+
+Use generous spacing. Long-form technical reports need breathing room.
+
+## Color
+
+Prefer muted paper-like backgrounds with one warm accent and one cool counterweight.
+
+Suggested token categories:
+
+- `--bg`
+- `--paper`
+- `--ink`
+- `--muted`
+- `--line`
+- `--accent`
+- `--good`
+- `--warn`
+- `--bad`
+
+The accent should highlight navigation, badges, and important labels. Do not
+let accent colors dominate body text.
+
+## Useful UI Elements
+
+Include small reusable styles for:
+
+- summary metrics
+- badges
+- quotes or callouts
+- finding cards
+- severity labels
+- reference labels
+- comparison cards
+- responsive two-column sections
+
+## Motion
+
+Keep motion restrained.
+
+Good:
+
+- soft fade/slide-in on first load
+- hover response on nav items or cards
+
+Bad:
+
+- constant animation
+- floating blobs
+- decorative motion with no reading benefit
+
+## Content Presentation
+
+Even when the user wants design polish, clarity stays primary.
+
+Good structure for long reports:
+
+1. executive summary
+2. what changed
+3. tutorial explanation
+4. strengths
+5. findings
+6. comparisons
+7. recommendation
+
+The exact headings can change. The important thing is to separate explanation
+from judgment.
+
+## References
+
+Reference labels should be visually quiet but easy to spot.
+
+Good pattern:
+
+- small muted text
+- monospace or compact sans
+- keep them close to the paragraph they support
+
+## Starter Usage
+
+If you need a fast polished base, start from:
+
+- `assets/html-report-starter.html`
+
+Customize:
+
+- fonts
+- color tokens
+- hero copy
+- section ordering
+- card density
+
+Do not preserve the placeholder sections if they do not fit the actual report.