Add style guide and improve skills

.claude/skills/polish/SKILL.md

@@ -1,32 +1,39 @@
 ---
 name: polish
-description: Proofreads documentation and improves clarity, readability, and word choice without changing meaning or reorganizing structure. Simplifies complex sentences, applies style guide standards, and converts passive voice to active voice. Use when the user wants to polish, improve clarity, make more readable, or clean up documentation while preserving its structure.
+description: Proofreads documentation and improves clarity, readability, and word choice without changing meaning or reorganizing structure. Simplifies complex sentences, applies style guide standards, and converts passive voice to active voice. Use when the user wants to polish, improve language and clarity, make more readable, check style guide compliance, or clean up documentation while preserving its structure.
 user-invocable: true
 disable-model-invocation: false
 ---
 
-> **Skill progression:** This preserves structure. If only basic fixes are needed, use `/proofread`. For deeper reorganization, suggest `/enhance`.
+> **Skill progression:** This does everything `/proofread` does plus clarity improvements and style guide enforcement. If only grammar and spelling fixes are needed, use `/proofread`. For deeper reorganization, suggest `/enhance`.
 
-First, use the Skill tool to invoke the `proofread` skill.
-
-Then immediately continue: improve clarity and readability without changing meaning, structure, or paragraph order:
+Improve clarity and readability without changing meaning, structure, or paragraph order:
 
 **Polish should**:
+* Read Mendix style guides first (in parallel): `grammar-formatting.md`, `terminology.md`, and `product-naming-guide.md` from `/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/`
+* Fix all spelling, grammar, and punctuation errors
+* Add missing alt text to images (use simple, factual descriptions)
+* Ensure required front matter fields are present (title, url, description) and make descriptions concise and action-oriented
+* Fix broken Markdown syntax
+* Fix capitalization and terminology inconsistencies
 * Break up long, complex sentences for better readability
 * Simplify wordy or awkward phrasing
 * Improve word choice (more precise or accessible terms)
 * Change passive voice to active voice where appropriate
-* Make front matter descriptions more concise and action-oriented
-* Apply all style standards from project instructions (tone, formatting, terminology)
 * Remove bold and italics used for emphasis (reword or use alerts if needed)
