← Back to the skills catalog

Skill Detail

Setup Blog SEO Foundation

stable

Set up a reusable blog, SEO, and discovery foundation for a Next.js App Router project: site constants, reusable metadata helpers, MDX content collections, Zod frontmatter validation, blog index/detail routes, article JSON-LD, CSP and security headers in `next.config.ts`, `llms.txt`, RSS, sitemap, robots, and Open Graph image resolution. Use when creating or refactoring a content-driven site or blog that needs consistent metadata, crawlable outputs, and contributor rules documented in `AGENTS.md` and/or `README.md`.

7 files
View on GitHub

Install

npx skills add dqstartupbuild/skills/library/seo-setup

README Preview

Overview

Open README

Setup Blog SEO Foundation Skill

A highly opinionated, reusable infrastructure for Next.js App Router projects that provides a battle-tested foundation for blog content, SEO optimization, and discovery.

🚀 Overview

This skill automates the setup of a professional content delivery system. It ensures clean separation of concerns between site constants, content logic, metadata generation, and security headers, resulting in a high-performance, crawlable, and secure site.

Key Features

  • MDX Pipeline: Powered by @content-collections/core with Zod validation.
  • Metadata Engine: Centralized helpers for titles, descriptions, canonicals, and OG images.
  • Security Headers: Managed CSP and security headers configuration in next.config.ts.
  • Discovery Layer: Automated sitemap.ts, robots.ts, RSS feeds (feed.xml), and llms.txt.
  • Premium SEO: Integrated JSON-LD (Schema.org) for articles and landing pages.

📦 Installation

To add this skill to all your local agents (Claude Code, Cursor, Windsurf, etc.), run the following command:

npx skills add https://github.com/dqstartupbuild/skills/library/seo-setup

🛠️ Usage

This skill should be invoked when:

  1. Starting a new project: Setting up the architectural bones for content and SEO.
  2. Adding a blog: Integrating MDX-based article collections.
  3. SEO Refactoring: Moving from ad-hoc metadata to a structured, helper-driven system.

Triggering the Skill

The agent will automatically recognize your intent when you ask to "set up a blog," "configure SEO," or "add security headers to a Next.js app."

🧩 Architectural Principles

  • Single Source of Truth: All site constants (URLs, brand names) live in lib/site.ts.
  • Thin Pages: Routing components should remain minimal, delegating logic to query helpers (lib/content/queries.ts).
  • Standardized Metadata: Strict enforcement of character lengths (Titles: 50-70, Descriptions: 110-170) and absolute canonical URLs.

📂 Repository Structure

  • SKILL.md: The primary instruction file for the AI agent.
  • references/: Specialized playbooks for each architectural layer.
    • implementation-checklist.md: The ordered sequence for successful setup.
    • source-map.md: Recommended file structure and responsibility split.
    • content-contract.md: Frontmatter schema and editorial rules.
    • security-and-discovery.md: CSP, security headers, and crawler optimization.

SKILL.md

1
---
2
name: seo-setup
3
description: >-
4
  Set up a reusable blog, SEO, and discovery foundation for a Next.js App
5
  Router project: site constants, reusable metadata helpers, MDX content
6
  collections, Zod frontmatter validation, blog index/detail routes, article
7
  JSON-LD, CSP and security headers in `next.config.ts`, `llms.txt`, RSS,
8
  sitemap, robots, and Open Graph image resolution. Use when creating or
9
  refactoring a content-driven site or blog that needs consistent metadata,
10
  crawlable outputs, and contributor rules documented in `AGENTS.md` and/or
11
  `README.md`.
12
---
13
14
# Setup Blog SEO Foundation
15
16
Set up a reusable Next.js content system with clean separation between site constants, content logic, metadata generation, and discovery/security outputs.
17
18
## Core Pattern
19
20
- Keep site-wide URLs, brand text, and OG path helpers in `lib/site.ts`.
21
- Keep generic metadata generation in `lib/metadata.ts`.
22
- Keep content schema, query helpers, and content SEO helpers under `lib/content/`.
23
- Keep authored MDX in `content/` and compile it through `content-collections.ts`.
24
- Keep CSP and the shared security header set in `next.config.ts`, applied to `/:path*`.
25
- Keep content pages inside an `app/(content)/` route group or equivalent shared content shell.
26
- Use Next.js metadata routes for `app/sitemap.ts` and `app/robots.ts`, plus `app/feed.xml/route.ts` for RSS.
27
- Keep `llms.txt` content in a source-of-truth helper and expose it through `app/llms.txt/route.ts`.
28
- Resolve Open Graph images from the route or canonical URL, with a fallback image if a route-specific asset is missing.
29
30
## Workflow
31
32
1. Read [references/implementation-checklist.md](references/implementation-checklist.md) first for the ordered setup.
33
2. Read [references/source-map.md](references/source-map.md) when you need the recommended file layout and responsibility split.
34
3. Read [references/content-contract.md](references/content-contract.md) when creating MDX collections, frontmatter, or editorial rules.
35
4. Read [references/security-and-discovery.md](references/security-and-discovery.md) when wiring CSP, security headers, `llms.txt`, `robots.ts`, or `sitemap.ts`.
36
5. Customize all project constants, route groups, supported embeds, discovery sections, and CTA variants for the target project.
37
6. Keep one source of truth for site URLs and canonical generation. Do not hardcode the site origin across many files.
38
7. Keep filtering, sorting, taxonomy, and related-content logic in query helpers instead of page components.
39
8. Add or update tests around metadata helpers, schema validation, `llms.txt`, and sitemap coverage whenever you change the structure.
40
41
## Non-Negotiables
42
43
- Use absolute canonical URLs in content frontmatter.
44
- Generate metadata through helpers instead of duplicating ad hoc metadata objects across content pages.
45
- Emit JSON-LD from shared helpers so article pages stay thin.
46
- Build content collections before typecheck, tests, or production builds.
47
- Keep MDX component registration centralized; do not import components directly inside MDX files.
48
- Keep SEO-facing titles in a dedicated `seoTitle` field and enforce a 50-70 character target there.
49
- Keep SEO descriptions in the 110-170 character range.
50
- For non-content pages, keep the metadata title between 50 and 70 characters and the metadata description between 110 and 170 characters, even if the visible page heading is longer.
51
- Keep the security header implementation centralized in `next.config.ts`; do not scatter CSP or header mutations across routes unless the user explicitly wants route-specific overrides.
52
- Keep `llms.txt`, `robots.ts`, and `sitemap.ts` driven from shared helpers and site constants rather than hardcoding disconnected values.
53
- Add these editorial rules and the full blog/SEO setup details to the target repository's `AGENTS.md` and/or `README.md` so future contributors keep following the same contract.
54
55
## Verification
56
57
From the target app root, run the equivalent of:
58
59
```bash
60
npm run content:build
61
npm run typecheck
62
npm test
63
npm run build
64
```
65
66
If the project uses `pnpm`, `yarn`, or `bun`, adapt the commands but keep the same order.
67
68
## References
69
70
- [references/implementation-checklist.md](references/implementation-checklist.md): ordered setup steps and verification sequence
71
- [references/source-map.md](references/source-map.md): recommended file-by-file architecture map
72
- [references/content-contract.md](references/content-contract.md): frontmatter schema, editorial rules, and authoring constraints
73
- [references/security-and-discovery.md](references/security-and-discovery.md): CSP, headers, `llms.txt`, `robots.ts`, and `sitemap.ts` patterns
74