one-step-seo · git:20261113.8c20bb1 · 2026-11-13 · sha256 e87c74d2b3e99eef

one-step-seo git:20261113.8c20bb1A

Immutable. This exact content never changes and is served at /api/v1/blob/e87c74d2b3e99eef.

---
name: one-step-seo
description: One-command SEO + AI-visibility audit for any website. Use when asked to audit SEO, check rankings readiness, validate schema, improve AI citation, or plan SEO fixes.
---

# one-step-seo skill

Run a full SEO + GEO/AEO audit in one step. Zero dependencies, Node 18+.

## When to use

- User asks: "audit my SEO", "why aren't we ranking", "check this page", "fix schema", "AI search readiness", "GEO audit".
- Example prompt to support: "Audit https://example.com with one-step-seo, summarize the top 5 fixes, and create an implementation plan."
- Any framework: Astro, Next.js, WordPress, Shopify, static HTML.

## Workflow

1. Run the audit (never guess — always fetch the live URL):
   ```bash
   # Auto-discover all website pages and generate full report:
   npx one-step-seo https://example.com
   # or dedicated site command (hybrid sitemap + link BFS crawl):
   npx one-step-seo site https://example.com
   # or full crawl with custom page limit/out folder:
   npx one-step-seo audit https://example.com --all --out ./seo-report
   ```
   Beginner shortcut (5 pages, all formats):
   ```bash
   npx one-step-seo quick https://example.com
   ```
   Single page:
   ```bash
   npx one-step-seo page https://example.com/pricing --out ./seo-report
   ```
   CI gating (exit 2 on P0 or worse):
   ```bash
   npx one-step-seo audit https://example.com --all --out ./seo-report --fail-on P0
   ```
   Offline local builds (Astro, Next.js static, Vite, HTML):
   ```bash
   npx one-step-seo site ./dist --out ./seo-report
   npx one-step-seo page ./dist/index.html --out ./seo-report
   ```
   Inspect auditing skills & filter by skill domain:
   ```bash
   npx one-step-seo skills
   npx one-step-seo audit https://example.com --skills onpage-optimization,schema-validation
   ```
2. Read `./seo-report/report.json` (machine) or `report.md` (human). Multi-page runs also write `report-N.*`, `index.md`, `site-report.json`, and a site-wide `index.html` dashboard (totals, worst-first pages, recurring issues, category distribution, duplicate titles/metas, internal linking & orphan risks) — start there for the big picture.
3. Present the **two scores separately** — Search SEO 0-100 and AI Visibility 0-100, never blended.
4. Fix in priority order P0 → P1 → P2. Each fix needs evidence from the report.

## Specialized Agent Sub-Skills (`skills/*/SKILL.md`) vs Executable CLI Skill Groups

`one-step-seo` separates **24 Agent Skill playbooks** (`skills/*/SKILL.md` across 10 domains — structured instructions for AI coding agents) from **22 executable CLI skill groups** (`lib/skills.mjs` across 9 categories — rule filters passed to `--skills` / `--exclude-skills` and inspected via `one-step-seo skills`).

Delegate domain-specific engineering and editorial workflows to the 24 structured playbooks in `skills/`:

