diff --git a/.claude/skills/validate/SKILL.md b/.claude/skills/validate/SKILL.md index 9d4added6e..7bac78bc89 100644 --- a/.claude/skills/validate/SKILL.md +++ b/.claude/skills/validate/SKILL.md @@ -88,7 +88,18 @@ Perform the following checks **only on files within the determined scope**: - This checks that highlighted lines match the intended content - Particularly important for Before/After comparison blocks -7. **Deep Lesson Review** (when reviewing a specific lesson file) +7. **Check Writing Style** + + - Search for LLM-style patterns that should be avoided: + - `Let's` or `let's` at start of sentences + - `Remember when` or `Remember that` callbacks + - `Don't worry` reassurances + - `worth mentioning` or `important to note` padding + - Exclamation marks used for emphasis (not in code/output) + - Check for em-dash elaborations (space-hyphen-space followed by lowercase) that could be periods + - Flag any issues found for manual review + +8. **Deep Lesson Review** (when reviewing a specific lesson file) If the user asks to review a specific lesson, perform this comprehensive checklist: @@ -143,6 +154,15 @@ Perform the following checks **only on files within the determined scope**: - [ ] Examples can be run as shown - [ ] Output examples match what code produces + g. **Writing Style** (see CLAUDE.md for full guidelines): + + - [ ] No LLM-style interjections ("Let's", "Remember when...?", "Don't worry") + - [ ] No exclamation-based emphasis ("Much faster!", "So powerful!") + - [ ] Em-dash elaborations replaced with periods or semicolons + - [ ] List explanations use colons, not hyphens + - [ ] Single clear explanation per concept (not multiple phrasings) + - [ ] Professional, direct tone throughout + ## Output Format Provide a structured report. For automated validation checks: @@ -177,6 +197,12 @@ Found 2 orphaned markdown files: ✓ All admonitions properly formatted [or list of issues] +## Writing Style +✓ No LLM-style patterns found +[or list of issues with file:line, e.g.:] +- docs/example.md:42: "Let's see how..." -> rephrase +- docs/example.md:87: em-dash elaboration -> use period + ## Summary [Overall assessment and recommended actions] ``` @@ -204,6 +230,9 @@ For deep lesson reviews, add: ### Examples & Code [Assessment of code quality] +### Writing Style +[Assessment of tone and language patterns] + ### Overall Assessment [Summary with severity-organized issues and recommendations] diff --git a/CLAUDE.md b/CLAUDE.md index 80c6fe4cc2..de23e0046d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -90,6 +90,56 @@ prettier --write docs/**/*.md - **UPPERCASE processes**: Process names like `PROCESS_NAME` - **Shebang required**: `#!/usr/bin/env nextflow` - **Educational focus**: Keep examples simple and well-commented +- **Dot notation for channels**: Use `.map{}`, `.view{}` instead of pipe operators + +### Writing Style + +Training materials should be clear, direct, and professional. Avoid patterns common in LLM-generated text: + +**Tone:** + +- Get to the point. Don't pad sentences with unnecessary elaboration +- Avoid casual interjections like "Let's", "Now let's", "Remember when we...?" +- Don't use exclamations for emphasis ("Much faster!", "So powerful!") +- Avoid phrases like "worth mentioning", "it's important to note", "don't worry" +- Use professional, neutral language rather than enthusiasm or reassurance + +**Sentence structure:** + +- Replace em-dash elaborations with periods or semicolons + - Instead of: "This downloads the plugin - which happens automatically" + - Write: "This downloads the plugin. It happens automatically." +- Use colons for list item explanations, not hyphens + - Instead of: "**Option A** - does something useful" + - Write: "**Option A**: does something useful" +- Keep explanations concise. One clear explanation is better than two different phrasings + +**Content organization:** + +- Don't explain the same concept two different ways. Pick one approach +- Avoid redundant sections (e.g., listing plugins when linking to a registry) +- Focus on practical, actionable information +- When teaching a concept, show one clear path rather than multiple alternatives + +**Examples of what to avoid:** + +```markdown + + +Let's see how this works! +Remember when we created the config file earlier? +This is really powerful - it means you can do X, Y, and Z! +Don't worry - the tool handles this automatically. +It's worth mentioning that... + + + +Here's how this works. +The config file from section 2.1 defines... +This enables X, Y, and Z. +The tool handles this automatically. +Note that... (or just state the fact directly) +``` ### Module Structure