How AI can transform even Microsoft's own documentation to meet its style standards.
As a security researcher at Corelight, I produce a significant amount of technical documentation. Much of this documentation ends up in GitHub repositories or gets deployed to our Corelight sensors, where consistency and clarity are crucial. Writing technical documentation that meets style guide standards can be incredibly time-consuming, especially when you're juggling multiple projects and deadlines.
That's why I developed the llm-styleguide-helper tool—to speed up the time it takes me to write technical documentation that meets professional standards. After seeing how much time it saved me, I wanted to share it as open source so that others can also accelerate their documentation efforts.
Style guides are essential for maintaining consistency in technical documentation; however, manually applying them can be time-consuming and prone to errors. What if you could automate this process using AI? That's exactly what the llm-styleguide-helper tool does - it combines the power of Vale linting with AI to automatically fix style guide violations.
The tool operates through a sophisticated pipeline that scans documents for style violations and generates AI prompts to fix them. You can then manually copy these prompts to your favorite large language model (LLM), or use the --gemini flag to automatically process the corrections through Google’s Gemini CLI. Gemini was chosen for the automatic mode because it is the only online LLM I am aware of that does not require an API key, which can be costly and has no bounds, plus I already use Gemini for other work at Corelight. The methodology introduced here can be adapted to any organization's style guide or writing standards, making it a versatile solution for technical documentation teams.
The llm-styleguide-helper is part of the LLM-Ninja collection of AI-powered tools for document processing and LLM integration. More about LLM-Ninja and other LLM tricks can be found in some of the prior blogs I wrote:
Traditional style guide compliance involves:
This process is not only tedious but also prone to human error and inconsistency. Even Microsoft's own documentation (example below) isn't immune to style guide violations.
The llm-styleguide-helper is a Python script that revolutionizes this process by:
The tool offers two distinct workflows. I will discuss the manual mode first, which can be used with any LLM, followed by an automatic mode that utilizes Gemini to automatically correct the style of your input text.
The tool generates detailed prompts that you can copy and paste into ChatGPT, Claude, or any other LLM of your choice. This gives you full control over the AI model, allowing you to review changes before applying them.
When you run the tool in manual mode, it creates .prompt files next to each of your original documents. These prompt files contain:
For example, if you have a file called README.md, the tool will create README.md.prompt. You can then:
This approach provides you with complete control over which AI model to use, allowing you to review and edit changes before applying them.
The beauty of manual mode is that you can iteratively refine your documents until you're satisfied with the results. Here's how:
vale your-corrected-file.mdThis manual iteration process gives you complete control over the refinement cycle. You can decide when to stop based on your quality requirements, and you can even manually edit the LLM's suggestions before applying them.
Use the --gemini flag to automatically process your documents through Google's Gemini CLI. This provides a fully automated workflow that handles the entire process from detection to final correction.
When you use the --gemini flag, the tool:
This creates a fully automated iterative refinement process that continues until your document meets the style guide standards. The tool intelligently stops when it detects no further improvements for 3 consecutive iterations, preventing infinite loops.
The tool is specifically designed to work with Microsoft's open-sourced style guide. Microsoft's style guide is comprehensive and well-maintained, making it an excellent choice for technical documentation. The tool leverages Microsoft's extensive vocabulary definitions and style rules to provide accurate and consistent corrections.
Let's examine how this tool can enhance even Microsoft's official documentation. Using their own SECURITY.md file as an example:
Running Vale on Microsoft's SECURITY.md reveals 26 style violations:
% vale txt/SECURITY.mdHere's what Vale's output looks like:
txt/SECURITY.md
5:1 suggestion Use the Oxford comma in Microsoft.OxfordComma
'DotNet, AspNet and Xamarin.'.
5:33 warning Try to avoid using Microsoft.We
first-person plural like
'our'.
5:68 warning Remove 'seriously' if it's not Microsoft.Adverbs
important to the meaning of
the statement.
5:139 warning Try to avoid using Microsoft.We
first-person plural like
'our'.
7:1 suggestion Try to keep sentences short (< Microsoft.SentenceLength
30 words).
7:214 warning Try to avoid using Microsoft.We
first-person plural like 'us'.
9:4 suggestion 'Reporting Security Issues' Microsoft.Headings
should use sentence-style
capitalization.
11:10 error Use 'don't' instead of 'do Microsoft.Contractions
not'.
15:152 warning Try to avoid using Microsoft.We
first-person plural like
'our'.
15:156 suggestion 'PGP' has no definition. Microsoft.Acronyms
15:163 suggestion Try to simplify this sentence. Microsoft.Semicolon
15:229 suggestion 'PGP' has no definition. Microsoft.Acronyms
17:71 error Use 'don't' instead of 'do Microsoft.Contractions
not'.
17:109 suggestion Verify your use of 'ensure' Microsoft.Vocab
with the A-Z word list.
17:116 warning Try to avoid using Microsoft.We
first-person plural like 'we'.
17:178 suggestion 'be found' looks like passive Microsoft.Passive
voice.
19:92 warning Try to avoid using Microsoft.We
first-person plural like 'us'.
21:20 error Use 'for example' instead of Microsoft.Foreign
'e.g. '.
22:30 error Don't add '(s)' to a singular Microsoft.Plurals
noun. Use plural instead.
23:75 warning For a general audience, use Microsoft.GeneralURL
'address' rather than 'URL'.
29:28 warning Try to avoid using Microsoft.We
first-person plural like 'us'.
29:55 warning Remove 'quickly' if it's not Microsoft.Adverbs
important to the meaning of
the statement.
31:116 warning Try to avoid using Microsoft.We
first-person plural like
'our'.
31:219 warning Try to avoid using Microsoft.We
first-person plural like
'our'.
33:4 suggestion 'Preferred Languages' Microsoft.Headings
should use sentence-style
capitalization.
35:1 warning Try to avoid using Microsoft.We
first-person plural like 'We'.
✖ 4 errors, 13 warnings and 9 suggestions in 1 file.The output shows multiple types of issues:
With the llm-styleguide-helper, we can automatically fix these issues:
% python llm-styleguide-helper.py --gemini --model gemini-2.5-flash --vale-ini ./vale.ini --styleguide-dir ./microsoft-style-guide/styleguide/a-z-word-list-term-collections/ --input-dir txt
The tool processes the file through 4 iterations:
--- Processing file: SECURITY.md ---
Prompt written to txt/SECURITY.md.prompt
--- Processing file with Gemini: SECURITY.md ---
Iteration 1 for SECURITY.md
Current Vale alerts: 26
Baseline alert count: 26
Prompt written to txt/SECURITY.md.prompt
--- Sending prompt to Gemini CLI ---
--- Received response from Gemini CLI ---
Fixed content written to txt/SECURITY.md.fixed
Iteration 2 for SECURITY.md
Current Vale alerts: 3
✓ Improvement! New best alert count: 3
Prompt written to txt/SECURITY.md.prompt
--- Sending prompt to Gemini CLI ---
--- Received response from Gemini CLI ---
Fixed content written to txt/SECURITY.md.fixed
Iteration 3 for SECURITY.md
Current Vale alerts: 1
✓ Improvement! New best alert count: 1
Prompt written to txt/SECURITY.md.prompt
--- Sending prompt to Gemini CLI ---
--- Received response from Gemini CLI ---
Fixed content written to txt/SECURITY.md.fixed
Iteration 4 for SECURITY.md
Current Vale alerts: 0
✓ Improvement! New best alert count: 0
✓ No more Vale alerts. File is clean!
File SECURITY.md.fixed is already the best version.
Cleaned up txt/SECURITY.md.prompt
Completed 4 iterations for SECURITY.md. Final alert count: 0
✓ Gemini processing completed for SECURITY.md
All prompts generated.
Gemini auto-fixing completed.The AI automatically transformed the content:
Here's the full wdiff comparison showing every change made by the AI:
% wdiff txt/SECURITY.md txt/SECURITY.md.fixed<!-- BEGIN MICROSOFT SECURITY.MD V0.0.9 BLOCK -->
## Security
Microsoft takes the security of [-our-] {+its+} software products and [-services seriously,-] {+services,+} which includes all source code repositories managed through [-our-] {+its+} GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [-[AspNet](https://github.com/aspnet)-] {+[AspNet](https://github.com/aspnet),+} and [Xamarin](https://github.com/xamarin).
If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/security.md/definition), [-please-] report it [-to us-] as described below.
## Reporting [-Security Issues-] {+security issues+}
**Please [-do not-] {+don't+} report security vulnerabilities through public GitHub issues.**
Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report).
If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with [-our PGP key; please-] {+the Pretty Good Privacy (PGP) key. Please+} download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/security.md/msrc/pgp).
You should receive a response within 24 hours. If for some reason you [-do not,-] {+don't,+} please follow up via email to [-ensure we-] {+make sure Microsoft+} received your original message. [-Additional information-] {+You+} can [-be found-] {+find additional information+} at [microsoft.com/msrc](https://www.microsoft.com/msrc).
Please include the requested information listed below (as much as you can provide) to help [-us-] {+Microsoft+} better understand the nature and scope of the possible issue:
* Type of issue [-(e.g.-] {+(for example,+} buffer overflow, SQL injection, cross-site scripting, etc.)
* Full paths of source [-file(s)-] {+files+} related to the manifestation of the issue
* The location of the affected source code (tag/branch/commit or direct [-URL)-] {+address)+}
* Any special configuration required to reproduce the issue
* Step-by-step instructions to reproduce the issue
* Proof-of-concept or exploit code (if possible)
* Impact of the issue, including how an attacker might exploit the issue
This information will help [-us-] {+Microsoft+} triage your [-report more quickly.-] {+report.+}
If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit [-our-] {+the+} [Microsoft Bug Bounty Program](https://aka.ms/security.md/msrc/bounty) page for more details about [-our-] {+Microsoft's+} active programs.
## Preferred [-Languages
We prefer all-] {+languages
All+} communications [-to-] {+should+} be in English.
## Policy
Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/security.md/cvd).
<!-- END MICROSOFT SECURITY.MD BLOCK -->This comprehensive diff shows how the AI systematically addressed every style violation, from removing first-person pronouns to standardizing terminology and improving clarity.
The beauty of this approach is its versatility. This methodology can be applied to any type of content that needs style guide compliance:
Many open source projects have inconsistent documentation. The tool can:
Technical documentation often suffers from:
The AI can automatically:
Content creators can use this tool to:
Research and technical writing can benefit from:
The tool operates through a sophisticated pipeline:
The tool requires:
Basic setup:
# Install Vale
brew install vale # macOS
# For other platforms, see: https://vale.sh/docs/vale-cli/installation/
# Clone Microsoft Style Guide
git clone https://github.com/MicrosoftDocs/microsoft-style-guide.git
# Run the tool
python llm-styleguide-helper.py --input-dir ./docs --styleguide-dir ./microsoft-style-guide/styleguide/a-z-word-list-term-collections --geminiImportant: If you plan to use the automatic Gemini processing (with the --gemini flag), you'll need to install and configure Gemini CLI:
# Install Gemini CLI
npm install -g @google/gemini-cli
# or with Homebrew: brew install gemini-cli
# Authenticate with your Google account
gemini
This will prompt you to sign in with your Google account and grant permissions for Gemini.
You'll need to create a .vale.ini configuration file in your project root. This file tells Vale to use the Microsoft style guide and how to process your files:
StylesPath = styles
MinAlertLevel = suggestion
Packages = Microsoft
[formats]
txt = md
fixed = md
[*.{md,txt,fixed}]
BasedOnStyles = Microsoft
BlockIgnores = (?s) *(<think>.*?</think>)After creating this file, run vale sync to download the required style files.
Note: The BlockIgnores line tells Vale to ignore any ... tags that LLMs might add to their output, so we don't style the AI's thinking process.
Note: Vale’s alert levels are “suggestion”, “warning”, and “error”, in increasing severity. If you only wish to see warnings and errors, you can change the “MinAlertLevel” to “warning”. If you only want to see errors, change “MinAlertLevel” to “error”
The script offers several command-line options to customize its behavior:
Basic usage (manual mode):
python llm-styleguide-helper.py --input-dir ./docs --styleguide-dir ./microsoft-style-guide/styleguide/a-z-word-list-term-collectionsAutomatic processing with a specific model:
python llm-styleguide-helper.py --input-dir ./docs --styleguide-dir ./microsoft-style-guide/styleguide/a-z-word-list-term-collections --gemini --model gemini-2.5-flashUsing a custom Vale configuration:
python llm-styleguide-helper.py --input-dir ./docs --styleguide-dir ./microsoft-style-guide/styleguide/a-z-word-list-term-collections --vale-ini ./custom-vale.iniThe llm-styleguide-helper demonstrates how AI can transform the tedious task of style guide compliance into an automated, efficient process. By combining the precision of linting tools with the intelligence of large language models, we can achieve consistent, professional-quality documentation at scale.
Whether you're maintaining open source documentation, creating user guides, or writing technical content, this tool can help ensure your content meets Microsoft's high standards of style and consistency. The fact that it can improve even Microsoft's own documentation speaks to its effectiveness and potential impact.
As we move toward more automated content creation and editing workflows, tools like this will become essential for maintaining quality and consistency across all types of written content that follow Microsoft's style guide.
Streamline alert triage and reduce alert fatigue with Corelight's Microsoft Defender integration, enabling faster, smarter decisions across your SOC.
Corelight’s Microsoft vTAP integration brings cloud-native packet mirroring to Azure, with broader support for AWS, GCP, and third-party packet...
Accelerate alert analysis with Corelight’s LLM prompts for Suricata and Corelight data, featuring summaries, threat analysis, and next steps.