Add Claude instructions

Author: dbreseman

.claude/skills/add/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: add
+description: Adds new content to existing documentation pages while preserving the original structure and meaning. Integrates new sections, paragraphs, or information smoothly with appropriate transitions. Use when the user wants to add, insert, include, or append new content to existing pages without rewriting what's already there.
+user-invocable: true
+disable-model-invocation: true
+---
+
+> **After adding content:** Consider running `/polish` to improve clarity or `/proofread` to check for errors in the final result.
+
+Ask the user for the new content to add. Determine a suitable place to smoothly integrate the new content into the existing content, with appropriate transitions and formatting, while preserving the original meaning and structure of the page. Don't make changes to existing content unless necessary for clarity or coherence when adding the new content.
+
+If the new content introduces redundancy or conflicts with existing content, flag these issues in the chat and suggest ways to resolve them without directly editing the existing content.

.claude/skills/enhance/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: enhance
+description: Performs comprehensive editing including reorganization, restructuring, and rephrasing while preserving original meaning and intent. Improves flow, strengthens weak phrasing, and enhances overall quality. Use when documentation needs significant structural improvements, better organization, or when the user mentions reorganize, restructure, rewrite, or enhance.
+user-invocable: true
+disable-model-invocation: true
+---
+
+> **Skill progression:** This is the most intensive editing. If restructuring isn't needed, use `/polish` for clarity improvements or `/proofread` for basic fixes.
+
+Perform holistic improvements, including reorganization and stronger phrasing, while preserving original intent. This goes beyond basic proofreading and polishing to enhance the overall quality and impact of the text. Consider restructuring sentences, paragraphs, or sections for better flow, replacing weak words with stronger alternatives, and improving clarity and consistency while maintaining the original meaning. However, avoid making changes just for the sake of change; every edit should serve a clear purpose in enhancing the text.

.claude/skills/polish/SKILL.md

@@ -0,0 +1,32 @@
+---
+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.
+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`.
+
+First, use the Skill tool to invoke the `proofread` skill.
+
+Then immediately continue: improve clarity and readability without changing meaning, structure, or paragraph order:
+
+**Polish should**:
+* 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
+
+**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)
+
+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.

.claude/skills/proofread/SKILL.md

@@ -0,0 +1,27 @@
+---
+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.
+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`.
+
+Proofread the document for technical correctness only. Do NOT rewrite, rephrase, or improve clarity:
+
+* **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
+
+Do NOT:
+* Rewrite sentences for clarity or conciseness
+* Shorten or improve descriptions
+* Change passive voice to active voice
+* Simplify complex sentences
+* Reorganize content
+
+If you notice style or clarity issues that need improvement, finish proofreading first, then suggest the user run `/polish` for those improvements.

.claude/skills/review/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: review
+description: Analyzes documentation pages 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.
+user-invocable: true
+disable-model-invocation: false
+---
+
+Analyze the page and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Make no edits.

.github/copilot-instructions.md

@@ -15,7 +15,7 @@ When instructions conflict, follow this order of precedence:
 5. Existing conventions in nearby pages within the same folder.
 6. Microsoft Writing Style Guide.
 
-### Default Execution Mode
+### Critical Constraints
 
 * MUST edit existing files in place unless the user explicitly asks to create new content.
 * MUST preserve meaning and intent.
