Add proofread_markdown skill and Dart wrapper script by antfitch · Pull Request #13258 · flutter/website

antfitch · 2026-04-07T23:06:32Z

Proofread markdown skill for the Flutter Docs repo. You can use this skill to update your markdown files to follow the Flutter doc teams formatting guidelines.

Changes title case to sentence case in headings.
Converts headings from passive case to active case (note: when working with how-to and tutorials, this is a good thing, but there are times when this should be avoided, such as when you're introducing concepts. Look carefully at the changes before accepting them.
Ensures there is a blank line between heading and body text.
Refactors steps for brevity.

This is an early version of this skill. As time goes on, we'll update it to be more complete, fix bugs, etc. Use this with your AI agents, but in a mode where you can approve the changes.

gemini-code-assist

Code Review

This pull request introduces a new markdown proofreading skill and a supporting Dart script for automated line wrapping. The review feedback identifies a hardcoded absolute path in the documentation that needs to be corrected to a relative path. Additionally, the line-wrapping script has limitations in detecting ordered lists beyond three items and contains logic errors in the wrapText function that cause indentation loss and inaccurate width calculations.

.agents/skills/proofread_markdown/SKILL.md

.agents/skills/proofread_markdown/scripts/wrap_lines.dart

flutter-website-bot · 2026-04-07T23:13:45Z

Visit the preview URL for this PR (updated for commit 8d727f8):

https://flutter-docs-prod--pr13258-add-proofreading-skill-sfkqpa8t.web.app

sfshaza2

See comments.

sfshaza2 · 2026-04-07T23:52:35Z

.agents/skills/proofread_markdown/SKILL.md

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


One thing that bugs me about the bots, is that they complain about this:

1. a 1. b 1. c 1. d

However, we PREFER this in a markdown file. Markdown numbers the steps and then if, later, you remove or add a line, it automatically fixes it.

Updated! Pulled in @conooi's changes.

sfshaza2 · 2026-04-07T23:55:59Z

.agents/skills/proofread_markdown/scripts/wrap_lines.dart

@@ -0,0 +1,96 @@
+import 'dart:io';


OK, I've said this offline, but I really don't like this form of breaking lines. It's ugly, it's nasty to maintain. Semantic line breaks are much easier for a writer to process, read, update. Meaning, break on punctuation first, like commas, periods, semi-colons, colons. THEN if lines are still too long, break on natural pauses. Since that might be harder to teach a bot, I could live with breaking on 80 chars THEN.

It's MUCH easier to understand the diff of a file that uses semantic line breaks, rather than a straight 80 char line break. MUCH MUCH easier.

Yes to this. Breaking at 80 characters without considering meaning or structure isn't really useful and I'm worried about maintaining this script as well.

I've found agents can write and update text to use semantic breaks quite well. You just need to tell them to and reference a reference doc that briefly explaina the format and provides some examples.

A few thoughts I had around this today:

When I read a book (paperback or kindle), words generally break after a certain number of characters that don't fit on a line and this has never bothered me. So when I look at this discussion through that lens, breaking things semantically doesn't do much for me. Because I've been looking at markdown files for several years at work that simply follow the 80-character rule, I just don't have the issues of readability with non-semantic breaks.

Having an agent go line by line through a markdown file burns up a lot of tokens and is slower than a script that doesn't require tokens. On very large markdown files, a lot of tokens can be burned.

I've noticed from past recent experience that agents make mistakes when I ask them to manually go through a markdown file and fix line length. Especially in longer files, like us, they sometimes miss lines and I have to go back and double-check everything.

So, I feel strongly that we need to keep this, and especially for larger documents. However, I think we should have the ability for the author to choose.

I feel very strongly about this. I just pulled up this answer from Antigravity (it has not seen our conversation)

"Can you assess how token expensive checking line lengths is? Let's assume you have a document with 500 lines."

Direct LLM Check: 8,000 to 20,000 tokens (Expensive and prone to counting errors).

Tool-Assisted Check: ~100 tokens (Extremely cheap and 100% accurate).
If you are planning to implement this as part of a skill, I strongly recommend writing a short Dart script or using a regex-based tool to do the line-length checking and reporting back to the agent!

For this reason, I want to make sure we give contributors a choice. If they want to, they can choose one of three options and do some of the work by hand if they need to use semantic breaks.

BUT I will admit. When I chose the semantic line breaks option when presented by the agent, I love the results.

sfshaza2 · 2026-04-07T23:56:52Z

.agents/skills/proofread_markdown/SKILL.md

+
+## 1. Check line length
+
+Leadership does not want markdown files to have lines that exceed 80 characters.


This is NOT about Leadership. Please change that. This is what GitHub wants and the convention that we've agreed to and adhered to.

Deal! Actually I just grabbed @conooi's intro (love it!)

sfshaza2 · 2026-04-07T23:58:12Z

.agents/skills/proofread_markdown/SKILL.md

+## Project Configuration
+```
+
+Change it to active voice that looks like this:


Also mention that we don't use gerunds in titles or headers. So: "Configure project" is cool but "Configuring project" is to be avoided.

Grabbed @conooi's version. I think you'll like!
Also, if a heading changes, I had the skill add the original link id after the heading to links don't break. ## Configure the project {: #project-configuration }

sfshaza2 · 2026-04-07T23:58:57Z

.agents/skills/proofread_markdown/SKILL.md

+Change steps to be direct like this:
+
+```
+ ### Search for a Topic


This should be:

### Search for a topic

facepalm updated.

sfshaza2 · 2026-04-07T23:59:50Z

.agents/skills/proofread_markdown/SKILL.md

+ 3.  Enter your query in the "Query" text box (e.g., "Flutter widgets").
+ 4.  Press **Enter**.
+ 5.  View results in the main content area.
+```


I had feedback I don't see now. But a numbered list should use "1." for each line.

antfitch · 2026-04-08T01:52:13Z

Add the format that @parlough is using here to separate sections: https://github.com/flutter/website-cms/blob/main/.agents/skills/generate-showcase-from-video/SKILL.md

parlough · 2026-04-08T13:15:48Z

Add the format that @parlough is using here to separate sections: https://github.com/flutter/website-cms/blob/main/.agents/skills/generate-showcase-from-video/SKILL.md

Just clarifying: That new, fancy skill is by @abdallahshaban557 :)

…ntation

antfitch requested review from a team and sfshaza2 as code owners April 7, 2026 23:06

gemini-code-assist bot reviewed Apr 7, 2026

View reviewed changes

.agents/skills/proofread_markdown/SKILL.md Outdated Show resolved Hide resolved

.agents/skills/proofread_markdown/scripts/wrap_lines.dart Outdated Show resolved Hide resolved

.agents/skills/proofread_markdown/scripts/wrap_lines.dart Show resolved Hide resolved

antfitch self-assigned this Apr 7, 2026

sfshaza2 reviewed Apr 8, 2026

View reviewed changes

antfitch added 3 commits April 9, 2026 22:09

Add proofread_markdown skill and Dart wrapper script

4d5d35f

Address PR comments: fix path, use regex for lists, and preserve inde…

127cad1

…ntation

Update proofread skill with heading IDs and conciseness prompt

8d727f8

antfitch force-pushed the add_proofreading_skill branch from 7f88129 to 8d727f8 Compare April 10, 2026 03:09


		## 1. Check line length

		Leadership does not want markdown files to have lines that exceed 80 characters.

Conversation

antfitch commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

flutter-website-bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

antfitch commented Apr 8, 2026

Uh oh!

parlough commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

antfitch commented Apr 7, 2026 •

edited

Loading

flutter-website-bot commented Apr 7, 2026 •

edited

Loading

parlough commented Apr 8, 2026 •

edited

Loading