Cmsify

CMSify

Convert a website whose content lives hardcoded in components into a site a non-technical client can edit from a browser panel — without changing how the site looks or behaves.

Core principle: conversion is partial by design. Everything you can convert with confidence becomes editable content; everything else stays untouched and gets documented. The build must be green at the end of every phase. When in doubt, don't convert.

When to use

• A finished site (often AI-generated with Lovable, v0, Bolt, Cursor, or Claude Code) needs to be handed off to a client who will edit copy, images, or blog posts.
• An existing static/marketing site needs a CMS or a blog without a rebuild.
• Content is scattered across JSX/Astro/TSX components and needs to move to structured files (content/*.mdx, *.json).

Do NOT use for: sites already wired to a CMS (headless or git-based), web apps whose "content" is application data (dashboards, e-commerce catalogs, user-generated content), or design/styling changes.

Non-negotiable rules

1. New branch, never main. All work happens on a branch like cmsify/convert. Never commit to the default branch. Never merge — the developer reviews and merges.
2. Privacy: never read, quote, or send as context .env* files, credentials, API keys, or anything matched by .gitignore. If a hardcoded secret is found in source, stop and report it; do not copy it anywhere.
3. Plan approval gate: no file is modified before the user approves the conversion plan produced in Phase 2.
4. Verify after every phase, not just at the end. Run the project's build (and type check if configured). A file that can't be repaired after 3 attempts is reverted to its original state and logged in the conversion report.
5. Zero visual/behavioral change. Styles, layout, interactivity, and framework config stay as they are. The converted site must render identically to the original.
6. When in doubt whether something is safely convertible, it isn't. Leave it hardcoded and list it in the report with the reason.

Workflow

Copy this checklist and track progress:

Conversion progress:
- [ ] Phase 1: Detect (framework, structure, panel choice)
- [ ] Phase 2: Scan & plan — STOP for user approval
- [ ] Phase 3: Extract (content out of components)
- [ ] Phase 4: Wire (install panel, config, admin route)
- [ ] Phase 5: Verify & deliver (build green, reports written)

Phase 1: Detect

Read package.json, framework config, and the routing/pages structure. Determine:

• Framework and version (Astro, Next.js, React+Vite, other).
• Existing content infrastructure (content collections, MDX setup, none).
• Package manager, build command, type checking.
• Panel choice: Keystatic by default. Consider Sveltia CMS instead when i18n is a hard requirement or the stack can't host Keystatic's routes (e.g. pure React+Vite SPA) — see references/keystatic-next.md.

Run the build once before touching anything. If the build is already broken, stop and report — never convert on top of a red build.

Phase 2: Scan & plan (approval gate)

Walk pages and components. Identify candidate content per the Conversion scope below. Use references/content-modeling.md to shape the model.

Present a plan to the user containing:

• The proposed content model: collections, singletons, and their fields.
• Which files will be modified, created, and (if a blog is added) which pages will be generated.
• What will NOT be converted and why.
• The panel choice and where the admin will live.
• Whether to add a blog if the site has none (ask — don't assume).

STOP. Do not proceed until the user approves the plan. Adjust and re-present if they push back.

Phase 3: Extract

On the new branch, move content into structured files and refactor components to read from them:

• Prose and page copy → MDX/Markdown in content/ (or the framework's conventional location).
• Structured data (nav items, feature lists, testimonials, settings) → JSON/YAML.
• Repeated card/list markup → one collection + a loop over its entries.
• Keep component markup and classes identical; only the source of the text/images changes.

Work in small units (one page or one collection at a time) and build after each unit. Revert any file you can't repair after 3 attempts.

Phase 4: Wire

Install and configure the panel. Framework guides:

• Astro + Keystatic (best-supported path): references/keystatic-astro.md
• Next.js + Keystatic, and React/Vite SPAs (experimental, Sveltia fallback): references/keystatic-next.md

The panel config must be generated from the approved content model — every collection and singleton in the plan appears in the panel, with an image/media setup that writes to the project's public assets directory.

Phase 5: Verify & deliver

1. Full build + type check green.
2. Smoke-test the admin: start the dev server, confirm the admin route loads and lists the collections. If a browser tool is available, edit one field and confirm the change lands in the content file and renders on the site.
3. Write the two reports using the templates in references/deliverables.md:
   • CONVERSION.md — what's editable, what isn't and why, files touched, how to review.
   • EDITING.md — non-technical instructions for the client.
4. Commit everything to the branch with clear messages. Tell the developer how to review (git diff main...cmsify/convert) and remind them the merge is theirs.

Conversion scope

Convert	Never convert (list in CONVERSION.md instead)
Static text in pages/components (headings, paragraphs, CTAs, footer copy)	Forms and their submission logic
Local images and their alt/captions	Interactive components and state logic
SEO metadata (title, description, Open Graph)	Remote data (fetch/API), auth, e-commerce
Repeated lists/cards that suggest a collection (features, testimonials, team, FAQ, static pricing)	Styles, layout, framework configuration
Blog: create a posts collection and its pages if the site has none and the user wants one	Anything you're not confident about

Deliverables — every conversion, no exceptions

1. A reviewable git branch (the developer merges, the skill never does).
2. CONVERSION.md at the repo root: what is editable, what is not, and why.
3. EDITING.md at the repo root: how the client opens the admin panel and edits content.

Reference files

• references/content-modeling.md — deciding collections vs singletons, field types, MDX vs JSON, blog schema.
• references/keystatic-astro.md — wiring Keystatic into Astro, known traps.
• references/keystatic-next.md — wiring Keystatic into Next.js; React/Vite SPAs and the Sveltia fallback.
• references/deliverables.md — templates for CONVERSION.md and EDITING.md.