| Domain                     | Sub-Skill Path                               | Primary CLI Commands & Flags                                   | When to Activate                                                                  |
| -------------------------- | -------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Core Workflow**          | `skills/seo-audit/SKILL.md`                  | `audit`, `page`, `quick`, `ai`                                 | Full-site or single-page audits, score triage, and 30/60/90-day action plans      |
| **Core Workflow**          | `skills/seo-fix/SKILL.md`                    | `fix [--apply] [--url] [--lang]`                               | Safe, dry-run-first automated HTML remediation with `.bak` backups                |
| **Technical SEO**          | `skills/technical-seo/SKILL.md`              | `audit/page --skills technical-seo`                            | HTTPS, HTTP 200 status, redirect chains, `noindex`, canonical URLs, mixed assets  |
| **Technical SEO**          | `skills/http-status/SKILL.md`                | `audit/page --skills http-status [--check-links]`              | 4xx/5xx responses, multi-hop redirects (`>1` hop), MIME headers, broken outlinks  |
| **Technical SEO**          | `skills/javascript-seo/SKILL.md`             | `audit/page --skills javascript-seo`                           | CSR vs SSR/SSG raw-HTML blindness, empty SPA shells, script & hydration bloat     |
| **Technical SEO**          | `skills/sitemap-robots/SKILL.md`             | `sitemap`, `audit --skills sitemap-robots --crawl sitemap`     | `robots.txt` directives, XML sitemaps, `<sitemapindex>` expansion                 |
| **Security & Hygiene**     | `skills/security-hygiene/SKILL.md`           | `audit/page --skills security-hygiene --block-private-ips`     | HTTPS transport, active/passive mixed content, CSP/HSTS headers, SSRF safety      |
| **Accessibility & UX**     | `skills/accessibility-seo/SKILL.md`          | `audit/page --skills accessibility-seo`, `fix --only lang`     | `<html lang>`, mobile viewport, image `alt`, heading order, `<main>`, anchors     |
| **International & Local**  | `skills/international-seo/SKILL.md`          | `audit/page --skills international-seo`                        | `hreflang` clusters, `x-default`, BCP-47 `lang`, self-referencing locale URLs     |
| **International & Local**  | `skills/local-seo/SKILL.md`                  | `page --skills local-seo`, `schema --generate localbusiness`   | `LocalBusiness` JSON-LD, Name-Address-Phone (NAP) consistency, geo/hours          |
| **On-Page & Content**      | `skills/onpage-optimization/SKILL.md`        | `audit/page --skills onpage-optimization`                      | `<title>`, meta description, H1–H6 hierarchy, Open Graph, Twitter Card, alt/CLS   |
| **On-Page & Content**      | `skills/social-metadata/SKILL.md`            | `audit/page --skills social-metadata`, `fix --only og,favicon` | Rich Slack/LinkedIn/X link previews (`og:*`, `twitter:card`, `og:url`, favicons)  |
| **On-Page & Content**      | `skills/image-seo/SKILL.md`                  | `audit/page --skills image-seo`                                | Image `alt` descriptions, `width`/`height` CLS prevention, image count & HTTPS    |
| **On-Page & Content**      | `skills/content-quality/SKILL.md`            | `audit/page --skills content-quality [--profile ...]`          | Word count depth, answer-first lead blocks, comparison tables (`<th>`), FAQs      |
| **On-Page & Content**      | `skills/duplicate-content/SKILL.md`          | `audit --pages N --skills duplicate-content`                   | Cross-page duplicate titles/descriptions and canonical consolidation              |
| **On-Page & Content**      | `skills/internal-linking/SKILL.md`           | `audit --pages N --skills internal-linking [--check-links]`    | Crawl depth, orphan/dead-end pages, generic anchor text, broken same-host links   |
| **GEO / AEO / AI Search**  | `skills/geo-optimization/SKILL.md`           | `ai`, `audit --skills geo-optimization`                        | AI crawler access (`GPTBot`, `ClaudeBot`, `PerplexityBot`), snippet gates, facts  |
| **GEO / AEO / AI Search**  | `skills/answer-engine-optimization/SKILL.md` | `page/ai --skills answer-engine-optimization`                  | 40–60w answer capsules, question H2s, `<th>` tables, quantified stats, FAQ parity |
| **GEO / AEO / AI Search**  | `skills/entity-optimization/SKILL.md`        | `page/ai --skills entity-optimization`, `schema`               | Knowledge Graph entity alignment (`<title>`/`<h1>`/`og:title`), authorship, dates |
| **GEO / AEO / AI Search**  | `skills/llms-txt/SKILL.md`                   | `llms`, `audit --skills llms-txt`                              | `/llms.txt` discovery, structural quality (`G05`), starter draft generation       |
| **Structured Data**        | `skills/schema-validation/SKILL.md`          | `schema [--generate <kind>]`, `audit --skills schema`          | JSON-LD syntax, `@graph` entity linking, 15 required-property validators, parity  |
| **Structured Data**        | `skills/ecommerce-seo/SKILL.md`              | `audit/page --profile product --skills ecommerce-seo`          | `Product`/`Offer`/`Review`/`BreadcrumbList` JSON-LD, facet canonicals, PDP media  |
| **Performance & Quality**  | `skills/core-web-vitals/SKILL.md`            | `audit/page --psi [--psi-strategy desktop] --skills cwv`       | HTML payload size, image count, Lighthouse lab metrics (LCP/CLS/TBT) & CrUX INP   |
| **Monitoring & Reporting** | `skills/seo-regression/SKILL.md`             | `diff <base.json> <head.json> [--fail-on P0\|P1]`              | CI/CD regression gating, score deltas, `rulesVersion` verification                |

## Reading report.json

Stable, schema-documented shape (`lib/schema-report.json`):

