content-management-systems

# Content Management Systems

Use this skill when the user is working on a content management system or on software that behaves like one.

This skill focuses on the seams that matter in CMS work:

- themes and templates
- plugins, apps, modules, and extensions
- admin and editor interfaces
- media and upload handling
- content models, taxonomy, and metadata
- render pipelines and static export flows

## When to Use This Skill

- The user mentions a CMS platform such as WordPress, Shopify, Drupal, Joomla, Webflow, Squarespace, Wix, WooCommerce, HubSpot CMS Hub, or Adobe Experience Manager.
- The task is about theme development, template changes, or design system work inside a CMS.
- The task is about plugins, modules, apps, or extension points.
- The task touches editor UX, previews, taxonomy, slugs, SEO fields, or publishing behavior.
- The task involves uploads, media libraries, authored assets, markdown rendering, or static export.

## First Pass

1. Identify the platform category: self-hosted CMS, SaaS site builder, commerce platform, or hybrid/headless system.
2. Find the owning implementation seam before editing:
   - theme or template layer
   - plugin, app, module, or extension layer
   - admin or editor surface
   - content model or storage layer
   - media pipeline
   - export, deploy, or rendering pipeline
3. Check platform constraints before choosing an approach:
   - what is editable locally
   - what is authored content versus code
   - where media belongs
   - whether the final site is server-rendered, static-exported, or hosted remotely

## CMS Rules

- Follow the platform's naming and folder conventions for themes, modules, template parts, or sections.
- Keep theme assets separate from user-uploaded media unless the platform explicitly combines them.
- Prefer structured content fields over storing important metadata inside presentation markup.
- Treat previews, slugs, taxonomy, excerpts, meta fields, and publish states as first-class CMS concerns.
- Prefer safe defaults and graceful fallback behavior when config, theme selection, or content input is invalid.
- When changing editor or admin behavior, trace the stored field, validation rules, preview path, and final render path together.

## Common Workflows

### Themes and Templates

- Start at the template loader or theme runtime, not at a downstream include.
- Preserve the platform's template hierarchy and partial naming conventions.
- Keep presentation changes close to templates and shared theme helpers.

### Plugins, Apps, and Modules

- Add behavior at the platform's extension seam instead of scattering logic into templates.
- Keep migrations, seed data, and configuration updates explicit and versioned.
- Document the extension's setup assumptions when the platform requires activation or registration.

### Admin and Editor UX

- Keep forms aligned with the stored content model.
- Prefer author-facing previews when content transformations are non-trivial.
- Keep validation, CSRF or equivalent safeguards, and permissions consistent with the surrounding admin code.

### Media and Uploads

- Use a dedicated upload path for authored media.
- Keep decorative or theme-owned imagery in the active theme folder.
- Default to conventional locations like `uploads/` for authored media and `img/` for theme assets unless the platform dictates a stronger convention.
- When a CMS supports configurable media directories, expose the setting with a safe fallback.

### Content Models and Migrations

- Distinguish content entities clearly: pages, posts, products, entries, collections, taxonomies, and settings.
- Prefer migration files or exportable schema definitions over ad hoc runtime mutations.
- Keep slugs, publish dates, excerpts, canonical metadata, and taxonomy relations structured.

### Markdown, HTML, and Static Export

- Decide whether markdown is authored input, intermediate content, or build output before changing the renderer.
- Pair renderer changes with preview or validation when feasible.
- For static-exported CMS systems, validate rewritten permalinks and asset paths after build changes.

## Identifying the Owning Seam

Regardless of platform, locate the owning seam before editing by mapping the codebase to these CMS roles:

- Runtime bootstrap and request routing
- Admin or editor controllers and their view templates
- Theme loading, template hierarchy, and shared template helpers
- Repositories, models, or schema/migration files for content, taxonomy, and settings
- Markdown or content transformation utilities
- Static export, deploy, or render pipeline entry points

Step to the owning seam first, then make the smallest change that preserves the CMS structure.

## Platform Notes

See `references/cms-platform-workflows.md` for a compact mapping of common CMS platforms, extension surfaces, and media conventions.