Update proofread skill with heading IDs and conciseness prompt

Author: antfitch

.agents/skills/proofread_markdown/SKILL.md

@@ -1,90 +1,57 @@
 ---
-name: proofread_markdown
-description: Proofreads markdown files that were changed in a workspace
+name: proofread-markdown
+description: Proofreads Markdown files against Google guidelines.
 ---
 
-# Proofread markdown files
+# Proofreading Markdown
 
-Hi there! You can use this skill to proofread markdown files. This particular
-project has documentation style rules that are slightly different than what you
-are used to, so please use the steps in this workflow to update any markdown
-files that have changed.
+## Overview
 
-## 1. Check line length
+Help us transform technical text into clear, concise,
+and machine-readable Markdown. We follow the
+Google Developer Documentation Style Guide.
 
-Leadership does not want markdown files to have lines that exceed 80 characters.
-The reason is that it makes it easier to read for humans, and this is easier for
-agents, when a screenshot of a markdown file is needed.
+## Workflow
 
-1. Run the `wrap_lines.dart` script on the file to automate line wrapping:
+### 1. Check line length
 
-   ```bash
-   dart .agents/skills/proofread_markdown/scripts/wrap_lines.dart <file_path>
-   ```
+- [ ] Keep lines under 80 characters.
+- [ ] Ask the user if they would like to use:
+      - **Semantic line breaks**: Break lines semantically.
+         according to the guidelines in
+        [references/semantic_breaks.md](references/semantic_breaks.md). 
+      - **Simple line wrapping**: Wrap lines every 80 characters using
+        [scripts/wrap_lines.dart](scripts/wrap_lines.dart).
+      - **No line wrapping**: Do not change the line wrapping, let the user
+        do it themselves.
+- [ ] Verify that the file was wrapped correctly, preserving headings and
+      code blocks
 
-2. Verify that the file was wrapped correctly (preserving headings and
-   code blocks).
+### 2. Fix voice and tone
 
+- [ ] Use active voice.
+- [ ] Use present tense.
+- [ ] Use second person ("you"). No "we".
 
-## 2. Convert headings with title case to sentence case
+### 3. Check word choice
 
-If you see a heading (any level) that use title case like this:
+- [ ] Replace forbidden terms: "e.g.", "i.e.", "etc.", "should", "would",
+      "could".
+- [ ] Use Oxford comma and American spelling.
 
-```
-## Do A Thing
-```
+### 4. Check style of headings and lists
 
-Change it to look like this
+- [ ] Use Sentence case for headings.
+      - If you change a heading, add an id after the heading like this:
+        "## Configure the project {: #project-configuration }"
+- [ ] Put a blank line after all headings.
+- [ ] Numbered lists MUST use `1.` for every item to allow easy reordering.
+- [ ] How-to sections must have active voice in headings.
+      - No: "## Project Configuration"
+      - Yes: "## Configure the project"
+      
+### 5. Use less words in sections with steps
 
-```
-## Do a thing
-```
-
-## 3. Use active voice in headings
-
-Let's use active voice in headings. So if you see a heading that looks like
-this:
-
-```
-## Project Configuration
-```
-
-Change it to active voice that looks like this:
-
-```
-## Configure the project
-```
-
-## 4. Put a blank line after headings
-
-Make sure there is always a blank line after a heading. So if you see a
-heading that looks like this:
-
-```
-## Configure the project
-Do a thing, blah blah blah.
-```
-
-Change it to look like this:
-
-```
-## Configure the project
-
-Do a thing, blah blah blah.
-```
-
-## 5. Use less words in sections with steps
-
-If a section has steps in it, be brief. Keep it short, simple, and accurate.
-
-Change steps to be direct like this:
-
-```
- ### Search for a Topic
-
- 1.  Navigate to the **Search** tab (Magnifying Glass icon).
- 2.  Select **View topics** from the dropdown (default).
- 3.  Enter your query in the "Query" text box (e.g., "Flutter widgets").
- 4.  Press **Enter**.
- 5.  View results in the main content area.
-```
+- [ ] Ask the user if they would like the steps to be more concise. 
+      If yes, update the steps to be brief. Keep it short, simple, and
+      accurate.

.agents/skills/proofread_markdown/references/semantic_breaks.md

@@ -0,0 +1,46 @@
+# Semantic Line Breaks
+
+Semantic line breaks make Markdown files easier to read,
+maintain, and review in diffs.
+Instead of wrapping text at a strict character limit,
+lines are broken at natural pauses.
+
+- **Max length**: Try to keep lines under 80 characters.
+- **Punctuation first**: Break lines after periods, commas, colons, and
+  semicolons.
+- **Natural pauses**: If a line is still too long after punctuation,
+  break at natural pauses (for example, ends of phrases).
+- **No mid-word breaks**: Never break a line in the middle of a word.
+- **Safety**: Do not break URLs, file paths, or code strings.
+
+## Examples
+
+### Bad: Strict 80-character wrapping
+
+This approach makes diffs hard to read
+because changing one word reflows the entire paragraph.
+
+```markdown
+This is a very long sentence that is wrapped at exactly eighty characters
+without considering the meaning of the words or the structure of the sentence.
+```
+
+### Good: Semantic line breaks
+
+This approach keeps lines readable
+and ensures that changes to one sentence only affect that line in the diff.
+
+```markdown
+This is a very long sentence,
+that is wrapped at natural pauses
+to make it easier to read and maintain.
+```
+
+Another example with list items:
+
+```markdown
+- This is a list item,
+  broken at the comma.
+- Here is another item
+  that is broken at a natural pause.
+```