diff --git a/CLAUDE.md b/CLAUDE.md
index 98e5bfef..88c4e2bf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,6 +5,7 @@ These guidelines ensure consistency and quality when writing or modifying Windmi
 ## Content
 
 - The doc should focus on the user experience, not on the engineering behind it, unless it's important (e.g. feature related to performance)
+- **Before writing new documentation, review @writing_style_guide.md for guidance about how to write good documentation**
 
 ## File structure and naming
 
diff --git a/writing_style_guide.md b/writing_style_guide.md
new file mode 100644
index 00000000..61b9ae86
--- /dev/null
+++ b/writing_style_guide.md
@@ -0,0 +1,22 @@
+# Claude writing style guide
+
+This file contains writing style guidance when creating Windmill documentation. Review this guide before writing new documentation.
+
+## General writing style issues
+
+### Overly marketing language
+
+**Problem example:**
+"Windmill can automatically fill your script and flow input forms using AI to save you time and effort. This intelligent feature analyzes your form parameters and can populate them with contextually appropriate values based on your requirements."
+
+**Issues:**
+
+- Too long and verbose for technical documentation
+- Marketing language like "This intelligent feature" sounds promotional rather than technical
+- Users prefer concise, direct explanations over flowery descriptions
+
+**Better approach:**
+
+- Keep descriptions short and technical
+- Focus on what the feature does, not how "intelligent" or "smart" it is
+- Use straightforward language: "Windmill can auto-fill script and flow inputs using AI" instead of verbose marketing copy