By name: grammar-check description: Scan content files for prohibited punctuation (hyphens as dashes, endashes, emdashes) and rewrite using preferred alternatives user_invocable: true
Grammar and Punctuation Check
Role: implementation. This skill modifies content files to fix prohibited dash punctuation.
Scan content files for prohibited dash-like punctuation and rewrite sentences to use preferred grammar marks instead.
Constraints
- Minimal changes. Only rewrite sentences containing prohibited punctuation. Do not reformat or improve surrounding content.
- Be concise. Output the change summary. No preambles.
- Preserve meaning. Rewrites must preserve the original meaning of every sentence.
- Validate after changes. Re-scan the file after edits to confirm no violations remain.
Prohibited Characters
These characters must NEVER appear as grammatical punctuation in content files:
| Character | Name | Example of violation |
|---|---|---|
- |
Hyphen used as a dash | The team ships - when ready |
-- |
Double hyphen | The team ships -- when ready |
– |
Endash (U+2013) | The team ships – when ready |
— |
Emdash (U+2014) | The team ships — when ready |
Hyphens are allowed in these non-dash contexts:
- Compound modifiers before a noun:
domain-aligned teams,well-defined APIs,cross-team coordination - Prefixed words:
re-examine,pre-commit - Technical terms and slugs:
trunk-based-development,risk_level: high - YAML front matter values
- Mermaid diagram syntax
- Code blocks and inline code
- List item markers at the start of a line (
- item)
Preferred Alternatives
When you find a dash used as grammatical punctuation, rewrite using one of these:
1. Split into two sentences (preferred for most cases)
- Before:
CI requires daily integration - without it, branches diverge - After:
CI requires daily integration. Without it, branches diverge.
2. Use a colon for elaboration or lists
- Before:
The result is predictable - slower delivery - After:
The result is predictable: slower delivery
3. Use parentheses for asides
- Before:
The team - all five members - agreed - After:
The team (all five members) agreed
4. Use a comma for light pauses
- Before:
The pipeline runs - then stops - After:
The pipeline runs, then stops
5. Restructure the sentence
- Before:
Architecture decoupling - through APIs and contracts - enables independent deployment - After:
Architecture decoupling through APIs and contracts enables independent deployment
Instructions
When this skill is invoked:
- Accept file paths as arguments. If no arguments are given, ask which files to check.
- Read each file.
- Skip YAML front matter, code blocks (fenced with triple backticks), inline code (backticks), Mermaid diagrams, and list markers.
- Find every instance of a hyphen, double hyphen, endash, or emdash used as grammatical punctuation (surrounded by spaces, or at sentence boundaries).
- Rewrite each violation using one of the preferred alternatives above. Choose the alternative that best preserves the original meaning and reads most naturally.
- Apply the edits to the file.
- Report what was changed: line number, original text, replacement text.
Pattern Matching
To distinguish dash-as-punctuation from legitimate hyphens:
-(space-hyphen-space) in running text is almost always a dash. Exception: list continuation lines where-starts a sub-item.--(space-double-hyphen-space) is always a dash.–and—are always prohibited regardless of context.- Hyphens between words with no spaces (
domain-aligned,re-examine) are compound modifiers and are allowed. - Hyphens at the start of a line followed by a space are list markers and are allowed.
Output
After fixing all violations, report a summary:
Fixed N violations in [file]:
- Line X: "original text" -> "replacement text"
If no violations are found, report: No dash punctuation violations found in [file].