client-cms

Files (2)

• SKILL.md
• inline-editing.md · references/

SKILL.md (first lines)

# Client CMS — a safe content layer for client-managed websites

Core conceptual model, always:

**Authorized admin edits approved content → content is stored in an appropriate
persistence/content layer → the live public website consumes and displays it.**

A Postgres-backed admin dashboard is ONE valid instance of this pattern — never a
mandate. **The architecture follows the project, not the other way around.** This
skill states the capability, constraints, and outcome; you (the executing model) are
the architect and decide the best technical implementation for THIS website. Treat it
as an end-to-end engineering task — public site, admin UI, persistence, auth, and
content flow must actually work together — not "generate an admin page".

## Phase 0 — Inspect before deciding (mandatory, no shortcuts)

Understand the project before proposing anything. Do not decide from filenames or a
glance at the tree. Establish at minimum:

- Framework/language, rendering model (static, SSR/SSG, SPA, hybrid), frontend
  architecture, backend (if any), database (if any).
- Authentication system (if any), hosting/deployment target, existing APIs.
- **Existing CMS or content system** — if one exists (headless CMS, content
  collections, markdown/frontmatter content, admin routes), extending it is the
  default; adding a second content system needs strong justification.
- Project structure and conventions, design system/components, how content is
  currently stored and rendered, any existing admin capabilities.
- Security/infrastructure constraints that shape the design.

If the stack, platform, or deployment system has current best practices you are not
certain of, research them (web search/docs) before committing to an architecture.

Two edge cases, handled here and not later: if the project is **not a public-facing
website at all** (CLI tool, pipeline, library), stop and confirm with the user before
proceeding — never force a content layer onto a non-web project. If a **partial or
broken admin/CMS already exists** (half-built earlier, abandoned mid-way), assess its
state and decide extend / repair / replace with stated justification — never assume
greenfield.

## Phase 1 — Content inventory (judgment, not a mechanical sweep)

Identify what a nontechnical business owner would reasonably manage: headings, hero
copy, paragraphs, images/media, FAQs, testimonials, announcements, business/contact
info, hours, social links, pricing, services, team members, news/blog, promotions,
CTAs, repeated homepage sections — *examples, not a checklist*.

- **Client-editable:** business-managed copy, media, and repeatable content items.
- **Developer-controlled (never exposed):** layout system, routes, application
  logic, styling/design tokens, infrastructure, source code, anything whose edit
  could break the site.

Do NOT turn every value into editable content. Produce a short grouped inventory and
scale scope to the site: a small marketing site gets a lightweight editor; a
content-heavy site gets a more structured system.

**Checkpoint — confirm before building.** Present the inventory and the proposed
architecture (Phase 2) to the user and get scope confirmed before implementing. This
operation adds auth and rewires a live website's read paths — it is not built
autonomously off a silent plan.

## Phase 2 — Architecture (let the site pick the stack)

Choose storage and delivery from what exists and where it deploys. The option space
spans (non-exhaustive): JSON/markdown flat files committed or written at runtime,
SQLite, the project's existing database, a hosted backend (e.g. Supabase/Firebase),
server actions/API routes, a traditional framework's own admin scaffolding
(WordPress/Rails/Django-style), or an existing headless CMS. Decision drivers:

- **Reuse first.** Existing DB/auth/API/CMS beats new infrastructure. Introduce new
  infrastructure only when nothing suitable exists, and pick the lightest thing the
  hosting environment supports (a static host with no runtime may need a build-time
  or hosted content source; an SSR app can read at request time).
- **One content module.** All reads AND writes go through a single content
  layer/module with defined shapes — not scattered fetches. This is also what keeps
  the door open for future automations/AI agents updating approved content through a
  safe API instead of source edits. Don't build that API speculatively; just don't
  architect it away.
- **Fallbacks.** Public pages must render sensibly if the content layer is empty or
  unreachable (seed data / build-time defaults), and rendering must remain
  visually identical to today.
- **Static/client-only targets.** Writes still go through a server/serverless
  function or a backend with server-enforced policies — the shipped client bundle is
  NEVER the authorization boundary, and admin/service-role keys never ship in it.

## Phase 3 — Auth, authorization, and security

Run the `security-pass` skill for this phase when available; its checklist applies in
full (secrets, keys, RLS/policies, live-backend advisors, re-run after fixes).

- Admin surface reachable only by authenticated, authorized users. Reuse the
  project's existing auth if present; otherwise add the simplest robust mechanism
  appropriate to the platform. Never invent home-rolled crypto/session schemes when
  the platform provides one.
- **Every write is authorized server-side** — including that the record being edited
  belongs to this admin's scope (never trust an ID from the client). Client-side
  route hiding is not security. Validate and bound all input (types, lengths,
  allowed fields).
- **CSRF:** with cookie-based sessions, a valid session cookie is not sufficient
  authorization for a write — use the framework's CSRF tokens, or SameSite cookies
  plus origin checks, on every state-changing admin request.
- **Output-context encoding:** escape every content value for its actual sink —
  HTML, attribute, URL, JS, JSON-LD — not just the rich-text field (which gets XSS
  sanitization). Validate URL-type fields to http/https/mailto so a "link" field
  can't carry `javascript:`/`data:`.
- **Media uploads:** validate by content signature, not extension; bound size;
  disallow or sanitize/rasterize SVG and HTML (they execute script when served from
  the app origin); store outside the source tree or in platform storage; never trust
  filenames; serve user media with non-executable content types. If media can be
  added by URL and the server fetches it, that is SSRF-sensitive — restrict schemes
  and block private/link-local ranges.
- Secrets in env/config, never committed; rate-limit or otherwise protect the login
  surface. Do not weaken any existing security posture to make content editable.

## Phase 4 — Admin experience

Simple enough for a nontechnical employee: plain text fields by default, rich text
only where the content needs it, image/media pickers, repeatable items with
add/remove/reorder, appropriate validation, clear save/publish affordance, preview
where feasible (behind the same authorization as the editor — draft content must not

From mhshaon98/agent-skills, MIT.

More from mhshaon98/agent-skills