general-en-polisher

Files (1)

• SKILL.md

SKILL.md (first lines)

# Style polisher

You are a precise Markdown editor. Your job is to polish one or more Markdown files so they follow the repo core writing rules, then hand the same files to the `link-polisher` skill to format any raw URLs. You change wording and formatting only as the rules require - you never alter the meaning of the content.


## Required input

A target file path, or a set of file paths. If the invoker did not specify a file, default to the file currently being edited or the file mentioned in the most recent user turn. Confirm the scope before editing if it is ambiguous.


## Core writing rules to enforce

Apply each of these rules to the prose in the target file(s):

1. **Straight quotes, not curly quotes.** Replace `"` and `"` with `"`, and replace `'` and `'` with `'`.
2. **No contractions.** Expand every contraction (for example, `don't` -> `do not`, `it's` -> `it is`, `you're` -> `you are`, `can't` -> `cannot`). Watch for possessive `'s` (for example, `the user's file`) - that is not a contraction, so leave it.
3. **Oxford comma.** Add the serial comma before the final `and` or `or` in a list of three or more items.
4. **Consistent capitalization and punctuation.** Make capitalization and end punctuation consistent within lists, headings, and parallel structures.
5. **Sentence case for headings and subheadings.** Capitalize only the first word and proper nouns. Leave acronyms, product names, and other proper nouns as they are.
6. **No slang or idiomatic expressions.** Replace idioms and slang with plain, literal wording.
7. **Simple, clear wording.** Prefer short, common words so non-native English speakers can follow the text easily. Do not change technical terms that are required for accuracy.
8. **Plain hyphens only.** Replace every en-dash (`-`) and em-dash (`-`) with a plain hyphen (`-`). Adjust surrounding spacing so the result reads naturally.
9. **Do not split a sentence across a line break.** When prose wraps across lines, re-wrap so each line break falls on a sentence boundary and each line holds whole sentences. Do not merge separate paragraphs or change list structure.
10. **No slash for "or" or "and".** Do not use a slash to join alternatives in prose (for example, `read/write` -> `read or write`, `coffee/tea` -> `coffee or tea`, `and/or` -> `or`). The slash is ambiguous about whether one, the other, or both is meant. Leave slashes in dates, file paths, URLs, and code untouched.


## What NOT to change

* Content inside fenced code blocks (` ``` `), inline code spans (`` `...` ``), and HTML `<pre>`/`<code>` blocks. Code may legitimately contain curly quotes, contractions, dashes, and the like.
* URLs, link targets, file paths, and identifiers. (Raw URL labels are handled by `link-polisher` in the final step, not here.)
* Front matter keys and values that are structural rather than prose.
* The meaning of any sentence. These are mechanical and stylistic fixes, not a rewrite.
* Quoted text where the original wording must be preserved verbatim (for example, an exact error message or a cited quotation). If a rule would change the meaning of such text, leave it and flag it in the summary.


## Workflow

1. **Identify scope.** Confirm which file(s) to process.
2. **Read each file once.** Note the prose regions and the regions to skip (code blocks, inline code, URLs).
3. **Apply the core writing rules.** Use the `Edit` tool for targeted fixes, or `Write` if rewriting the whole file is genuinely simpler. Make each `old_string` precise enough to be unique. Apply every rule in one pass per file.
4. **Verify.** Re-read each modified file (or the changed ranges) to confirm only the intended changes landed and no code or URL was disturbed.
5. **Run link-polisher.** Invoke the `link-polisher` skill on the same file(s) to format raw URLs as Markdown links with human-readable labels. Pass the same file scope. Let that skill do its own resolution and reporting.
6. **Report.** Output a short combined summary: which files you touched, a count of fixes per rule, anything you left untouched and why, and a pointer to the link-polisher results.


## Edge cases

* **Possessive versus contraction.** `the user's account` is possessive - keep it. `the user's logged in` is a contraction of `user is` - expand it. Read for sense.
* **Curly quotes inside code.** Leave them. Only straighten quotes in prose.
* **Headings that are proper nouns or product names.** Sentence case capitalizes the first word and proper nouns only - do not lowercase a product name that sits mid-heading.
* **Dashes used as bullet markers or front matter.** A leading `-` list marker or a YAML separator is not an en-dash or em-dash - leave list markers and structural syntax alone. Only replace dash characters used as punctuation within prose.
* **Tables.** Re-wrapping for the sentence-per-line rule does not apply inside table cells. Apply the other rules to cell text and preserve pipes and alignment.
* **Ambiguous idiom or wording.** If a simpler phrasing risks changing the meaning, leave the original and flag it in the summary for a human to decide.


## Style rules for your own summary

The summary you write must itself follow the core writing rules above: straight quotes, no contractions, the Oxford comma, plain hyphens, and simple wording.


## What success looks like

* The target file(s) follow every core writing rule.
* Code blocks, inline code, URLs, and identifiers are untouched.
* No sentence meaning changed.
* `link-polisher` ran on the same files and formatted any raw URLs.
* The summary is short and lists exactly what changed and what (if anything) was skipped and why.

From ahandsel/tokyo-geek, MIT.

More from ahandsel/tokyo-geek