Skip to content

Commit 4375c80

Browse files
pinin4fjordsclaude
andcommitted
Add writing style guidance to Claude configuration
Based on feedback from PR reviews, add comprehensive writing style guidelines to help maintain consistent, professional tone in training materials. Changes: - CLAUDE.md: Add "Writing Style" section with guidelines on tone, sentence structure, and content organization - CLAUDE.md: Add dot notation guidance for Nextflow channel operations - validate skill: Add task 7 "Check Writing Style" with specific patterns to search for - validate skill: Add writing style checklist to Deep Lesson Review - validate skill: Add Writing Style section to output format Key style guidelines: - Avoid LLM-style interjections ("Let's", "Remember when...?") - Replace em-dash elaborations with periods/semicolons - Use colons for list explanations, not hyphens - One clear explanation per concept, not multiple phrasings - Professional, direct tone throughout Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 5e9f261 commit 4375c80

File tree

2 files changed

+78
-1
lines changed

2 files changed

+78
-1
lines changed

.claude/skills/validate/SKILL.md

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,18 @@ Perform the following checks **only on files within the determined scope**:
8888
- This checks that highlighted lines match the intended content
8989
- Particularly important for Before/After comparison blocks
9090

91-
7. **Deep Lesson Review** (when reviewing a specific lesson file)
91+
7. **Check Writing Style**
92+
93+
- Search for LLM-style patterns that should be avoided:
94+
- `Let's` or `let's` at start of sentences
95+
- `Remember when` or `Remember that` callbacks
96+
- `Don't worry` reassurances
97+
- `worth mentioning` or `important to note` padding
98+
- Exclamation marks used for emphasis (not in code/output)
99+
- Check for em-dash elaborations (` - ` followed by lowercase) that could be periods
100+
- Flag any issues found for manual review
101+
102+
8. **Deep Lesson Review** (when reviewing a specific lesson file)
92103

93104
If the user asks to review a specific lesson, perform this comprehensive checklist:
94105

@@ -143,6 +154,15 @@ Perform the following checks **only on files within the determined scope**:
143154
- [ ] Examples can be run as shown
144155
- [ ] Output examples match what code produces
145156

157+
g. **Writing Style** (see CLAUDE.md for full guidelines):
158+
159+
- [ ] No LLM-style interjections ("Let's", "Remember when...?", "Don't worry")
160+
- [ ] No exclamation-based emphasis ("Much faster!", "So powerful!")
161+
- [ ] Em-dash elaborations replaced with periods or semicolons
162+
- [ ] List explanations use colons, not hyphens
163+
- [ ] Single clear explanation per concept (not multiple phrasings)
164+
- [ ] Professional, direct tone throughout
165+
146166
## Output Format
147167

148168
Provide a structured report. For automated validation checks:
@@ -177,6 +197,12 @@ Found 2 orphaned markdown files:
177197
✓ All admonitions properly formatted
178198
[or list of issues]
179199
200+
## Writing Style
201+
✓ No LLM-style patterns found
202+
[or list of issues with file:line, e.g.:]
203+
- docs/example.md:42: "Let's see how..." -> rephrase
204+
- docs/example.md:87: em-dash elaboration -> use period
205+
180206
## Summary
181207
[Overall assessment and recommended actions]
182208
```
@@ -204,6 +230,9 @@ For deep lesson reviews, add:
204230
### Examples & Code
205231
[Assessment of code quality]
206232
233+
### Writing Style
234+
[Assessment of tone and language patterns]
235+
207236
### Overall Assessment
208237
[Summary with severity-organized issues and recommendations]
209238

CLAUDE.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,54 @@ prettier --write docs/**/*.md
9090
- **UPPERCASE processes**: Process names like `PROCESS_NAME`
9191
- **Shebang required**: `#!/usr/bin/env nextflow`
9292
- **Educational focus**: Keep examples simple and well-commented
93+
- **Dot notation for channels**: Use `.map{}`, `.view{}` instead of pipe operators
94+
95+
### Writing Style
96+
97+
Training materials should be clear, direct, and professional. Avoid patterns common in LLM-generated text:
98+
99+
**Tone:**
100+
101+
- Get to the point. Don't pad sentences with unnecessary elaboration
102+
- Avoid casual interjections like "Let's", "Now let's", "Remember when we...?"
103+
- Don't use exclamations for emphasis ("Much faster!", "So powerful!")
104+
- Avoid phrases like "worth mentioning", "it's important to note", "don't worry"
105+
- Use professional, neutral language rather than enthusiasm or reassurance
106+
107+
**Sentence structure:**
108+
109+
- Replace em-dash elaborations with periods or semicolons
110+
- Instead of: "This downloads the plugin - which happens automatically"
111+
- Write: "This downloads the plugin. It happens automatically."
112+
- Use colons for list item explanations, not hyphens
113+
- Instead of: "**Option A** - does something useful"
114+
- Write: "**Option A**: does something useful"
115+
- Keep explanations concise. One clear explanation is better than two different phrasings
116+
117+
**Content organization:**
118+
119+
- Don't explain the same concept two different ways. Pick one approach
120+
- Avoid redundant sections (e.g., listing plugins when linking to a registry)
121+
- Focus on practical, actionable information
122+
- When teaching a concept, show one clear path rather than multiple alternatives
123+
124+
**Examples of what to avoid:**
125+
126+
```markdown
127+
<!-- Avoid these patterns -->
128+
Let's see how this works!
129+
Remember when we created the config file earlier?
130+
This is really powerful - it means you can do X, Y, and Z!
131+
Don't worry - the tool handles this automatically.
132+
It's worth mentioning that...
133+
134+
<!-- Better alternatives -->
135+
Here's how this works.
136+
The config file from section 2.1 defines...
137+
This enables X, Y, and Z.
138+
The tool handles this automatically.
139+
Note that... (or just state the fact directly)
140+
```
93141

94142
### Module Structure
95143

0 commit comments

Comments
 (0)