seo

Files (11)

• SKILL.md
• evals.json · evals/
• answer-engines.md · references/
• audit.md · references/
• brief-template.md · references/
• metadata-copy.md · references/
• monitoring.md · references/
• nextjs-implementation.md · references/
• research-protocol.md · references/
• sources.md · references/
• validation-evidence.md · references/

SKILL.md (first lines)

# SEO

- **IS:** one entry point for search visibility: evidence-led audits, implementation, demand research, writer briefs, and performance measurement across search engines and AI search (AEO for AI answers inside search, GEO for standalone assistants; see `references/answer-engines.md`).
- **IS NOT:** writing the article or standalone marketing copy (`ghostwriter`), visual redesign (`ui-design`), tenant infrastructure (`multi-tenant-architecture`), or implementing AFDocs / Is Agentic / Is It Agent Ready scorecards (`agent-ready`). Fix SEO copy and markup when they are part of the requested implementation.

## Route the task

| Request | Load | Deliverable |
|---|---|---|
| Audit a site, diagnose indexing, review a migration | `references/audit.md` and `references/validation-evidence.md` | Prioritized findings with URLs, observed evidence, impact, and correction |
| Fix or implement SEO | Audit references, then applicable implementation references below | Code changes, scoped checks, and served-page evidence for the changed behavior |
| Research demand, choose a target, brief a page | `references/research-protocol.md`; `references/brief-template.md` for a brief | Sourced demand table and decision, or a durable writer brief |
| Explain traffic movement, measure AI visibility, monitor SEO | `references/monitoring.md` | Property-scoped diagnosis or configured monitoring with explicit data gaps |

For a combined request, reuse one property and URL inventory across modes. An audit request produces findings; a request to fix them proceeds through implementation and verification within the user's authorized scope. A research-only request does not require crawling every URL or changing code.

## Establish the evidence boundary

Identify the exact public host, URL-prefix or domain property, production environment, project/subpath, audience, and business outcome. On a shared domain, filter each project's path separately. In analytics, verify hostname, path, conversion event and attribution window before interpreting a number.

Discover connected tools and existing project bindings first. Prefer the established reporting source, then an available equivalent, then a signed-in browser. No vendor is required. Ownership verification, API consent and a successful scoped query are separate states. An export for a neighboring property is not a fallback.

Use `No data` with its reason for inaccessible, missing, unsupported or unmeasured metrics; distinguish these from a measured zero. Label historical exports by their actual dates. Do useful public checks while an authenticated metric is unavailable.

## Working sequence

For substantial mixed work, track only the applicable steps:

- [ ] Confirm property, scope, baseline and intended outcome.
- [ ] Inspect live evidence and map affected route patterns or research questions.
- [ ] Prioritize blocking defects and high-value opportunities; separate observations from hypotheses.
- [ ] Implement authorized corrections or deliver the requested research/brief.
- [ ] Recheck the changed behavior, identify the tested environment, and report remaining gaps.

Prioritize crawl/index defects before cosmetic metadata changes. Page titles, headings and content structure follow the page's purpose and reader intent. Descriptive non-brand terms help category discovery; brand-led portfolio and product pages can be appropriate. Neither a fixed title character count nor question-shaped headings are ranking requirements. A title or description rewrite is a positioning change, not a technical fix: follow `references/metadata-copy.md` and keep copy out of the technical-fix commits.

For AI visibility, the owner builds crawl access, content and extractable structure; independent reviews, comparisons and coverage are earned, and they supply most of what answers say about a brand. Fix the owned layers first, then say where the remaining leverage sits instead of padding the site. Original evidence, useful comparisons and honest product limitations earn their place ahead of manufactured keyword permutations. Research likely reader questions; do not present invented query fan-outs as engine telemetry or create a page for every variation.

## References

