@clize/clize 0.26.1 → 0.28.0

package/skills/clize-seo/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: clize-seo
+description: >-
+  Read what `clize seo` returns and decide what to do about it. The commands give facts —
+  keyword metrics, who occupies a results page, your positions, where your traffic comes
+  from, what Search Console is showing you. This skill is the judgment layer: which keywords
+  are worth attacking at your authority level, what a results page is actually telling you,
+  where to place content so it gets found, how to write so AI engines can quote you, and how
+  to read a `seo check` without fooling yourself.
+  Triggers: "should I go after this keyword", "why aren't we ranking", "what does this SERP
+  mean", "read my seo check", "how do I get cited by ChatGPT", "write this page for AI search",
+  "where should I publish this", "is our SEO working".
+---
+
+# Reading and acting on `clize seo`
+
+The commands are deliberately dumb: they compress facts, they never advise. `serp` will tell
+you a page is a `listicle_window`; it will not tell you to pitch those listicles. That call is
+yours, and this file is how to make it.
+
+Run `clize seo <cmd> --help` for exact flags. Everything below assumes you have the output.
+
+---
+
+## 1. Reading a results page (`seo serp`)
+
+`verdict` compresses **who occupies the page**. Four values, and what each one means for
+whether you can get in:
+
+| verdict | what it means | what it implies |
+| --- | --- | --- |
+| `official_wall` | The brand named in the query owns ≥3 of the top 5 | You are not getting in on this query. It is a navigational query wearing a category costume. |
+| `definition_wall` | Big vendors / encyclopedias hold ≥4 of the top 10 with "what is X" content | Do not write another definition. Go long-tail, or go where the discussion is (Reddit, HN). |
+| `listicle_window` | Roundups hold ≥3 of the top 10 | **The only shape you can enter without authority.** `parasiteTargets` lists the roundups — getting included in one is cheaper than outranking them. |
+| `open` | No single occupancy pattern the classifier can identify | **Not the same as "there's room."** Read `items` yourself. |
+
+### `open` is the one that will fool you
+
+`open` means *the machine found no mechanical pattern*, not *the page is winnable*. Measured
+case: `agentic payments` came back `open`, but the top eight were ACI Worldwide, AWS,
+Fireblocks, Accenture, Mastercard and Kearney — an enterprise definition wall in everything
+but the classifier's domain list. Whenever you see `open`, read the hosts. If they are all
+large vendors publishing thought-leadership, treat it as `definition_wall`.
+
+### KD and the SERP are different questions — check both
+
+`seo keywords` says `stripe mcp server` is KD 4, `band: attackable`. `seo serp` on the same
+keyword returns `official_wall`: three of the top five are Stripe's own properties. **A low
+difficulty score on a page nobody can enter is not an opportunity.** Never pick keywords from
+`band` alone; run `serp` on anything you are about to invest a page in.
+
+### The classifier does not judge intent — you do
+
+`ai agent deployment` returns `open`. Read the items and you find they are all about deploying
+*agent runtimes*, not about agents deploying *websites*. That is an intent mismatch, and it is
+invisible to a rule engine because it requires knowing what your product is. Same for
+`ai domain registration`, which turns out to mean "buy a .ai domain". **Always read `items`
+before committing to a keyword**, whatever the verdict says.
+
+### `aiOverview: true`
+
+An AI Overview sits above the organic results and answers the query in place. Position 3 under
+an AI Overview is worth much less than position 3 without one, and some of your impressions will
+never become clicks no matter what you do. Note it, factor it into expectations, and lean harder
+on being *quotable* (§4) than on being *ranked*.
+
+---
+
+## 2. Picking keywords at your authority level (`seo keywords`)
+
+`band` is a mechanical bucket of keyword difficulty: `attackable` (<10), `stretch` (10–30),
+`wall` (>30), `no_volume`.
+
+For a site with near-zero authority (new domain, few referring domains):
+
+- Attack `attackable` **that also pass the SERP check** (§1).
+- `stretch` is a 6–12 month bet; take at most one or two, and only if the SERP is a
+  `listicle_window` you can parasitize meanwhile.
+- `wall` is not a plan. Skip it.
+- `no_volume` is not automatically worthless: a keyword with no recorded volume whose SERP is
+  already full of category roundups is a **pre-emergence** signal — the searches exist, the
+  keyword tools have not caught up. `email api for ai agents` had no volume and a
+  `listicle_window` with four roundups on it. That is a keyword worth an early page.
+
+`--ai` adds `aiSv`, the volume inside AI engines. **It is a different unit from `sv`.** Measured:
+`agent mail` is 5,400 on Google and 125 in AI engines; `ai email agent` is 140 and 5. Compare a
+keyword to itself over time, or rank keywords against each other — never put `sv` and `aiSv` in
+the same sentence as if they were the same quantity, and never add them.
+
+---
+
+## 3. Where to place content
+
+Priority order, most effective first for a low-authority site:
+
+1. **Third-party trust positions.** Registries and directories that accept submissions, and the
+   roundups in `parasiteTargets`. Getting listed in a page that already ranks beats trying to
+   outrank it. This is manual outreach — the product produces the target list, it does not send
+   anything.
+2. **Where the discussion already is.** Reddit and HN rank on a large share of these queries
+   (they appear in nearly every SERP fixture we have). Participating is legitimate; astroturfing
+   is not, and it will cost you the account and the credibility.
+3. **Your own site last.** Not because it doesn't matter, but because on a new domain it is the
+   slowest of the three. Publish there, then go get the first two.
+
+---
+
+## 4. Writing so AI engines can quote you
+
+Retrieval-augmented engines quote passages, not pages. What survives extraction:
+
+- **Answer completely in the first 200 words.** Assume the extractor never reaches your second
+  section.
+- **One-sentence extractables.** Each key claim should stand alone when lifted out of context.
+  Pronouns and "as mentioned above" destroy quotability.
+- **Statistics and named sources.** Concrete numbers with attribution get quoted; adjectives
+  don't.
+- **Define your terms verbatim and identically everywhere.** If your definition sentence varies
+  between pages, no single phrasing accumulates authority.
+- **Machine-readable surface**: `llms.txt`, schema.org markup, a sitemap, and IndexNow pings.
+
+---
+
+## 5. Reading a `seo check`
+
+### `rank`
+
+`rank.source` is always `"gsc"`: positions come from Search Console, free, and `check` makes no
+upstream calls at all. Read them accordingly.
+
+- `position` is the **impression-weighted average over `rank.window`**, not your rank at a moment.
+  A 62.4 means "across the window, the average slot Google gave you was ~62". Two consequences:
+  a single good day barely moves it, and it is **not comparable** to a scraped SERP position
+  (or to any number a pre-0.28.0 check reported).
+- `delta` is **positive when you moved up** (the number got smaller), measured against
+  `rank.prevWindow` — the equal-length window right before this one. `movers` shifted by 3+;
+  anything smaller is averaging noise. `series` is weekly, newest first; weeks with no
+  impressions are simply absent, so read the dates, not the spacing.
+- `unseen` lists the keywords on your list that **Search Console did not see this window**.
+  This is not "not ranking" — GSC only has a row once you get impressions. It is the honest
+  statement "no data yet", and it costs nothing to say. **If you need one of these words' real
+  position, that is a separate, deliberate act: `clize seo serp <keyword>`** (~$0.02, and its
+  `items` carry both your position and your competitors'). Do not ask for all of them: for a
+  word with no demand signal yet, the answer is a slow, expensive way to keep reading "still
+  not there".
+- `rank: null` means **this round had nothing to synthesise from** (no Search Console access, or
+  no keyword list) — read `notes`. It is not "you rank nowhere".
+- **Competitor positions are not in `check`.** `--competitors` is remembered configuration only;
+  a head-to-head on one keyword is `seo serp <keyword>`, where the whole page comes back at once.
+
+### `traffic`
+
+- `ai` is always present, **including when it is all zeros — zero is the finding.** First
+  non-zero AI referral is a real milestone; note the date.
+- The numbers are **adaptively sampled and rounded by magnitude**. Compare them over time.
+  Never quote them as exact counts, to yourself or to anyone else.
+- Same-host referrers are internal navigation and already excluded.
+
+### `gsc`
+
+- `newQueries` is the feedback loop closing: Google is telling you which queries it *considers*
+  you relevant for. Queries you never targeted showing real impressions are the most valuable
+  output of the whole command.
+- **Impressions with zero clicks at position 60–90 is not a content problem.** It means Google
+  is offering you the keyword surface and withholding the position. That is an authority
+  bottleneck; writing another page on the same theme will not move it. Go do §3.1.
+- `gsc: null` is not an error. Read `notes` — usually it means the service account has not been
+  added to that property yet.
+
+### The one rule that ties it together
+
+When `rank` puts you at ~70 on a keyword, `gsc` shows hundreds of impressions and almost no
+clicks on it, and `serp` says that page is a `listicle_window` — that is a complete, actionable
+picture: **the demand exists, the position is authority-limited, and the way in is the roundups,
+not another page.** This exact configuration is what clize.ai looked like on 2026-08-30.
+
+The mirror image is a word sitting in `unseen` round after round: no impressions at all means
+Google is not even offering you the surface. That is a **discovery** question (is this word
+reachable at your authority? what occupies it? — `seo serp`), not a measurement one. Running
+the measurement again will not answer it.
+
+---
+
+## 6. Two playbooks
+
+**New site, cold start.** `seo keywords` on your seed set → drop `wall`, keep `attackable` and
+interesting `no_volume` → `seo serp` each survivor → discard `official_wall` and
+`definition_wall` → for `listicle_window`, collect `parasiteTargets` and start outreach → write
+one page per surviving keyword following §4 → deploy → `seo check --keywords <the survivors>
+--brand <you> --competitors <the two you keep seeing>`. That first check is your baseline.
+
+**Recheck.** `clize seo check` with no flags (it remembers everything) → read `movers` first,
+then `traffic.ai`, then `gsc.newQueries`, then what is still in `unseen` → decide: keep waiting,
+add the new queries to the tracked list, or change approach. The check is free, so nothing stops
+you running it — but **SEO is a weeks-to-months system, and the window it measures is 4 weeks
+wide: checking daily just re-reads the same window.** Every two weeks is plenty.
+
+---
+
+## 7. Calibration discipline
+
+Every measurement here is a sample, not a census. Rank sampling is one fetch of a personalized,
+rotating results page. Traffic is adaptively sampled. AI-engine visibility measured by any tool
+is a sample of a non-deterministic system — one independent evaluation found a major commercial
+tool undercounting by 40×.
+
+So: **promise time series against yourself, never absolute share.** "Our AI referrals went from
+0 to 40 a month" is defensible. "We have 3% AI visibility" is not, no matter which tool printed
+it. Breaking this rule in customer-facing copy is a product-integrity failure, not a rounding
+error.
+
+---
+
+## What this skill will not do
+
+Generate the content (that's your job — clize is the hands, you're the brain), submit to
+directories or post to forums (manual, on purpose), or promise rankings. And there is no
+automatic monitoring: measurement only pays off when someone can act on it, so a recheck happens
+when you show up to run one.