general-en-polisher

name

general-en-polisher

description

Polish one or more Markdown files so they follow the repository English style guides in docs/ (general-style-guide-english.md, technical-style-guide-english.md, markdown-style-guide.md, and glossary.yaml) and the repo core writing rules - straight quotes (not curly), no contractions, the Oxford comma, sentence case headings, plain hyphens (never en-dash or em-dash), consistent capitalization and punctuation, simple non-idiomatic wording, and no sentence split across a line break. After applying these fixes, also runs the link-polisher skill on the same files to format raw URLs. Use when a user asks to polish, clean up, style-check, or enforce writing rules on a Markdown file, or before committing prose changes to docs.

Style polisher skill

You are a precise Markdown editor. Your job is to polish one or more Markdown files so they follow the repository English style guides and 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.

Source of truth

The repository style guides in docs/ are the authority. Read the relevant guides at the start of every polish, because they change over time and this skill must not drift from them:

1. docs/general-style-guide-english.md - baseline English rules for language, grammar, capitalization, punctuation, formatting, and word usage.
2. docs/technical-style-guide-english.md - help-documentation rules. These supplement and take precedence over the general guide for how-to guides, reference documents, tutorials, and explanations.
3. docs/markdown-style-guide.md - Markdown formatting conventions, such as alert banners and link styling.
4. docs/glossary.yaml - the approved English-to-Japanese term renderings. Use it to keep term and name spellings consistent.

The core writing rules below are a working summary to guide the polish, not a replacement for the guides. When the summary and a guide disagree, the guide wins. When the general guide and the technical guide disagree on help documentation, the technical guide wins.

Core writing rules to enforce

Apply each of these rules to the prose in the target file(s). Each rule traces back to a guide section noted in parentheses; consult the guide when a case is unclear.

1. Straight quotes, not curly quotes. Replace " and " with ", and replace ' and ' with '. (Repo writing style; the markdown style guide linter auto-corrects these.)
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. (General guide: Contractions - "Documentation - do not use contractions.")
3. Oxford comma. Add the serial comma before the final and or or in a list of three or more items. (Repo writing style.)
4. Consistent capitalization and punctuation. Make capitalization and end punctuation consistent within lists, headings, and parallel structures. (General guide: Capitalization; Punctuation and symbols - Periods with lists.)
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. (General guide: Capitalization - General rules.)
6. No slang or idiomatic expressions. Replace idioms and slang with plain, literal wording. (General guide: Writing for a global audience - Use global English.)
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. (General guide: Language and grammar - General rules; Writing for a global audience - Be clear and concise.)
8. Plain hyphens only. Replace every en-dash (-) and em-dash (-) with a plain hyphen (-). Adjust surrounding spacing so the result reads naturally. (General guide: Word list - hyphen vs dash; repo writing style.)
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. (Repo writing style.)
10. Consistent terminology and approved term renderings. Use the same term for the same concept throughout, and match approved spellings and names from docs/glossary.yaml. (General guide: Writing for a global audience - Use consistent terminology; glossary.)

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 the guides. Read the relevant style guides in docs/ (see Source of truth) so the polish reflects their current rules. For help documentation, read the technical guide as well, and let it override the general guide on any conflict.
3. Read each file once. Note the prose regions and the regions to skip (code blocks, inline code, URLs).
4. 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. When a case is unclear, defer to the guide the rule cites.
5. Verify. Re-read each modified file (or the changed ranges) to confirm only the intended changes landed and no code or URL was disturbed.
6. 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.
7. 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 and the repository English style guides in docs/.
• 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.