SEO Rewriter

What this skill does

Rewrites an existing blog post to incorporate target keywords without overstuffing or distorting the author's voice. Reports keyword density, heading structure, and Flesch-Kincaid readability before and after.

Inputs

• post_path: markdown file of the original post.
• target_keywords: array of phrases (1-5 words each).
• Optional target_density: percentage per primary keyword (default 1-2%).
• Optional voice_examples: paths to 2-3 of the author's other posts to anchor tone.

Steps

1. Compute baseline metrics: word count, sentence count, average sentence length, Flesch-Kincaid grade.
2. For each target_keywords entry, count occurrences and compute density.
3. Audit headings: H1 must contain the primary keyword once (only); H2/H3 should mention secondary keywords where natural.
4. Identify rewrite candidates by sentence: short sentences with vague verbs (is, are, does) where a keyword could fit naturally. Avoid sentences quoting other sources.
5. Rewrite candidates: substitute generic nouns for the target keyword; preserve sentence structure and punctuation. Never insert a keyword where it makes the sentence ungrammatical.
6. Add or strengthen the meta description (first 155 chars of the lede) to include the primary keyword.
7. Recompute density. If a keyword exceeds target_density * 1.5, remove the latest insertion.
8. Recompute Flesch-Kincaid; if it drops by more than 1 grade level, revert problematic rewrites — voice integrity matters more than marginal SEO.
9. Diff the original vs rewritten with diff -u. Save the rewritten post as <post>-seo.md and a report <post>-seo-report.md.

Output

The rewritten post, plus a report containing the before/after density table, heading audit, FK grades, and a diff. Stdout summarizes density changes and any reverts.

Verification

Render the rewritten post in a markdown viewer and read it aloud — it must still sound like the original. Run a plagiarism diff (diff plus a structural similarity check) ensuring more than 90% of original sentences are preserved verbatim. Submit the meta description to a SERP previewer and confirm it doesn't truncate at the wrong word. If FK grade rose by 2+, the rewrite over-corrected toward "writing for keywords" — revert and limit insertions.

Edge cases

• Posts under 400 words: skip; keyword density math is meaningless on short content.
• Posts with code blocks dominating the body: do not insert keywords inside fenced blocks; only prose is editable.
• Highly technical posts where the keyword is awkward outside a specific section: confine insertions to introduction and conclusion.
• Posts where the target keyword conflicts with the author's terminology (e.g., target "AI agent" but author always says "autonomous worker"): surface the conflict and ask before rewriting wholesale.