# Article Review > Publish-readiness review for blog posts — content, structure, flow, typos, demos, code, SEO, facts, and STYLEGUIDE compliance. Use when the user asks to review, proofread, or audit an article or draft before publishing. Use when this capability is needed. - Skill: `tomevault-io/article-review` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/article-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/article-review/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/article-review --- # Article Review Goal: determine whether a post is **ready to go live**. Read [STYLEGUIDE.md](../../../STYLEGUIDE.md) for editorial and formatting rules; apply them without restating them in the report. This skill adds publish-readiness checks beyond the styleguide. ## Workflow 1. **Identify the target** — `posts/YYYY-MM-DD-slug.md`, editor draft, or pasted content. 2. **Read STYLEGUIDE.md** — Especially [Editorial checklist](STYLEGUIDE.md#editorial-checklist) and [Things to avoid](STYLEGUIDE.md#things-to-avoid). 3. **Read the full article** — Front matter, body, Liquid shortcodes, footnote assigns, embedded demos, code blocks. 4. **Follow references** — Open linked posts, demo files under `includes/demos/`, cited source URLs, and GitHub permalinks when claims or code depend on them. 5. **Verify what you can** — Asset paths exist; demo partials resolve; internal URLs use `/YYYY/MM/DD/slug/` form. Run `npm start` or `npm run build` when interactively verifying demos, anchors, or rendered output is needed. 6. **Report** — Use the output format below. Quote short excerpts; propose concrete fixes. ## Review dimensions ### Content and accuracy - Does the post deliver what the title and description promise? - Are technical claims accurate? Trace APIs, flags, versions, and behavior against docs or the linked repo when possible. - Flag unsupported claims, outdated information, internal contradictions, and logical gaps (missing steps, non sequiturs, causation without evidence). - Distinguish opinion from fact; opinions should be reasoned, not presented as universal truth. - Credit sources; ensure attributions match [Links](STYLEGUIDE.md#links) conventions. ### Structure and reading flow - Opening hooks without restating the title ([Document structure](STYLEGUIDE.md#document-structure)). - Section order makes sense; each `##` earns its place; no orphaned or redundant sections. - Heading hierarchy is logical (`##` → `###`, no skipped levels). - Paragraph length and pacing: no walls of text; dense stretches broken up appropriately. - Closing reflection (Wrapping up / Lessons learned / etc.) — not a bullet recap of the whole post. - Transitions between sections; reader always knows *why* the next section exists. ### Editorial style and formatting Work through STYLEGUIDE sections; cite the section name when flagging (e.g. “Footnotes”, “Things to avoid”). Run the [Editorial checklist](STYLEGUIDE.md#editorial-checklist) and report only failures. Includes: voice, locale, typography, links, figures, callouts vs blockquotes, footnotes, code block conventions, lists. ### Typos and copy-editing - Spelling (American English per styleguide). - Grammar, punctuation, curly quotes, en/em dashes used appropriately. - Consistent terminology within the post (product names, acronyms after first ``). - Front matter `title` in APA title case; `description` is one clean sentence. ### Code snippets - Snippets match what the prose describes; no stale or misleading examples. - Language tags present; indentation uses tabs ([Code blocks](STYLEGUIDE.md#code-blocks)). - Liquid in fences is escaped (`{% raw %}` or zero-width spaces). - Focused blocks with `// …` where appropriate; teaching comments explain intent, not mechanics. - When the post references production code, spot-check the linked file or path if available. - Flag security-sensitive patterns only when clearly wrong for the context (hardcoded secrets, dangerous copy-paste). ### Demos Posts embed demos via `{% render "demos/…" %}`. For each embed: - Confirm the partial exists under `includes/demos/`. - Read associated `script.js`, `styles.css`, `data.js` when the article discusses their behavior. - Prose around the demo should explain what to try and what to notice (context before; interpretation after if needed). - Flag broken paths, missing `noscript` warnings where JS is required, or demos that contradict the article. - If the article teaches something interactive but has no demo (and similar posts in the archive use one), note it as a **Consider** — not a blocker unless the post explicitly promises interactivity. Do not build new demos during review unless the user asks; only assess existing ones. ### SEO and discoverability Front matter drives meta tags and OG cards (see `tests/head.test.ts`). - `title` — clear, accurate, APA title case, no trailing period. - `description` — single sentence; works as OG/RSS summary; not a keyword dump. - `tags` — Title Case; reuse existing tags where sensible. - `image` — path set and file exists under `assets/images//`. **Flag if missing**; do not generate (use the `article-image` skill when asked). - Filename `YYYY-MM-DD-kebab-case-slug.md` matches intended publish date and URL. - `draft: true` should be removed before publish. - First paragraph and headings give enough context for search and social previews. ### Assets and build - Figure paths under `/assets/images//`; meaningful `alt` distinct from caption. - No bare Markdown images; CodePen embeds use `codepen.liquid` when present. - Note if a local preview build is recommended to confirm anchors, demos, or footnote rendering. ## Severity - **Must fix** — Blocks publish: factual errors, broken links/paths, missing required front matter, styleguide violations with wrong semantics (blockquote vs callout, bare images, spaces in code blocks), misleading code, broken or missing demo files referenced in the post, `draft: true` left on, missing `alt`. - **Should fix** — Weakens the post materially: poor flow, vague claims without support, SEO description weak or wrong length, voice drift, checklist gaps, code that doesn’t match prose, demo lacks context. - **Consider** — Polish: tighter prose, optional demo, friendlier closing, fewer em dashes, optional OG image format upgrade (AVIF/WebP per styleguide). ## Output format ```markdown # Review: [Post title] **File:** `posts/…` **Verdict:** Ready to publish | Needs revision | Major rework ## Summary [2–4 sentences: readiness, main blockers, overall quality.] ## Must fix - **[Category]** — `excerpt…` → fix. ## Should fix - … ## Consider - … ## Publish checklist - [ ] Editorial checklist (STYLEGUIDE) — pass / N items failing - [ ] Content accurate and complete - [ ] Code and demos verified - [ ] SEO front matter (`title`, `description`, `tags`, `image`) - [ ] `draft` removed, filename/date correct - [ ] Local preview (`npm start`) if demos or anchors need human check ## Strengths [1–3 specific positives.] ``` Keep findings actionable. Do not dump STYLEGUIDE content into the report. ## When asked to fix Apply minimal diffs for agreed findings. Re-read changed sections. For factual or technical corrections, confirm with the author when uncertain rather than inventing details. ## Out of scope - **Generating** OG/cover images — flag absence only; use `article-image` when the user wants one created. - **Rewriting for a different angle** unless asked — review improves readiness, not the thesis. - **Deploying or committing** — unless explicitly requested. --- > Source: [KittyGiraudel/site](https://github.com/KittyGiraudel/site) — distributed by [TomeVault](https://tomevault.io).