feat(skills): add docs authoring and maintenance skills

.claude/skills/capture-screenshots/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: capture-screenshots
+description: >-
+  Capture consistent Mergify dashboard screenshots for the docs site using
+  Chrome browser automation, save them to the correct images/ directory, and
+  emit the ready-to-paste astro:assets import and <Image> tag with alt text. Use
+  when adding or refreshing a dashboard/app screenshot in docs, when a docs page
+  needs a UI image, or when asked to screenshot app.mergify.com for
+  documentation. Drives the claude-in-chrome MCP tools against the user's
+  existing logged-in Chrome session.
+---
+
+# Capture Dashboard Screenshots
+
+Produce clean, consistent screenshots of the Mergify dashboard
+(`app.mergify.com`) and wire them into a docs page.
+
+## Prerequisite
+
+The user must already be **logged into app.mergify.com in Chrome**. This skill
+reuses the existing browser session through the claude-in-chrome MCP tools; it
+never handles credentials. If navigation lands on a login page, stop and ask the
+user to log in (`! open https://app.mergify.com`), then continue.
+
+## Load the browser tools first
+
+This skill targets the **claude-in-chrome** MCP server (a user/Claude Code-level
+MCP, not declared in this repo's `.claude/mcp.json`). The tool names below are its
+stable, documented interface. If you drive a different browser MCP, map each step
+to that server's equivalent capability — list tabs, create a tab, navigate,
+resize the window, run in-page JavaScript, read the page, capture a screenshot.
+
+If the `mcp__claude-in-chrome__*` tools are deferred, load them in ONE ToolSearch
+call before anything else:
+
+```
+ToolSearch select:mcp__claude-in-chrome__tabs_context_mcp,mcp__claude-in-chrome__tabs_create_mcp,mcp__claude-in-chrome__navigate,mcp__claude-in-chrome__resize_window,mcp__claude-in-chrome__computer,mcp__claude-in-chrome__read_page,mcp__claude-in-chrome__javascript_tool
+```
+
+## Workflow
+
+1. **Get tab context** — call `tabs_context_mcp` first to see current tabs. Do
+   NOT reuse an old tab unless the user asks; create a fresh one with
+   `tabs_create_mcp`.
+2. **Set a standard window size** — `resize_window` to the standard viewport
+   (see `references/conventions.md`). Consistency across screenshots matters more
+   than any single size.
+3. **Navigate** — `navigate` to the target dashboard URL. Wait for the page to
+   finish loading (`read_page` to confirm content is present).
+4. **Clean the frame** — dismiss overlays that would pollute the shot (cookie
+   banner, Intercom launcher, product tours). Use the dismissal snippets in
+   `references/conventions.md`. NEVER trigger a JS `alert`/`confirm`/`prompt` —
+   it freezes the extension.
+5. **Capture** — take the screenshot with the `computer` tool. Frame the relevant
+   region; capture the specific panel rather than the whole chrome when possible.
+6. **Save** — write the image to
+   `src/content/docs/images/<section>/<page>/<kebab-name>.png` following the
+   naming convention.
+7. **Emit the snippet** — output the ready-to-paste import + `<Image>` tag with
+   drafted alt text (see below). Hand it back so it can be dropped into the MDX
+   page (or applied directly if this was called from document-a-feature).
+
+## Output snippet format
+
+```mdx
+import { Image } from "astro:assets"
+import <camelCaseName> from "../../images/<section>/<page>/<kebab-name>.png"
+
+<Image src={<camelCaseName>} alt="<what the screenshot shows, specifically>" />
+```
+
+Alt text describes what the reader sees and why it matters, not "screenshot of
+dashboard". Example: `alt="Merge queue view showing two pull requests batched
+together"`.
+
+## Details
+
+Read `references/conventions.md` for: the standard viewport sizes, theme
+handling (light by default), the overlay-dismissal snippets, the
+`section/page/name` directory convention, common dashboard URLs, and tips for
+stable, repeatable framing.
+
+## Guardrails
+
+- Stop and ask if: a page won't load, you hit a login wall, or a tool errors
+  2–3 times. Do not loop on a failing browser action.
+- Capture a couple of extra frames if recording a flow with `gif_creator`, for
+  smooth playback.
+- Never commit screenshots that contain another customer's private data — use the
+  user's own org or a demo org.

.claude/skills/capture-screenshots/references/conventions.md

@@ -0,0 +1,99 @@
+# Screenshot Conventions
+
+Consistency is the whole point. Use the same viewport, theme, and framing across
+every docs screenshot so pages look coherent and re-captures diff cleanly.
+
+## Table of contents
+
+- [Viewport](#viewport)
+- [Theme](#theme)
+- [Directory & naming](#directory--naming)
+- [Overlay dismissal](#overlay-dismissal)
+- [Common dashboard URLs](#common-dashboard-urls)
+- [Stable framing tips](#stable-framing-tips)
+
+## Viewport
+
+Use `resize_window` before capturing. Standard sizes:
+
+| Purpose | Size |
+| --- | --- |
+| Default docs screenshot | 1440 × 900 |
+| Wide / full-table view | 1680 × 1050 |
+| Narrow / focused panel | 1024 × 768 |
+
+Default to **1440 × 900** unless the content needs more width. Astro + Sharp
+optimize and downscale on the site, so capture at the full standard size rather
+than a cramped window — never upscale a small capture.
+
+## Theme
+
+Capture in **light theme by default** (the docs render on a light surface and the
+existing screenshots are light). Only capture dark theme when the page is
+specifically about a dark-mode feature, and then keep light and dark variants
+side by side with matching framing.
+
+## Directory & naming
+
+Save to:
+
+```
+src/content/docs/images/<section>/<page>/<kebab-name>.png
+```
+
+- `<section>` mirrors the docs section (`merge-queue`, `integrations`,
+  `ci-insights`, …).
+- `<page>` is the page slug the image belongs to (omit if the section is flat and
+  matches existing layout — check neighbors first).
+- `<kebab-name>` describes the content: `queue-view-batched-prs.png`, not
+  `screenshot-1.png`.
+
+Match the existing layout under `src/content/docs/images/` — look before you
+create a new subfolder.
+
+## Overlay dismissal
+
+Remove chrome that pollutes the shot. Run via `javascript_tool`. These only
+remove elements from the DOM — they do NOT trigger dialogs.
+
+```js
+// Intercom launcher + messenger
+document.querySelectorAll(
+  '.intercom-lightweight-app, #intercom-container, [class*="intercom"]'
+).forEach((el) => el.remove());
+
+// Cookie / consent banners (adjust selector to what is present)
+document.querySelectorAll(
+  '[id*="cookie"], [class*="cookie-banner"], [class*="consent"]'
+).forEach((el) => el.remove());
+```
+
+NEVER call `alert`, `confirm`, or `prompt` from `javascript_tool` — a modal
+dialog freezes the extension and ends the session. Use `console.log` for
+debugging and read it back with `read_console_messages`.
+
+## Common dashboard URLs
+
+`app.mergify.com` (confirm against the live app; paths evolve):
+
+| Area | Path |
+| --- | --- |
+| Org dashboard | `/github/<org>` |
+| Merge queues | `/github/<org>/queues` |
+| CI Insights | `/github/<org>/ci-insights` |
+| Test Insights | `/github/<org>/tests` |
+| Settings | `/github/<org>/settings` |
+
+If a path 404s, navigate from the dashboard UI and read the resulting URL with
+`read_page` rather than guessing.
+
+## Stable framing tips
+
+- Wait until data has loaded (no spinners) before capturing — `read_page` to
+  confirm real content is present.
+- For re-captures (freshness updates), reuse the exact same viewport and URL so
+  the new image lines up with the one it replaces.
+- Prefer capturing a specific panel/region over the entire browser chrome; it
+  keeps the reader focused and survives unrelated UI changes.
+- Avoid capturing personal account names or other customers' data — use the
+  user's own org or a demo org.

.claude/skills/docs-gap-analysis/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: docs-gap-analysis
+description: >-
+  Find undocumented or stale Mergify features by comparing what the product
+  shipped against what the docs cover. Use when asked what is missing from the
+  docs, to audit docs coverage, to find undocumented features, to check whether
+  recent features/PRs are documented, or to plan documentation work. Gathers
+  shipped-feature signal from merged PRs, Linear, and the changelog, maps it
+  against src/content/docs/, and produces a prioritized gap report that feeds the
+  document-a-feature skill.
+---
+
+# Docs Gap Analysis
+
+Docs rot silently: the product ships, the docs don't follow, and nobody notices
+until a customer does. This skill surfaces the gap so it can be closed.
+
+The output is a prioritized report. Each item is shaped to hand straight to the
+**document-a-feature** skill.
+
+## Workflow
+
+Create a todo for each step.
+
+1. **Set the window.** Default to the last 90 days unless the user gives a range.
+   Convert to absolute dates.
+
+2. **Gather shipped-feature signal.** Read `references/signal-sources.md` for
+   exactly where to look and which tools to use. In short, pull from:
+   - **Changelog** (primary) — `src/content/changelog/` entries: the curated,
+     confirmed list of announced user-facing changes. Highest signal per token.
+     Read-only — NEVER edit these files.
+   - **Merged PRs** (supplementary) in `Mergifyio/monorepo` via `gh` — to catch
+     unannounced changes and get a specific feature's exact surface. The monorepo
+     is too active to enumerate fully; spot-check, don't sweep.
+   - **Linear** — completed issues/projects via the Linear MCP tools, for the
+     "why" framing.
+
+3. **Build a feature inventory.** Distill the signal into discrete, user-facing
+   capabilities. Drop pure refactors, internal-only changes, and bug fixes that
+   don't change documented behavior. For each capability note: name, the surface
+   it touches (config key / action / CLI / API / dashboard), and the source link.
+
+4. **Map against the docs.** For each capability, search `src/content/docs/`:
+   - `grep -ri "<feature name / config key / action>" src/content/docs/`
+   - Check whether the schema-driven references already cover new config/CLI
+     options (`OptionsTable`, `CliCommand` pull from the live schema, so a new
+     key may already render in a table while its prose context is missing).
+
+5. **Classify each capability:**
+   - **Undocumented** — no meaningful coverage anywhere.
+   - **Partial** — mentioned but missing setup, options, or context.
+   - **Stale** — documented, but the behavior described predates a change (the
+     PR/changelog says it changed; the docs still describe the old behavior).
+   - **Covered** — adequately documented (omit from the action list, count only).
+
+6. **Produce the report.** Prioritize by reader impact: customer-facing config /
+   merge-queue / protections behavior first; niche or advanced last. For each gap
+   give: capability, classification, the source link, the target docs page (or
+   "new page in `<section>/`"), and a one-line suggested action. Consider pushing
+   the report to the hublot kiosk for review.
+
+## Report format
+
+```
+## Docs Gap Report — <date range>
+
+### Undocumented (N)
+- <capability> — <surface> — src: <PR/Linear/changelog link>
+  → suggest: new page in <section>/ (use document-a-feature)
+
+### Partial (N)
+- <capability> — missing <what> on <page path>
+  → suggest: extend <page path>
+
+### Stale (N)
+- <capability> — <page path> describes old behavior; changed in <link>
+  → suggest: update <page path>
+
+### Covered: N capabilities (no action)
+```
+
+## Guardrails
+
+- Read-only on `src/content/changelog/` — it's a signal source, never an edit
+  target.
+- Don't flag internal/refactor PRs as doc gaps. Only user-facing capability
+  changes count.
+- Be honest about uncertainty: if you can't tell whether something is documented,
+  say "needs review" rather than asserting a gap.
+- The output is a plan, not edits. To actually write a page, hand the item to
+  document-a-feature.

.claude/skills/docs-gap-analysis/references/signal-sources.md

@@ -0,0 +1,94 @@
+# Signal Sources
+
+Where to find "what the product shipped", and how to query each source.
+
+## Table of contents
+
+- [Changelog (primary)](#changelog-primary)
+- [Merged PRs (supplementary)](#merged-prs-supplementary)
+- [Linear](#linear)
+- [The docs themselves](#the-docs-themselves)
+- [Schemas](#schemas)
+
+## Changelog (primary)
+
+Start here. `src/content/changelog/` is the curated, confirmed list of
+user-facing changes — every entry is an announced capability with a date, tags,
+and a one-line description. It is the highest-signal source per token and the
+practical primary for gap analysis. (It is autogenerated and **must never be
+edited** — read only.)
+
+```bash
+# Recent changelog entries by filename date
+ls src/content/changelog/ | sort -r | head -40
+```
+
+Treat each entry as a capability and map it against the docs. An entry whose
+linked docs page doesn't reflect it is a strong stale/partial candidate. The
+residual blind spot is a user-facing change that shipped but was not announced in
+the changelog — catch those with the supplementary PR sweep below.
+
+When an entry asserts a behavior change (e.g. a changed default), confirm it
+against the live schema before editing docs — the two can disagree (the schema
+is synced separately and may lag, or the default field may differ from runtime).
+If they conflict, flag it rather than guessing. See [Schemas](#schemas).
+
+## Merged PRs (supplementary)
+
+The product lives in `Mergifyio/monorepo` (engine + dashboard ship together).
+Use this to catch changes the changelog missed.
+
+> Volume warning: the monorepo is extremely active. A single `gh pr list` page
+> (max ~250 PRs) may only span ~2 weeks, so a full 90-day PR-by-PR sweep is not
+> feasible. Use PRs to spot-check recent activity and to get the exact surface of
+> a specific feature — not as the primary enumeration. Use the GitHub CLI; no
+> local checkout needed.
+
+```bash
+# Merged PRs in a window (adjust date)
+gh pr list --repo Mergifyio/monorepo --state merged --limit 200 \
+  --search "merged:>=2026-04-01" \
+  --json number,title,labels,mergedAt,url
+
+# Inspect one PR's user-facing surface
+gh pr view <num> --repo Mergifyio/monorepo --json title,body,files,labels
+```
+
+Focus on PRs whose title/body/labels indicate user-facing change: new config
+keys, new actions, new CLI commands/flags, new dashboard features, changed
+defaults or behavior. Ignore pure refactors, dependency bumps, internal tooling,
+and bug fixes that don't change documented behavior.
+
+## Linear (optional)
+
+If the Linear MCP tools are configured, use them (`list_issues`,
+`list_projects`, `get_issue`) to pull **completed** issues and shipped projects
+in the window. If Linear MCP is not available, skip it or work from the Linear
+UI / an export — the changelog already covers confirmed surface, so Linear is a
+nice-to-have for the "why" framing, not a hard dependency. Linear is best for the
+"why"; PRs are best for the exact surface. A Linear project often maps to several
+PRs.
+
+## The docs themselves
+
+To check coverage:
+
+```bash
+grep -ri "<feature name | config key | action name>" src/content/docs/
+```
+
+Remember the schema-driven components: a new config key may already appear in an
+`OptionsTable` (because it renders from the live schema) while having no prose
+explanation. "Appears in a generated table" is not the same as "documented" —
+look for the explanatory context, not just the key.
+
+## Schemas
+
+The committed schemas show the current full surface area; diffing intent against
+them helps spot keys/commands with no prose:
+
+- `public/mergify-configuration-schema.json` — all config keys/models
+- `public/cli-schema.json` — all CLI commands/flags
+- `public/api-schemas.json` — API endpoints
+
+A key present in the schema but absent from any prose page is a coverage gap.