// Check formatting compliance in changed English documentation against writing-guides/formatting-guide.md. Use after finalizing a draft, or when the user says "check formatting", "format audit", "format check" on English content.
Use when editing, auditing, or creating OpenAPI specs for the Dify documentation repo. Applies to files in en/api-reference/. Covers formatting rules, error code conventions, example standards, operationId patterns.
Use when writing, rewriting, or auditing environment variable documentation for Dify self-hosted deployment. Applies to en/self-host/configuration/environments.mdx. Covers the full process from codebase tracing to user-facing descriptions.
Use when preparing documentation updates for a Dify release. User provides two version references to compare (e.g., v1.13.2 and v1.13.3, or v1.13.2 and main). Covers API reference, help documentation, environment variable changes, and UI i18n glossary impact.
Check formatting compliance in changed Chinese and Japanese documentation against writing-guides/formatting-guide.md, tools/translate/formatting-zh.md, and tools/translate/formatting-ja.md. Use after finalizing a translation batch, or when the user says "check formatting (zh/ja)", "check CJK formatting", or "format audit" on translated content.
Research a Dify feature before writing or optimizing documentation. Use when starting any doc task that requires understanding a feature's implementation, user pain points, or community feedback. Triggers: 'research this feature', 'investigate the code for', 'what do users say about', 'let's understand how X works before writing', or any documentation task where the current docs are being rewritten or significantly expanded.
Use when writing, improving, or reviewing Dify user guide documentation. Covers pages in en/use-dify/, en/develop-plugin/, and en/self-host/. Triggers: "write docs for [feature]", "improve this page", "review this documentation section".
| name | dify-docs-format-check-en |
| description | Check formatting compliance in changed English documentation against writing-guides/formatting-guide.md. Use after finalizing a draft, or when the user says "check formatting", "format audit", "format check" on English content. |
Verify English documentation against every rule in writing-guides/formatting-guide.md. Mechanical rules are enforced by a linter script (check-format-en.py); judgment-call rules are checked by reading the file.
Audit the entire file, not just the diff. Default to files currently under review, detected via:
git diff --name-only (unstaged changes in tracked files)git diff --cached --name-only (staged changes)git status --porcelain (lines starting with ??)Filter for .mdx and .md files under en/. If no files are detected, ask the user which files to check.
Run the linter and capture its output:
python3 .claude/skills/dify-docs-format-check-en/check-format-en.py <file> [<file> ...]
The script checks these rules. Each violation includes the file path, line number, rule ID, severity, and a short message.
Frontmatter
F-title-missing — file lacks title field.F-desc-trailing-period — description ends with a period.F-quote-needed — value contains : (colon + space) but is not quoted.F-quote-unnecessary — value is quoted but contains no character that requires quoting.F-single-quote — value uses single quotes; should use double.F-blank-after-fm — no blank line between closing --- and body.Headings
H-trailing-hash — heading ends with a trailing #.H-blank-before / H-blank-after — missing blank line adjacent to a heading.H-skip-level — jump in depth (e.g., H2 to H4 without H3).H-ing-verb — heading starts with a verb in -ing form where the base form should be used. The linter carries a curated verb list and strips leading numeric/parenthetical prefixes (1., (a), etc.) before detection. Section-name gerunds in a skip list are not flagged (Troubleshooting, Logging, Getting Started, Monitoring Data List, etc.). The skip list lives in the script constant SKIP_TEXTS.Bold and Italic
B-trailing-colon-inside — **X:** or **X：** patterns. Colon must be outside the bold markers.B-underscore-italic — _italic_ style; must use *italic*.Lists
L-asterisk-bullet — * used as a bullet; must use - .L-blank-before / L-blank-after — missing blank line around a list block.L-nested-indent — nested list item not indented by a multiple of 2 spaces.Code
C-no-language — fenced code block opens with ``` but no language tag.C-blank-before / C-blank-after — missing blank line around a fenced code block.Links
Li-click-here — link text is click here, here, or Click here.Li-http-external — external link uses http:// rather than https://.Li-internal-no-prefix — internal link starts with a relative path or omits the language prefix (/en/...).Images
I-raw-img-tag — raw <img> element used instead of <Frame> + markdown.I-alt-empty —  with no alt text on a non-decorative image. The script flags every empty alt as a prompt to confirm the image is truly decorative.I-alt-too-long — alt text exceeds 125 characters.I-caption-alt-mismatch — <Frame caption="..."> value differs from the alt text of the enclosed markdown image.I-filename-uppercase-ext — filename ends with an uppercase extension (.PNG, .JPG).I-filename-retina-suffix — filename contains @2x, @3x, or similar.I-filename-default-tool — filename begins with CleanShot, Screenshot, IMG_, etc.I-filename-non-kebab — filename has underscores, spaces, uppercase letters, or non-ASCII characters.I-filename-ing-verb — filename begins with a verb in -ing form.Mintlify Components
M-tab-no-title — <Tab> without a title attribute.UI Element References
U-menu-arrow — menu path uses →, ->, or => instead of >.Spacing
S-double-blank — two or more consecutive blank lines.Punctuation
P-em-dash-spaces — em dash — surrounded by spaces.P-en-dash-spaces — en dash – surrounded by spaces in a numeric range.P-fullwidth-in-english — full-width punctuation (，。；：！？（）、) adjacent to ASCII letters.For each changed file, read it and look for:
Headings
a, and, the, of, in, on, to, etc.) lowercase except at the start. Flag any heading that reads as sentence case, all-lowercase, or inconsistent.Bold and emphasis
"word" patterns used emphatically (not as direct quotations or literal-phrase references).Lists
- **Label**: description. A list where each item introduces a labeled concept should use this pattern.Links
this page, here) even when it isn't click here exactly.Images
alt="" should be used only for images that carry no information. Confirm that any empty alt flagged by the linter is truly decorative./images/<tier-1>/<tier-2>/... follows the content-domain taxonomy in the guide.workflow-llm-node-parameters.png, not workflow-01.png or screenshot.png).Tables
:---; bold used in header row only when it aids clarity.<br/><br/><br/><br/> when a manual break is unavoidable.General
<Info>, <Note>, etc.).## English Formatting Check Results
### File: {path}
**Deterministic violations** ({n})
- Line {n} [{rule-id}]: {message}
- ...
**Judgment-call findings** ({n})
- Line {n}: {description of issue} — {rule area}
- ...
**Clean checks**
- ✅ Frontmatter valid
- ✅ No deterministic violations in {area}
Group by file. If a file has no issues in any area, report a single ✅ line for it.
-ing verb that should have been in SKIP_TEXTS, or _ that is a legitimate filename/identifier), surface it as a finding but note the ambiguity so the user can decide.