| 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].
