home / skills / gtmagents / gtm-agents / technical-seo

technical-seo skill

safe

This skill analyzes crawl, performance, and structured data signals to diagnose technical SEO issues and guide migrations and CWV improvements.

npx playbooks add skill gtmagents/gtm-agents --skill technical-seo

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.8 KB

---
name: technical-seo
description: Use when diagnosing crawl/index issues, performance regressions, or structured
  data gaps.
---

# Technical SEO Playbooks

## When to Use
- Sites experiencing ranking drops despite strong content.
- Launching major site changes (CMS migrations, redesigns).
- Investigating Core Web Vitals, crawl budget, or indexing issues.

## Framework
1. **Crawl Health** – Screaming Frog/JetOctopus results, search console coverage, log file sampling.
2. **Performance** – Lighthouse field vs lab data, render-blocking assets, code splitting, image optimization.
3. **Indexation & Signals** – robots.txt, canonicals, hreflang, pagination, parameter handling.
4. **Structured Data** – schema coverage, errors, merchant/product feeds.
5. **Security & Compliance** – HTTPS, mixed content, cookie banners, accessibility.

## Playbooks
- **Migrations** – pre/post launch checklist, redirect maps, monitoring dashboards.
- **CWV Improvements** – prioritized backlog (LCP, INP, CLS fixes) with eng dependencies.
- **International SEO** – hreflang matrix, localized sitemaps, translation QA.
- **GTM Agents Audit Checklist** – five-pass review (crawl → index → performance → schema → reporting) @puerto/README.md#183-212.
- **Issue Escalation Flow** – Marketing Director ↔ DevOps ↔ Content to fast-track blocking defects.

## Templates
- Crawl issue tracker (URL, issue, severity, owner, status).
- Core Web Vitals monitoring dashboard.
- Structured data coverage sheet.
- KPI guardrail sheet (sessions, rankings, conversions) with "alert" thresholds matching GTM Agents governance cadence.

## Tips
- Pair log-file analysis with Search Console stats to confirm real-world crawl behavior.
- Automate regression alerts via Lighthouse CI or SpeedCurve.
- Document every infra change with timestamp to correlate with ranking volatility.
- Share Guardrail snapshots weekly using GTM Agents-style status packet (target vs actual vs guardrail) to keep Sales + Execs aligned.
- Trigger rollback when three guardrail breaches occur in 24h or when crawl errors spike >25% vs baseline.

## GTM Agents SEO Escalation Workflow
1. **Detection** – SEO specialist flags issue via crawl report or KPI guardrail breach.
2. **Triage** – assign severity (P0-P2) + owner across Engineering, Content, or RevOps.
3. **Action** – implement fix, document via Serena patch or CMS change log.
4. **Validation** – rerun crawl/perf audits, update structured data validator.
5. **Comms** – send 3-point summary (issue, fix, KPI impact) in status packet.

## KPI Guardrails
- Organic sessions: ±10% vs trailing 4-week baseline (alert beyond 15%).
- Priority keyword avg rank: no more than 2 position drop for Tier-1 terms.
- Conversion contribution: must stay within 5% of forecasted pipeline; otherwise notify Growth + Sales.

---

Overview

This skill provides a production-ready technical SEO playbook for diagnosing crawl and indexation issues, Core Web Vitals regressions, and structured data gaps. It bundles practical checklists, monitoring templates, and an escalation workflow to coordinate Engineering, Content, and RevOps. Use it to reduce time-to-detect and time-to-fix SEO regressions during launches or ongoing operations.

How this skill works

The skill inspects crawl health, performance metrics, indexation signals, structured data coverage, and security/compliance checkpoints. It synthesizes log-file sampling, Search Console coverage, Lighthouse lab/field data, and structured-data validators into prioritized action items and dashboards. Results include an issue tracker, CWV backlog, and a clear escalation flow to assign owners and validate fixes.

When to use it

After a CMS migration, domain change, or major site redesign.
When organic rankings drop but content quality appears unchanged.
To investigate Core Web Vitals regressions or performance degradations.
If crawl budget, indexing, or sitemap/hreflang issues arise.
Before and after launching international or large product feeds.

Best practices

Pair server log-file sampling with Search Console stats to confirm real-world crawl behavior.
Prioritize fixes into a CWV backlog tied to engineering dependencies (LCP, INP, CLS first).
Maintain a timestamped infra change log to correlate releases with ranking volatility.
Automate regression alerts via Lighthouse CI or SpeedCurve and feed into the issue tracker.
Share weekly guardrail snapshots (target vs actual vs guardrail) with Sales and Execs for alignment.

Example use cases

Run a pre/post migration checklist with redirect map validation and live monitoring dashboards.
Triage a sudden rankings drop using crawl reports, KPI guardrails, and log-file evidence to assign a P0 fix.
Create a prioritized CWV fix list and coordinate sprint work with Engineering to remediate LCP and INP issues.
Audit structured data across product pages, fix schema errors, and validate feed health for merchant platforms.
Implement an escalation flow to fast-track blocking defects from SEO to DevOps with clear communications and validation steps.

FAQ

How quickly can I detect a crawl or indexing issue?

Initial detection can be immediate with KPI guardrails and crawl reports; full validation typically takes 24–72 hours using log samples and Search Console updates.

What are the highest-impact CWV fixes to prioritize?

Start with Largest Contentful Paint (LCP), then Interaction to Next Paint (INP), and Cumulative Layout Shift (CLS), focusing on render-blocking assets, image optimization, and code-splitting.

When should I trigger a rollback?

Trigger a rollback when three guardrail breaches occur within 24 hours or when crawl errors spike more than 25% versus baseline, after confirming causality.