From c8189f55d98f2abfdb61b33f08593eb7fe254831 Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Mon, 29 Jun 2026 18:48:50 +0200 Subject: [PATCH 1/2] feat(skills): add docs authoring and maintenance skills Add four project skills that compose into one docs workflow: - document-a-feature: end-to-end orchestrator (placement, component selection, writing, navItems/_redirects/SEO plumbing, proofread + config validation + build check) - capture-screenshots: Chrome MCP dashboard screenshots with consistent viewport, correct images/ path, and ready-to-paste astro:assets snippet - validate-config-examples: extract and classify YAML fences, validate real Mergify configs via `mergify config validate` - docs-gap-analysis: diff shipped product (PRs/Linear/changelog) against docs to surface undocumented/partial/stale features docs-gap-analysis finds the work, document-a-feature does it and calls the other two as tools; all reuse the existing mdx-documentation and proofread-* skills rather than duplicating them. No changelog skill by design (changelog entries are autogenerated and must not be touched). Co-Authored-By: Claude Opus 4.8 (1M context) Change-Id: Ie17e7c5434df6122f99d1904ae9eeaf6e71f2211 --- .claude/skills/capture-screenshots/SKILL.md | 90 +++++++++++ .../references/conventions.md | 99 ++++++++++++ .claude/skills/docs-gap-analysis/SKILL.md | 92 +++++++++++ .../references/signal-sources.md | 94 +++++++++++ .claude/skills/document-a-feature/SKILL.md | 125 +++++++++++++++ .../references/component-decision-table.md | 144 +++++++++++++++++ .../references/placement-guide.md | 111 +++++++++++++ .../skills/validate-config-examples/SKILL.md | 83 ++++++++++ .../scripts/extract_yaml.py | 149 ++++++++++++++++++ 9 files changed, 987 insertions(+) create mode 100644 .claude/skills/capture-screenshots/SKILL.md create mode 100644 .claude/skills/capture-screenshots/references/conventions.md create mode 100644 .claude/skills/docs-gap-analysis/SKILL.md create mode 100644 .claude/skills/docs-gap-analysis/references/signal-sources.md create mode 100644 .claude/skills/document-a-feature/SKILL.md create mode 100644 .claude/skills/document-a-feature/references/component-decision-table.md create mode 100644 .claude/skills/document-a-feature/references/placement-guide.md create mode 100644 .claude/skills/validate-config-examples/SKILL.md create mode 100755 .claude/skills/validate-config-examples/scripts/extract_yaml.py diff --git a/.claude/skills/capture-screenshots/SKILL.md b/.claude/skills/capture-screenshots/SKILL.md new file mode 100644 index 0000000000..83f388830f --- /dev/null +++ b/.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 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/
//.png` following the + naming convention. +7. **Emit the snippet** — output the ready-to-paste import + `` 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 from "../../images/
//.png" + +} alt="" /> +``` + +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. diff --git a/.claude/skills/capture-screenshots/references/conventions.md b/.claude/skills/capture-screenshots/references/conventions.md new file mode 100644 index 0000000000..8b408e43ed --- /dev/null +++ b/.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/
//.png +``` + +- `
` mirrors the docs section (`merge-queue`, `integrations`, + `ci-insights`, …). +- `` is the page slug the image belongs to (omit if the section is flat and + matches existing layout — check neighbors first). +- `` 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/` | +| Merge queues | `/github//queues` | +| CI Insights | `/github//ci-insights` | +| Test Insights | `/github//tests` | +| Settings | `/github//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. diff --git a/.claude/skills/docs-gap-analysis/SKILL.md b/.claude/skills/docs-gap-analysis/SKILL.md new file mode 100644 index 0000000000..bbf8f5594e --- /dev/null +++ b/.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 "" 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 `
/`"), and a one-line suggested action. Consider pushing + the report to the hublot kiosk for review. + +## Report format + +``` +## Docs Gap Report — + +### Undocumented (N) +- — — src: + → suggest: new page in
/ (use document-a-feature) + +### Partial (N) +- — missing on + → suggest: extend + +### Stale (N) +- — describes old behavior; changed in + → suggest: update + +### 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. diff --git a/.claude/skills/docs-gap-analysis/references/signal-sources.md b/.claude/skills/docs-gap-analysis/references/signal-sources.md new file mode 100644 index 0000000000..ac9fa7d760 --- /dev/null +++ b/.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 --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 "" 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. diff --git a/.claude/skills/document-a-feature/SKILL.md b/.claude/skills/document-a-feature/SKILL.md new file mode 100644 index 0000000000..3f6c7f9d7b --- /dev/null +++ b/.claude/skills/document-a-feature/SKILL.md @@ -0,0 +1,125 @@ +--- +name: document-a-feature +description: >- + End-to-end workflow for documenting a Mergify feature on the docs site. Use + when asked to document a feature, write a new docs page, document a PR or + Linear ticket, or add/update a page under src/content/docs/. Orchestrates + placement, component selection, writing, site plumbing (navItems + redirects + + SEO), and validation (proofread pipeline, config-example validation, build + check). Composes with mdx-documentation, proofread-*, capture-screenshots, and + validate-config-examples skills. +--- + +# Document a Feature + +The spine for turning a feature into a correct, fully-wired docs page. Follow the +checklist in order. Do not skip the plumbing or validation steps — a page that is +not in `navItems.tsx` is invisible, and a page that fails `pnpm check` cannot ship. + +This skill orchestrates other skills. Invoke them with the Skill tool when the +checklist points to them; do not duplicate their content here. + +## Checklist + +Create a todo for each step and complete them in order. + +1. **Gather context** — Understand the feature. +2. **Place the page** — Decide section, new-vs-edit, and URL path. +3. **Choose components** — Map content to the right components. +4. **Write the page** — Draft MDX following conventions. +5. **Wire the plumbing** — navItems, redirects, SEO. +6. **Add visuals** — Screenshots and diagrams if needed. +7. **Validate** — Proofread pipeline, config validation, build check. + +## Step 1 — Gather context + +Identify the source of truth for the feature: + +- **A PR**: `gh pr view --json title,body,files` (use the product repo + `Mergifyio/monorepo` for engine/dashboard changes). Read the diff to learn the + real config keys, CLI flags, and UI surfaces — never invent them. +- **A Linear ticket**: use the Linear MCP tools if they are configured; + otherwise read the issue from the Linear UI or have the user paste its + acceptance criteria. +- **A description**: work from what the user gave you; ask only if a fact you + cannot derive (exact key name, plan availability) is missing. + +Establish: what the feature does, who uses it, the exact config/CLI/API surface, +and any plan/tier gating. + +## Step 2 — Place the page + +Read `references/placement-guide.md` for the full section map and decision rules. + +Decide: + +- **Which section** under `src/content/docs/` the feature belongs to. +- **New page vs. edit existing** — search for existing coverage first + (`grep -ri "" src/content/docs/`). Extending an existing page is + usually better than adding a thin new one. +- **The URL path** — match sibling naming (kebab-case, no `.mdx` in links). + +## Step 3 — Choose components + +Read `references/component-decision-table.md`. It maps each kind of content +(config reference, CLI reference, callouts, video, integration logo, CI upload +steps, interactive tables) to the right component, with import paths and props. + +Prefer the schema-driven components (`OptionsTable`, `ActionOptionsTable`, +`CliCommand`) over hand-written tables — they stay in sync with the product +automatically. + +## Step 4 — Write the page + +Invoke the **mdx-documentation** skill for frontmatter, imports, heading +hierarchy, callouts, and the complete-page example. + +While drafting, already obey the **proofread-style** rules (no em dashes, no +"let's" openers, no corporate jargon, assume the reader knows CI/Git/PRs) so the +later proofread pass is a check, not a rewrite. + +Required frontmatter: `title` and `description`. The `description` doubles as the +SEO meta description and OpenGraph description — write it for a human searching, +~120–155 characters. + +## Step 5 — Wire the plumbing + +A page is not done until it is reachable. See `references/placement-guide.md` for +exact snippets. + +1. **Navigation** — add a `NavItem` to `src/content/navItems.tsx` at the correct + nesting level, with `title`, `path`, and an `icon` (lucide / octicon / + simple-icons / mergify namespace — match siblings). +2. **Redirects** — if you renamed or moved a path, add a 301 line to + `public/_redirects` (`/old/path /new/path 301`). Never break an existing URL. +3. **SEO** — confirm the `description` is present and a reasonable length. + +## Step 6 — Add visuals + +- **Screenshots** of the Mergify dashboard: invoke the **capture-screenshots** + skill. It produces consistent images in the right `images/` subdir plus the + ready-to-paste `astro:assets` import and `` tag with alt text. +- **Diagrams** (lifecycles, flows): use Graphviz `dot` code blocks — see + mdx-documentation for the styled template. + +## Step 7 — Validate + +Run these before claiming the page is done: + +1. **Proofread pipeline** — if total changed/added docs lines ≥ 10, spawn the 4 + proofread subagents in parallel per the repo CLAUDE.md (`proofread-style`, + `proofread-technical`, `proofread-structure`, `proofread-consistency`) on the + diff. +2. **Config examples** — if the page contains any YAML/`.mergify.yml` snippets, + invoke the **validate-config-examples** skill. +3. **Build check** — run `pnpm check` (astro check + eslint + biome). Fix any + errors. For a final SSG sanity check, `pnpm build`. + +## Hard rules + +- **Never** create, edit, or delete files in `src/content/changelog/` — those are + autogenerated externally. +- **Never** hardcode image paths or use raw `![]()` markdown for images — use + `astro:assets` ``. +- **Never** add an H1 in body content — the title becomes the H1. +- Match existing patterns over inventing new ones. diff --git a/.claude/skills/document-a-feature/references/component-decision-table.md b/.claude/skills/document-a-feature/references/component-decision-table.md new file mode 100644 index 0000000000..82d3cf0233 --- /dev/null +++ b/.claude/skills/document-a-feature/references/component-decision-table.md @@ -0,0 +1,144 @@ +# Component Decision Table + +Which component to reach for, by content type. All live in `src/components/`. +Import with the `~/components/...` alias or a relative path. React components are +`.tsx`, Astro components are `.astro`. + +## Table of contents + +- [Quick map](#quick-map) +- [Config & reference tables (schema-driven)](#config--reference-tables-schema-driven) +- [Callouts](#callouts) +- [Media](#media) +- [Integration & CI pages](#integration--ci-pages) +- [Layout & navigation](#layout--navigation) +- [Specialized visualizations](#specialized-visualizations) + +## Quick map + +| You are documenting… | Use | +| --- | --- | +| Config options for a model/action | `OptionsTable` / `ActionOptionsTable` | +| A CLI command | `CliCommand` | +| A note / warning / tip | `:::note` / `:::tip` / `:::caution` / `:::danger` (Aside) | +| A dashboard screenshot | `` from `astro:assets` (see capture-screenshots skill) | +| A YouTube walkthrough | `Youtube` | +| An integration page header | `IntegrationLogo` | +| CI report upload steps | `MergifyCIUploadStep` / `BuildkiteCIUploadStep` / `MergifyCliUploadStep` | +| A product overview card grid | `DocsetGrid` + `Docset` | +| A call-to-action button | `Button` | +| A lifecycle/flow diagram | Graphviz `dot` code block (see mdx-documentation) | + +## Config & reference tables (schema-driven) + +Prefer these over hand-written tables — they render from the live schema and +never go stale. + +```mdx +import OptionsTable from "~/components/OptionsTable.tsx" +import ActionOptionsTable from "~/components/ActionOptionsTable.tsx" + + + +``` + +- `OptionsTable` `def`: a model name from the config schema (e.g. + `PullRequestRuleModel`, `QueueRuleModel`). +- `ActionOptionsTable` `def`: an action model (e.g. `QueueActionModel`, + `LabelActionModel`). +- To find valid `def` names, look at `public/mergify-configuration-schema.json` + or existing usages: `grep -rh "OptionsTable def=" src/content/docs/`. + +CLI reference card from `public/cli-schema.json`: + +```mdx +import CliCommand from "~/components/CliCommand.astro" + + +``` + +## Callouts + +Use directive syntax (renders via `Aside.astro`). Content indented 2 spaces. + +```mdx +:::note + Neutral context the reader should know. +::: + +:::tip + A best practice or shortcut. +::: + +:::caution + A risk or gotcha. +::: + +:::danger + Destructive or irreversible action. +::: +``` + +## Media + +```mdx +import { Image } from "astro:assets" +import shot from "../../images/
//.png" + +What the screenshot shows +``` + +```mdx +import Youtube from "~/components/Youtube.astro" + + +``` + +All article `` get lightbox zoom automatically (`ImageZoom`); add class +`no-zoom` to opt out. + +## Integration & CI pages + +```mdx +import IntegrationLogo from "~/components/IntegrationLogo.astro" +import logo from "../../images/integrations//logo.svg" + + +``` + +CI upload steps (props vary — check the component source for the exact prop, e.g. +`reportPath`): + +- `MergifyCIUploadStep.astro` — GitHub Actions YAML step +- `BuildkiteCIUploadStep.astro` — Buildkite pipeline step +- `MergifyCliUploadStep.astro` — CLI-based upload +- `CIInsightsSetupNote.astro`, `CliInstall.astro` — reusable setup snippets + +## Layout & navigation + +```mdx +import DocsetGrid from "~/components/DocsetGrid.astro" +import Docset from "~/components/Docset.astro" + + + + Keep your main branch green. + + +``` + +`Button.astro` props: `href`, `variant` (`primary|secondary|ghost|solid`), +`target` (default `_blank`), `icon`, `colorScheme`, `rel`. + +## Specialized visualizations + +These are bespoke to specific topics — reuse them only on their topic pages, and +read the component source before using: + +- `GitGraph.astro`, `StackMapping.astro`, `StacksLocalModel.astro` — stacks +- `ScopesDetection.astro` — merge-queue scopes +- `MergeQueueCalculator/` (React) — interactive queue calculator +- `AcademyCallout.astro` — link to Merge Queue Academy + +If unsure whether a specialized component fits, grep for where it is already used: +`grep -rl "ComponentName" src/content/docs/`. diff --git a/.claude/skills/document-a-feature/references/placement-guide.md b/.claude/skills/document-a-feature/references/placement-guide.md new file mode 100644 index 0000000000..4fb4d4f47d --- /dev/null +++ b/.claude/skills/document-a-feature/references/placement-guide.md @@ -0,0 +1,111 @@ +# Placement & Plumbing Guide + +How to place a new docs page and wire it into the site. + +## Table of contents + +- [Section map](#section-map) +- [New page vs. edit existing](#new-page-vs-edit-existing) +- [Naming and paths](#naming-and-paths) +- [Navigation (navItems.tsx)](#navigation-navitemstsx) +- [Redirects (_redirects)](#redirects-_redirects) +- [SEO](#seo) + +## Section map + +Top-level sections under `src/content/docs/`: + +| Section | Put here | +| --- | --- | +| `merge-queue/` | Queue behavior: setup, modes, rules, lifecycle, priority, batches, scopes, performance, monitoring, deploy | +| `merge-protections/` | Branch protection, auto-merge, builtin/custom protections, freezes | +| `workflow/` | Rule syntax + the `actions/` family (assign, backport, comment, label, merge, queue, rebase, review, …) | +| `configuration/` | Config reference: file-format, conditions, data-types, sharing | +| `commands/` | GitHub comment commands (queue, dequeue, rebase, squash, backport, copy, update, refresh) | +| `ci-insights/` | CI analytics setup (GitHub Actions, Buildkite, Jenkins) | +| `test-insights/` | Test framework integrations (pytest, Jest, Go, Rust, RSpec, Cypress, …) | +| `monorepo-ci/` | Monorepo CI guides | +| `stacks/` | Stacked PRs: concepts, setup, workflow, adoption | +| `integrations/` | Third-party integrations (GitHub, Datadog, Slack, Dependabot, Terraform, …) | +| `api/`, `cli/` | API and CLI usage + reference | +| `enterprise/`, `migrate/`, `security/`, `billing/`, `support/`, `browser-extensions/` | As named | + +Images mirror this layout under `src/content/docs/images/
/`. + +## New page vs. edit existing + +Search before creating: `grep -ri "" src/content/docs/`. + +Prefer **extending an existing page** when the feature is an option, sub-behavior, +or variant of something already documented. Create a **new page** only when the +feature is a distinct concept a reader would look for on its own. A thin new page +that duplicates context is worse than a new section on an existing page. + +## Naming and paths + +- File: `src/content/docs/
/.mdx` +- URL path: `/
/` (no `.mdx`, no trailing slash in links) +- Match sibling naming style exactly (look at the directory first). + +## Navigation (navItems.tsx) + +`src/content/navItems.tsx` is a hierarchical `NavItem[]`. Each entry: + +```tsx +{ title: 'Priority', path: '/merge-queue/priority', icon: 'lucide:traffic-cone' } +``` + +Nested sections use `children`, and the first child is usually an `Overview` +pointing at the section root: + +```tsx +{ + title: 'Scopes', + path: '/merge-queue/scopes', + icon: 'lucide:network', + children: [ + { title: 'Overview', path: '/merge-queue/scopes', icon: 'lucide:lightbulb' }, + { title: 'File Patterns', path: '/merge-queue/scopes/file-patterns', icon: 'lucide:file' }, + ], +}, +``` + +Rules: + +- Add the new entry next to its logical siblings, not at the end. +- Pick an `icon` from the same namespaces siblings use: `lucide:*`, `octicon:*`, + `simple-icons:*` (for branded tools), or `mergify:*` (product icons). +- `id` is auto-generated (uuid v5) — do not set it. +- The sidebar renders automatically from this file; no other nav edit is needed. + +## Redirects (_redirects) + +`public/_redirects` uses Netlify syntax, one rule per line: + +``` +/old/path /new/path 301 +``` + +When to add a redirect: + +- You **renamed or moved** a page (old URL must keep working). +- A path has a common alias or an old shape people link to. + +Patterns in use: both bare and trailing-slash forms are listed, and `:splat` is +used to forward subtrees: + +``` +/conditions /configuration/conditions 301 +/conditions/ /configuration/conditions 301 +/conditions/* /configuration/conditions/:splat 301 +``` + +Never delete an existing redirect target without providing a new one. + +## SEO + +- `title` + `description` frontmatter drive the page ``, meta description, + OpenGraph, and the auto-generated OG image (`getOgImageUrl()`). +- Write `description` for a human searching: specific, ~120–155 chars, no filler. +- Optional frontmatter: `canonicalURL` (only if the canonical differs from the + page URL). diff --git a/.claude/skills/validate-config-examples/SKILL.md b/.claude/skills/validate-config-examples/SKILL.md new file mode 100644 index 0000000000..3ba097b0de --- /dev/null +++ b/.claude/skills/validate-config-examples/SKILL.md @@ -0,0 +1,83 @@ +--- +name: validate-config-examples +description: >- + Validate Mergify YAML configuration examples embedded in the docs against the + real Mergify schema, so broken config snippets never ship. Use after editing + docs pages that contain .mergify.yml / YAML examples, when reviewing a docs PR + with config snippets, or when asked to check/validate config examples in the + docs. Extracts YAML code fences, classifies them, and validates full Mergify + configs with `mergify config validate` (optionally via the mergify:mergify-config + skill when that plugin is installed). +--- + +# Validate Config Examples + +Mergify config snippets in the docs are the most-copied content on the site. A +broken example erodes trust instantly. This skill finds every YAML example and +validates the ones that are real Mergify configs. + +## Workflow + +1. **Pick the scope.** + - Reviewing a change: run against the changed MDX files only. + - Auditing: run against the whole `src/content/docs/` tree. + +2. **Extract and classify** with the bundled script: + + ```bash + .claude/skills/validate-config-examples/scripts/extract_yaml.py <files-or-dir> + ``` + + It prints a JSON array of every YAML fence with `file`, `line`, + `classification`, and `code`. Classifications: + + | Classification | Meaning | Action | + | --- | --- | --- | + | `mergify-config` | A real Mergify config (has top-level keys like `queue_rules`, `pull_request_rules`, `merge_protections`) | **Validate it** | + | `github-actions` | A CI workflow YAML, not Mergify config | Skip | + | `partial` | Marked `# partial` or a fragment (no top-level key) | Skip validation | + | `unknown` | YAML that fits none of the above | Eyeball manually | + +3. **Validate each `mergify-config` snippet** with `mergify config validate` — + the authoritative validator (it understands condition syntax and action + options, not just the JSON shape). Write each snippet to a temp file and pass + it with `--config-file` (the command auto-detects `.mergify.yml` from the + current directory otherwise, so the flag is required for a temp file): + + ```bash + printf '%s\n' "$CODE" > /tmp/mergify-example.yml + mergify config validate --config-file /tmp/mergify-example.yml + ``` + + If the **mergify:mergify-config** plugin skill is installed, you can invoke it + instead of calling the CLI directly — it wraps the same command. As a + structural fallback when the CLI is unavailable, validate against + `public/mergify-configuration-schema.json` (JSON Schema). + +4. **Report** each failure as `file:line — <error>`. Fix clear errors directly in + the MDX (wrong key name, bad indentation, invalid condition). For anything + ambiguous, flag rather than guess — a wrong "fix" to a config example is worse + than a flagged one. + +## The fragment convention + +Many doc examples are partial on purpose — they show one rule, not a whole file. +A bare fragment cannot be validated standalone and will false-positive. + +The script treats a snippet as `partial` (and skips it) when: + +- it has no unindented top-level key (it is clearly a fragment), or +- its first lines contain a `# partial` marker comment. + +When you intentionally show a fragment that the script can't auto-detect, add a +leading `# partial` comment to the code block so it is skipped cleanly. Do not add +the marker to examples that are meant to be complete, valid configs — those should +validate. + +## Scope & guardrails + +- Only validates YAML/`yml` fences; ignores all other languages. +- Skips GitHub Actions and other non-Mergify YAML automatically. +- Never edits `src/content/changelog/`. +- Fix only genuine errors; leave valid examples alone even if you'd phrase the + surrounding prose differently. diff --git a/.claude/skills/validate-config-examples/scripts/extract_yaml.py b/.claude/skills/validate-config-examples/scripts/extract_yaml.py new file mode 100755 index 0000000000..24a2deb675 --- /dev/null +++ b/.claude/skills/validate-config-examples/scripts/extract_yaml.py @@ -0,0 +1,149 @@ +#!/usr/bin/env python3 +"""Extract YAML/yml fenced code blocks from MDX docs and classify each. + +Pure stdlib. Does NOT validate — it locates every YAML snippet, records its +file:line, and classifies it so the caller knows which snippets to feed to +`mergify config validate` and which to skip. + +Usage: + extract_yaml.py <file_or_dir> [<file_or_dir> ...] + +If a directory is given, all .mdx files under it are scanned recursively. +Outputs a JSON array to stdout: + [{"file", "line", "lang", "classification", "code"}, ...] + +Classifications: + mergify-config -> a Mergify config; validate it with `mergify config validate` + github-actions -> a CI workflow, not Mergify config; skip + partial -> explicitly marked `# partial` or a fragment; skip validation + unknown -> YAML that is none of the above; review manually +""" + +import json +import os +import re +import sys + +FENCE_RE = re.compile(r"^([ \t]*)(`{3,}|~{3,})([^\n`]*)$") + +# Top-level keys that mark a full Mergify configuration file. +MERGIFY_TOP_KEYS = { + "queue_rules", + "pull_request_rules", + "merge_protections", + "commands_restrictions", + "merge_queue", + "shared", + "defaults", + "extends", + "partition_rules", + "priority_rules", +} + +# Signals that a YAML block is a GitHub Actions / CI workflow, not Mergify config. +CI_SIGNALS = ("runs-on:", "uses:", "jobs:", "steps:") + + +def lang_of(info_string): + """First token of a fence info string, lowercased (e.g. 'yaml title=...').""" + token = info_string.strip().split()[0] if info_string.strip() else "" + # Strip a leading '{' from formats like ```{yaml} + return token.lstrip("{").rstrip("}").lower() + + +def classify(code): + lines = code.splitlines() + stripped = [ln for ln in lines if ln.strip() and not ln.lstrip().startswith("#")] + + # Explicit author marker wins. + for ln in lines[:3]: + if re.match(r"^\s*#\s*partial\b", ln, re.IGNORECASE): + return "partial" + + text = "\n".join(lines) + if any(sig in text for sig in CI_SIGNALS) and "on:" in text: + return "github-actions" + + top_keys = set() + for ln in lines: + m = re.match(r"^([A-Za-z_][\w-]*):", ln) + if m: + top_keys.add(m.group(1)) + if top_keys & MERGIFY_TOP_KEYS: + return "mergify-config" + + # No unindented top-level key at all -> a fragment (e.g. a single rule shown + # inline). Treat as partial: not independently validatable. + if stripped and all(ln.startswith((" ", "\t", "-")) for ln in stripped): + return "partial" + + return "unknown" + + +def extract_from_file(path): + out = [] + with open(path, encoding="utf-8") as fh: + lines = fh.readlines() + + i = 0 + n = len(lines) + while i < n: + m = FENCE_RE.match(lines[i].rstrip("\n")) + if not m: + i += 1 + continue + indent, fence, info = m.group(1), m.group(2), m.group(3) + lang = lang_of(info) + fence_line = i + 1 # 1-based + # Find closing fence: same marker char, at least as long, no info string. + body = [] + j = i + 1 + closed = False + while j < n: + cm = FENCE_RE.match(lines[j].rstrip("\n")) + if cm and cm.group(2)[0] == fence[0] and len(cm.group(2)) >= len(fence) and not cm.group(3).strip(): + closed = True + break + body.append(lines[j].rstrip("\n")) + j += 1 + if lang in ("yaml", "yml"): + # Strip the common fence indentation from the body. + code = "\n".join(ln[len(indent):] if ln.startswith(indent) else ln for ln in body) + out.append( + { + "file": path, + "line": fence_line, + "lang": lang, + "classification": classify(code), + "code": code, + } + ) + i = j + 1 if closed else j + return out + + +def iter_targets(args): + for arg in args: + if os.path.isdir(arg): + for root, _, files in os.walk(arg): + for f in files: + if f.endswith(".mdx"): + yield os.path.join(root, f) + elif arg.endswith(".mdx"): + yield arg + + +def main(argv): + if not argv: + print(__doc__, file=sys.stderr) + return 2 + results = [] + for path in iter_targets(argv): + results.extend(extract_from_file(path)) + json.dump(results, sys.stdout, indent=2) + sys.stdout.write("\n") + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) From 4970034288563a017ded4c5c10b0ae576e2a2de8 Mon Sep 17 00:00:00 2001 From: Julien Danjou <julien@danjou.info> Date: Wed, 1 Jul 2026 18:50:31 +0200 Subject: [PATCH 2/2] docs: install Mergify plugin from official Claude Code marketplace The Mergify plugin is now published as a single unified `mergify` plugin on the built-in `claude-plugins-official` marketplace. Replace the three-command install (add the `Mergifyio/mergify-cli` marketplace, install `mergify-stack@mergify`, reload) with a single: /plugin install mergify@claude-plugins-official Since the official marketplace ships with Claude Code, there's nothing to add first. The unified plugin bundles every Mergify skill (Merge Queue, CI Insights, config validation, scheduled freezes), so the tips are updated accordingly and the obsolete third-party auto-update tip is dropped. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Change-Id: I91db52200925f4707f5226dc795a047d9678dcaf --- src/content/docs/stacks/agents.mdx | 7 ++++--- src/content/docs/stacks/setup.mdx | 23 +++++++++-------------- 2 files changed, 13 insertions(+), 17 deletions(-) diff --git a/src/content/docs/stacks/agents.mdx b/src/content/docs/stacks/agents.mdx index 4ff8ad486d..bbf684cf19 100644 --- a/src/content/docs/stacks/agents.mdx +++ b/src/content/docs/stacks/agents.mdx @@ -28,11 +28,12 @@ Pick the command that matches your runtime. **Claude Code:** ```text -/plugin marketplace add Mergifyio/mergify-cli -/plugin install mergify-stack@mergify -/reload-plugins +/plugin install mergify@claude-plugins-official ``` +This installs the unified `mergify` plugin, which includes the Stacks skill +(along with skills for the merge queue, CI Insights, and more). + **Any agent supporting [skills.sh](https://skills.sh) (Cursor, Cline, and others):** ```bash diff --git a/src/content/docs/stacks/setup.mdx b/src/content/docs/stacks/setup.mdx index 531c3e8cd2..7451c567d2 100644 --- a/src/content/docs/stacks/setup.mdx +++ b/src/content/docs/stacks/setup.mdx @@ -24,13 +24,12 @@ creating fixups, and follow stack conventions automatically. **Claude Code:** ```text -/plugin marketplace add Mergifyio/mergify-cli -/plugin install mergify-stack@mergify -/reload-plugins +/plugin install mergify@claude-plugins-official ``` -Or run `/plugin` on its own and use the **Marketplaces** tab to add -`Mergifyio/mergify-cli`, then pick `mergify-stack` from **Discover**. +The `claude-plugins-official` marketplace ships with Claude Code, so there's +nothing to add first. Or run `/plugin` on its own, open **Discover**, and +search for `mergify`. **Any agent supporting [skills.sh](https://skills.sh)** (Cursor, Cline, and others): @@ -46,15 +45,11 @@ npx skills add Mergifyio/mergify-cli ::: :::tip - The same marketplace ships plugins for other Mergify features: merge queue, - CI insights, config validation, and scheduled freezes. Open `/plugin` and - browse **Discover** to pick the ones you want. -::: - -:::tip - Third-party marketplaces don't auto-update by default. Open `/plugin`, go to - **Marketplaces**, select **mergify**, and choose **Enable auto-update** to - receive new skills and fixes as we ship them. + The `mergify` plugin also ships skills for other Mergify features: + [Merge Queue](/merge-queue), [CI Insights](/ci-insights), + [config validation](/configuration/file-format), and + [scheduled freezes](/merge-protections/freeze). Installing it enables all of + them. ::: ## 3. Configure GitHub