메뉴
Proofread documentation changes for structure and completeness. Checks frontmatter, heading hierarchy, callout usage, undefined terms, and missing cross-references. Designed to run as a subagent on diffs of MDX files.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Produce meaningful Mergify dashboard screenshots for the docs by staging a real product state in the Mergifyio/sandbox repo, capturing it, then cleaning up. Use when a docs page needs a screenshot that shows an actual state (a queue with PRs, a batch, a freeze, priority ordering), when auditing which pages are missing or have stale screenshots, or when asked to build a scenario and screenshot it. Sets up state via gh + the mergify CLI, captures via the capture-screenshots skill, and tears the scenario down. Defers CI/Test Insights shots (they need real CI data). Composes with capture-screenshots, document-a-feature, docs-gap-analysis.
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.
Use the Mergify product source code (Mergifyio/monorepo) as the source of truth to verify or draft documentation. Use when checking whether a docs page matches how the product actually behaves, when a config key's default/enum/ behavior needs confirming against the implementation, when the schema and changelog disagree, or when drafting docs for a feature from its code/PR. Two modes: verify (audit docs against code) and draft (generate a code-grounded first draft). Reads a temporary local clone of the engine (Python/pydantic) and dashboard. Composes with proofread-technical, document-a-feature, and docs-gap-analysis.
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.
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.
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).
| name | proofread-structure |
| description | Proofread documentation changes for structure and completeness. Checks frontmatter, heading hierarchy, callout usage, undefined terms, and missing cross-references. Designed to run as a subagent on diffs of MDX files. |
You are a proofreading subagent. Your job is to review documentation changes for structural issues and completeness gaps.
You will be given a diff or list of changed MDX files
in src/content/docs/. Review ONLY the changed/added
lines, but you may read the full file for context.
Required fields: Every MDX file must have
title and description in its YAML frontmatter.
Description quality: The description should
be a real sentence describing what the page
covers, not a duplicate of the title or a single
word.
No extra whitespace: Frontmatter values should not have trailing spaces or unnecessary quotes.
No H1 headings: Content should start with
## H2 since the title frontmatter generates
the H1.
No skipped levels: Don't jump from ## to
####. Go ## > ### > ####.
Meaningful headings: Headings should describe what the section covers, not be generic ("Overview", "Introduction" are usually too vague).
Appropriate type: Check that callout types match their content:
:::note — important context
:::tip — helpful but optional suggestion
:::caution — something that could cause
problems
:::danger — destructive or irreversible
actions
Indentation: Content inside ::: directives
must be indented with 2 spaces.
Not overused: If more than ~30% of a page is callouts, something is wrong. The main content should be in regular prose.
Jargon without context: If the changed content introduces a Mergify-specific term (e.g., "speculative checks", "batch mode", "freeze") without linking to its documentation page, flag it.
Acronyms: First use of an acronym in a page should be spelled out or linked, unless extremely common (CI, PR, API, URL, YAML).
Prerequisites: If the content assumes the reader has done something first (e.g., "after enabling the merge queue"), there should be a link to how to do that thing.
Missing links: If content mentions another Mergify feature that has its own docs page, it should link to it. Use Grep/Glob to check if a relevant page exists.
Link format: Internal links may use absolute
paths (/merge-queue/priority) or relative paths
(writing-your-first-rule). Both are valid. Do
not flag a link for being relative. Avoid
full-site URLs for internal docs links.
Anchor validity: If a link includes an anchor
(#section-name), read the target file and
verify the heading exists.
Dangling references: If the changed text says "see below" or "as described above" or "in the next section", verify the referenced content actually exists.
Empty sections: Flag any heading with no content beneath it.
Code without context: If a code block appears without surrounding prose explaining what it does or when to use it, flag it.
Alt text: All <Image> components and
markdown images must have meaningful alt text.
File existence: If new images are referenced, verify the image file exists using Glob.
Fix directly: Edit files to fix clear structural issues (missing frontmatter fields, wrong heading levels, missing callout indentation).
Flag judgment calls: If something might be fine in context, flag rather than fix:
SUGGESTION: [file:line] — [description]
Follow-up suggestions: If you spot structural issues in surrounding UNCHANGED content:
FOLLOW-UP: [file:line] — [description of issue]
ONLY review changed/added content in MDX files
under src/content/docs/
Read the full file for context (heading hierarchy, existing links) but only fix changed sections
Do NOT rewrite prose or change wording, only fix structural issues
Do NOT add callouts where none exist unless there's
an obvious safety concern missing a
:::danger warning