-* Ensure consistent application of Microsoft Writing Style Guide
+* Apply Mendix style guide standards (overrides the Microsoft Writing Style Guide)
+* Apply Microsoft Writing Style Guide standards, unless they conflict with the Mendix style guide standards
 
 **Polish should NOT**:
 * Move paragraphs or restructure sections (that's `/enhance`)
 * Change technical meaning or accuracy
 * Significantly increase document length
-* Modify code samples (flag issues instead)
+* Change command syntax, code identifiers, variable names, placeholders, or any other text that appears in code formatting (inline backticks or code blocks). Code-formatted text represents literal technical content that must remain unchanged. If you notice an issue with code-formatted text, flag it in the chat but don't edit it directly.
 
 Every edit should serve a clear purpose in making the text easier to read, scan, and understand.
 
-Do not change any code samples directly, but flag any code issues or inconsistencies in the chat.
+Priority order for determining scope:
+1. If the user has selected text in a file (check for `ide_selection` tags), only polish the selected text in that file. Don't polish the entire document.
+2. If there's one open file (check for `ide_opened_file` tags) and no selection, work on the entire file.
+3. If there are multiple open files, list them and ask which to process.
+4. If no files are open, ask for a file path.

.claude/skills/proofread/SKILL.md

@@ -1,18 +1,17 @@
 ---
 name: proofread
-description: Checks and fixes spelling, grammar, punctuation, basic Markdown formatting, alt text, and required front matter fields. Makes minimal technical corrections without rewording or restructuring. Use when the user asks to proofread, check for errors, fix typos, or perform a light technical review of documentation.
+description: Checks and fixes spelling, grammar, punctuation, basic Markdown formatting, and required front matter fields. Makes minimal corrections without rewording or restructuring. Use when the user asks to proofread, check for spelling and grammar errors, or fix typos.
 user-invocable: true
 disable-model-invocation: false
 ---
 
-> **Skill progression:** This is the lightest touch. If more clarity work is needed, suggest `/polish`. For deeper restructuring, suggest `/enhance`.
+> **Skill progression:** This is the lightest touch. If more clarity and style guide work is needed, suggest `/polish`. For deeper restructuring, suggest `/enhance`.
 
-Proofread the document for technical correctness only. Do NOT rewrite, rephrase, or improve clarity:
+Do NOT rewrite, rephrase, or improve clarity. Proofread only:
 
 * **Spelling**: Fix typos and misspellings
 * **Grammar**: Fix grammatical errors (subject-verb agreement, tense consistency, etc.)
 * **Basic formatting checks**:
-  * Add missing alt text to images (use simple, factual descriptions)
   * Ensure required front matter fields are present (title, url, description)
   * Fix broken Markdown syntax
   * Fix any capitalization and terminology inconsistencies
@@ -24,4 +23,10 @@ Do NOT:
 * Simplify complex sentences
 * Reorganize content
 
+Priority order for determining scope:
+1. If the user has selected text in a file (check for `ide_selection` tags), only proofread the selected text in that file. Don't proofread the entire document.
+2. If there's one open file (check for `ide_opened_file` tags) and no selection, work on the entire file.
+3. If there are multiple open files, list them and ask which to process.
+4. If no files are open, ask for a file path.
+
 If you notice style or clarity issues that need improvement, finish proofreading first, then suggest the user run `/polish` for those improvements.

CLAUDE.md

@@ -2,7 +2,7 @@
 
 <!-- markdownlint-disable-file -->
 
-**Your role**: Edit and review Markdown documentation files under `content/en/docs/` following Microsoft Writing Style Guide and the project-specific conventions below.
+**Your role**: Edit and review Markdown documentation files under `content/en/docs/` following the style guidance and project-specific conventions below.
 
 ## Instruction Precedence
 
@@ -12,8 +12,9 @@ When instructions conflict, follow this order of precedence:
 2. Task-specific prompt files in `.github/prompts/*.prompt.md` (for Copilot) or skills in `.claude/skills/*/SKILL.md` (for Claude) when explicitly referenced or invoked.
 3. Overlay instruction files (for example, `.github/release-notes-instructions.md`) when path-scoped.
 4. This file (`CLAUDE.md`).
-5. Existing conventions in nearby pages within the same folder.
-6. Microsoft Writing Style Guide.
+5. Mendix Style Guide files in `content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/` for detailed grammar, terminology, and formatting rules.
+6. Existing conventions in nearby pages within the same folder.
+7. Microsoft Writing Style Guide.
 
 ### Critical Constraints
 
@@ -73,7 +74,7 @@ Before creating a new file, use Glob to explore the directory structure and unde
 
 ## Style Standards
 
-* **Guiding manual** – Microsoft Writing Style Guide (https://learn.microsoft.com/style-guide/). Apply grammar, inclusive language, terminology, and formatting rules from that document.
+* **Guiding manual** – Mendix-specific style guides (see subsection below) extend and customize the Microsoft Writing Style Guide (https://learn.microsoft.com/style-guide/). Consult the Mendix style guides first for grammar, inclusive language, terminology, and formatting rules; use MSG as fallback for topics not covered by Mendix guides.
 * **Tone** – Clear, concise, active voice; use imperative mood for procedures; second person (you/your) when addressing readers. Keep a conversational, straightforward tone. Present tense. Use American English and write for a global audience. Prefer short, everyday words; avoid or explain jargon. Keep it simple—short sentences and fragments are easier to scan and read, and prune excess words. Avoid marketing language.
 * **Terminology** – Capitalize product names (Mendix, Studio Pro, Developer Portal); use "microflow", "nanoflow", etc. consistently. Never use e.g. or i.e.
 * **Text formatting** – Reserve bold for UI labels, button names, menu items, or other interface text, or for introductions in list items. Don't use italics except to refer to titles and sections. Use wording or alert shortcodes for emphasis; don't use text formatting for emphasis. Use code font only to wrap literal code, filenames, paths, or command-line input. Use `<kbd>` for keyboard shortcuts.
@@ -82,9 +83,19 @@ Before creating a new file, use Glob to explore the directory structure and unde
 * **Indentation** – Four spaces for sub-lists and nested content. Alerts in lists are an exception:  don't indent alert lines but do omit preceding blank line.
 * **Links** – Use absolute paths starting with a leading slash (`/deployment/`). Use descriptive link text such as the page title, not "click here". To link to a heading, add an anchor ID (`{#anchor-id}`) next to the heading and use that ID in the URL (for example, `[Section title](/path/to/page#anchor-id)` to link to a heading in another page or `[Section title](#anchor-id)` to link to a heading in the same page).
 * **Images** – Always include `alt` text (or `alt=""` if decorative). Use W3C guidelines. Reference images with the `figure` shortcode.
-* **Code** – Use fenced code blocks with language specifier.
+* **Code** – Use fenced code blocks with language specifier. Do not modify text that appears in code formatting (inline backticks or code blocks), even to fix apparent inconsistencies or apply naming conventions. 
 
-Project‑specific preferences are documented in the templates and in `community-tools` example pages; consult them for tricky formatting cases.
+### Mendix-Specific Style Guides
+
+For detailed guidance beyond the basics above, consult these Mendix style guide files in `content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/`:
+
+* **`grammar-formatting.md`** – Grammar and formatting rules including acronyms, active/passive voice, alerts, bold/italics, capitalization, contractions, dashes, dates, emphasis, headings, lists, numbers, person, verb tense, keyboard shortcuts, URL handling, and cross-reference conventions. This is the most detailed style reference.
+* **`terminology.md`** – General terminology guidance for common terms, with capitalization and hyphenation rules.
+* **`product-naming-guide.md`** – Reference for Mendix product names and other Mendix terms.
+
+When encountering style questions not covered in this file, read the relevant style guide file above before falling back to the Microsoft Writing Style Guide.
+
+Project‑specific preferences are also documented in the templates; consult them for tricky formatting cases.
 
 ## Tool Usage Guidelines
 

content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/_index.md

@@ -0,0 +1,14 @@
+---
+title: "Mendix Documentation Style Guide"
+url: /community-tools/contribute-to-mendix-docs/style-guide/
+weight: 10
+description: "Comprehensive guidelines on terminology, grammar, formatting, inclusive language, document structuring, and image usage for Mendix documentation."
+---
+
+## Introduction
+
+The Documentation group maintains guidelines on terminology, grammar, formatting, inclusive language, document structuring, and image usage that are applied to the [Mendix Documentation](/) and the [Mendix Platform Evaluation Guide](https://www.mendix.com/evaluation-guide/).
+
+The tone of the Mendix documentation is conversational, relaxed, and always straight-forward. The tone reflects the Documentation group's values.
+
+Our language conventions are based on American English.