Was macht add-seo?
SEO mechanisms, not content. Every project-specific value lives in one file, lib/site.ts, and anything the developer (or their agent) must write is a TODO(seo) placeholder. Run it after add-env, which it requires, and before add-guardrails.
Generation source of truth: scripts/init.sh. The script writes every file. Do not hand-write or restate the templates.
Locked defaults
| Knob | Value |
|---|---|
| Packages | none: metadata, sitemap.ts, robots.ts, opengraph-image.tsx, next/og |
| Site URL | NEXT_PUBLIC_SITE_URL: z.url() in lib/env.ts client + runtimeEnv; .env.example gets NEXT_PUBLIC_SITE_URL=, .env.local gets http://localhost:3000. Skipped if already declared |
| Config | lib/site.ts: name (from package.json), description (TODO(seo) placeholder), url (env, localhost fallback for SKIP_ENV_VALIDATION builds), routes (["/"]) |
| Root metadata | metadataBase, title template %s | name, description, openGraph.siteName + type. No canonical or og:url: Next.js would inherit them on every page |
| Sitemap | maps over site.routes; no filesystem scan |
| Robots | allow all, points at /sitemap.xml |
| OG image | 1200×630, site.name centred on a plain dark background |
| AGENTS.md | appends a ## SEO section when AGENTS.md exists: where values live, TODO(seo), routes, per-page canonicals |
| Existing config | replaces only the untouched create-next-app metadata; anything customized aborts. Never merges |
| Out of scope | JSON-LD, keywords, per-page metadata, llms.txt, AEO/GEO/SXO, Vercel-specific URLs |
Steps
-
Resolve target
- Default: current workspace root. Use another path only if the user named one.
- Completion: absolute target path chosen.
-
Self-hit guard
- Abort if the target is this skill package (
SKILL.mdwithname: add-seo). - Completion: target is not the skill package.
- Abort if the target is this skill package (
-
Compatibility guard
- Abort unless all hold:
package.jsonexists and listsnextapp/orsrc/app/existspnpm-lock.yamlor packageManager pnpm. Abort ifpnpmmissing on PATH
scripts/init.shalso aborts, before writing anything, if:lib/site.tsexists (already initialized),add-envhas not run,next.config.tsdoes not import the env module,sitemap.*/robots.*/opengraph-image.*already exist inapp/, rootmetadata/generateMetadatais customized, orlib/env.tsis not in the shapeadd-envgenerates.- Completion: compatible, uninitialized project.
- Abort unless all hold:
-
Generate
- Run this skill’s
scripts/init.shwith the absolute target. It takes no other input. - Do not open, print, or copy
.env*files yourself. - Completion: script exits 0.
- Run this skill’s
-
Verify artifacts
lib/site.ts,app/sitemap.ts,app/robots.ts,app/opengraph-image.tsxexist.app/layout.tsximportssitefrom@/lib/siteand setsmetadataBase.lib/env.tsdeclaresNEXT_PUBLIC_SITE_URLinclientandruntimeEnv.- If
AGENTS.mdexists, it contains## SEOexactly once. - Completion: all expected artifacts present.
-
Smoke check
- From the target:
pnpm build. - A failure listing
Invalid environment variablesmeans a variable is missing or invalid in this environment. That is validation working. Report the names, leave the tree as-is, stop. - Any other failure: leave the tree as-is, surface the error, stop. No rollback.
- Completion:
pnpm buildexits 0.
- From the target:
-
Lint check
- From the target:
pnpm lint. - Completion: no errors from the generated files.
- From the target:
-
Report and stop
- Report only: target path; files written;
pnpm buildpassed. - Note: replace
TODO(seo)inlib/site.ts; setNEXT_PUBLIC_SITE_URLto the production URL in production; add public routes tosite.routes; give each page its ownalternates.canonical. - Do not write the description or other copy for the user. Do not start
dev, open a browser, commit, or deploy unless the user asks in the same turn. - Completion: minimal report delivered; no unsolicited follow-on.
- Report only: target path; files written;
Ask only when blocked
Ask for a different path only when the default target fails a guard or the user already named another path that needs clarification.