Skip to main content
skill CX Codex

suggest-improvements — Claude Code skill: what it does, how to install

suggest-improvements is a Claude Code skill that audits converted websites across eight technical areas. Runs before opening a pull request and never modifies site code directly.

MIT ★ 137 updated 2026-10-31

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add ethanplusai/astro-conversion-kit
/plugin install astro-conversion@astro-conversion-kit
Open on GitHub

What suggest-improvements does

The skill runs scripts/suggest.mjs to evaluate captured site artifacts across SEO, content, links, accessibility, performance, security, analytics, and design. Each finding includes the target route, capture evidence, effort rating (S, M, L), risk level, and a flag indicating whether the fix can be automated. It reads exclusively from local capture/, baseline/, and review/ folders without issuing requests to the live server.

A strict golden rule governs the workflow: nothing applies directly to the default build. Every item becomes a proposal entry in proposals.json, shipping strictly under PROPOSALS=on or applied via convert-site --apply <id> on its own commit to protect visual parity. If review/ is missing from disk, design checks cannot execute and fall into the Not covered list verbatim.

Execution requires Node.js along with pre-existing capture, baseline, and review directories. The output produces a human-readable Markdown file at docs/suggestions.md and machine-readable data in suggestions.json.

What it helps with

  • audit converted sites for regressions without altering source code
  • inspect captures for missing h1 tags, broken links, and SEO gaps
  • calculate effort and risk ratings for identified site defects
  • prepare a structured improvements document for pull request reviews

Example prompts for the agent

  • Run suggest-improvements against our review artifacts
  • Generate docs/suggestions.md using suggest-improvements
  • List all high-risk items found by suggest-improvements

How to install suggest-improvements

1Plugin marketplace

/plugin marketplace add ethanplusai/astro-conversion-kit
/plugin install astro-conversion@astro-conversion-kit

This installs the whole astro-conversion plugin with all its skills

2Skills CLI (Vercel)

npx skills add ethanplusai/astro-conversion-kit --skill suggest-improvements -a claude-code

3Manually: put the files in place

~/.claude/skills/suggest-improvements/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/suggest-improvements/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about suggest-improvements

How to install suggest-improvements in Claude Code?

Register the marketplace using /plugin marketplace add ethanplusai/astro-conversion-kit and run /plugin install astro-conversion@astro-conversion-kit.

What does suggest-improvements do?

It analyzes local conversion snapshots to output a categorized defect report covering SEO, performance, and accessibility without editing project files.

What is required to run suggest-improvements?

It needs Node.js to execute node scripts/suggest.mjs alongside pre-generated capture/, baseline/, and review/ folders.

Source text

SKILL.md · MIT
---
name: suggest-improvements
description: List what is worth fixing on a site the conversion reproduced as-is — SEO, content, links, accessibility, performance, security, analytics and design — each item with its path, evidence, effort, risk and whether it can be applied mechanically, plus the agent's own design and content observations. Use after the parity gates and the visual review are green and before the pull request, or when someone asks what could be better on the converted site. It changes nothing.
---

# suggest-improvements

The converted site reproduces the live site on purpose, flaws included. This skill writes down
the flaws, with evidence, so the site owner can decide which to fix. It never fixes them.

## The golden rule

**Nothing from here is applied directly.** An improvement becomes a proposal: an entry in
`proposals.json` that ships only in a `PROPOSALS=on` build until a person approves it, or a later
`convert-site --apply <id>` run that does the same on its own commit. Editing the default build
because this report said so breaks parity, and the gates will say so.

## When to run

After every parity gate passes and the visual review is green for every page, with `review/`
still on disk (it feeds the design checks), and before the pull request is opened. The report
goes in the PR.

## The command

From the site root:

    node <skill-dir>/scripts/suggest.mjs --capture capture --baseline baseline --review review --out docs/suggestions.md --json suggestions.json

Add `--gates gates.json` when the gate runner wrote that file (the header then summarises the
gates), and `--lighthouse capture/lighthouse-live` when that folder exists (it is also the
default). Run `node <skill-dir>/scripts/suggest.mjs --help` for every option.

Exit 0 means the report was written, whatever it found; 2 is a usage error or a missing input.
It reads `capture/`, `baseline/` and `review/` only and never requests the live site.

## Reading the report

`docs/suggestions.md` opens with the site, the counts and the gates line, then the
**Not covered** list, then one section per category: SEO, Content, Links, Accessibility,
Performance, Security, Analytics, Design. Inside each, one heading per check with its reason,
then one line per item:

    - `/about/` `h1` (`missing-h1`, effort S, risk low)
      - Evidence: no <h1> on the page

- **Path** is the page (for a site-wide problem, the first page it appears on).
- **Effort** is S, M or L; **risk** is none, low, medium or high; **applyable** means
  `convert-site --apply <id>` can make the change mechanically.
