/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.