- `scores.search {score, band}` and `scores.ai {score, band}` — the two axes. Bands A–F.
- `counts {P0, P1, P2, P3, pass}` — severity totals for gating and progress tracking.
- `findings[] {id, category, severity, title, evidence, fix, seoImpact, geoImpact}` — priority-sorted, P0 first. Finding IDs match `^[A-Z]+[0-9]+-[a-z0-9-]+$`.
- `page {title, metaDescription, canonical, wordCount, h1[], images, internalLinks, externalLinks, psi?}` — page facts without re-fetching.
- `site {origin, robots, sitemap, sitemapUrls, llms}` — booleans + sitemap size.
- Severity: P0 critical (today) → P1 high (this week) → P2 medium (this month) → P3 polish → pass healthy.
- Categories: `technical`, `onpage`, `content`, `schema`, `geo`, `performance`.

## Prioritizing fixes

1. Take the first 3–5 non-`pass` findings (they are already priority-sorted).
2. For each: quote `evidence`, state `fix`, and add triage from `report.md` (“Fix this first”): impact (low/medium/high), effort (minutes/hours/days), owner (developer/content/SEO/agency).
3. Group by owner so the user can delegate: content fixes to writers, developer fixes to engineers.
4. Never present a fix without its evidence. Never invent statistics, reviews, business facts, or competitor data.

## Remediation plans

Structure every plan as:

- **Executive summary** (3 bullets: scores, verdict, biggest win).
- **Priority actions** (Problem → Evidence → Action → Impact → Effort → Owner).
- **Passed checks** (1 line each — reassure the user what is fine).
- **30/60/90-day plan** (P0/P1 now, P2 this month, P3 + monitoring later).
- **Verification**: re-run `npx one-step-seo page <url>` after fixes and report the score delta.

## Rules

- Never invent statistics, reviews, business facts, or competitor data.
- Only recommend Schema.org markup for content visible on the page.
- Prefer additive, reversible fixes. Show the exact snippet or diff.
- Distinguish: **verified fact** vs **observed data** vs **inference** vs **recommendation**.
- Never claim guaranteed rankings or guaranteed AI citations. Frame results as readiness signals and best practices.

## Explaining findings to non-technical users

- Lead with the verdict sentence from `report.md` (“Executive summary”).
- Translate each finding via its plain-language explanation (same section): no jargon, one sentence on why it matters to traffic or customers.
- Use impact/effort/owner labels so they know what to approve, how long it takes, and who does it.
- End with the citable checklist (“Make this page more citable”) for AI-visibility work.

## Client-ready summary

```markdown
## SEO audit — <url>

- Search SEO: **{search}/100 ({band})** · AI Visibility: **{ai}/100 ({band})**
- Verdict: {one-sentence verdict from report.md}
- Fix this first:
  1. [{sev}] {title} ({id}) — {one-line fix} (Impact: {x} · Effort: {y} · Owner: {z})
  2. …
- Passed: {count} checks, including {2–3 notable passes}.
- Next: {re-run command} after fixes. Full report: `report.html`.
```

## Report shape

`report.json` fields: `scores {search {score,band}, ai {score,band}}`, `rulesVersion` (scoring ruleset — diff warns across versions), `counts`, `findings[] {id, category, severity, title, evidence, fix}`, `page`, `site`.
Severity: P0 critical, P1 high, P2 medium, P3 low, pass healthy.

## Fix workflow

For safe auto-fixes on **local HTML files**, prefer the built-in writer:

```bash
npx one-step-seo fix ./dist --url https://example.com/          # dry-run diff
npx one-step-seo fix ./dist --url https://example.com/ --apply  # write + .bak
```

It is additive-only, previews a unified diff, verifies every fix in memory,
and never invents facts (language/titles/images need flags when they cannot
be derived from the page). For everything else, follow
`skills/seo-fix/SKILL.md`: default to preview and ask before writing files.

## AI-visibility paperwork

```bash
npx one-step-seo llms https://example.com   # llms.txt status + starter draft + robots snippet
```

Review the starter draft with the user before publishing — it contains
explicit placeholders where facts are unknown. The robots snippet allows the
major AI crawlers; only apply it when AI citation is wanted.

## Crawler access check

```bash
npx one-step-seo bots https://example.com          # what Googlebot, Bingbot, Applebot and AI crawlers get vs a browser
npx one-step-seo bots https://example.com --json   # verdicts per crawler, problems per page
```

The requests come from this machine with each crawler's published user
agent, while CDNs and firewalls recognise real crawlers by IP address.
Present a block, challenge or difference as a lead to confirm in the CDN or
firewall settings (and, for Googlebot, with Search Console's URL Inspection
live test), never as what the crawler definitely gets. Only run it on sites
the user owns or may test.