@@ -48,7 +48,7 @@ content/en/docs/
 …
 ```
 
-* **Index files (`_index.md`)** define landing pages or categories. They often use `cascade` to pass metadata to children and may set `type`, `layout`, `no_list`, `description_list` etc.
+* **Index files (`_index.md`)** define landing pages or categories. They often use `cascade` to pass metadata to children and may set `type`, `layout`, `no_list`, `description_list`, etc.
 * Other `.md` files represent individual articles, how‑tos, reference topics, release notes, etc. File names must be simple, lowercase, and hyphen‑separated.
 
 Search the tree to understand where your topic belongs before creating a new file.
@@ -61,7 +61,7 @@ Search the tree to understand where your topic belongs before creating a new fil
 * **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.
 * **Headings** – H1 is generated from the front‑matter title. Subsequent headings increment by one level at a time. Don't use bold or italics as a replacement for headings. Use title case. Never start headings with numbers.
 * **Lists and tables** – Bullet lists use asterisks; ordered lists use numbers followed by a period. If there are more than three data points per item, use a table instead. Use the same syntax and structure for all list items in a given list. Use complete sentences to introduce lists and tables, not partial sentences completed with the list items. 
-* **Indentation** – Use four spaces to indent content—for example, to create a sub-list or nest an image or code block in a list. Alerts are an exception: To indent an alert within a list, omit the blank line before the alert. Don't indent the lines of the alert. 
+* **Indentation** – Use four spaces to indent content—for example, to create a sub-list or nest an image or code block in a list. Alerts 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 and alt text** – Always provide `alt` text describing the content; if the image is purely decorative, use `alt=""`. Use W3C guidelines to write alt text. Reference images with the `figure` shortcode (see below).
 * **Code** – Use fenced code blocks with language specifier.
@@ -87,9 +87,9 @@ All Markdown files begin with YAML metadata.
 
 ### Shortcodes
 
-Hugo shortcodes start with `{{` and encapsulate reusable components. The ones you will encounter most frequently include:
+Hugo shortcodes start with `{{`. Some common ones:
 
-* `figure` – Images and screenshots. Attributes: `src` (required), `alt` (required or `""`), `class`, `max-width`, `link`. Always store assets under `static/attachments/...` and reference with `/attachments/...`.
+* `figure` – Images. Attributes: `src` (required), `alt` (required), `class`, `max-width`, `link`. Always store assets under `static/attachments/...` and reference with `/attachments/...`.
 
   ```md
   {{< figure src="/attachments/quickstarts/part1/3.login.png" alt="Sign in to Studio Pro" max-width="80%" >}}
@@ -102,15 +102,15 @@ Hugo shortcodes start with `{{` and encapsulate reusable components. The ones yo
   {{% /alert %}}
   ```
 
-* `button` – Link buttons with `color`, `href`, `text`, and optional `title` attributes.
+* `button` – Link buttons with `color`, `href`, `text`, and optional `title`.
 * `icon` – Inline SVG icons stored in `static/mx-icons` (`name` required, optional `color`) for use in UI descriptions.
 * `youtube` / `vidyard` – Embed videos by ID.
 * `swaggerui` / `swaggerui-disable-try-it-out` – Render OpenAPI specs on pages with `type:swagger`.
 * `snippet` – Include external code or page content.
 * `tabpane` / `tab` – Create tabbed code examples.
 * `todo` – Internal draft notes; omitted in production.
 
-The `community-tools/contribute-to-mendix-docs/markdown-shortcodes.md` page contains comprehensive examples. Review it when adding new types or debugging rendering.
+For comprehensive shortcode examples and edge cases, read `community-tools/contribute-to-mendix-docs/markdown-shortcodes.md`.
 
 ## Editorial Workflow
 
@@ -123,11 +123,11 @@ The `community-tools/contribute-to-mendix-docs/markdown-shortcodes.md` page cont
 
 ## Standard Content Template
 
-If asked to create new content, start from `templates/*.md` and then follow the same checks above. Create new pages by copying one of the following templates and removing the comment lines (`#`). :
+If asked to create new content:
 
-* **How‑to** – `templates/how-to-template.md`
-* **Reference** – `templates/reference-template.md`
-* **Marketplace component** – `templates/marketplace-component-page-template.md`
-* **Release notes** – `templates/release-notes-template.md`
+1. Read the appropriate template from `templates/`: `how-to-template.md`, `reference-template.md`, `marketplace-component-page-template.md`, or `release-notes-template.md`
+2. Create the new file based on the template
+3. Remove comment lines (`#`) from the template
+4. Follow the editorial workflow above
 
 For all pages, required sections are front matter and the introduction; other sections vary by content type.

.github/prompts/add.prompt.md

@@ -2,6 +2,6 @@
 description: Add new content to a page without rewriting existing content.
 ---
 
-Prompt the user for the new content to add. Determine a suitable place to smoothly integrate the new content into the existing content, with appropriate transitions and formatting, while preserving the original meaning and structure of the page. Don't make changes to existing content unless necessary for clarity or coherence when adding the new content.
+Ask the user for the new content to add. Determine a suitable place to smoothly integrate the new content into the existing content, with appropriate transitions and formatting, while preserving the original meaning and structure of the page. Don't make changes to existing content unless necessary for clarity or coherence when adding the new content.
 
 If the new content introduces redundancy or conflicts with existing content, flag these issues in the chat and suggest ways to resolve them without directly editing the existing content.