From b338686d09ce48595a4a716244bf7db9abded4a1 Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Thu, 16 Apr 2026 12:12:38 +0200 Subject: [PATCH 1/8] Add docs-pr-review skill --- .claude/skills/docs-reviewpr/SKILL.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 .claude/skills/docs-reviewpr/SKILL.md diff --git a/.claude/skills/docs-reviewpr/SKILL.md b/.claude/skills/docs-reviewpr/SKILL.md new file mode 100644 index 00000000000..b5d97cb5157 --- /dev/null +++ b/.claude/skills/docs-reviewpr/SKILL.md @@ -0,0 +1,12 @@ +--- +name: docs-pr-review +description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull requestumentation, or when they want suggestions before making changes. +user-invocable: true +disable-model-invocation: false +--- + +Analyze all the changes in the current pull request or branch and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Read the whole of each document modified in the pull request to ensure the changes do not make inconsistencies. + +When referring to the files, ensure you are clear about the file and lines ahich raise your concerns. + +Make no edits. From 1d303f5127427787eed60f6450a831b6d8c22eb9 Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Thu, 16 Apr 2026 12:34:05 +0200 Subject: [PATCH 2/8] Apply claude spelling recommendations --- .claude/skills/docs-reviewpr/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/docs-reviewpr/SKILL.md b/.claude/skills/docs-reviewpr/SKILL.md index b5d97cb5157..1f3b8cbd73b 100644 --- a/.claude/skills/docs-reviewpr/SKILL.md +++ b/.claude/skills/docs-reviewpr/SKILL.md @@ -1,12 +1,12 @@ --- name: docs-pr-review -description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull requestumentation, or when they want suggestions before making changes. +description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull request, or when they want suggestions before making changes. user-invocable: true disable-model-invocation: false --- Analyze all the changes in the current pull request or branch and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Read the whole of each document modified in the pull request to ensure the changes do not make inconsistencies. -When referring to the files, ensure you are clear about the file and lines ahich raise your concerns. +When referring to the files, ensure you are clear about the file and lines which raise your concerns. Make no edits. From 897e90d94332968f033ef82a3137fa9f46b01cff Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Thu, 16 Apr 2026 12:36:42 +0200 Subject: [PATCH 3/8] Correct skill name and add reference in using-ai-tools --- .claude/skills/{docs-reviewpr => docs-pr-review}/SKILL.md | 0 .../community-tools/contribute-to-mendix-docs/using-ai-tools.md | 1 + 2 files changed, 1 insertion(+) rename .claude/skills/{docs-reviewpr => docs-pr-review}/SKILL.md (100%) diff --git a/.claude/skills/docs-reviewpr/SKILL.md b/.claude/skills/docs-pr-review/SKILL.md similarity index 100% rename from .claude/skills/docs-reviewpr/SKILL.md rename to .claude/skills/docs-pr-review/SKILL.md diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md b/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md index c9197cf665b..0346d67ffeb 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md @@ -55,6 +55,7 @@ This repository includes custom Claude Code skills optimized for documentation w * `/docs-enhance` - Performs comprehensive editing including reorganization, restructuring, and stronger phrasing * `/docs-review` - Analyzes documentation and generates suggestions for improvements * `/docs-add` - Adds new content to an existing page while preserving original structure +* `/docs-pr-review` - Reviews all changes in the PR rather than just a single document. These skills are available to all contributors using Claude Code with this repository. From 5551595b529c08eae774c35e6bd89d753ecbaa2e Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Thu, 16 Apr 2026 12:38:50 +0200 Subject: [PATCH 4/8] Typo --- .../community-tools/contribute-to-mendix-docs/using-ai-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md b/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md index 0346d67ffeb..5a3bd95464c 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md @@ -55,7 +55,7 @@ This repository includes custom Claude Code skills optimized for documentation w * `/docs-enhance` - Performs comprehensive editing including reorganization, restructuring, and stronger phrasing * `/docs-review` - Analyzes documentation and generates suggestions for improvements * `/docs-add` - Adds new content to an existing page while preserving original structure -* `/docs-pr-review` - Reviews all changes in the PR rather than just a single document. +* `/docs-pr-review` - Reviews all changes in the PR rather than just a single document These skills are available to all contributors using Claude Code with this repository. From 718c5c6c28c81d77a54535d04246eb74c9d57a5d Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Thu, 16 Apr 2026 13:20:40 +0200 Subject: [PATCH 5/8] Add helper script to resolve internal links. --- .claude/scripts/README.md | 38 ++++++++++++++++++++++++++++++ .claude/scripts/resolve-doc-url.sh | 15 ++++++++++++ CLAUDE.md | 5 ++++ 3 files changed, 58 insertions(+) create mode 100644 .claude/scripts/README.md create mode 100644 .claude/scripts/resolve-doc-url.sh diff --git a/.claude/scripts/README.md b/.claude/scripts/README.md new file mode 100644 index 00000000000..66d4c1e58cc --- /dev/null +++ b/.claude/scripts/README.md @@ -0,0 +1,38 @@ +# Claude Helper Scripts + +Utility scripts to support Claude Code when working with this documentation repository. + +## resolve-doc-url.sh + +Resolves a documentation URL to its source markdown file. + +### Usage + +```bash +.claude/scripts/resolve-doc-url.sh "/path/to/page/" +``` + +### Examples + +```bash +# Find the file for a specific URL +.claude/scripts/resolve-doc-url.sh "/community-tools/contribute-to-mendix-docs/" +# Output: content/en/docs/community-tools/contribute-to-mendix-docs/_index.md + +# Check if a URL exists +.claude/scripts/resolve-doc-url.sh "/some/page/" +# Exit code 0 if found, 1 if not found +``` + +### Benefits + +- **Fast**: Uses grep optimized for file-only output +- **Token-efficient**: Returns only the file path, no surrounding context +- **Reliable**: Matches exact URL in front matter using fixed-string search + +### When to Use + +- Following cross-references between documentation pages +- Validating internal links +- Finding files by their published URL +- Checking if a URL is already in use diff --git a/.claude/scripts/resolve-doc-url.sh b/.claude/scripts/resolve-doc-url.sh new file mode 100644 index 00000000000..4af6c42229e --- /dev/null +++ b/.claude/scripts/resolve-doc-url.sh @@ -0,0 +1,15 @@ +#!/bin/bash +# Resolve a documentation URL to its source markdown file +# Usage: resolve-doc-url.sh "/path/to/page/" + +if [ -z "$1" ]; then + echo "Usage: resolve-doc-url.sh " + echo "Example: resolve-doc-url.sh '/community-tools/contribute-to-mendix-docs/'" + exit 1 +fi + +# Search for the URL in front matter +# Using grep with -l (files only) and -F (fixed string) for speed +grep -rl --include="*.md" "^url: $1$" content/en/docs/ + +# Exit code 0 if found, 1 if not found diff --git a/CLAUDE.md b/CLAUDE.md index 380a57902bc..97bd4b5136f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -99,9 +99,14 @@ Call tools in parallel for independent operations (reading multiple files, multi * **Glob** – Use to find files by pattern (e.g., `*.md`, `**/*config*`) * **Grep** – Use to search file contents for specific text or patterns * **Write** – Use only for creating new files (prefer Edit for existing files) +* **Helper Scripts** – Use `.claude/scripts/resolve-doc-url.sh` to resolve documentation URLs (e.g., `/path/to/page/`) to their source markdown files. This is faster and more token-efficient than using Grep to search front matter. ### Cross-Reference Verification +When following or verifying documentation links: +* Use `.claude/scripts/resolve-doc-url.sh "/path/to/page/"` to quickly find the source file for a URL +* This is more efficient than Grep for URL-to-file lookups + When modifying URLs or anchor IDs: 1. Use Grep to search for the old URL/anchor across all documentation files 2. Identify all references that need updating From ff69d0e9255f7e525d6aaeac8022a4bd56011c51 Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Thu, 16 Apr 2026 15:15:36 +0200 Subject: [PATCH 6/8] Clarify how to identify changes for review --- .claude/skills/docs-reviewpr/SKILL.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .claude/skills/docs-reviewpr/SKILL.md diff --git a/.claude/skills/docs-reviewpr/SKILL.md b/.claude/skills/docs-reviewpr/SKILL.md new file mode 100644 index 00000000000..54145073755 --- /dev/null +++ b/.claude/skills/docs-reviewpr/SKILL.md @@ -0,0 +1,16 @@ +--- +name: docs-pr-review +description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull requestumentation, or when they want suggestions before making changes. +user-invocable: true +disable-model-invocation: false +--- + +Compare changes between the current branch and the base branch (typically `development`). Read the complete final state of each modified file, not just the diff, to ensure changes don't introduce inconsistencies with unchanged content. + +Analyze all the changes in the current pull request or branch and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Read the whole of each document modified in the pull request to ensure the changes do not make inconsistencies. + +Follow links to other documents in the repo to check for inconsistencies if they seem to provide important related information. + +Do not worry about possible invalid internal links to anchors in the repo as these will be picked up by a separate testing tool after the site has been built. + +Make no edits. From 7bc1c3c77325ad3aea2990fce6283ccf6dcaad19 Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Thu, 16 Apr 2026 15:18:48 +0200 Subject: [PATCH 7/8] Remove duplicate skill with different name. --- .claude/skills/docs-pr-review/SKILL.md | 8 ++++++-- .claude/skills/docs-reviewpr/SKILL.md | 16 ---------------- 2 files changed, 6 insertions(+), 18 deletions(-) delete mode 100644 .claude/skills/docs-reviewpr/SKILL.md diff --git a/.claude/skills/docs-pr-review/SKILL.md b/.claude/skills/docs-pr-review/SKILL.md index 1f3b8cbd73b..54145073755 100644 --- a/.claude/skills/docs-pr-review/SKILL.md +++ b/.claude/skills/docs-pr-review/SKILL.md @@ -1,12 +1,16 @@ --- name: docs-pr-review -description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull request, or when they want suggestions before making changes. +description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull requestumentation, or when they want suggestions before making changes. user-invocable: true disable-model-invocation: false --- +Compare changes between the current branch and the base branch (typically `development`). Read the complete final state of each modified file, not just the diff, to ensure changes don't introduce inconsistencies with unchanged content. + Analyze all the changes in the current pull request or branch and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Read the whole of each document modified in the pull request to ensure the changes do not make inconsistencies. -When referring to the files, ensure you are clear about the file and lines which raise your concerns. +Follow links to other documents in the repo to check for inconsistencies if they seem to provide important related information. + +Do not worry about possible invalid internal links to anchors in the repo as these will be picked up by a separate testing tool after the site has been built. Make no edits. diff --git a/.claude/skills/docs-reviewpr/SKILL.md b/.claude/skills/docs-reviewpr/SKILL.md deleted file mode 100644 index 54145073755..00000000000 --- a/.claude/skills/docs-reviewpr/SKILL.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: docs-pr-review -description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull requestumentation, or when they want suggestions before making changes. -user-invocable: true -disable-model-invocation: false ---- - -Compare changes between the current branch and the base branch (typically `development`). Read the complete final state of each modified file, not just the diff, to ensure changes don't introduce inconsistencies with unchanged content. - -Analyze all the changes in the current pull request or branch and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Read the whole of each document modified in the pull request to ensure the changes do not make inconsistencies. - -Follow links to other documents in the repo to check for inconsistencies if they seem to provide important related information. - -Do not worry about possible invalid internal links to anchors in the repo as these will be picked up by a separate testing tool after the site has been built. - -Make no edits. From 739672cb68712ce58eba6aa0de32829f7562993a Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 17 Apr 2026 13:31:26 +0200 Subject: [PATCH 8/8] Update descriptions Changes suggested by docs-pr-review --- .claude/skills/docs-pr-review/SKILL.md | 2 +- .claude/skills/docs-review/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/docs-pr-review/SKILL.md b/.claude/skills/docs-pr-review/SKILL.md index 54145073755..90a0bbcee7b 100644 --- a/.claude/skills/docs-pr-review/SKILL.md +++ b/.claude/skills/docs-pr-review/SKILL.md @@ -1,6 +1,6 @@ --- name: docs-pr-review -description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull requestumentation, or when they want suggestions before making changes. +description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull request, or when they want suggestions before making changes. user-invocable: true disable-model-invocation: false --- diff --git a/.claude/skills/docs-review/SKILL.md b/.claude/skills/docs-review/SKILL.md index 4d48a03cb34..b8986ed2659 100644 --- a/.claude/skills/docs-review/SKILL.md +++ b/.claude/skills/docs-review/SKILL.md @@ -1,6 +1,6 @@ --- name: docs-review -description: Analyzes a single documentation page and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on documentation, or when they want suggestions before making changes. +description: Analyzes a single documentation page and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a documentation page or section, or when they want suggestions before making changes. user-invocable: true disable-model-invocation: false ---