dify-docs-format-check-en - SKILL.md Agent Skill

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.

English Formatting Check

Purpose

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.

Before Starting

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)
Untracked files from 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.

Checks

Part 1 — Deterministic (run the linter)

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.

Part 2 — Judgment-call review (LLM reads each file)

For each changed file, read it and look for:

Headings

Title case: every heading uses proper title case. Major words capitalized; minor words (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

Bold for UI elements and key terms only. Running-text emphasis should be italic or restructured. Flag bold that isn't a UI label, a menu path, a tab/field name, or a first-use key term.
Double quotation marks not used for emphasis. Flag "word" patterns used emphatically (not as direct quotations or literal-phrase references).

Lists

Numbered lists only for sequential steps. If items are not ordered steps, they should be unordered (dashes).
Descriptive-list pattern: - **Label**: description. A list where each item introduces a labeled concept should use this pattern.
Period consistency: items are either all complete sentences (period) or all fragments (no period). Flag mixed styles within a list.
Child content indentation: when a list item has an expanded description, callout, or image, it must be indented two spaces under that item.

Links

Descriptive link text. Flag link text that is vague (this page, here) even when it isn't click here exactly.

Images

Alt text in title case, describes what the image communicates (not its appearance). "LLM Node Configuration Panel" is correct; "Screenshot of a form" is not.
Comparison images (two or more images shown together for comparison) each need a caption. The linter cannot detect image adjacency; check by reading.
Decorative alt="" should be used only for images that carry no information. Confirm that any empty alt flagged by the linter is truly decorative.
Image storage path under /images/<tier-1>/<tier-2>/... follows the content-domain taxonomy in the guide.
Filenames are descriptive and specific (workflow-llm-node-parameters.png, not workflow-01.png or screenshot.png).

Tables

Left-aligned with :---; bold used in header row only when it aids clarity.
Multi-line cells: prefer lists or components; fall back to <br/><br/><br/><br/> when a manual break is unavoidable.

General

Content inside Mintlify components reads cleanly (bold, links, etc. work as expected inside <Info>, <Note>, etc.).

Output Format

## 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.

Important

Do NOT modify any files. This is a read-only audit.
Report findings to the user for review.
When the script flags a rule that looks like a false positive on inspection (e.g., -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.