tibi-svelte-starter/.agents/skills/media-seo-publishing/SKILL.md

name, description

name	description
media-seo-publishing	Model media, SEO, and publishing workflows for website projects on this starter. Covers file fields, image validation/filtering, alt texts, social metadata, publication windows, and SSR/cache implications.

media-seo-publishing

When to use this skill

Use this skill when:

• Designing media-heavy website content models
• Adding image/file fields and image filters
• Modeling SEO fields for pages or reusable content
• Defining publication windows and how they interact with runtime and SSR
• Building authoring workflows around images, metadata, and release control

Goal

The goal is to make media, SEO, and publishing part of the actual solution design instead of leaving them as late add-ons.

For real website projects, these concerns affect:

• collection schema
• admin ergonomics
• frontend rendering
• SSR/cache validity
• editorial quality

Source of truth

Use these sources when implementing or reviewing these areas:

• tibi-server/docs/08-file-upload-images.md
• api/collections/medialib.yml
• api/collections/content.yml
• tibi-admin-nova/docs/collection-config.md
• api/hooks/config.js
• api/hooks/lib/ssr-server.js

Media modeling

Use file fields deliberately.

Typical choices:

• file for a single image or asset
• file[] for galleries or multi-asset attachments
• foreign references to a media collection when assets need their own lifecycle or reuse

Choose between inline file fields and dedicated media references based on reuse and editorial workflow, not just convenience.

File validation rules

For serious website builds, do not leave file fields unconstrained.

Define validators where appropriate:

• accepted mime types
• max file size
• min/max image dimensions
• whether mixed media is allowed

This should reflect actual content needs. Hero images, logos, documents, and gallery media often need different constraints.

Image filters

If the project serves resized or transformed assets, define image filters intentionally.

Use filters for:

• thumbnails
• card images
• hero images
• OpenGraph/social images when relevant

Do not leave every consuming component to invent its own ad hoc asset sizes.

Alt texts and captions

Accessibility and SEO-relevant image metadata should be explicit in the model.

Recommended approach:

• store alt text explicitly
• keep captions separate from alt text
• use localized fields if the site is multilingual
• optionally use AI assistance only as a suggestion flow

Do not treat filenames as acceptable alt text.

SEO modeling

Page-like collections should usually model SEO explicitly.

Typical fields:

• meta.title
• meta.description
• social/share image
• optional canonical information if required
• optional index/follow controls for advanced projects

SEO fields should be easy to find in Nova, usually via sidebar groups or clearly named sections.

Publishing model

If the site uses publication timing, define it intentionally.

Typical concerns:

• draft versus active state
• publication window (from / to)
• visibility of unpublished content in public reads
• SSR cache validity for time-sensitive content

Publishing is not just a boolean. If publication windows exist, they must influence runtime and cache behavior.

SSR implications

Media, SEO, and publishing affect SSR directly.

Examples:

• page meta tags must exist in SSR HTML when relevant
• navigation or content with publication windows must invalidate cached HTML correctly
• image-driven blocks must render stable URLs/markup in SSR

If publication timing can make cached HTML stale, the relevant collections must be accounted for in SSR publish-check logic.

Admin ergonomics

Use current Nova features to make media/SEO workflows usable:

• sidebar groups for SEO/publication fields
• viewHint.media for media-focused collections
• previews for image-bearing entities
• layout grouping so editors do not scroll through one long file/SEO form

Media and SEO fields are often technically present but operationally poor if the admin layout is ignored.

Recommended modeling patterns

Marketing page

Recommended shape:

• main content blocks
• explicit SEO object or fields
• hero/share image strategy
• publication controls in sidebar

Media library entry

Recommended shape:

• file field
• title/name
• alt text / caption
• optional copyright/source
• image-focused admin view

Reusable teaser or card entity

Recommended shape:

• image reference or file
• short label/title
• teaser text
• consistent image filter usage in frontend components

Anti-patterns

• No file validators on public/editor-uploaded images
• No explicit alt field
• Mixing captions and alt text into one field
• Hardcoding image sizes only in frontend CSS/components
• Treating publication as frontend-only logic
• Forgetting that publish windows can invalidate SSR HTML

Verification checklist

After changing media/SEO/publishing behavior, verify all of these:

1. Upload validation matches the intended asset type.
2. Image filters are named and used consistently.
3. Alt/caption/SEO fields are explicit and editor-friendly.
4. Publication state affects public output correctly.
5. SSR HTML still reflects the intended published state.
6. yarn validate stays clean.

What an LLM should inspect first

When asked to work on media, SEO, or publishing on this starter, inspect in this order:

1. tibi-server/docs/08-file-upload-images.md
2. the relevant collection YAML
3. admin layout and previews for those fields
4. frontend components consuming the media/SEO data
5. SSR publish-check and invalidation logic if timing matters

This prevents “just add an image field” changes that break runtime, editorial UX, or caching.