- **Evidence** is what the check saw in the capture: a value, a count, the pages.
- **Grouped items.** One problem repeated across the site (a script in the header, an image, a
  link, a title) is one item, not one per page. The evidence names the page count and the first
  three pages; `pages` in `suggestions.json` lists every page it applies to. Use the JSON when
  you need the full list.
- The report ends with **How to apply**, listing the checks that can be applied mechanically.

**Not covered is never a pass.** A check with no input (no `--review`, no Lighthouse reports, no
`media.json`) is listed there, and so is part of one. A check that threw is listed as
`check failed: <message>`; a check whose coverage note threw keeps its items and is listed as
`(partly): coverage note failed: <message>`. The other checks still ran. Quote the whole Not covered list verbatim in the PR, unedited. If
`--review` was missing because `review/` was deleted, rerun the visual review's shoot and styles
steps and run this again rather than shipping the gap.

## What you add by hand

The scripts cannot see everything. At the end of `docs/suggestions.md`, add a section:

    ## From the review

    - `/services/` hero: the heading overlaps the image at 390 px on live and new alike
      - Evidence: review/index.html, pair /services/ at 390, top of page

What goes there:

1. **Design observations from the contact sheet**: anything that looks wrong on live and was
   reproduced faithfully (cramped spacing, an image cropped badly on mobile, low contrast, a
   misaligned grid). Name the route and width.
2. **Content issues noticed while building**: typos, outdated copy, dead offers, a phone number
   that differs between pages, a page that duplicates another. Quote the text and name the
   captured file it came from.

Each line carries the same discipline as the script's items: a path, evidence a person can check
(a route and width on the contact sheet, a file under `capture/`, a quoted snippet), and nothing
you did not see. No guesses, no "probably". If the list is empty, write "Nothing further noticed."
so the reader knows you looked.

Do not rerun the script after adding the section: it rewrites `docs/suggestions.md`. Rerun it
first if the inputs changed, then add the section again.

## Acting on an item

Never in this run. When the person picks an item:

- **Applyable checks**: `convert-site --apply <id>` records the proposal in `proposals.json`,
  makes the change on its own commit, reruns the gates and the contact sheet, and ships it only
  with `PROPOSALS=on`.
- **Everything else** (alt text, copy, which duplicate page to keep, a design fix): a person
  decides or writes it, and it goes in as a proposal the same way, never into the default build.

## The checks

`references/catalogue.md` lists every check: its id, category, what it looks for, the evidence it
cites, its default effort and risk, whether it is applyable, which checks group across pages, and
which inputs each check needs. Read it when an item's reason is unclear or a check is missing
from the report.

## Present the result

1. **The counts per category**, then the items with risk medium or high and the applyable ones.
2. **From the review**, every line.
3. **Not covered, verbatim**: every line of the report's list, unedited. None of it was checked.
4. **What happens next**: nothing is applied until the person picks items; each becomes a
   proposal or a `--apply` run.

## References

| File | Covers |
|---|---|
| `references/catalogue.md` | Every check, its evidence, effort, risk, applyability and inputs |

© ethanplusai · MIT · ethanplusai/astro-conversion-kit

Similar skills

All skills for Code review and refactoring →

From the same set9

astro-conversion astro-conversion is a Claude Code plugin that moves WordPress or another HTTP-accessible site to static Astro. It captures the site and checks routes, SEO data, and visual similarity. ★ 137repo stars launch-audit launch-audit is a Claude Code skill that checks a website before or after launch. It also runs for site QA and domain moves. CX Codex +1 ★ 137repo stars post-launch post-launch is a Claude Code skill that checks a site the moment DNS moves and once a day for thirty days after. It answers the question of whether a launch actually worked. CX Codex +1 ★ 137repo stars pre-launch pre-launch is a Claude Code skill that checks a website before launch and blocks release when a check fails. Run it before a launch, DNS change, or site replacement. CX Codex +1 ★ 137repo stars visual-review visual-review is a Claude Code skill that checks whether an Astro rebuild matches the live site: full-page screenshots of both sides, a pixel diff, a computed-style comparison. CX Codex +1 ★ 137repo stars convert-site convert-site is a Claude Code skill that rebuilds a live site as a static Astro project. It starts when asked to convert, migrate, rebuild, or clone a site. CX Codex +1 ★ 137repo stars parity-gates The parity-gates skill for Claude Code freezes a site capture into baseline/ and proves an Astro build matches it. It runs when verifying redirects or checking a staging deployment. CX Codex +1 ★ 137repo stars capture-site capture-site is a Claude Code skill that records a live site in capture/ for rebuild checks. Run it before a site conversion or when asked to crawl, snapshot, inventory, or resume a blocked capture. CX Codex +1 ★ 137repo stars

Project sponsors

Companies that keep this analytics open