| File | Read when |
|---|---|
| [references/audit.md](references/audit.md) | Crawling, diagnosing or prioritizing a site audit; canonicals, redirects, exclusions and programmatic pages; hreflang; CDN, response headers or preview environments affecting discovery |
| [references/nextjs-implementation.md](references/nextjs-implementation.md) | Implementing App Router metadata, sitemaps, rendering, status codes, Markdown twins, or schema; verify APIs against the installed Next.js docs |
| [references/answer-engines.md](references/answer-engines.md) | SEO, AEO and GEO terms, AI visibility, which AI-search tactics have evidence, crawler policies, owned versus earned coverage, Markdown alternatives or `llms.txt` |
| [references/metadata-copy.md](references/metadata-copy.md) | Writing or changing page titles, meta descriptions or social titles; deciding whether a metadata edit is mechanical or needs owner sign-off |
| [references/validation-evidence.md](references/validation-evidence.md) | Verifying findings, a built page or a deployed correction |
| [references/research-protocol.md](references/research-protocol.md) | Keyword/prompt metrics, opportunity selection and question maps |
| [references/brief-template.md](references/brief-template.md) | Producing a writer brief |
| [references/monitoring.md](references/monitoring.md) | Search/AI performance, attribution, anomalies or recurring work; where AI visibility data comes from and what replaces a paid tracker |
| [references/sources.md](references/sources.md) | A claim depends on current engine behavior, supported reports, or vendor research |

## Delivery

Findings go in chat unless a file is requested. Writer briefs go to the requested project destination; retain prior dated briefs when producing a new revision. Keep scratch crawls and exports out of the repository. No em dashes in authored reports or briefs.

For a measurement request, report per property: a table per source with the window and method, a `No data` list with each reason, and what the numbers mean for the next decision. For a fix, report what changed, why, exact verification evidence, and what remains unmeasured. A successful local build, ready deployment, public URL probe, Google index record and measured conversion are different evidence. Name the strongest state actually verified.

Sending recaps to others, scheduling recurring work, spending on tools and production deployment follow the user's authorization and host rules. Reuse an existing matching monitor rather than creating another owner or schedule.

## Gotchas

- A sitemap can parse while listing `/studio` that intentionally returns 404. Check its URLs, not just XML validity.
- A canvas gated on mounted state can leave the homepage and category hubs with only navigation in initial HTML. Inspect those hubs as well as deep pages; `use client` alone does not imply missing server-rendered content.
- `lastModified: new Date()` or a build timestamp describes generation, not necessarily a significant page update. Use content dates or omit the field.
- A canonical tag on each URL does not resolve two copies that both self-canonicalize. Compare content and choose the preferred URL.
- Two consistent JSON-LD scripts are not an error. Verify entity identity, eligible properties and visible supporting content instead of script count.
- DNS verification needs no invented meta token. Confirm scoped data access separately.
- A crawler user-agent probe does not authenticate a bot IP or establish index inclusion. Treat CDN logs and engine inspection as separate evidence.
- Prompt demand, measured citations, mentions, AI impressions and referral sessions are different quantities. Preserve engine, source, match type, scope and window.
- A prompt panel run through vendor APIs measures the API, not the consumer app; the OpenAI API recovered about a quarter of the URLs ChatGPT cited in a 2026 study. Label each series by collection method. For keys, use what the user names or the current environment; do not search other projects' `.env` files for credentials.
- One prompt run, or one score averaged across engines, is not a visibility measurement. Repeat each prompt, report per engine, and keep recall separate from citations.
- Schema, `llms.txt` and fixed answer-block lengths are not measured citation levers. Keep them for their real consumers; do not sell them as AI visibility.
- An audit PR that also rewrote titles on priority and campaign pages was sent back with those rewrites reverted, because the wording was the owner's positioning call. Ship mechanical metadata fixes and list the rest for the owner.
- A vendor Search Console connector may under-report. Reconcile property, filters and aggregation against native Search Console before diagnosing a drop.

Maintenance only: `evals/evals.json` holds behavioral scenarios and routing prompts. It is loaded when changing the skill, not during ordinary SEO work.

From mblode/agent-skills, MIT.

More from mblode/agent-skills