{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "agent-kit",
  "title": "AgentBlog agent kit",
  "description": "Seven skills that take a blog from install to published: finish the setup for your site, research what to write with real search and AI citation data, plan the topic clusters, write posts to the GEO playbook, refresh them without falsifying dateModified, audit before publish, and publish with the IndexNow response code actually read. Installs into your project's .claude/skills directory, so any agent working in this repository picks them up. Also available as a Claude Code plugin and through npx skills add.",
  "files": [
    {
      "path": "registry/agent/skills/agentblog-setup/SKILL.md",
      "content": "---\nname: agentblog-setup\ndescription: >\n  Finishes an AgentBlog install end to end: repairs the config wiring the registry\n  alone cannot do, then replaces the seed identity, authors, categories, and posts\n  with the user's own so the blog is theirs rather than AgentBlog's. Verifies with\n  agentblog doctor rather than asserting success. Use after installing AgentBlog\n  with shadcn add or agentblog init, when asked to finish setting up the blog or\n  configure it for a site, when agentblog doctor reports findings, or when the blog\n  still shows placeholder branding, example.com links, or the AgentBlog seed posts.\nallowed-tools: Read Write Edit Glob Grep Bash(npx agentblog *) Bash(git check-ignore *)\nlicense: MIT\ncompatibility: A Next.js project with AgentBlog installed. Needs network access for the live crawler check.\nmetadata:\n  package: agentblog\n  homepage: https://agentblog.dev\n---\n\n# Finish the install, then make the blog theirs\n\nAgentBlog installs in two layers and finishes in three. `shadcn add` copies the\nfiles. The `agentblog` CLI patches the two files that live outside the block.\nNeither can do the third thing, which is turn a correct install into this user's\nblog: the seed content ships AgentBlog's own author, AgentBlog's own four\ncategories, and two posts about AI search.\n\nA user who stops after layer two has a blog that renders, passes `doctor`, and\npublishes somebody else's topics under a placeholder byline.\n\nWork in that order. Phase 1 is mechanical and mostly automated. Phase 2 needs the\nuser, and it is the phase that decides whether the blog is worth crawling.\n\nAssume the shadcn CLI skill covers `shadcn add`, registries, and `components.json`.\nAssume `node_modules/next/dist/docs/` covers Next.js API shapes for the exact\nversion installed. This skill covers the wiring between them.\n\n**Never use an em dash** in anything you write into this repository, including\nconfig comments, author bios, and category descriptions.\n\n```\n- [ ] 1. Read the state before changing anything\n- [ ] 2. Let doctor --fix do the mechanical repairs\n- [ ] 3. Fill agentblog.config.ts with real values\n- [ ] 4. Write the real author record\n- [ ] 5. Replace the taxonomy with the user's topics\n- [ ] 6. Decide what happens to the seed posts\n- [ ] 7. Verify, do not assert\n```\n\n## Phase 1: converge the install\n\n### 1. Read the state before changing anything\n\n```bash\nnpx agentblog doctor --verbose\n```\n\nIt enumerates every check and names the ones that fail, which is a better starting\npoint than inspecting files by hand. Read its output before opening anything.\n\nThen read `components.json`. **If it is absent, stop.** AgentBlog requires an\ninitialised shadcn project, and creating `components.json` on the user's behalf\nmakes decisions about style, base colour, and aliases that are theirs. Tell the user\nto run `npx shadcn@latest init` and stop.\n\nNote whether the project uses a `src/` directory, because every path below shifts.\n\n### 2. Let `doctor --fix` do the mechanical repairs\n\n```bash\nnpx agentblog doctor --fix --dry-run   # show the user the diff first\nnpx agentblog doctor --fix\n```\n\nIt repairs exactly this, and backs every file up to `.agentblog/backup/` first:\nthe `htmlLimitedBots` union and `images.qualities` in `next.config.ts`;\n`metadataBase`, `title.template`, and the RSS alternates link in the root layout;\nan environment guard in `app/robots.ts`; the AgentBlog block in `AGENTS.md`, placed\nafter the region Next.js manages; `INDEXNOW_KEY` and `AGENTBLOG_REVALIDATE_SECRET`\nin `.env.local`, moved out of any git-tracked env file; and the IndexNow key file\nin `public/`. Anything it declines to change is printed with the reason.\n`npx agentblog revert` puts it all back.\n\nPrefer it over hand-editing every time. Three things are worth knowing anyway,\nbecause they decide whether you accept its output or investigate.\n\n**`htmlLimitedBots` replaces the Next.js default bot list rather than extending\nit.** The value must be a union: every AI crawler _plus_ the entire Next.js default\nlist. A patch that writes only the AI crawlers drops Googlebot, Bingbot, Applebot,\nTwitterbot, LinkedInBot, Slackbot, Discordbot, and facebookexternalhit from\nHTML-limited treatment, which trades a live SEO and social-preview regression for a\nGEO gain. `doctor --fix` performs the union correctly and widens rather than\nreplaces, preserving entries the user added. If you ever edit it by hand: the type\nis `RegExp` and a string fails config validation at startup, it is a top-level key\nrather than an `experimental` one, and `/.*/` is never the answer because it\ndisables streaming metadata for every human visitor.\n\n**`doctor --fix` leaves `htmlLimitedBots` byte for byte alone when it cannot read\nthe current value as a literal.** That is deliberate, and it means a computed value\nneeds your eyes. Widen it by hand, never replace it.\n\n**Never write `CLAUDE.md`.** Next.js generates it containing `@AGENTS.md`, which\nalready imports everything in `AGENTS.md`. Writing there duplicates the block into\ncontext twice, and `next dev` may rewrite the file underneath you. If\n`agentRules: false` is set in `next.config.ts`, Next.js writes neither file, so our\nblock is the only agent instruction in the project. Say so to the user rather than\nassuming Next.js has their back.\n\n### 3. Fill `agentblog.config.ts` with real values\n\nThe template ships with placeholders, and `doctor` reports them rather than\ninventing replacements. The config must call `defineConfig(...)`, not export a bare\nobject and not use `satisfies`, because `defineConfig` enforces the cross-field\nrequirements the type alone cannot express.\n\nAsk the user for anything you cannot determine from the repository. Do not guess a\nsite URL from `package.json` and do not invent a brand name.\n\n| Field           | Notes                                                                                                                                                          |\n| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `siteUrl`       | Absolute https URL, bare origin, no trailing slash, no query, no fragment. Anchors every canonical, every `@id`, and the sitemap.                              |\n| `brand.name`    | The publisher name. Appears in `Organization`, `WebSite`, and the title template.                                                                              |\n| `brand.logo`    | `url`, `width`, and `height`. All three. A logo without dimensions is an incomplete `ImageObject`.                                                             |\n| `brand.sameAs`  | Absolute profile URLs, never handles. LinkedIn, Crunchbase, YouTube, Wikidata where they genuinely exist. Leave the array empty rather than inventing entries. |\n| `source`        | The content adapter. `mdxSource({ dir: 'content/blog' })` for the default filesystem install.                                                                  |\n| `deployHook`    | Required when the adapter's `prerenderStrategy` is `'deploy-hook'`. Without it, publishing without a rebuild silently serves stale content.                    |\n| `defaultAuthor` | A slug that exists in `content/authors.json`. Set it in the same change as step 4.                                                                             |\n\nEverything else is defaulted. Do not restate a default in the config file just to\nmake it visible. That is how a default silently becomes a pin.\n\n## Phase 2: make the blog theirs\n\nPhase 1 produced a correct install. Everything in it would pass `doctor` while the\nsite published a placeholder byline linking to `example.com`. This phase is the one\nnothing can automate, and it is where the entity signals come from.\n\nInterview the user. Ask for what you cannot read out of the repository, in one\nround rather than one question at a time: who writes here, what they are credible\non, which profile URLs are real, and what the blog is about.\n\n### 4. Write the real author record\n\n`content/authors.json` ships one record with slug `editorial` and placeholder\nvalues. `agentblog.config.ts` points `defaultAuthor` at it and both seed posts name\nit, so **keep the slug or change it in all three places in one commit**. `doctor`\nreports `seed-authors-unedited` until the values change.\n\nThis record is a ranking surface rather than metadata. The Search Quality Rater\nGuidelines direct raters to look authors up, and an engine resolving \"who wrote\nthis\" reads these fields together.\n\n- `name`: the person's name and nothing else. No job title, no honorific, no\n  publisher name. Google's Article guidance is explicit, and `jobTitle` exists so\n  the correct shape is the only constructible one.\n- `bio`: two or three sentences on why this person is credible on these topics.\n  Specific experience, not adjectives.\n- `jobTitle`, `worksFor`, `alumniOf`: fill what is true, omit what is not.\n- `knowsAbout`: the topics this author is genuinely credible on. These become\n  `Person.knowsAbout` and should overlap the taxonomy in step 5.\n- `sameAs`: absolute profile URLs. This is the single strongest entity signal in\n  the whole graph, and a handle disambiguates nothing. **Ask the user for these.\n  Never invent one, and never leave an `example.com` placeholder in place.** An\n  empty array is better than a wrong URL.\n\nDelete the `guest-author` record unless the user wants it. It exists only to show\nthe shape of a roster with more than one person in it, and no seed post names it.\n\n### 5. Replace the taxonomy with the user's topics\n\n`content/categories.json` ships four categories that are AgentBlog's own subject\nmatter. Two of them are load-bearing while the seed posts are present: `ai-search`\nand `content-strategy` are named in seed post frontmatter, and removing either\nbefore the post that references it fails the next build with `unknown category\nslug`. Do step 6 first, or do both in one commit.\n\nAim for five to ten fixed categories. Each one is an indexable hub page, and a hub\nwith two posts on it is a crawl liability rather than an asset. Fewer real\ncategories beats more aspirational ones.\n\nEvery category needs a real `description`, because the hub page is indexable and\nthe schema rejects an empty one. Two sentences saying what belongs in the category\nand what does not.\n\n### 6. Decide what happens to the seed posts\n\n`content/blog/` holds two posts about how AI search engines read a blog. They are\ngood posts and they are not this user's posts. Put the decision to the user with a\nrecommendation rather than deleting content on your own initiative:\n\n- **Delete them** if the blog is about something else, which is the usual case.\n  Then remove the categories they pinned, in the same commit.\n- **Keep them** if the blog is about search, AI, or web performance, and rewrite\n  the byline and internal links to match the new identity.\n- **Keep them unpublished** by setting `draft: true`, if the user wants the format\n  reference without the URLs. They stay out of every query, the sitemap, and the\n  feed.\n\nWhichever way it goes, the seed posts are the format specification for everything\n`write-blog-post` produces afterwards. If they are deleted, say so, because the\nnext post has no house example to read.\n\n## 7. Verify, do not assert\n\n```bash\nnpx agentblog doctor --verbose\n```\n\nReport its output. If findings remain, fix them or explain why each one is\nintentional.\n\nThen, if the site is deployed, run the live check. It is the only one that tests\nwhat a crawler actually receives:\n\n```bash\nnpx agentblog doctor --url https://example.com\n```\n\nThat probes the site as GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot, and\nGooglebot, and detects a CDN sitting in front. **Run it from your own machine or\nfrom CI, never from inside the deployment**, because a request originating inside\nthe network can bypass the CDN rule the check exists to find.\n\nA 403, a 429, or a challenge page there means a CDN is blocking AI crawlers\nregardless of what `robots.txt` says. That is the single most common cause of a\ncorrectly installed blog getting no citations, and it is a blocking failure. Name\nthe CDN in the report.\n\n`Googlebot` is in that list for a reason worth passing on: Cloudflare classifies\nmulti-purpose crawlers by their broadest use, and Googlebot crawls for both Search\nand AI training with one bot. Ticking a setting that reads as \"do not train on my\ncontent\" can therefore remove the site from Google entirely.\n\n**Do not report setup as complete while `doctor` reports an error, or while any\nauthor, category, or config field still holds a placeholder.** List what failed and\nwhat it would take to fix.\n\nWhen it is genuinely done, tell the user the next step is `plan-blog-content` if\nthey have no editorial plan, and `write-blog-post` if they do.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/agentblog-setup/SKILL.md"
    },
    {
      "path": "registry/agent/skills/dataforseo-research/SKILL.md",
      "content": "---\nname: dataforseo-research\ndescription: >\n  Runs keyword, competitor, SERP, and AI citation research through DataForSEO, and\n  keeps it. Reads the research catalog in content/research/ before spending\n  anything: with no catalog it establishes a baseline of what the site ranks for,\n  who owns the answers, and which queries are worth a post; with a catalog it\n  re-asks the same questions, diffs against the stored snapshots, and reports what\n  moved. Produces clusters built from SERP overlap, striking-distance wins,\n  competitor page gaps, and a citation baseline, written to disk so the next run\n  compares rather than repeats. Use when asked to research keywords or topics,\n  find what to write about next, size an opportunity, check what a site ranks for,\n  measure AI, LLM, or AI Overview visibility, analyse competitors, or put real\n  numbers under a content plan.\nargument-hint: '[topic, domain, or question]'\nallowed-tools: Read Write Edit Glob Grep WebFetch Bash(curl *) Bash(npx agentblog *) Bash(git check-ignore *) Bash(claude mcp list)\nlicense: MIT\ncompatibility: A Next.js project with AgentBlog installed, plus a DataForSEO account. Works over the DataForSEO MCP server or plain REST.\nmetadata:\n  package: agentblog\n  homepage: https://agentblog.dev\n---\n\n# Research the blog, and keep the research\n\nEvery other AgentBlog skill decides something. This one is the evidence those\ndecisions stand on, and it is the only skill that leaves durable state behind.\n\nThat state is the point. A research run that answers a question and evaporates is\na run the user pays for again next month, against a different sample, with no way\nto tell a real change from a different question. A run that writes itself down\nturns the second run into a diff, which is cheaper, faster, and the only thing\nthat can say whether the writing is working.\n\nSo the first move is never a query. **It is to look at `content/research/` and\nfind out what this project already knows.** That costs nothing, it decides\neverything after it, and skipping it is how an agent bills a user for the answer\nthey already have on disk.\n\n## The money rule\n\n**Never make a billable call before printing an estimate and getting the user to\napprove it.** DataForSEO is prepaid and real. A loop that expands a seed at depth\n4 and then reads a SERP per row can spend a hundred dollars in one turn while\nlooking exactly like a run that spent forty cents.\n\nThree things are free and none of them need approval: reading `content/research/`,\n`GET /v3/appendix/user_data`, and any call sent to the sandbox host. Do all of\nthem first. Everything else waits for a yes.\n\n```\n- [ ] 1. Read the catalog before touching the API\n- [ ] 2. Reach a working call\n- [ ] 3. Decide which run this is, price it, get a yes\n- [ ] 4. Baseline run, or\n- [ ] 5. Delta run, or targeted run\n- [ ] 6. Turn rows into decisions\n- [ ] 7. Write the catalog back\n- [ ] 8. Report, and hand off\n```\n\nReference material, all one level down and all optional until you need it:\n\n- **Access, credentials, MCP against REST, failure codes**: see\n  [references/setup.md](references/setup.md).\n- **Which endpoint answers which question, and what it costs**: see\n  [references/endpoints.md](references/endpoints.md).\n- **How to read the rows as editorial decisions**: see\n  [references/playbook.md](references/playbook.md).\n- **The on-disk catalog format and the comparison protocol**: see\n  [references/catalog.md](references/catalog.md).\n\n### 1. Read the catalog before touching the API\n\nGlob `content/research/`. Then read, in this order, whatever exists:\n\n- `content/research/ledger.md`, the append-only index of every run.\n- `content/research/baseline.md`, the current standing answers.\n- The filenames in `content/research/snapshots/`, which tell you what was\n  measured and when without reading any of them.\n\nRead the newest snapshot only for the question you are about to ask. The others\nstay on disk costing nothing.\n\nAlso read what the research is for, because research nobody can act on is not\nworth buying: `agentblog.config.ts` for the site URL and brand, `content/authors.json`\nfor what this roster can credibly write, `content/categories.json` for the current\ntaxonomy, `content/editorial-plan.md` if `plan-blog-content` has run, and the\nposts in `content/blog/`.\n\nThen say out loud which of the three states you are in, because the rest of the\nrun differs:\n\n| On disk                                          | State                                 | Go to                 |\n| ------------------------------------------------ | ------------------------------------- | --------------------- |\n| No `content/research/`                           | First contact. Nothing is known       | Step 4                |\n| A ledger with runs in it                         | There is a history to compare against | Step 5                |\n| A ledger, and the user asked one narrow question | Targeted                              | Step 5, narrow branch |\n\n### 2. Reach a working call\n\nClimb this ladder and stop at the first rung that works. Do not install anything\nwithout asking.\n\n1. **MCP tools already in the session.** List them and match on the distinctive\n   part of the endpoint path (`ranked_keywords`, `keyword_ideas`, `search_mentions`).\n   Never hardcode an MCP tool name: they are not stable, and several currently\n   point at paths DataForSEO has renamed.\n2. **`DATAFORSEO_USERNAME` and `DATAFORSEO_PASSWORD` in the environment**, or in\n   `.env.local`. Use REST.\n3. **Neither.** Stop. Give the user the registration and credentials steps from\n   [references/setup.md](references/setup.md) and offer to configure the MCP\n   server, which needs a session restart and is therefore their call.\n\nThen prove the credentials work before believing anything:\n\n```bash\nset -a; [ -f .env.local ] && . ./.env.local; set +a\ncurl -s -u \"$DATAFORSEO_USERNAME:$DATAFORSEO_PASSWORD\" \\\n  \"https://api.dataforseo.com/v3/appendix/user_data\"\n```\n\nFree, and it returns three things the run needs: `money.balance`, so you know\nwhether the plan can finish; the account's real `price` map, which differs by\nplan and beats every published figure; and whether an LLM Mentions subscription\nexists at all, which decides whether the AI citation half of this skill is\navailable.\n\n**A connected MCP server is not an authenticated one.** It builds a valid header\nout of two empty strings and reports itself connected, then returns 401 on every\ncall. `references/setup.md` section 3 has the reason and the fix.\n\n### 3. Decide which run this is, price it, get a yes\n\nWrite the plan as a table before spending: each call, why it is in the run, the\nrow limit, and the cost from the account's own price map. Total it. Show the\nbalance next to the total.\n\nThen cut it. A first baseline for one blog is well under a dollar when the AI\ncitation section is aggregates only, and several dollars the moment\n`search_mentions` runs at full limit. Most of the value is in the cheap half.\n\nTwo habits that keep the estimate honest:\n\n- **Batch everything that batches.** `bulk_keyword_difficulty` and `search_intent`\n  take 1,000 keywords per call. `keyword_overview` takes 700, not 1,000. Sending\n  200 keywords one at a time costs 200 times what one call costs and returns the\n  same rows.\n- **Tag every call with the run date**, so the response can be traced back to the\n  question later. `tag` is echoed back and costs nothing.\n\nIf the balance cannot cover the plan, say so and propose the shorter plan\nexplicitly. Do not quietly run a smaller version and present it as the whole\nthing: a report missing its AI citation section reads exactly like a site with no\nAI citations.\n\n### 4. Baseline run\n\nThe order matters, because each step narrows the next one and the cheapest\nfindings come first.\n\n**4a. Harvest before you hunt.** `ranked_keywords` on the user's own domain, then\n`domain_rank_overview` for the distribution. This is routinely the most surprising\noutput of a first run, because a blog usually ranks for queries nobody targeted.\nPositions 4 to 20 on a query the site already half-answers beat a new post on a\nquery it does not answer at all, and they cost a refresh rather than an article.\n\n**4b. Find out who the competitors actually are.** `competitors_domain` on the\ndomain. The sites competing for the queries are usually not the businesses\ncompeting for the customers, and assuming otherwise is how a research run studies\nthe wrong sites carefully. Take the top three by keyword overlap, then `relevant_pages`\non each to see which of their posts carry the traffic. Those pages are the real\nbrief.\n\n**4c. Expand, once, deliberately.** `keyword_ideas` on two or three seeds per\nsubject when you do not yet have the vocabulary, `keyword_suggestions` on the head\nterms when you do, `related_keywords` at **depth 2** when you want phrasing you\nwould not have guessed. Depth 3 and 4 return 584 and 4,680 rows and are how a\nresearch run becomes a spreadsheet nobody opens.\n\n**4d. Qualify in bulk.** Push every candidate through\n`bulk_keyword_difficulty` and `search_intent` in batched calls. Cheapest\ninstruments in the API per keyword. Drop everything the site cannot plausibly\nrank for and everything whose intent wants a page this blog is not.\n\n**4e. Read the SERPs of the finalists.** Ten to twenty queries, one\n`serp/google/organic/live/advanced` each, with **`load_async_ai_overview: true`**\nand `people_also_ask_click_depth: 2`.\n\nThis one call does four jobs: it shows whether an AI Overview fires, it shows who\nholds the page, it gives you the People Also Ask phrasing that becomes question\nheadings, and its top-10 URL sets are what you cluster on in step 6.\n\n`load_async_ai_overview` defaults to `false`, and at the default you get AI\nOverview items from cache only. A run that leaves it alone reports that AI\nOverviews are rare for these queries, which is a statement about DataForSEO's\ncache and not about Google.\n\n**4f. Take an AI citation baseline, aggregates only.** `top_mentioned_domains` for\nthe subject, and `target_metrics` for the site. Skip `search_mentions` on a first\nrun unless the user asks for the underlying prompts and accepts the price.\n\nRecord the exact prompt set, targets, platform, and date. Everything this section\nis worth later depends on the next run asking the identical question.\n\n### 5. Delta run, or targeted run\n\n**The cheapest useful run is a diff, not a re-collection.** Something is already\non disk. Re-ask only what can have changed, and read the rest.\n\nRe-measure: `ranked_keywords` on the domain, and the AI citation aggregates\nagainst the same targets, platform, and prompt set as last time. Both move.\n\nDo not re-measure: keyword expansion, difficulty, and intent. Those move slowly,\nthey are on disk, and re-buying them produces a diff full of rounding.\n\nThen compare against the stored snapshot and report the four movements that\nmatter. Each one hands off somewhere different, which is why they are worth\nseparating rather than reporting as churn:\n\n| Movement                                         | What it means                    | Hand to                             |\n| ------------------------------------------------ | -------------------------------- | ----------------------------------- |\n| A post fell several positions and did not change | Decay, or somebody else improved | `refresh-blog-post`                 |\n| A query newly ranks at 4 to 20                   | Striking distance, unplanned     | `refresh-blog-post`                 |\n| Two of our URLs rank for one query               | Cannibalisation                  | Merge, or differentiate the targets |\n| A competitor page appeared where we were         | A specific page to beat          | `plan-blog-content`                 |\n\n**Targeted branch.** When the user asked one narrow question, answer that\nquestion and nothing else. Check the catalog first: if a snapshot from the last\nfew weeks already answers it, say so, quote it, and ask whether it is worth\nre-buying. Then append the run to the ledger anyway, because a targeted answer is\nstill research and the next run should know it happened.\n\n### 6. Turn rows into decisions\n\nRows are not a finding. [references/playbook.md](references/playbook.md) has the\nreasoning and the honest limits. These five decide most runs, and they are here\nrather than in the reference file because a rule you have to fetch is a rule you\nwill skip.\n\n- **Cluster on SERP overlap, not on wording.** Two queries whose top ten share\n  three or more URLs are one post, because Google has already decided they are\n  one information need. Writing both is how a site competes with itself. Zero or\n  one shared URL means two posts.\n- **Intent decides the format before volume decides anything.** An informational\n  query the roster can answer completely is worth more to this blog than a\n  transactional query with ten times the volume, because the transactional SERP\n  wants a product page and will not give the slot to a post.\n- **Read the SERP, not the difficulty score.** A page of forum threads is an\n  opening. A page of documentation from the vendor whose product the query names\n  is not, at any difficulty score.\n- **An AI Overview changes the target, not the decision.** Its presence means the\n  click is going to be harder to win and the citation is the prize, which is the\n  format `write-blog-post` already produces. Absence is not a reason to skip a\n  query the site should own.\n- **One AI citation measurement is not a fact.** These models are\n  non-deterministic, so a single reading is a sample. Report the baseline as a\n  sample with its date and prompt set attached, and never report a change from\n  one measurement to one other measurement as a trend.\n\nThen rank what survives by what the roster can credibly write, then by what\ncompletes a hub too thin to index, and put raw volume last. That order comes from\n`plan-blog-content` and this skill feeds it, so contradicting it here would just\nproduce a plan that gets reordered.\n\n### 7. Write the catalog back\n\n[references/catalog.md](references/catalog.md) has the exact file shapes. The\nthree rules that matter:\n\n- **Snapshots are immutable.** Date-prefixed, never edited, never deleted. A\n  rewritten snapshot destroys the only baseline the next run had.\n- **The ledger is append-only**, one row per run, with the cost actually spent.\n- **`baseline.md` is rewritten every run**, and git holds the previous version,\n  which is what makes the diff reviewable by a person.\n\nStore the request alongside the response. A snapshot without the exact body that\nproduced it cannot be re-asked identically, and a comparison between two\ndifferent questions is worse than no comparison, because it looks like a result.\n\n`content/research/` sits outside `content/blog/`, so the content adapter never\nreads it and none of it can become a published page by accident.\n\n### 8. Report, and hand off\n\nReport in this shape:\n\n1. **What was already known**, from the catalog, and what this run added.\n2. **What moved**, on a delta run, with the previous value beside the new one.\n3. **The decisions**, as a short ranked list, each with the row that supports it.\n4. **What was spent**, against the estimate, and the balance now.\n5. **What is missing and why**, naming any section that a degraded state removed.\n\nThen hand off by name rather than continuing:\n\n- Clusters and priorities go to `plan-blog-content`, which turns them into\n  `content/editorial-plan.md` with the link graph settled.\n- Decayed and striking-distance posts go to `refresh-blog-post`.\n- New posts go to `write-blog-post`, carrying the People Also Ask phrasing as the\n  headings and the cited sources already found.\n\n**What this cannot tell you.** DataForSEO measures the SERP and the answer, not\nthe cause. Nothing here establishes that a change in the writing produced a change\nin the numbers, and the strongest published correlates of AI visibility are\noff-site anyway. A research run that reports a rank movement as the result of last\nmonth's posts has invented a causal claim out of two measurements, which is\nexactly the kind of unsupported number `agentblog audit` exists to catch in the\nposts themselves. Report what was observed, and say what is unexplained.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/dataforseo-research/SKILL.md"
    },
    {
      "path": "registry/agent/skills/dataforseo-research/references/setup.md",
      "content": "# Getting access to DataForSEO\n\nReference material for `dataforseo-research`. Read it when the access ladder in\nSKILL.md step 2 does not reach a working call, or when a call starts failing and\nyou need to work out which layer broke.\n\n> **License.** This file is prose documentation, licensed CC BY 4.0. See\n> `LICENSE-CONTENT` in the AgentBlog repository.\n\n## Contents\n\n1. The two access paths, and which to prefer\n2. Getting credentials\n3. Where the credentials live, and the trap\n4. Path A: the MCP server\n5. Path B: REST with curl\n6. Verifying without spending anything\n7. Reading a failure\n8. Degraded modes, and what to do in each\n\n---\n\n## 1. The two access paths, and which to prefer\n\nDataForSEO is one HTTP API. There are two ways to reach it, and they cost the\nsame because the MCP server is a pass-through to the same account.\n\n|                    | MCP server                                | REST with curl               |\n| ------------------ | ----------------------------------------- | ---------------------------- |\n| Setup              | One config file, then restart the session | None beyond credentials      |\n| Discovery          | Tools appear with typed parameters        | You supply the path and body |\n| Response size      | Trimmed by default, see section 4         | Trimmed only if you ask      |\n| Endpoint coverage  | 90 tools, some on stale paths             | Every documented endpoint    |\n| Failure visibility | Errors arrive as text, not tool failures  | Status code is in the body   |\n\n**Prefer MCP when it is already configured. Prefer REST when it is not.**\nConfiguring an MCP server requires a session restart to take effect, so a skill\nthat stops to install one has ended the run. REST works in the same turn.\n\nNever set up the MCP server without asking. It writes to the user's Claude Code\nconfiguration, which is theirs.\n\n## 2. Getting credentials\n\nRegistration is at https://app.dataforseo.com/register and the credentials are on\nthe API Access tab at https://app.dataforseo.com/api-access.\n\n**The API password is generated by DataForSEO and is not the account password.**\nA user who types their login password into the config gets a server that connects\nand then returns 401 on every call, which is the most common setup failure.\n\nNew accounts carry $1 of credit, which is real money and enough for a first\nbaseline run if you spend it deliberately. The minimum top-up after that is $50.\nEmail or phone verification has to be completed first, or every call returns\nstatus `40104`.\n\nDo not create a second account to get another $1. DataForSEO treats it as a terms\nviolation and suspends both, reported as status `40201`.\n\n## 3. Where the credentials live, and the trap\n\nThese are secrets. The rule is the one AgentBlog already applies to\n`INDEXNOW_KEY` and `AGENTBLOG_REVALIDATE_SECRET`: they belong in a file git does\nnot track.\n\n**The trap.** Claude Code expands `${VAR}` in `.mcp.json` from the shell\nenvironment of the process that launched it. It does not read `.env.local`, and\nAgentBlog puts secrets in `.env.local`. So the natural move, putting the\ncredentials where every other AgentBlog secret lives and referencing them from\n`.mcp.json`, produces a server that reports itself connected and fails\nevery call with a 401.\n\nThe MCP server never validates credentials at startup. It builds a syntactically\nvalid Basic header out of two empty strings, so the process starts cleanly and\n`claude mcp list` says the server is connected. Connected does not mean\nauthenticated, and nothing tells you which one you have until a call fails.\n\nTwo arrangements work. Say which one you are using rather than assuming.\n\n- **Shell export**, for the MCP path. The user exports both variables in the\n  shell profile, then starts Claude Code from that shell. `.mcp.json` refers to\n  them as `${DATAFORSEO_USERNAME}` and `${DATAFORSEO_PASSWORD}`, so the file\n  itself holds no secret and is safe to commit.\n- **`.env.local`**, for the REST path. `curl` reads it because you source it in\n  the same command. This is the arrangement that matches the rest of AgentBlog,\n  and it is the reason the REST path is worth keeping even after MCP works.\n\nCheck `git check-ignore .env.local` before writing anything into it. If git\ntracks it, stop and say so. A committed API password is a bill somebody else can\nrun up.\n\n## 4. Path A: the MCP server\n\nThe package is `dataforseo-mcp-server` on npm. It requires **Node 20 or newer**,\nwhich contradicts both its own README and the DataForSEO landing page. On Node 18\nit installs and then fails at runtime.\n\nProject scope, credentials by reference, pinned version:\n\n```json\n{\n  \"mcpServers\": {\n    \"dataforseo\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"dataforseo-mcp-server@2.9.11\"],\n      \"env\": {\n        \"DATAFORSEO_USERNAME\": \"${DATAFORSEO_USERNAME}\",\n        \"DATAFORSEO_PASSWORD\": \"${DATAFORSEO_PASSWORD}\",\n        \"ENABLED_MODULES\": \"DATAFORSEO_LABS,SERP,AI_OPTIMIZATION,ONPAGE\"\n      }\n    }\n  }\n}\n```\n\nFour things in that block are load-bearing.\n\n- **`ENABLED_MODULES` is not optional in practice.** Left unset it loads all ten\n  modules and 90 tools into the session. The four above are what this skill uses.\n  The full set is `AI_OPTIMIZATION`, `SERP`, `KEYWORDS_DATA`, `ONPAGE`,\n  `DATAFORSEO_LABS`, `BACKLINKS`, `BUSINESS_DATA`, `DOMAIN_ANALYTICS`,\n  `CONTENT_ANALYSIS`, `MERCHANT`. A name outside that list is fatal rather than\n  ignored: the server throws at startup and presents as a failed connection with\n  no useful message.\n- **The version is pinned.** `npx -y dataforseo-mcp-server` floats to whatever is\n  latest at launch, so the tool surface can change between sessions.\n- **The credentials are references.** See section 3.\n- **`type` is `stdio`.** The hosted server at `https://mcp.dataforseo.com/mcp` is\n  the alternative, taking `Authorization: Basic` as a header. Both `/mcp` and\n  `/http` are served, and DataForSEO's own pages disagree about which to use.\n\nDo not tell a user to run `claude test-mcp`. DataForSEO's help centre recommends\nit and the command does not exist. `claude mcp list` is the real one.\n\n**Response trimming.** The server appends `.ai` to every endpoint path unless\n`DATAFORSEO_FULL_RESPONSE=true`. That is a DataForSEO server-side feature: it\nstrips empty fields, drops `position` and `xpath`, rounds floats, and **defaults\n`depth` and `limit` to 10**. It costs the same as the untrimmed response. Leave\nit on. If a field you need is missing, that is the first thing to suspect.\n\n**Five LLM Mentions tools are on stale paths.** At 2.9.11 the server calls\n`/llm_mentions/search/live`, `/aggregated_metrics/live`,\n`/cross_aggregated_metrics/live`, `/top_domains/live`, and `/top_pages/live`. The\ndocumented paths are `/search_mentions/live`, `/target_metrics/live`,\n`/multi_target_metrics/live`, `/top_mentioned_domains/live`, and\n`/top_mentioned_pages/live`. Whether DataForSEO still aliases the old names could\nnot be established from outside. If those tools return a not-found error, use\nREST with the documented paths in `references/endpoints.md`.\n\n## 5. Path B: REST with curl\n\nBasic auth is the only mechanism. There is no token exchange and no API key\nheader.\n\n```bash\nset -a; [ -f .env.local ] && . ./.env.local; set +a\n\ncurl -s -X POST \"https://api.dataforseo.com/v3/dataforseo_labs/google/bulk_keyword_difficulty/live\" \\\n  -u \"$DATAFORSEO_USERNAME:$DATAFORSEO_PASSWORD\" \\\n  -H 'Content-Type: application/json' \\\n  -d '[{\"keywords\":[\"headless cms\"],\"location_code\":2840,\"language_code\":\"en\"}]'\n```\n\nThree shapes to get right, each of which fails loudly the first time and quietly\nlater:\n\n- **The body is always an array**, even for one task. A bare object returns\n  `40503`.\n- **Live endpoints take exactly one task per call** and return `40000` for more.\n  Task-based endpoints take up to 100 and return `40006` past that.\n- **Unknown fields are rejected**, not ignored, with `40506`. Do not send extra\n  keys defensively.\n\nAppend `.ai` to the path to get the same trimmed response the MCP server gets, at\nthe same price.\n\n## 6. Verifying without spending anything\n\nTwo free instruments, and both should run before the first billable call.\n\n**The account probe.** `GET /v3/appendix/user_data` is free and returns the\naccount's live balance, its rate limits, and its actual price list per endpoint.\n\n```bash\ncurl -s -u \"$DATAFORSEO_USERNAME:$DATAFORSEO_PASSWORD\" \\\n  \"https://api.dataforseo.com/v3/appendix/user_data\"\n```\n\nRead three things out of it: `money.balance`, so you know whether the run can\nfinish; the `price` map, so cost estimates use the account's real prices rather\nthan the published ones; and `llm_mentions_subscription_expiry_date`, which tells\nyou whether the AI citation half of this skill is available at all.\n\n**The sandbox.** Swapping the host to `https://sandbox.dataforseo.com` runs any\ncall for free against dummy data with the identical response shape. Use it to\ncheck that a request body is well formed before paying for the real one. The MCP\nserver cannot reach it, because the base URL is hardcoded with no override, so\nsandbox verification is a REST-only move.\n\n## 7. Reading a failure\n\nDataForSEO puts `status_code` at two levels, and **the top-level one being\n`20000` does not mean the task succeeded**. Check `tasks_error`, then each\n`tasks[i].status_code`.\n\nThrough the MCP server this gets worse: a failed call is returned as a text block\nbeginning `Error:` rather than as a tool failure, so an agent that only checks\nwhether the tool call threw will read the error as data and report a finding\nbased on nothing.\n\n| Code                      | Meaning                           | Action                                         |\n| ------------------------- | --------------------------------- | ---------------------------------------------- |\n| `20000`                   | Success                           | Continue                                       |\n| `40100`                   | Not authorised                    | Credentials wrong or unexpanded. Section 3     |\n| `40104`                   | Account not verified              | User completes email or phone verification     |\n| `40102`                   | No search results                 | Not an error. The query has no data            |\n| `40200`, `40210`          | Balance empty, insufficient funds | Stop. Do not retry                             |\n| `40203`                   | Cost limit hit                    | Stop. The user set this in the dashboard       |\n| `40204`                   | Not entitled                      | Subscription required. Record it, do not retry |\n| `40202`                   | Over 2,000 calls per minute       | Back off                                       |\n| `40209`                   | Over 30 concurrent requests       | Back off. This one fires first                 |\n| `40501`, `40503`, `40506` | Bad request body                  | Your bug. Fix it, do not retry                 |\n| `40505`                   | Stale location code               | Refetch the location list for that API         |\n| `50401`                   | Live task passed 120 seconds      | Retry once, then narrow the request            |\n\nRetry `40103`, `50000`, `50301`, `50303`, `50401`, `50402`. Never retry a `405xx`\nor a funds error: the first is your request and the second needs a human.\n\n## 8. Degraded modes, and what to do in each\n\nEach of these is a state where part of this skill works and part does not. Name\nthe state in the report. **Do not silently fall back to a smaller run and present\nit as a complete one.**\n\n| State                        | Detection                                     | What still works                                                            |\n| ---------------------------- | --------------------------------------------- | --------------------------------------------------------------------------- |\n| No credentials anywhere      | The SKILL.md step 2 ladder reaches nothing    | Nothing. Stop and give the user section 2                                   |\n| Credentials, no MCP server   | Env vars set, no matching tools               | All of it, over REST                                                        |\n| MCP connected but 401        | Tools exist, every call returns 401           | Switch to REST and tell the user their expansion is broken                  |\n| No LLM Mentions subscription | `40204`, or the expiry date is absent or past | Everything except AI citation measurement. Say which sections are missing   |\n| Balance too low for the plan | `money.balance` below the estimate            | Narrow to the highest-value calls, get the user to approve the shorter plan |\n| Balance empty                | `40200` or `40210`                            | Nothing billable. The free probes still answer                              |\n\nWhen a state removes a section, the run report says which section is missing and\nwhy. A research report that quietly omits the AI citation half reads exactly like\none where the site has no AI citations.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/dataforseo-research/references/setup.md"
    },
    {
      "path": "registry/agent/skills/dataforseo-research/references/endpoints.md",
      "content": "# The endpoint cookbook\n\nReference material for `dataforseo-research`. Read it when you are choosing a\ncall, and before every call that costs more than a cent.\n\n> **License.** This file is prose documentation, licensed CC BY 4.0. See\n> `LICENSE-CONTENT` in the AgentBlog repository. Prices and parameters are\n> DataForSEO's and are quoted from https://docs.dataforseo.com/v3/ as read in\n> August 2026. Verify them against the account's own price list before spending.\n\n## Contents\n\n1. How to call these, whether over MCP or REST\n2. Shared parameters, and the two that are billed\n3. Finding candidate queries\n4. Qualifying them\n5. Competitors, and the gap\n6. What the site already ranks for\n7. AI Overviews in the SERP\n8. Are we cited in AI answers\n9. Reading our own pages\n10. The price list\n11. Traps that cost money quietly\n\n---\n\n## 1. How to call these, whether over MCP or REST\n\n**Do not hardcode MCP tool names.** They are not stable, and at least five of\nthem currently point at endpoint paths DataForSEO has renamed. List the tools\navailable in the session, match on the distinctive part of the endpoint path\n(`keyword_ideas`, `ranked_keywords`, `search_mentions`), and use what is\nactually there.\n\nThe REST paths below are the contract. They are read from DataForSEO's own\nmachine-readable index at https://docs.dataforseo.com/v3/llms.txt and they are\nwhat the MCP tools are wrappers over. When an MCP tool disagrees with a path\nhere, the path here is the one that is documented.\n\nEvery path is prefixed `https://api.dataforseo.com/v3/`. Every POST body is a\nJSON array of task objects. Append `.ai` to any path for the trimmed response.\n\n## 2. Shared parameters, and the two that are billed\n\n| Parameter       | Notes                                                                    |\n| --------------- | ------------------------------------------------------------------------ |\n| `location_code` | Integer. United States is `2840`. Each API family has its own list       |\n| `language_code` | `en`. Pair it with the location, never omit it                           |\n| `limit`         | Labs default 100, max 1000. The trimmed response defaults it to 10       |\n| `offset`        | Paging. LLM Mentions caps at 1000000, then use `search_after_token`      |\n| `filters`       | A nested array, not an object. Maximum 8 conditions                      |\n| `order_by`      | Array, maximum 3 rules, written as `\"field,desc\"`                        |\n| `tag`           | Your own label, echoed back. Use the run date so responses are traceable |\n\nFilters are nested arrays joined by string operators, which is the shape people\nget wrong most often:\n\n```json\n[[\"keyword_info.search_volume\", \">\", 50], \"and\", [\"keyword_properties.keyword_difficulty\", \"<\", 40]]\n```\n\nLook the legal field names up per endpoint at `/dataforseo_labs/available_filters`,\nwhich is free. Guessing a field name returns `40501` and wastes the call.\n\n**Two parameters change the price rather than the result.**\n`include_clickstream_data: true` doubles a Labs request. `depth` on a SERP call\nis billed per ten results and rounds up, so `depth: 11` costs what `depth: 20`\ncosts.\n\n## 3. Finding candidate queries\n\nThree Labs endpoints expand a seed, and they do different things. Picking the\nwrong one is the most common waste in a first run.\n\n| Endpoint                                          | Returns                                                               | Use it when                                                  |\n| ------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------ |\n| `dataforseo_labs/google/keyword_suggestions/live` | Long-tail queries **containing** the seed                             | You have the right head term and want its tail               |\n| `dataforseo_labs/google/related_keywords/live`    | The \"searches related to\" graph, expanded by `depth`                  | You want adjacent phrasing you would not have guessed        |\n| `dataforseo_labs/google/keyword_ideas/live`       | Keywords in the same **category** as the seeds, need not contain them | You are mapping a subject you do not yet have vocabulary for |\n\n`related_keywords` takes `depth` 0 to 4, returning roughly 1, 8, 72, 584, and\n4680 keywords. **Depth 2 is the working default.** Depth 3 and 4 are how a\nresearch run turns into a five-figure row count nobody reads.\n\nFor a blog, run `keyword_ideas` once per cluster on two or three seeds, then\n`keyword_suggestions` on the handful of terms that survive. Both cost\n$0.012 per call plus $0.00012 per row.\n\n## 4. Qualifying them\n\nTwo endpoints take up to 1,000 keywords in a single call, which makes them the\ncheapest per-keyword instruments in the whole API. Batch aggressively.\n\n- `dataforseo_labs/google/bulk_keyword_difficulty/live` returns difficulty 0 to\n  100 for up to 1,000 keywords.\n- `dataforseo_labs/google/search_intent/live` returns intent and a probability\n  for up to 1,000 keywords.\n\n`dataforseo_labs/google/keyword_overview/live` returns volume, CPC, competition,\nintent, and monthly series together, but it **caps at 700 keywords**, not 1,000.\nAssuming a uniform cap fails on exactly this endpoint.\n\nFor volume specifically, `keywords_data/google_ads/search_volume/live` is Google\nAds data at $0.09 per call for up to 1,000 keywords. That is cheaper per keyword\nthan anything in Labs when all you need is volume.\n\n**Intent is worth more than volume for a blog.** A 90-a-month informational query\nthat the roster can answer completely is worth more than a 5,000-a-month\ntransactional one that wants a product page.\n\n## 5. Competitors, and the gap\n\nStart by finding out who the actual competitors are rather than assuming. The\nsites competing for the queries are usually not the businesses competing for the\ncustomers.\n\n- `dataforseo_labs/google/competitors_domain/live` ranks domains by how much\n  their ranked keyword set overlaps ours.\n- `dataforseo_labs/google/serp_competitors/live` does the same for a specific\n  keyword set, which is the better instrument once clusters exist.\n\nThen find the gap:\n\n- `dataforseo_labs/google/domain_intersection/live` returns keywords where two\n  domains both rank. Invert it with filters to get what they rank for and we do\n  not, which is the content gap.\n- `dataforseo_labs/google/relevant_pages/live` returns a competitor's pages\n  ranked by traffic, which tells you which of their posts to study.\n- `dataforseo_labs/google/page_intersection/live` does the same comparison at URL\n  level rather than domain level. It is the one to reach for once you know which\n  of their posts holds the cluster, because it answers what that page ranks for\n  and ours does not, which is a brief. The domain-level version answers a question\n  no single post can act on.\n\n## 6. What the site already ranks for\n\n`dataforseo_labs/google/ranked_keywords/live` returns every keyword a domain,\nsubdomain, or single page ranks for, with positions and SERP features.\n\nRun this on the user's own domain in the first session. It is routinely the most\nsurprising output of a baseline run, because a blog usually ranks for a set of\nqueries nobody targeted, and those are the cheapest wins available: positions 4\nto 20 on a query the site already half-answers beat a new post on a query it does\nnot answer at all.\n\n`dataforseo_labs/google/domain_rank_overview/live` gives the distribution and\ntraffic estimate in one cheap call.\n\n**The historical variants cost ten times their siblings.**\n`historical_rank_overview`, `historical_bulk_traffic_estimation`, and\n`domain_metrics_by_categories` are $0.12 per call plus $0.0012 per row, against\n$0.012 plus $0.00012. Do not reach for them to answer a question the snapshot\nfiles in `content/research/snapshots/` already answer, because after the second\nrun this skill has its own history and does not need to buy DataForSEO's.\n\n## 7. AI Overviews in the SERP\n\n`serp/google/organic/live/advanced` returns `ai_overview` as one item type\nalongside `organic`, `featured_snippet`, and `people_also_ask`.\n\n**`load_async_ai_overview` defaults to `false`, and with the default you get AI\nOverview items from cache only.** Google loads these asynchronously, so the\ndefault silently under-reports how often an AI Overview appears. Set it to\n`true`. It adds $0.002, refunded when the element turns out not to be there.\n\nThis is the single most important parameter in this file. A run that leaves it\nalone produces a report saying AI Overviews are rare for these queries, which is\na statement about DataForSEO's cache rather than about Google.\n\n`people_also_ask_click_depth` from 1 to 4 expands the People Also Ask box into\nreal question phrasing at $0.00015 per click, refunded for clicks not performed.\nThat phrasing is the raw material for question-format headings, and it is the\ncheapest source of real user wording in the API.\n\nGoogle AI Mode has its own endpoint at `serp/google/ai_mode/live/advanced`, at\n$0.004 live. Its `keyword` accepts up to 700 characters, because the queries\npeople put into AI Mode are sentences.\n\n## 8. Are we cited in AI answers\n\nThis is the part of the API that measures the thing AgentBlog exists to improve.\nIt is also the most expensive per call and the least stable per measurement, so\nread section 11 and the playbook before spending here.\n\n| Endpoint                                                  | Returns                                       |\n| --------------------------------------------------------- | --------------------------------------------- |\n| `ai_optimization/llm_mentions/target_metrics/live`        | Citation metrics for one target, ours         |\n| `ai_optimization/llm_mentions/multi_target_metrics/live`  | The same for several targets at once          |\n| `ai_optimization/llm_mentions/top_mentioned_domains/live` | Who owns the answers in this subject          |\n| `ai_optimization/llm_mentions/top_mentioned_pages/live`   | Which individual pages get cited              |\n| `ai_optimization/llm_mentions/search_mentions/live`       | The underlying prompts and answers            |\n| `ai_optimization/llm_mentions/top_mentioned_brands/live`  | Which brands own the subject, ours among them |\n| `ai_optimization/llm_mentions/historical/live`            | DataForSEO's own series for a target          |\n| `ai_optimization/llm_mentions/timeseries_delta/live`      | Change over a period                          |\n| `ai_optimization/llm_mentions/timeseries_new_lost/live`   | What was gained and lost between two points   |\n\nThe last three are the exception to the rule that this skill buys its own history.\nOn a first run there is nothing in `content/research/snapshots/` to compare\nagainst, so DataForSEO's series is the only past available and is worth the call\nonce. From the second run on, the snapshots answer the same question for nothing,\nand the reason to keep buying these is a longer window than the catalog has yet,\nnot convenience.\n\n`top_mentioned_brands` is the honest version of the share-of-voice number people\nask for. Read it as the standings in a subject rather than as a score.\n\nEach has a `_lite` variant returning a simplified shape for less money. Prefer\nthe aggregate endpoints and the lite variants. `search_mentions` with `limit: 1000`\nis $1.10 for one call, because the pricing is $0.10 per request plus $0.001 per\nrow.\n\n**The field pair that decides whether the answer is right.** Each result carries\nboth `sources`, which the model actually cited, and `search_results`, which it\nretrieved and may never have used. Counting `search_results` overstates citation\ndramatically. `sources` is the number.\n\nTwo other fields are worth reading every time. `is_web_search_based` says whether\nthe model used live retrieval or answered from training, and a citation from\ntraining is not something this quarter's writing caused. `fan_out_queries` is the\nset of sub-queries the engine expanded the prompt into, which is the only\nobserved rather than guessed view of that expansion available here.\n\n**Constraints.** `target` takes up to 10 entities and at least one must be an\n`include`. `platform` is optional, and omitting it queries both ChatGPT and\nGoogle AI Overview, which changes the row count you are billed for. ChatGPT data\nis **United States and English only**.\n\n`ai_optimization/ai_keyword_data/keywords_search_volume/live` returns an\n`ai_search_volume` per keyword for up to 1,000 keywords at $0.01 plus $0.0001 per\nrow. Read DataForSEO's own note on it before quoting it: the values are\n\"calculated using statistical data from questions in the People Also Ask SERP\nelement\". It is a modelled proxy for prompt volume, not observed LLM traffic, and\npresenting it as the latter is the kind of claim `agentblog audit` exists to\ncatch elsewhere.\n\n## 9. Reading our own pages\n\n`on_page/content_parsing/live` returns a page's headings, links, and text as\nstructure. It answers whether the answer capsule is really the first thing under\nthe heading, and whether the H2s are really questions, against what the server\nsent rather than against the MDX source.\n\n`on_page/instant_pages` audits a single page with no crawl task at $0.00015.\n\nNeither replaces the raw `curl` with a bot user agent in the `agentblog-audit`\nskill. That check exists precisely because it has no tooling in the path.\n\n## 10. The price list\n\nPublished prices, August 2026. **Read the account's real ones from the free\n`/appendix/user_data` before estimating**, because they differ by plan.\n\n| Call                                      | Price                                          |\n| ----------------------------------------- | ---------------------------------------------- |\n| Labs, standard endpoints                  | $0.012 per call plus $0.00012 per row          |\n| Labs, historical variants                 | $0.12 per call plus $0.0012 per row            |\n| Google Ads search volume, live            | $0.09 per call, up to 1,000 keywords           |\n| SERP organic, task based, normal priority | $0.0006 per SERP                               |\n| SERP organic, live                        | $0.002 per SERP                                |\n| SERP organic, `load_async_ai_overview`    | plus $0.002, refunded if absent                |\n| People Also Ask, per click                | $0.00015                                       |\n| SERP AI Mode, live                        | $0.004                                         |\n| AI keyword search volume                  | $0.01 per call plus $0.0001 per row            |\n| LLM Mentions                              | $0.10 per call plus $0.001 per row             |\n| LLM Responses, live                       | $0.0006 plus the model provider's token charge |\n| OnPage, basic per page                    | $0.00015                                       |\n\nA first baseline run for one blog, done the way the playbook describes, costs\nwell under a dollar if the AI citation section is aggregates only. It costs\nseveral dollars if `search_mentions` is called at full limit. That difference is\nthe whole reason the cost gate exists.\n\n**Live costs about 3.3 times the task-based price for the same SERP data.** When\na run needs many SERPs and can wait, post the tasks and collect them. When it\nneeds one, pay for live.\n\n## 11. Traps that cost money quietly\n\nEach of these produces a plausible answer, so nothing looks wrong.\n\n- **`load_async_ai_overview` left at `false`.** Section 7. Reports cache as\n  reality.\n- **Counting `search_results` instead of `sources`.** Section 8. Inflates\n  citation.\n- **A search operator in a `keyword`.** `site:`, `intitle:`, `inurl:` and eleven\n  others multiply the SERP price by **five**, with no warning. Filter after the\n  call instead.\n- **`include_clickstream_data: true`.** Doubles a Labs request for data a blog\n  workflow rarely reads.\n- **`depth` above 10 on SERP calls.** Billed per ten and rounded up.\n- **The historical Labs endpoints.** Ten times the price of the snapshot you\n  already store.\n- **`limit: 1000` on LLM Mentions.** $1.10 per call.\n- **Reading only the top-level `status_code`.** It can be `20000` over a failed\n  task. Check `tasks_error` and each `tasks[i].status_code`.\n- **Treating one AI citation measurement as a fact.** The playbook covers why.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/dataforseo-research/references/endpoints.md"
    },
    {
      "path": "registry/agent/skills/dataforseo-research/references/playbook.md",
      "content": "# The research playbook\n\nReference material for `dataforseo-research`. Read it when you are deciding what\na set of rows means, when you are choosing between two queries that both look\nfine, or when a user asks why a recommendation is a recommendation and deserves a\nreal answer rather than an assertion.\n\n> **License.** This file is prose documentation, licensed CC BY 4.0. See\n> `LICENSE-CONTENT` in the AgentBlog repository. Figures quoted from third-party\n> research are attributed and remain those authors' work.\n\n> **Scope.** No endpoint paths, parameters, or prices live here. Those are in the\n> endpoint cookbook beside this file. This file is about what to conclude.\n\n## Contents\n\n1. What a research run is actually for\n2. The evidence, graded, including what is only convention\n3. Harvest before you hunt\n4. Clustering on SERP overlap\n5. Intent, and what a blog can win\n6. Reading a SERP as an opportunity\n7. The gap is a page-level question\n8. Measuring AI citation without lying to yourself\n9. Cadence, and what a comparison has to hold constant\n10. Anti-patterns, each of which produces a confident wrong answer\n\n---\n\n## 1. What a research run is actually for\n\nA blog gets traffic and citations for queries where three things are true at\nonce: somebody asks it, this roster can answer it better than what currently\nholds the page, and the answer belongs in a blog post rather than on some other\nkind of page.\n\nEvery instrument in this skill exists to test one of those three. Volume tests the\nfirst. Difficulty, the SERP itself, and the competitor's page test the second.\nIntent tests the third. A run that only measures volume has tested one third of\nthe question and will happily recommend a query the site cannot win with a format\nthat does not fit.\n\nThe output of a run is not a keyword list. It is a ranked set of decisions, each\nwith the row that supports it, and each pointing at a skill that acts on it.\n\n## 2. The evidence, graded, including what is only convention\n\nSay which of these three a claim is, whenever it decides something expensive.\n\n**Measured here.** Anything read out of a DataForSEO response this run. Positions,\nSERP composition, the presence of an AI Overview, the citation counts. These are\nobservations of a sample at a moment.\n\n**Published research.** Two figures worth carrying, both from Ahrefs, both\ncorrelational and industry rather than peer reviewed:\n\n- Across 75,000 brands, the strongest correlates of AI visibility were off-site:\n  YouTube mentions at Spearman 0.737 and branded web mentions at 0.664, against\n  backlinks at 0.218 (https://ahrefs.com/blog/ai-brand-visibility-correlations,\n  12 December 2025). This is the single most important number in this file,\n  because it bounds what any amount of research inside this repository can do.\n- Across 174,048 pages in 560,346 AI Overviews, the correlation between word count\n  and being cited was 0.04, with 53.4% of cited pages under 1,000 words\n  (https://ahrefs.com/blog/short-vs-long-content-in-ai-overviews/, 3 December\n  2025). Word count is not a lever. Do not recommend a length.\n\n**Practitioner convention.** Widely used, not established by a study anybody can\npoint at. The three-shared-URL clustering threshold in section 4 and the\npositions 4 to 20 striking-distance band in section 3 are both conventions. They\nare good defaults and they are not findings. Do not present either as research,\nand do not let a user's specific SERP lose an argument to a rule of thumb.\n\n## 3. Harvest before you hunt\n\nThe first question of a first run is not \"what should we write\". It is \"what does\nthis site already almost rank for\", and it is asked with one call against the\nuser's own domain.\n\nA blog that has been publishing for any length of time ranks for queries nobody\ntargeted, because posts get read for reasons their authors did not plan. Those\nqueries are the cheapest inventory available:\n\n- **Positions 4 to 20.** The page is already considered relevant. Something\n  specific is missing, and finding it is a reading job on one existing post, not a\n  writing job on a new one. The conventional band is 11 to 20, which is page two.\n  Widen it to 4, because moving from 7 to 3 changes the click share more than\n  moving from 18 to 12 does, and both are within reach of the same edit.\n- **A post that fell and did not change.** The post is the same, so the SERP moved\n  around it. Either the query drifted, or somebody published something better.\n  Look at what now holds the positions above it before touching the post.\n- **Two of our URLs on one query.** Cannibalisation. Neither page accumulates the\n  signals that would have made one of them the answer. Decide which page owns the\n  query, then either merge the other into it or retarget it. Merging is usually\n  right, and the internal links have to move with it.\n\nEach of these ends at `refresh-blog-post`, not at `write-blog-post`. A refresh of\na post with inbound links and existing position beats a new post with neither,\nand the whole point of running this step first is that the comparison is available\nbefore anybody commits to writing.\n\n## 4. Clustering on SERP overlap\n\nGroup queries by what the search engine returns for them, not by how they are\nworded.\n\n**The rule.** Two queries whose top ten results share three or more URLs belong\non one page. Zero or one shared URL means two pages. Two is a judgement call, and\nthe tie-breaker is whether one post could answer both without changing subject.\n\n**Why it beats grouping by wording.** String similarity is a guess about intent.\nThe SERP is the engine's already-published answer to that guess. When two\ndifferently worded queries return the same pages, the engine has decided they are\none information need, and a site that publishes two posts against them splits its\nown signals between two pages that then compete. When two similarly worded\nqueries return different pages, one post covering both will satisfy neither.\n\n**What this decides beyond the post count.** The query in the cluster with the\nbroadest SERP overlap across the others is the pillar. The rest are supporting\nposts, and they link up to it. That is exactly the structure `plan-blog-content`\nneeds, and deriving it from measured overlap is better than deriving it from\nwhich query has the highest volume, because volume does not tell you which page\nthe engine would treat as the parent.\n\nClustering needs one SERP read per query, so it is the step that decides the\nbudget. Cluster the ten to twenty finalists, not the six hundred candidates.\n\n## 5. Intent, and what a blog can win\n\nIntent is worth more than volume for a blog, because it decides whether a post is\neven the right object.\n\n- **Informational.** The blog's home ground. A post can hold the page and can be\n  the thing an answer engine quotes.\n- **Commercial investigation.** Comparisons, alternatives, \"best\" queries. A post\n  can win these, and the SERP will tell you whether the current holders are\n  editorial or vendor pages. Worth doing when the roster has real grounds for an\n  opinion, and a trap when it does not, because an uninformed comparison is the\n  most obviously thin thing a blog can publish.\n- **Transactional and navigational.** Not a blog post. The SERP wants a product\n  page, a pricing page, or a specific brand's own site. Recommending a post here\n  produces an article that ranks nowhere and serves nobody.\n\nA 90-a-month informational query this roster can answer completely is worth more\nthan a 5,000-a-month transactional one it cannot, and a run that sorts by volume\ninverts exactly that.\n\n## 6. Reading a SERP as an opportunity\n\nThe difficulty score is a summary. The SERP is the evidence, and it answers a\nquestion the score cannot: what would we have to beat.\n\nRead four things off it:\n\n- **Who holds the top five.** Forum threads and thin aggregators are an opening.\n  Primary documentation from the vendor the query names is not, at any difficulty\n  score, because no post outranks a product's own reference for a question about\n  that product.\n- **Which SERP features fire.** A featured snippet is a specific extractable\n  answer somebody already wrote, and the shape of it tells you what format wins.\n  People Also Ask is the cheapest source of real user phrasing in the whole API,\n  and that phrasing becomes question-format H2s rather than being paraphrased into\n  marketing wording.\n- **Whether an AI Overview appears.** Its presence means the click is harder and\n  the citation is the prize, which is the format `write-blog-post` already\n  produces. It is not a reason to skip a query the site should own, and its\n  absence is not a reason to relax the format, because the element appears and\n  disappears on the same query over time.\n- **Whether the results answer the question the query asks.** When the top ten\n  are all adjacent but none of them answers it directly, that is the best finding\n  a research run can produce, and no metric in the API reports it.\n\n## 7. The gap is a page-level question\n\nDomain-level competitor overlap tells you who to study. It does not tell you what\nto write, because a domain does not rank, a page does.\n\nWork down: find the competing domains by keyword overlap, take the top three, then\npull each one's pages ranked by traffic. Those pages are the brief. Read the ones\nthat hold the queries in the clusters, and record for each what it actually covers\nand where it stops. Where it stops is the post.\n\nTwo failure modes here:\n\n- **Studying the businesses instead of the pages.** The sites competing for the\n  queries are usually not the companies competing for the customers. A publisher\n  with no product often holds more of the subject's queries than any vendor does.\n- **Producing a keyword gap and calling it a content gap.** A list of queries a\n  competitor ranks for and we do not is not a plan. Most of that list is queries\n  this roster should not write about. The gap worth acting on is a query inside a\n  cluster we already own, where their page is the reason we do not hold it.\n\n## 8. Measuring AI citation without lying to yourself\n\nThis is the part of the API that measures the thing AgentBlog exists to improve,\nand it is the easiest place in this skill to produce a confident wrong number.\n\n**Count `sources`, not `search_results`.** The model retrieves far more than it\ncites. `search_results` is what it looked at, `sources` is what it used. Counting\nretrieval as citation inflates the number dramatically and in the flattering\ndirection, which is why nobody catches it.\n\n**Read `is_web_search_based`.** A citation produced from training data is not\nsomething this quarter's writing caused, and reporting it as though it were\nattributes an outcome to work that could not have produced it.\n\n**Read `fan_out_queries`.** The sub-queries the engine expanded the prompt into\nare the only observed rather than guessed view of that expansion available\nanywhere in this stack. They are a better source of post targets than any keyword\nendpoint, because they are what the engine actually asked on the user's behalf.\n\n**Treat one measurement as a sample.** These models are non-deterministic: the\nsame prompt run repeatedly returns different answers with different citations. A\nsingle reading is a draw from a distribution, not a value. Two readings taken a\nmonth apart differ for reasons that include the writing and also include the\nweather. Report a baseline with its date, its prompt set, its targets, and its\nplatform attached, and never report the difference between two single\nmeasurements as a trend.\n\n**Say which platform.** Omitting the platform queries both ChatGPT and Google AI\nOverview and changes the row count billed. ChatGPT data is United States and\nEnglish only, so a non-US site measuring without saying so is reporting a number\nabout a market it does not sell in.\n\n## 9. Cadence, and what a comparison has to hold constant\n\nA comparison is only a comparison if the question did not change. Hold the\ntarget, the platform, the location, the language, the prompt set, and the limit\nconstant between runs, and record all six in the snapshot. Change one of them and\nyou have a new baseline, not a movement, and the honest thing to do is say so and\nstart the series again.\n\nSensible defaults, all adjustable and none of them findings:\n\n| Measurement                           | Cadence                                      | Why not more often                                                                   |\n| ------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------ |\n| Own ranked keywords                   | Monthly                                      | Positions move daily and the noise swamps the signal below a month                   |\n| AI citation aggregates                | Monthly, same prompt set                     | Expensive, and non-deterministic enough that weekly readings mostly measure variance |\n| Cluster SERPs                         | When a cluster is being planned or replanned | The composition is stable enough that re-reading it monthly buys nothing             |\n| Keyword expansion, difficulty, intent | Once, then when the subject changes          | These move over quarters, and they are already on disk                               |\n\nThe rule underneath all four rows: re-buy what moves, read what does not.\n\n## 10. Anti-patterns, each of which produces a confident wrong answer\n\n- **Starting with expansion.** The first call of a first run is against the user's\n  own domain. Starting with a seed expansion produces six hundred rows and no idea\n  which of them the site is already close to.\n- **Sorting by volume.** It inverts section 5 and buries every query worth writing.\n- **Recommending a word count.** Correlation 0.04. Section 2.\n- **Clustering by wording.** Section 4. Produces posts that compete with each\n  other, which is worse than not writing the second one.\n- **Reporting `search_results` as citations.** Section 8.\n- **Comparing two runs that asked different questions.** Section 9. Worse than no\n  comparison, because it looks like a result.\n- **Attributing a movement to the writing.** Nothing in this API establishes\n  cause, and the strongest published correlates of AI visibility are off-site.\n  Report the movement, name the plausible causes, and say which one the data\n  cannot distinguish.\n- **Re-buying what is on disk.** The catalog exists so the second run is a diff.\n  A run that re-collects everything has thrown away the only compounding asset\n  this skill produces.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/dataforseo-research/references/playbook.md"
    },
    {
      "path": "registry/agent/skills/dataforseo-research/references/catalog.md",
      "content": "# The research catalog\n\nReference material for `dataforseo-research`. Read it before writing anything\ninto `content/research/`, and before comparing a new measurement against an old\none.\n\n> **License.** This file is prose documentation, licensed CC BY 4.0. See\n> `LICENSE-CONTENT` in the AgentBlog repository.\n\n## Contents\n\n1. Why the research lives in the repository\n2. The layout\n3. `ledger.md`, the index every run reads first\n4. `baseline.md`, the current standing answers\n5. `snapshots/`, and the rule that makes them worth keeping\n6. The `_meta` block, which is what makes a snapshot re-askable\n7. Bootstrapping the directory on a first run\n8. The comparison protocol\n9. Size, and what to do when the directory gets big\n10. What must never be written here\n\n---\n\n## 1. Why the research lives in the repository\n\nBecause the next agent is not this one.\n\nA research finding held in a conversation dies with the session. The user then\nasks the same question next month, a different agent runs a different query\nagainst a different sample, and the two answers disagree for reasons nobody can\nreconstruct. That is not research, it is repeated purchasing.\n\nCommitting the research to the repository fixes three things at once. Any agent in\nany session can read what is already known before spending. Git holds the previous\nversion of every file, so a change is a reviewable diff rather than an assertion.\nAnd the raw responses stay available, so a later question can often be answered\nfrom disk for nothing.\n\n`content/research/` sits outside `content/blog/`, so the content adapter never\nreads it and nothing in it can become a published page by accident. This is the\nsame placement `content/editorial-plan.md` already uses.\n\n## 2. The layout\n\n```\ncontent/research/\n├── README.md                     written once, for the human who finds this directory\n├── ledger.md                     append-only index of every run\n├── baseline.md                   the current standing answers, rewritten each run\n└── snapshots/\n    ├── 2026-08-08-account.json\n    ├── 2026-08-08-ranked-keywords.json\n    ├── 2026-08-08-competitors.json\n    ├── 2026-08-08-candidates.json\n    ├── 2026-08-08-serp-chunking-strategies.json\n    └── 2026-08-08-ai-citations.json\n```\n\nEvery snapshot filename is `YYYY-MM-DD-<what>.json`, using the date the call was\nmade rather than the date the file was written. Sorting the directory sorts the\nhistory, and the filenames alone tell a new agent what has been measured without\nreading a byte of JSON.\n\nUse these `<what>` names, and add new ones rather than overloading an existing\none: `account`, `ranked-keywords`, `competitors`, `competitor-pages`,\n`candidates`, `serp-<cluster-slug>`, `ai-citations`, `ai-prompts`.\n\n## 3. `ledger.md`, the index every run reads first\n\nThe ledger is the whole point of the catalog. It is the one file a run must read\nbefore it does anything else, and it is append-only: correct a mistake by adding\na row that says so, never by editing history.\n\n```markdown\n# Research ledger\n\nEvery DataForSEO run against this project. Append only. Newest last.\n\nSite: https://example.com\nLocation: 2840 (United States), language `en`, unless a row says otherwise.\n\n| Date       | Type     | Questions asked                                  | Snapshots                                                                        | Spent  | What changed                                                                  |\n| ---------- | -------- | ------------------------------------------------ | -------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------- |\n| 2026-08-08 | baseline | What do we rank for, who competes, what to write | ranked-keywords, competitors, candidates, serp-chunking-strategies, ai-citations | $0.71  | First run. 214 ranked keywords, 9 in positions 4 to 20, 0 AI citations found  |\n| 2026-09-05 | delta    | What moved in rankings and AI citations          | ranked-keywords, ai-citations                                                    | $0.34  | 3 posts gained, 1 fell 6 places without changing, first citation on 2 prompts |\n| 2026-09-11 | targeted | Is \"rag evaluation metrics\" worth a post         | serp-rag-evaluation                                                              | $0.004 | Yes. Top 5 is forum threads and one vendor blog from 2024                     |\n```\n\nThen a short prose section under the table for anything a cell cannot hold: a\nprompt set that changed and why, a degraded run and which section it lost, a\nfinding that needed a sentence.\n\n## 4. `baseline.md`, the current standing answers\n\nOne file that answers, right now, the questions a run exists to answer. Rewritten\nin full every run. Git holds the previous version, and that diff is the most\nreadable artefact this skill produces, so keep the section order stable between\nruns or the diff becomes noise.\n\n```markdown\n# Research baseline\n\nLast updated 2026-09-05 from the run of the same date. Every number here is a\nsample, with the snapshot that produced it named beside it.\n\n## What the site ranks for\n\n217 keywords, 12 in positions 4 to 20. Source: 2026-09-05-ranked-keywords.json.\n\n| Query | Position | Was | Our URL | Action |\n| ----- | -------- | --- | ------- | ------ |\n\n## Who competes for these queries\n\n## The clusters, and the pillar of each\n\n| Cluster | Pillar query | Members | Shared URLs | Intent | AI Overview |\n| ------- | ------------ | ------- | ----------- | ------ | ----------- |\n\n## AI citation\n\nPrompt set of 12, ChatGPT and Google AI Overview, United States, English.\nBaseline taken 2026-08-08, re-measured 2026-09-05. Source: 2026-09-05-ai-citations.json.\nNon-deterministic: read these as samples, not values.\n\n## Open questions this research has not answered\n```\n\nThat last section is not decoration. It is what stops the next run from starting\nover: it says what was deliberately left unmeasured and what it would cost.\n\n## 5. `snapshots/`, and the rule that makes them worth keeping\n\n**A snapshot is immutable.** Never edit one, never delete one, never overwrite one\nbecause a call was re-run the same day. A snapshot is the record of what an API\nreturned at a moment, and rewriting it destroys the only baseline the next\ncomparison had. If a call is repeated on the same date, suffix the second one\n(`2026-08-08-ranked-keywords-2.json`) and say in the ledger why.\n\nStore the trimmed response, not a summary. The trimmed `.ai` response costs the\nsame as the full one and is already stripped of the fields nobody reads. A summary\nwritten now cannot answer a question asked later, and the whole reason to keep\nthese is that later questions are free to answer from disk.\n\nSet `limit` explicitly on every call that goes into a snapshot. The trimmed\nresponse defaults `depth` and `limit` to 10, so a snapshot taken without an\nexplicit limit is silently ten rows, and a comparison against a later run that set\none will show a gain that is entirely an artefact of the request.\n\n## 6. The `_meta` block, which is what makes a snapshot re-askable\n\nEvery snapshot file is an object with two keys: the request that produced it, and\nthe response. Not the bare response.\n\n```json\n{\n  \"_meta\": {\n    \"run\": \"2026-09-05\",\n    \"type\": \"delta\",\n    \"endpoint\": \"dataforseo_labs/google/ranked_keywords/live.ai\",\n    \"transport\": \"rest\",\n    \"request\": [\n      {\n        \"target\": \"example.com\",\n        \"location_code\": 2840,\n        \"language_code\": \"en\",\n        \"limit\": 500,\n        \"tag\": \"2026-09-05-delta\"\n      }\n    ],\n    \"status_code\": 20000,\n    \"tasks_error\": 0,\n    \"cost\": 0.072,\n    \"compares_to\": \"2026-08-08-ranked-keywords.json\"\n  },\n  \"response\": {}\n}\n```\n\n`request` is the load-bearing field. A snapshot without the exact body that\nproduced it cannot be re-asked identically, and a comparison between two different\nquestions is worse than no comparison because it looks like a result. `compares_to`\nnames the snapshot this one is a successor of, which turns the directory into a\nseries rather than a pile.\n\nRecord `status_code` and `tasks_error` from the response, both of them. The\ntop-level status can be `20000` over a failed task, so a snapshot that stored only\nthe top-level code can be a record of a failure that reads as a success.\n\n## 7. Bootstrapping the directory on a first run\n\nCreate all four paths in the same commit as the first run's data, so the directory\nis never half-formed.\n\n`README.md` is written once and then left alone. It exists for the human who finds\nthis directory in a diff and wonders what it is:\n\n```markdown\n# Research\n\nDataForSEO research for this blog, kept in the repository so it compounds.\n\n- `ledger.md` is the index of every run. Read it first.\n- `baseline.md` is the current standing answer to what we rank for, who competes,\n  and what to write next. It is rewritten each run; git holds the previous one.\n- `snapshots/` holds the raw API responses, dated and immutable.\n\nThe `dataforseo-research` skill maintains all of this. It reads the ledger before\nspending anything, so it can tell you what is already known rather than buying it\nagain. Nothing here is published: the blog only reads `content/blog/`.\n```\n\nDo not gitignore this directory. Committing it is the mechanism, not a side\neffect. The files carry no credentials, and the responses are data the account\nalready paid for.\n\n## 8. The comparison protocol\n\nRun this whenever a snapshot has a predecessor.\n\n1. **Confirm the questions match.** Compare the two `_meta.request` bodies field by\n   field. Target, platform, location, language, limit, filters, and prompt set all\n   have to be identical. If any differs, this is a new baseline. Say so in the\n   ledger, start the series again, and do not report a movement.\n2. **Diff the rows, keyed on the stable identifier.** Keyword for keyword rows,\n   URL for page rows, prompt for citation rows. Never diff by array position: the\n   ordering is not stable and a reordered response reads as total churn.\n3. **Classify each difference** as new, lost, improved, declined, or unchanged.\n   The counts of each are the headline, and they belong in the ledger row.\n4. **Separate what moved from what was not asked last time.** A row that is new\n   because the earlier run used a smaller limit is not a gain. This is the failure\n   that step 1 and the explicit-limit rule in section 5 exist to prevent, and it\n   is the most common way a delta run reports a fictional improvement.\n5. **Attribute nothing.** Report the movement and the plausible causes. Nothing in\n   this data distinguishes a change caused by the writing from a change caused by\n   a competitor, an algorithm update, or, for the citation numbers, sampling.\n\n## 9. Size, and what to do when the directory gets big\n\nSnapshots are small. A 500-row trimmed Labs response is on the order of a hundred\nkilobytes, so a monthly cadence produces a directory a reader can still browse\nafter several years, and the git history is the point rather than a cost.\n\nTwo limits worth respecting anyway. Do not commit a `search_mentions` response at\n`limit: 1000` unless the run needed it, because that is a large file for data\nmostly summarised elsewhere. And do not store raw HTML SERP responses: keep the\nadvanced JSON, which is what every comparison reads.\n\nIf the directory ever does need pruning, prune the middle of a series and keep the\nendpoints, then record in the ledger which files were removed. Never prune the\noldest snapshot in a series: it is the baseline every long comparison runs\nagainst.\n\n## 10. What must never be written here\n\n- **Credentials.** Not in a `_meta` block, not in a shell snippet copied into the\n  ledger, not in a README. They live in the environment or in `.env.local`, and\n  `git check-ignore .env.local` is the check to run before touching that file. A\n  committed API password is a bill somebody else can run up.\n- **A summary in place of a response.** Section 5.\n- **An estimate in the ledger's `Spent` column.** Record what was actually spent,\n  read back from the account. An estimate recorded as a fact makes the whole\n  column useless for budgeting the next run.\n- **A finding without the snapshot that supports it.** Every number in\n  `baseline.md` names its source file. A number with no source cannot be checked,\n  cannot be re-derived, and is indistinguishable from one that was invented.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/dataforseo-research/references/catalog.md"
    },
    {
      "path": "registry/agent/skills/plan-blog-content/SKILL.md",
      "content": "---\nname: plan-blog-content\ndescription: >\n  Builds the editorial plan a blog needs before anyone writes: the entity the site\n  should be known for, a taxonomy of five to ten category hubs, query clusters\n  mined from what people actually search, a pillar and supporting post per cluster\n  with the internal link direction decided in advance, and a prioritised backlog\n  written to content/editorial-plan.md. Use when asked what to write about, for a\n  content or editorial plan, a topic or keyword cluster map, a blog strategy or\n  calendar, or when a blog has posts but no structure connecting them.\nallowed-tools: Read Write Edit Glob Grep WebSearch WebFetch Bash(npx agentblog *)\nlicense: MIT\ncompatibility: A Next.js project with AgentBlog installed. Needs web access to mine real queries.\nmetadata:\n  package: agentblog\n  homepage: https://agentblog.dev\n---\n\n# Plan what the blog is for\n\nA pile of individually good posts does not get cited. Retrieval systems resolve\nentities and follow links, so what earns citations is a site that is legibly about\nsomething, with hub pages that have enough on them to be worth indexing and a link\ngraph that says which post is the authority on what.\n\nThis skill produces a plan. It writes no posts. The deliverable is\n`content/editorial-plan.md`, and every line of it has to be specific enough that\n`write-blog-post` can start from one row without asking a question.\n\nBe honest with the user about the limit of this work. In Ahrefs' study of 75,000\nbrands, the strongest correlates of AI visibility were off-site: YouTube mentions\nat Spearman 0.737 and branded web mentions at 0.664, against backlinks at 0.218\n(https://ahrefs.com/blog/ai-brand-visibility-correlations, 12 December 2025,\nindustry and correlational). None of that lives in this repository. A perfect\neditorial plan is necessary and it is not sufficient, and saying so early is better\nthan saying it in month four.\n\n```\n- [ ] 1. Read what already exists\n- [ ] 2. Name the entity\n- [ ] 3. Mine real queries\n- [ ] 4. Cluster into hubs\n- [ ] 5. Assign pillars and supporting posts\n- [ ] 6. Check what is already answered well\n- [ ] 7. Write the backlog\n- [ ] 8. Reconcile the taxonomy\n```\n\n### 1. Read what already exists\n\n- `agentblog.config.ts` for `brand.name`, `siteUrl`, and `defaultAuthor`.\n- `content/authors.json`. `knowsAbout` and `bio` are the constraint nobody\n  remembers: a plan that requires posts this roster cannot credibly write is a plan\n  to publish thin content under a real name. If the plan needs expertise the roster\n  does not have, the answer is a new author record, not a shrug.\n- `content/categories.json` for the current taxonomy.\n- Every post in `content/blog/`. Record the target query, the category, and both\n  directions of its internal links.\n\n```bash\nnpx agentblog audit --stale --days 90\n```\n\nRun it before planning anything new. It ranks posts by `dateModified` age weighted\nby inbound internal links, so it tells you which existing posts are worth more than\na new one. Refreshing a post with authority usually beats writing a fourth post\nnobody links to.\n\n### 2. Name the entity\n\nWrite one sentence: **this site is the place to read about X**. Then check it\nagainst three things: the products or services the business actually sells, the\nexpertise in `content/authors.json`, and what a reader arriving from a generative\nanswer would expect to find.\n\nNarrower wins. A site about \"retrieval evaluation for RAG systems\" resolves as an\nentity. A site about \"AI\" does not resolve as anything, and it competes with every\npublisher on earth for queries it cannot win.\n\nThis sentence decides everything after it. Get the user to agree to it explicitly\nrather than inferring it and proceeding.\n\n### 3. Mine real queries\n\n**Check `content/research/` first.** If `dataforseo-research` has run, its\n`baseline.md` already holds measured clusters, the queries this site is close to\nranking for, and the People Also Ask phrasing, all of it better evidence than\nanything this step can produce on its own. Use it, and use this step only for what\nit did not cover. If that directory does not exist and the project has a\nDataForSEO account, running that skill first is worth the delay: it is the\ndifference between a plan built on measurement and a plan built on inference.\n\nOtherwise, `WebSearch` the entity's obvious head terms. Collect phrasing from\nPeople Also Ask boxes, forum threads, and the questions competitors' posts\nactually answer in their H2s. If the project has Search Console access, that is\nbetter than all of it.\n\nTwo rules:\n\n- **Do not invent phrasing.** The point of this step is the gap between how a\n  practitioner phrases a question and how a marketer would. The practitioner's\n  phrasing is the one that matches a retrieval query.\n- **Record the question, not the keyword.** \"how long should a rag chunk be\" is a\n  target. \"rag chunk size\" is a keyword, and a keyword does not tell you what the\n  post has to answer.\n\nCollect 40 to 80 real questions before clustering. Fewer and the clusters are\nguesses.\n\n### 4. Cluster into hubs\n\nGroup the questions by what a reader would consider one subject. Each surviving\ngroup becomes a category in `content/categories.json`.\n\n**Five to ten categories, and no more.** Each is an indexable hub page. A hub with\ntwo posts on it is a crawl liability rather than an asset, so a category needs at\nleast four to six posts planned before it earns a slug. Categories that cannot\nreach that go back into a neighbouring cluster.\n\nEvery category needs a real two-sentence description saying what belongs in it and\nwhat does not, because the hub page is indexable published prose and the schema\nrejects an empty one.\n\n### 5. Assign pillars and supporting posts\n\nWithin each cluster, decide which single post is the authority and which support\nit. Then decide the link direction **now**, in the plan, rather than post by post:\n\n- Every supporting post links up to its pillar, with anchor text naming the\n  pillar's topic.\n- The pillar links down to every supporting post.\n- Cross-cluster links happen where the subject genuinely crosses, and not to hit a\n  count.\n\nDeciding this in advance is the entire reason to plan. Decided post by post, the\ngraph becomes whatever the most recent post felt like linking to, and the pillar\nnever accumulates the inbound links that make it the authority.\n\nEvery post in the plan must have at least one planned inbound link before it is\nwritten, because a post with none is an orphan and `agentblog audit` fails it.\n\n### 6. Check what is already answered well\n\nFor each planned post, look at what currently ranks and what a generative engine\ncurrently answers. Drop or reframe anything where a well-resourced publisher has\nalready answered the question completely and you would only be paraphrasing.\n\nReframe toward what the roster can say and others cannot: a measurement somebody\nran, a failure mode from real operation, a comparison nobody has done, a document\nread properly rather than summarised.\n\n**Do not plan by length.** Ahrefs analysed 174,048 pages across 560,346 AI\nOverviews and found the correlation between word count and being cited was 0.04,\nwhich is no relationship at all, with 53.4% of cited pages under 1,000 words\n(https://ahrefs.com/blog/short-vs-long-content-in-ai-overviews/, 3 December 2025).\nPlan the question each post answers. Length follows.\n\n### 7. Write the backlog\n\nWrite `content/editorial-plan.md`. It sits outside `content/blog/`, so the content\nadapter never reads it and it cannot become a published page by accident.\n\nOne table per cluster, plus the entity sentence at the top:\n\n| Target question (as searched) | Role | Category | Author | Links out to | Links in from | Sources already found | Priority |\n| ----------------------------- | ---- | -------- | ------ | ------------ | ------------- | --------------------- | -------- |\n\n`Sources already found` is what makes this plan worth more than a list of titles.\nWhen step 3 or step 6 turned up a study, a specification, or a primary document\nworth citing, put the URL in the row. The writing skill has a hard rule against\nciting anything it did not fetch, so a plan that carries real sources removes the\nmost expensive part of writing each post.\n\nPrioritise by three things in this order: whether the roster can credibly write it,\nwhether it completes a hub that is currently too thin to index, and whether anyone\nis searching for it. Traffic potential is last, because a hub that never reaches\nenough posts never earns the citations any of them would have brought.\n\n### 8. Reconcile the taxonomy\n\nThe plan is not finished until `content/categories.json` matches it.\n\n- Adding a category is safe.\n- **Removing or renaming a slug that any existing post names in frontmatter fails\n  the next build** with `unknown category slug`. Change the posts in the same\n  commit, or leave the slug in place until the posts move.\n- A fresh install ships four categories that are AgentBlog's own topics. If\n  `agentblog-setup` has not replaced them yet, do that here.\n\nThen report: the entity sentence, the categories with their post counts, the\nbacklog length, which existing posts should be refreshed instead of replaced, and\nwhat the plan cannot do because it is off-site.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/plan-blog-content/SKILL.md"
    },
    {
      "path": "registry/agent/skills/write-blog-post/SKILL.md",
      "content": "---\nname: write-blog-post\ndescription: >\n  Writes or rewrites a blog post that generative engines cite, in a Next.js project\n  running AgentBlog: answer-first capsules, question-format H2 headings,\n  self-contained sections, statistics and quotations verified at a real source,\n  prose that does not read as machine-written, and frontmatter that parses against\n  the AgentBlog post schema. Use when asked to write a post, draft an article,\n  outline a piece, add a post to the blog, rewrite a post for AI visibility, or\n  make a post citable, in any project that has an agentblog.config.ts.\nargument-hint: '[topic or target query]'\nallowed-tools: Read Write Edit Glob Grep WebSearch WebFetch Bash(npx agentblog *)\nlicense: MIT\ncompatibility: A Next.js project with AgentBlog installed. Needs web access to verify sources.\nmetadata:\n  package: agentblog\n  homepage: https://agentblog.dev\n---\n\n# Write a blog post for AI citation\n\nThis post has to survive two readers: a person deciding whether to trust it, and a\nretrieval system deciding whether to quote it. The rules below serve both. They are\nnot style preferences, they are the shape that gets extracted.\n\nAssume the shadcn CLI skill already covers the registry and component primitives.\nAssume `node_modules/next/dist/docs/` already covers Next.js APIs. This skill covers\nonly what those do not: how to write the post.\n\n## Rules you may not violate\n\nThese are in the body rather than in a reference file, because a rule you have to\nfetch is a rule you will skip.\n\n- **Never fabricate a statistic, a quotation, or a source.** If you cannot verify a\n  number at a real source you have actually fetched, state the claim qualitatively\n  instead (\"most\", \"a majority of\", \"the largest share\") and say where the\n  qualitative claim comes from. Do not round an unverified number into precision.\n  Do not attribute a quote to a person unless you fetched the page it appears on.\n  One invented figure turns this skill from an asset into a liability, because the\n  post is then worse than not publishing.\n- **Never invent experience.** No anecdote, no first-person story, no \"a client we\n  worked with\", no opinion the source material does not support, no detail added\n  for texture. Writing that sounds human by inventing a human is the worst\n  available outcome: it is fabrication that also reads as fabrication. Credibility\n  here comes from verified evidence and a named author with a real bio.\n- **Never use an em dash.** Not one. Use a comma, a colon, parentheses, or a full\n  stop and a new sentence. Do not substitute a double hyphen either. The em dash is\n  the most recognisable tell of machine-written prose, and a product that sells\n  AI-assisted writing cannot ship copy that reads as AI-generated. This covers the\n  post body, the frontmatter, the alt text, and anything else you write into the\n  repository. `agentblog audit` fails the post on it.\n- **Never keyword-stuff.** In the GEO paper's own results table, keyword stuffing\n  scored _below_ the unoptimised baseline on Position-Adjusted Word Count. It is\n  the one technique measured to make things worse.\n- **Never pad to hit a word count.** Length is a proxy for completeness, not a\n  target. Padding degrades the retrieval quality of every section it touches,\n  because a chunk that wanders retrieves worse than a chunk that does not.\n\nConstructions that are banned outright, with no exceptions:\n\n- \"In today's fast-paced world\", or any variant of throat-clearing before the answer.\n- \"It's not just X, it's Y.\"\n- A rhetorical question followed immediately by its own answer as a paragraph opener.\n  (Question-format **H2 headings** are required. Rhetorical questions inside prose\n  are banned. These are different things.)\n- The words \"delve\", \"leverage\", \"robust\", \"seamless\", \"landscape\", \"tapestry\".\n- Three-item lists where two items carry the meaning. Cut the filler item.\n- \"Studies show\", \"experts agree\", \"industry reports suggest\". Name the source and\n  link it, or cut the claim.\n\nThe full catalogue of weaker patterns is in `references/voice.md`, and step 9 is\nwhere you work through it.\n\n## Procedure\n\nCopy this into your reply and check items off as you go. Steps 8 through 11 are the\nones that get skipped when the draft feels finished, which is why they are listed.\n\n```\n- [ ] 1. Read the project\n- [ ] 2. Fix the target query and its sub-questions\n- [ ] 3. Outline in question-format H2s\n- [ ] 4. Draft answer-first\n- [ ] 5. Write self-contained sections\n- [ ] 6. Ground every section in evidence\n- [ ] 7. Put comparison data in a real table\n- [ ] 8. Wire the post into the link graph\n- [ ] 9. Revise for voice\n- [ ] 10. Write the frontmatter\n- [ ] 11. Run agentblog audit, then the judgment checks\n```\n\n### 1. Read the project before you write\n\n- Read `agentblog.config.ts` for `brand.name`, `siteUrl`, `locale`, and\n  `defaultAuthor`.\n- Read `content/authors.json` for the author roster. `author.name` is a person's\n  name and nothing else: no job title, no honorific, no publisher name. `jobTitle`\n  is a separate field for exactly this reason. Note the author's `bio` and\n  `knowsAbout`, because the post has to be something that person could credibly\n  have written.\n- Read `content/categories.json` for the taxonomy.\n- Glob `content/blog/*.mdx` and read the frontmatter of every existing post, plus\n  the body of the closest one. You need four things: the brand voice, the category\n  and cluster structure, the internal link graph (`relatedPosts` plus in-body\n  links), and the house sentence rhythm.\n\n**Categories.** `category` in frontmatter must name a `slug` that exists in\n`content/categories.json`, or the build fails with `unknown category slug`. Prefer\nan existing category: five to ten fixed categories is the working range, because\neach one is an indexable hub page and a hub with two posts on it is a crawl\nliability rather than an asset.\n\nA fresh install ships four categories that are AgentBlog's own topics, not the\nuser's, so on an early post there may genuinely be no fit. When there is none, say\nso, propose the new category, and add a record to `content/categories.json` in the\nsame change as the post:\n\n```json\n{\n  \"slug\": \"your-new-category\",\n  \"name\": \"Your New Category\",\n  \"description\": \"Two sentences saying what belongs in this category and what does not. The hub page is indexable, so this is published prose, and the schema rejects an empty one.\"\n}\n```\n\n`slug` is lowercase and hyphen separated. Do not add a category you will put one\npost in, and do not add one silently: name it in your report.\n\n### 2. Fix the target query and its sub-questions\n\nIdentify the head query the post answers, then the sub-questions a reader who asked\nit would ask next. Use `WebSearch` to find the real phrasing people use, from People\nAlso Ask boxes and forum threads, rather than the phrasing you would invent. The\nsub-questions become the H2s.\n\nRead the top two or three results that already rank. You are looking for what they\nfail to answer, not for what to restate.\n\n### 3. Outline in question-format H2s\n\nEvery H2 is a question a real person would type. Give every H2 and H3 a stable,\nlowercase, hyphenated `id` derived from its text. Nest H2 then H3 with no skipped\nlevels. The title lives in frontmatter and renders as the page's only H1, so the\nbody starts at H2.\n\nContent that a generative engine cites is about twice as likely to contain a question\nmark, and 78.4% of citations tied to questions came from headings rather than body\ntext (Kevin Indig, 3M ChatGPT responses and 30M citations, reported by Search Engine\nLand, 18 February 2026, industry and correlational). The mechanism is more convincing\nthan the correlation: a heading phrased as a question matches the shape of the query\nthe retrieval system is matching against.\n\n### 4. Draft answer-first\n\n- **The `answerCapsule` frontmatter field**: 40 to 60 words answering the head query\n  completely. It renders under the H1. No preamble, no hyperlinks.\n- **Under each H2**: a 40 to 60 word capsule answering that heading's question, then\n  the supporting detail.\n\nThe capsule is what gets lifted into an answer. If it needs the paragraph after it\nto make sense, it is not a capsule.\n\n### 5. Write self-contained sections\n\n150 to 300 words per H2 section. Each section must make complete sense read in\nisolation, because retrieval systems split pages into chunks at heading boundaries\nand a chunk arrives without its neighbours.\n\n- **Repeat the entity name instead of using a pronoun.** Write \"Next.js Cache\n  Components\", not \"it\". This will feel repetitive as you write and will read\n  correctly to anyone who lands mid-page.\n- One idea per paragraph.\n- Front-load the highest-value sentence in each section so it survives truncation.\n- Never rely on a table caption or a definition from two sections earlier.\n\n### 6. Ground every section in evidence\n\nEach post needs at least one real statistic with a real number and at least one\nquotation from a named source, and both must be cited. Fetch the source. Read it.\nThen write the claim.\n\n`agentblog audit` warns when a post has neither, and errors when a post makes\nstatistical or quoted claims with no `citations[]` entries at all. It cannot tell\nyou that one claim among several is unsourced, and it can never tell you a\ncitation is wrong. That half is yours, and step 11 is where you report it.\n\nCarry the evidence grade with the claim, in the prose, the way a competent editor\nwould: \"peer-reviewed\", \"industry study, correlational\", \"vendor-reported\". Record\nthe same grade in the `citations[].kind` frontmatter field. A reader who knows a\nnumber is correlational trusts you more, not less.\n\nIf a source will not load or the number is not in it, do not use the number.\n\n### 7. Put comparison data in a real table\n\nAnything with more than two dimensions goes in a markdown table, never in prose.\nTables are associated with citation, and prose that describes a table is prose that\na retrieval system has to reconstruct.\n\nPair every chart or diagram image with the underlying numbers in a table nearby, so\nthe data is machine-readable. Text that exists only inside an image does not exist.\n\n### 8. Wire the post into the link graph\n\n- 5 to 15 contextual internal links in the body, with descriptive anchor text that\n  names the target topic. Never \"click here\", never \"read more\". `agentblog audit`\n  reports the count and fails outside that range.\n- **Add at least one inbound link from an existing post** to the new post, by\n  editing that post. A post with no inbound links is an orphan, and the audit fails\n  on it.\n- Fill `relatedPosts` with the slugs that genuinely belong, in the order they should\n  appear.\n\n### 9. Revise for voice\n\nRead `references/voice.md` and work the draft against it. Do this after the draft\nexists and before the frontmatter is final. Writing while scanning a list of\nforbidden patterns produces prose that avoids them and says nothing.\n\nThe three failures that survive every other check in this skill:\n\n- **Uniform sentence length.** Read each paragraph aloud in your head. Where three\n  sentences in a row share a shape, rewrite the middle one. Do not alternate lengths\n  mechanically, which is a different pattern rather than the absence of one.\n- **A closing flourish.** No summary recap, no final metaphor that inflates the\n  point. End on the strongest concrete thing the post established.\n- **Weasel attribution.** Anything phrased as evidence that carries none.\n\nDo not flatten the draft into uniform polish while fixing it. Leave strong sentences\nalone.\n\n### 10. Write the frontmatter\n\nThe contract is `PostFrontmatterSchema` in the AgentBlog schema package, and it\nrejects the post at build time. Full field reference in `references/schema-reference.md`.\n\n`npx agentblog new \"Your Title\"` scaffolds a file with the correct shape, and takes\n`--slug`, `--dir`, `--author`, and `--category`. Use it rather than writing the block\nfrom memory.\n\n- `slug`: lowercase, hyphen separated, no slashes, **no leading date**. A date in\n  the slug advertises the post's age forever. The filename is the slug: the MDX\n  adapter derives it from the file name with `.mdx` removed, so\n  `content/blog/do-ai-crawlers-run-javascript.mdx` publishes at\n  `/blog/do-ai-crawlers-run-javascript`. A `slug` in frontmatter overrides the\n  filename silently, which is how a post ends up at a URL that does not match the\n  file anyone is editing. Name the file correctly and either omit `slug` or write\n  the same value.\n- `title`: at most 70 characters, aim for 60. Keyword near the front.\n- `description`: target 150 to 160 characters. The schema's hard floor is 50, so a\n  shorter one parses, and a 60-character description wastes most of the space a\n  search result gives you. This must match `BlogPosting.description` exactly, so\n  write it once and do not paraphrase it later.\n- `answerCapsule`: the 40 to 60 word capsule from step 4.\n- `datePublished` and `dateModified`: ISO 8601 **with a UTC offset**, for example\n  `2026-08-06T09:30:00-04:00`. A bare `YYYY-MM-DD` is widened to midnight UTC by the\n  adapter, which is a convenience rather than a licence: write the offset when the\n  publish time matters. Without an offset Google reads the date in Googlebot's\n  timezone, which can move a post across a day boundary.\n- `author`, `category`: slugs that exist in the roster and the taxonomy. The adapter\n  hydrates them, and an unknown slug fails the build.\n- `tags`, `relatedPosts`, `citations`, `faq`: fill them. They default to empty, so\n  the schema will not remind you.\n- `heroImage` requires `heroAlt`. The alt text describes what the image shows in\n  plain language. It is not a keyword slot.\n\n### 11. Run the audit, then the judgment checks\n\n```bash\nnpx agentblog audit <slug> --verbose\n```\n\nThat command is the mechanical half of the gate and it is not optional. It checks\ncapsule presence and length, links inside capsules, question headings, heading ids,\ntitle and description lengths, date offsets and ordering, evidence presence,\ninternal link counts, broken internal links, orphan status, hero alt text, and copy\nstyle, and reports observed values. Do not restate any of it by reading.\n\nIt exits non-zero on an error and zero on a warning, so read the findings rather\nthan the exit code. **Do not report the post as done while it reports anything at\neither severity.**\n\nThen run `references/checklist.md`, which holds only the checks a script cannot\nmake. Report each as pass or fail **with the observed value**, not with a claim\nthat you looked.\n\n**Do not report the post as done while any item fails.** List the failures, say what\neach would take to fix, and stop. A checklist you always pass is a checklist you are\nnot running.\n\n## Reference material\n\nLoad these when the step that names them arrives. The rules above are the part you\nalways need.\n\n| File                             | When to read it                                                                                                                                 |\n| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |\n| `references/voice.md`            | Step 9, every time. The full pattern catalogue for the revision pass.                                                                           |\n| `references/checklist.md`        | Step 11, every time. Only the checks `agentblog audit` cannot make.                                                                             |\n| `references/schema-reference.md` | Step 10, and any time you are debugging the JSON-LD `@graph` the block emits.                                                                   |\n| `references/geo-playbook.md`     | Choosing between techniques, or explaining to a user why a suggestion matters. Carries the verified effect sizes with the metric named on each. |\n\n## FAQ section\n\nIf the post has genuine reader questions, add an `faq` array to the frontmatter. The\nquestions render visibly on the page before they are ever emitted as `FAQPage`\nJSON-LD. Marking up an FAQ that is not visible on the page is a structured-data\npolicy violation and the most common way blogs earn one.\n\nDo not add an FAQ section because the schema supports one. Add it because a reader\nwould ask those questions.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/write-blog-post/SKILL.md"
    },
    {
      "path": "registry/agent/skills/write-blog-post/references/geo-playbook.md",
      "content": "# GEO playbook\n\nReference material for `write-blog-post` and `refresh-blog-post`. Load it when you\nare choosing between techniques, or when a user asks why a suggestion matters and\ndeserves a real answer rather than an assertion.\n\n> **License.** This file is prose documentation, licensed CC BY 4.0. See\n> `LICENSE-CONTENT` in the AgentBlog repository. Figures quoted from third-party\n> research below are attributed to their sources and remain those authors' work.\n\n> **Scope.** This file deliberately contains no Next.js API shapes. Next.js 16.3\n> ships version-matched documentation at `node_modules/next/dist/docs/`, so anything\n> we wrote about Next.js APIs would drift and would lose to the bundled copy. Read\n> the bundled docs for framework questions. Read this file for writing questions.\n\n## Contents\n\n1. How the effect sizes in this file were verified\n2. GEO paper results, quoted with the metric named\n3. Everything else, with its evidence grade, plus the figures removed and why\n4. The writing rules, in priority order\n5. Extraction killers\n6. Things not to build\n7. Off-site, which is most of it\n\n---\n\n## 1. How the effect sizes in this file were verified\n\nThe section below quotes the GEO paper (Pranjal Aggarwal et al., \"GEO: Generative\nEngine Optimization\", ACM KDD 2024, https://arxiv.org/abs/2311.09735).\n\n**We read the paper's own results tables rather than a secondary summary.** That\nchoice matters, because secondary summaries of this paper disagree with each other\nabout which technique the headline figure belongs to and which metric it is measured\nagainst.\n\nHere is what the paper actually says, so you can check it yourself:\n\n- The abstract claims GEO can \"boost visibility by up to 40% in generative engine\n  responses\".\n- The Table 1 caption says: \"The best methods improve upon baseline by 41% and 28%\n  on Position-Adjusted Word Count and Subjective Impression respectively.\" The\n  caption names no technique.\n- Table 1 itself reports **absolute** impression scores, not relative improvements,\n  with an explicit `No Optimization` baseline row at **19.3 on both metrics**.\n\nSo the technique attribution has to be derived from the table, which is why the\nsummaries disagree. Doing that derivation: Quotation Addition is the only method\nreaching 27.2 on Position-Adjusted Word Count (Overall) and 24.7 on Subjective\nImpression (Average), which against the 19.3 baseline is +40.9% and +28.0%. **The\n41% belongs to Quotation Addition on Position-Adjusted Word Count.** Summaries that\nattribute it to Statistics Addition are wrong.\n\nEvery percentage in section 2 is derived by that same arithmetic from the printed\nabsolute scores and the printed baseline. The absolutes are given alongside so the\narithmetic is checkable.\n\n**What the figures do not mean.** The GEO paper's main experiments used\nGPT-3.5-turbo as the generative engine over the top 5 Google results, in 2023. The\nrank order of the techniques is what should drive your writing. The decimals are\ndecoration, and they are decoration measured on an engine nobody uses now.\n\n---\n\n## 2. GEO paper results, quoted with the metric named\n\n**Evidence grade for this whole section: peer-reviewed (ACM KDD 2024).**\n\n### 2.1 GEO-bench, Table 1\n\nBaseline (`No Optimization`) is 19.3 on both metrics. \"abs\" is the paper's printed\nabsolute score. \"rel\" is that score against the 19.3 baseline.\n\n| Rank | Method               | Position-Adjusted Word Count (Overall) | Subjective Impression (Average) |\n| ---- | -------------------- | -------------------------------------- | ------------------------------- |\n| 1    | Quotation Addition   | 27.2 abs, **+40.9% rel**               | 24.7 abs, **+28.0% rel**        |\n| 2    | Statistics Addition  | 25.2 abs, **+30.6% rel**               | 23.7 abs, +22.8% rel            |\n| 3    | Fluency Optimization | 24.7 abs, +28.0% rel                   | 21.9 abs, +13.5% rel            |\n| 4    | Cite Sources         | 24.6 abs, +27.5% rel                   | 21.9 abs, +13.5% rel            |\n| 5    | Technical Terms      | 22.7 abs, +17.6% rel                   | 21.4 abs, +10.9% rel            |\n| 6    | Easy-to-Understand   | 22.0 abs, +14.0% rel                   | 20.5 abs, +6.2% rel             |\n| 7    | Authoritative        | 21.3 abs, +10.4% rel                   | 22.9 abs, +18.7% rel            |\n| 8    | Unique Words         | 20.5 abs, +6.2% rel                    | 20.4 abs, +5.7% rel             |\n| 9    | **Keyword Stuffing** | 17.7 abs, **-8.3% rel**                | 20.2 abs, +4.7% rel             |\n\nThe paper's own prose summary of the same table: \"our top-performing methods, Cite\nSources, Quotation Addition, and Statistics Addition, achieved a relative\nimprovement of 30-40% on the Position-Adjusted Word Count metric and 15-30% on the\nSubjective Impression metric.\"\n\nTwo readings worth carrying into the writing:\n\n- **Keyword Stuffing is the only technique measured below baseline** on the primary\n  metric. The paper groups it by name under \"Non-Performing\" methods. This is the\n  most useful single result in the paper for practitioners, because it inverts an\n  SEO habit rather than confirming one.\n- **Authoritative tone is weak.** It ranks 7th of 9 on Position-Adjusted Word Count.\n  The paper: \"one would expect a more persuasive and authoritative tone in website\n  content to boost visibility. However, we find no significant improvement.\" Writing\n  more confidently is not a strategy. Adding evidence is.\n\n### 2.2 The effect depends on where the page already ranks, Table 2\n\nRelative improvement in visibility, by the source's rank in the search results.\n\n| Method               | Rank 1     | Rank 2 | Rank 3 | Rank 4 | Rank 5      |\n| -------------------- | ---------- | ------ | ------ | ------ | ----------- |\n| Cite Sources         | **-30.3%** | +2.5%  | +20.4% | +15.5% | **+115.1%** |\n| Quotation Addition   | **-22.9%** | -7.0%  | +3.5%  | +25.1% | +99.7%      |\n| Statistics Addition  | **-20.6%** | -3.9%  | +8.1%  | +10.0% | +97.9%      |\n| Authoritative        | -6.0%      | +4.1%  | -0.6%  | +12.6% | +6.1%       |\n| Fluency Optimization | -2.0%      | +5.2%  | +3.6%  | -4.4%  | +2.2%       |\n\nThe paper's framing: \"GEO is especially helpful for lower ranked websites.\"\n\nThe negative column is the part most summaries drop, and it is the interesting part.\nFor a source already ranked first, all three top techniques _reduced_ visibility.\nRead that as a ceiling effect rather than as an instruction to strip citations off\nyour best page, but do read it: these techniques are how a page that is not already\ndominant earns its way in, not a universal multiplier.\n\n### 2.3 The same techniques on a real deployed engine, Table 5\n\nThe paper re-ran a 200-example subset against Perplexity.ai. Baseline is 24.1 on\nPosition-Adjusted Word Count and 24.7 on Subjective Impression.\n\n| Method              | Position-Adjusted Word Count | Subjective Impression    |\n| ------------------- | ---------------------------- | ------------------------ |\n| No Optimization     | 24.1 abs                     | 24.7 abs                 |\n| Quotation Addition  | 29.1 abs, +20.7% rel         | 32.1 abs, +30.0% rel     |\n| Statistics Addition | 26.2 abs, +8.7% rel          | 33.9 abs, **+37.2% rel** |\n| Keyword Stuffing    | 21.9 abs, **-9.1% rel**      | 28.1 abs, +13.8% rel     |\n\nThe paper's prose reports these as a 22% improvement for Quotation Addition, \"up to\n9% and 37%\" for Cite Sources and Statistics Addition, and Keyword Stuffing \"10%\nworse\", all consistent with the printed table within rounding.\n\nNote the metric split, because it is routinely collapsed in summaries. On Perplexity\nthe quotations figure is a Position-Adjusted Word Count result and the statistics\nfigure is a Subjective Impression result. They are not the same measurement, and\nquoting one number without naming its metric is how the attribution confusion\nstarted.\n\n---\n\n## 3. Everything else, with its evidence grade\n\nNothing below is peer-reviewed. Treat each as a hypothesis worth acting on because\nthe cost of acting is low, not as a measured effect.\n\n**Every figure in this section carries the URL it was read at, the publisher, the\ndate, and the metric it is measured against.** That is not decoration. Section 2\nexists because secondary summaries of one paper disagreed about which technique and\nwhich metric a number belonged to, and the same rot is worse in this half of the\nfield. If a row below has no URL, it has no number either, on purpose. Several\nfigures that circulate widely were removed from this table when the source could not\nbe retrieved, and what is left in their place is the rank order, which was never the\npart in doubt.\n\n| Claim                                    | Figure and metric                                                                                                               | Source, fetched                                                                                                                                                                                                |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Structural formatting lifts citation     | 17.3% relative improvement in citation rate, and 18.5% in subjective quality, across six generative engines                     | Preprint. Yu, Yang, Ding, Sato, \"Structural Feature Engineering for Generative Engine Optimization\", arXiv:2603.29979, 31 March 2026. https://arxiv.org/abs/2603.29979                                         |\n| Answer capsule under the heading         | Present in 72.4% of cited blog posts. Metric: share of ChatGPT-cited blog posts containing an identifiable capsule              | Industry, correlational. Adam Gnuse, Search Engine Land, 19 November 2025, 7,500 ChatGPT referral sessions. https://searchengineland.com/how-to-get-cited-by-chatgpt-the-content-traits-llms-quote-most-464868 |\n| Capsules containing no links             | More than nine in ten cited capsules contained no links. Reported as a proportion, not a precise percentage                     | Same study, same URL                                                                                                                                                                                           |\n| Question-format headings                 | Cited content was about twice as likely to contain a question mark, and 78.4% of citations tied to questions came from headings | Industry, correlational. Kevin Indig, 3M ChatGPT responses and 30M citations, reported by Search Engine Land, 18 February 2026. https://searchengineland.com/chatgpt-citations-content-study-469483            |\n| Tables                                   | Tables present on 40.0% of top-decile cited pages against 28.2% of bottom-half pages, an 11.8 point gap                         | Industry, correlational. Trakkr Research, 16 April 2026, 1,465 AI-cited pages across 950 domains. https://trakkr.ai/trakkr-research/anatomy-of-an-ai-citation                                                  |\n| YouTube brand mentions                   | Spearman 0.737 against **ChatGPT** brand visibility. Not AI Overviews                                                           | Industry, correlational. Ahrefs, 12 December 2025, 75,000 brands. https://ahrefs.com/blog/ai-brand-visibility-correlations                                                                                     |\n| Branded web mentions, linked or unlinked | Spearman 0.664 against **AI Overview** brand visibility                                                                         | Industry, correlational. Ahrefs, 26 May 2025, 75,000 brands. https://ahrefs.com/blog/ai-overview-brand-correlation/                                                                                            |\n| Backlinks                                | Spearman 0.218 against AI Overview brand visibility. Domain Rating 0.326, referring domains 0.295                               | Same study, same URL                                                                                                                                                                                           |\n| No major AI crawler executes JavaScript  | GPTBot requested .js in 11.50% of requests and ClaudeBot in 23.84%. Neither executed any of it                                  | Vendor-reported. Vercel and MERJ, \"The rise of the AI crawler\", 17 December 2024, one month of traffic totalling roughly 1.3 billion AI crawler fetches. https://vercel.com/blog/the-rise-of-the-ai-crawler    |\n\n### Figures removed from this table, and why\n\nDo not reintroduce these. Each was traced and each failed.\n\n| Claim that circulates                                        | What actually happened                                                                                                                                                                                                           |\n| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Tables earn 2.5x to 4.2x more citations                      | The 2.5x traces to a vendor page that states its data is \"synthesized\" rather than measured. The 4.2x has no source at all. Some blogs attribute both to the KDD 2024 GEO paper, which contains no table-versus-prose comparison |\n| 76.4% of ChatGPT's most-cited pages updated within 30 days   | Attributed to a \"GEO Benchmark Study 2026\" whose domain does not resolve                                                                                                                                                         |\n| Long-form content is cited roughly 3x more                   | Contradicted by primary data. See below                                                                                                                                                                                          |\n| 5 to 15 internal links gives 38% higher citation probability | Same vendor page as the 2.5x, which describes its own figures as representing \"realistic patterns\"                                                                                                                               |\n| Question headings are cited at 18% versus 8.9%               | Republished by Ahrefs but sourced from a paywalled third-party analysis. The underlying study is real (Kevin Indig); this specific pair of percentages could not be read at its source. Use the row in the table above instead   |\n\n**On length specifically, the primary data points the other way.** Ahrefs analysed\n174,048 pages across 560,346 AI Overviews (3 December 2025,\nhttps://ahrefs.com/blog/short-vs-long-content-in-ai-overviews/) and found 53.4% of\ncited pages under 1,000 words, an average cited length of 1,282 words, and a Spearman\ncorrelation between word count and being cited of **0.04**, which is no relationship\nat all. Write to the length the question needs. Do not tell a user that longer wins.\n\n### The confidence-interval warning, with its citation\n\nRonald Sielinski, \"Quantifying Uncertainty in AI Visibility: A Statistical Framework\nfor Generative Search Measurement\", arXiv:2603.08924, 9 March 2026,\nhttps://arxiv.org/abs/2603.08924. Sampling across Perplexity Search, OpenAI\nSearchGPT, and Google Gemini, the paper reports that confidence intervals for a\nfrequently cited domain's citation share span 3 to 6 percentage points on SearchGPT,\nand that \"overlapping confidence intervals of this kind are the norm rather than the\nexception for domains that appear to differ in citation share by less than 5 to 7\npercentage points\".\n\nCarry that when you quote any row in this section. A reported improvement smaller\nthan about 5 points is not distinguishable from noise in the published measurements.\n\n**Conflicting data, noted rather than resolved.** The overlap between AI Overview\ncitations and Google's top 10 was 76.10% in July 2025 (Ahrefs, 1.9 million citations\nacross 1 million AI Overviews, https://ahrefs.com/blog/search-rankings-ai-citations)\nand 38% in March 2026 (Ahrefs, 863,000 keyword SERPs and 4 million AI Overview URLs,\nhttps://ahrefs.com/blog/ai-overview-citations-top-10). Ahrefs frames the second as a\ndecline from the first and attributes it to query fan-out. Trust the direction over\neither figure. Ranking is necessary and no longer sufficient.\n\n---\n\n## 4. The writing rules, in priority order\n\n1. **Answer first.** The complete answer in the first 40 to 60 words, under the H1\n   and under each H2. Inverted pyramid after that: answer, context, detail. No links\n   inside a capsule, because a link signals the answer lives somewhere else.\n2. **Chunk cleanly.** Retrieval splits pages into chunks, often 200 to 500 tokens,\n   frequently at heading boundaries, and each chunk becomes one vector. A chunk that\n   mixes two topics produces an ambiguous embedding and retrieves poorly. Write each\n   section to stand alone.\n3. **Repeat entity names and drop pronouns.** The chunk may be retrieved with no\n   preceding context, and \"it\" resolves to nothing there.\n4. **Question-format H2s** mirroring real query phrasing, mined from People Also\n   Ask, Search Console, and forums rather than invented.\n5. **Sections of 150 to 300 words**, each answering its heading completely.\n6. **Evidence in every section**: a real number from a real source, a quotation from\n   a named person, or an honest outbound citation. Section 2 ranks quotations, then\n   statistics, then citations, and all three beat writing more confidently.\n7. **Tables for anything comparative.** Pair every chart with its numbers in HTML.\n8. **Stable ids on every H2 and H3**, and a table of contents on anything over about\n   1,200 words.\n9. **Length is a proxy for completeness, not a target.** A 900-word post that fully\n   answers a narrow question beats a padded 2,500-word one.\n\n## 5. Extraction killers\n\nEach of these makes content invisible to engines that do not execute JavaScript,\nwhich is all of them except Googlebot and Applebot.\n\n- Body content fetched client-side, or mounted on interaction. CSS-hidden is fine\n  (`<details>`, a class toggle). JavaScript-mounted is not.\n- Infinite scroll, and pagination built on click handlers rather than real\n  `<a href>` links.\n- Text that exists only inside an image, with no HTML equivalent.\n- Keyword stuffing. See section 2.1: measured below baseline.\n- Paywalled content with no `isAccessibleForFree` markup.\n- Redirect chains. AI crawlers handle redirects poorly. In the Vercel and MERJ study\n  cited in section 3, ChatGPT spent 14.36% of its fetches following redirects and\n  34.82% of them on 404 pages.\n\n## 6. Things not to build\n\n- **llms.txt.** Google states on record that Search does not use it: \"You don't need\n  to create new machine readable files, AI text files, markup, or Markdown to appear\n  in Google Search (including its generative AI capabilities), as Google Search\n  itself doesn't use them\"\n  (https://developers.google.com/search/docs/fundamentals/ai-optimization-guide). No\n  major provider consumes it in production. The best-documented measurement of demand\n  is small and consistent with that: OtterlyAI logged 84 requests to `/llms.txt` out\n  of 62,100 AI bot visits over 90 days, against an average of about 265 AI bot visits\n  per ordinary page in the same window (Thomas Peham, 5 February 2026,\n  https://otterly.ai/blog/the-llms-txt-experiment/). The one legitimate use is a\n  machine-readable index for developer documentation with programmatic consumers. A\n  blog is not that.\n- **Special AI markup.** Google's stated position is that there is no special markup\n  or optimization for AI Overviews or AI Mode, because both run on core Search\n  ranking and quality systems: \"There are no additional requirements to appear in AI\n  Overviews or AI Mode, nor other special optimizations necessary\"\n  (https://developers.google.com/search/docs/appearance/ai-features).\n- **FAQ schema on invisible FAQs.** Google restricted FAQ rich results to\n  authoritative government and health sites in 2023, so the rich result is not\n  coming. The markup still helps machine parsing, and marking up FAQs that do not\n  render is a policy violation. Only mark up what a reader can see.\n\n## 7. Off-site, which is most of it\n\nThe strongest correlational signals in section 3 are off-site. In Ahrefs' 75,000\nbrand study, YouTube mentions (0.737) and branded web mentions (0.664) both rank\nabove backlinks (0.218). That work does not live in this repository and cannot be\ndone by this skill. Say so honestly when a user asks why their citation share is flat\ndespite a clean install.\n\nWhat the codebase can do is make sure the entity resolves. Keep `sameAs` on both\n`Organization` and `Person` pointing at every profile that genuinely exists, as\nabsolute URLs, so an engine can connect the mentions it finds to the site it is\nreading.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/write-blog-post/references/geo-playbook.md"
    },
    {
      "path": "registry/agent/skills/write-blog-post/references/schema-reference.md",
      "content": "# Schema reference\n\nThe JSON-LD `@graph` shapes AgentBlog emits, the mapping from AgentBlog frontmatter\nto schema.org properties, and the markup errors that actually happen.\n\n> **License.** This file is prose documentation, licensed CC BY 4.0. See\n> `LICENSE-CONTENT` in the AgentBlog repository.\n\n> **Scope: no Next.js APIs in this file, deliberately.** Next.js 16.3 ships\n> version-matched documentation at `node_modules/next/dist/docs/`, generated for the\n> exact version installed in the project. Anything we wrote here about `Metadata`,\n> `generateMetadata`, `sitemap.ts`, or `revalidateTag` would drift with every\n> release and would lose to the bundled copy the moment it did. For framework\n> questions, read the bundled docs. This file covers the vocabulary layer, which is\n> ours.\n\n## Contents\n\n1. Where the JSON-LD comes from\n2. The connected `@graph` for a post\n3. The other graph shapes: blog index, `FAQPage`, author page\n4. Frontmatter to schema.org mapping, for posts, authors, and config\n5. Property weight\n6. Markup errors that actually happen\n7. Validating\n\n---\n\n## 1. Where the JSON-LD comes from\n\n`lib/schema.ts` in the installed block builds every node. It is typed with\n`schema-dts`, and it has exactly one serialization point, `renderJsonLd`, which\nescapes `<` as `<` so an injected `</script>` cannot break out of the tag.\n\nDo not hand-write a `<script type=\"application/ld+json\">` anywhere. If a node is\nmissing, add a builder to `lib/schema.ts`. Two serialization points is how a graph\nstarts contradicting itself.\n\nThe builders are `buildOrgGraph`, `buildPersonGraph`, `buildArticleGraph`,\n`buildBlogGraph`, `buildBreadcrumb`, and `buildFaq`. Node `@id` values come from the\n`ids` object, never from string concatenation at the call site, because the `@id`\nvalues are what link the graph together and a typo in one silently disconnects a\nnode instead of erroring.\n\n## 2. The connected `@graph` for a post\n\nEvery node in one `@graph`, cross-referenced by `@id`. Separate disconnected script\ntags describe several unrelated things instead of one thing.\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@graph\": [\n    {\n      \"@type\": \"Organization\",\n      \"@id\": \"https://example.com/#organization\",\n      \"name\": \"Your Brand\",\n      \"url\": \"https://example.com\",\n      \"logo\": {\n        \"@type\": \"ImageObject\",\n        \"@id\": \"https://example.com/#logo\",\n        \"url\": \"https://example.com/logo.png\",\n        \"width\": 512,\n        \"height\": 512\n      },\n      \"sameAs\": [\n        \"https://www.linkedin.com/company/yourbrand\",\n        \"https://www.crunchbase.com/organization/yourbrand\",\n        \"https://www.youtube.com/@yourbrand\",\n        \"https://www.wikidata.org/wiki/Q000000\"\n      ]\n    },\n    {\n      \"@type\": \"WebSite\",\n      \"@id\": \"https://example.com/#website\",\n      \"url\": \"https://example.com\",\n      \"name\": \"Your Brand\",\n      \"publisher\": { \"@id\": \"https://example.com/#organization\" },\n      \"inLanguage\": \"en-US\"\n    },\n    {\n      \"@type\": \"Person\",\n      \"@id\": \"https://example.com/authors/jane-doe#person\",\n      \"name\": \"Jane Doe\",\n      \"url\": \"https://example.com/authors/jane-doe\",\n      \"image\": \"https://example.com/authors/jane-doe.jpg\",\n      \"jobTitle\": \"Senior Analyst\",\n      \"description\": \"Jane has spent 11 years building retrieval systems.\",\n      \"worksFor\": { \"@id\": \"https://example.com/#organization\" },\n      \"knowsAbout\": [\"Information retrieval\", \"Search ranking\"],\n      \"alumniOf\": \"Stanford University\",\n      \"sameAs\": [\"https://www.linkedin.com/in/janedoe\", \"https://github.com/janedoe\"]\n    },\n    {\n      \"@type\": \"BlogPosting\",\n      \"@id\": \"https://example.com/blog/my-post#article\",\n      \"isPartOf\": { \"@id\": \"https://example.com/blog/my-post#webpage\" },\n      \"mainEntityOfPage\": { \"@id\": \"https://example.com/blog/my-post#webpage\" },\n      \"headline\": \"Exact Title, Kept Concise\",\n      \"description\": \"One sentence summary, identical to the meta description.\",\n      \"image\": {\n        \"@type\": \"ImageObject\",\n        \"@id\": \"https://example.com/blog/my-post#primaryimage\",\n        \"url\": \"https://example.com/blog/my-post/hero.jpg\",\n        \"width\": 1200,\n        \"height\": 630\n      },\n      \"datePublished\": \"2026-01-15T09:00:00-08:00\",\n      \"dateModified\": \"2026-08-01T11:30:00-07:00\",\n      \"author\": { \"@id\": \"https://example.com/authors/jane-doe#person\" },\n      \"publisher\": { \"@id\": \"https://example.com/#organization\" },\n      \"inLanguage\": \"en-US\",\n      \"articleSection\": \"Technical SEO\",\n      \"keywords\": [\"generative engine optimization\", \"AI crawlers\"],\n      \"about\": [{ \"@type\": \"Thing\", \"name\": \"Generative Engine Optimization\" }],\n      \"mentions\": [{ \"@type\": \"SoftwareApplication\", \"name\": \"Next.js\" }],\n      \"citation\": [\n        {\n          \"@type\": \"CreativeWork\",\n          \"name\": \"GEO: Generative Engine Optimization\",\n          \"url\": \"https://arxiv.org/abs/2311.09735\"\n        }\n      ]\n    },\n    {\n      \"@type\": \"WebPage\",\n      \"@id\": \"https://example.com/blog/my-post#webpage\",\n      \"url\": \"https://example.com/blog/my-post\",\n      \"name\": \"Exact Title\",\n      \"isPartOf\": { \"@id\": \"https://example.com/#website\" },\n      \"primaryImageOfPage\": { \"@id\": \"https://example.com/blog/my-post#primaryimage\" },\n      \"breadcrumb\": { \"@id\": \"https://example.com/blog/my-post#breadcrumb\" },\n      \"datePublished\": \"2026-01-15T09:00:00-08:00\",\n      \"dateModified\": \"2026-08-01T11:30:00-07:00\"\n    },\n    {\n      \"@type\": \"BreadcrumbList\",\n      \"@id\": \"https://example.com/blog/my-post#breadcrumb\",\n      \"itemListElement\": [\n        { \"@type\": \"ListItem\", \"position\": 1, \"name\": \"Blog\", \"item\": \"https://example.com/blog\" },\n        {\n          \"@type\": \"ListItem\",\n          \"position\": 2,\n          \"name\": \"Content Strategy\",\n          \"item\": \"https://example.com/blog/category/content-strategy\"\n        }\n      ]\n    }\n  ]\n}\n```\n\nThe trail starts at `/blog` and ends at the category hub, matching the visible\nbreadcrumb on the page exactly, because the route builds one array and passes it\nto both. Google requires neither end: \"It is not required to include a\nbreadcrumb ListItem for the top level path\", and a trail may stop above the\ncurrent page. On a list page, where the last crumb is the page the reader is on,\nthat crumb has no `item` property, which is the documented shape rather than an\nomission.\n\n## 3. The other graph shapes\n\n### Blog index\n\n```json\n{\n  \"@type\": \"Blog\",\n  \"@id\": \"https://example.com/blog#blog\",\n  \"url\": \"https://example.com/blog\",\n  \"name\": \"Your Brand Blog\",\n  \"description\": \"…\",\n  \"publisher\": { \"@id\": \"https://example.com/#organization\" },\n  \"isPartOf\": { \"@id\": \"https://example.com/#website\" },\n  \"blogPost\": [\n    { \"@id\": \"https://example.com/blog/post-a#article\" },\n    { \"@id\": \"https://example.com/blog/post-b#article\" }\n  ]\n}\n```\n\n`blogPost` holds `@id` references, not inlined article nodes. Inlining duplicates\nevery article body into the index page's markup.\n\n### FAQPage\n\nEmitted only when the post has a non-empty `faq` array **and** those questions\nrender visibly in the article.\n\n```json\n{\n  \"@type\": \"FAQPage\",\n  \"@id\": \"https://example.com/blog/my-post#faq\",\n  \"mainEntity\": [\n    {\n      \"@type\": \"Question\",\n      \"name\": \"Do AI crawlers execute JavaScript?\",\n      \"acceptedAnswer\": {\n        \"@type\": \"Answer\",\n        \"text\": \"No. GPTBot, ClaudeBot, and PerplexityBot read only the raw HTML the server returns.\"\n      }\n    }\n  ]\n}\n```\n\n### Author page\n\n`buildPersonGraph` emits the same `Person` node as the article graph, at the same\n`@id`. One identity, referenced from two pages, is the point of `@id`.\n\n## 4. Frontmatter to schema.org mapping\n\nAgentBlog frontmatter is validated by `PostFrontmatterSchema`. This table is the\ncontract between that schema and the graph above. If you add a frontmatter field\nthat maps to schema.org, add a row here and a branch in `lib/schema.ts`.\n\n### Post fields\n\n| Frontmatter             | Schema.org target                                    | Notes                                                                                                                                     |\n| ----------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `slug`                  | none directly                                        | Composes every `@id` and the canonical URL. Defaults to the file name with `.mdx` removed; frontmatter overrides it. Keep them identical. |\n| `title`                 | `BlogPosting.headline`, `WebPage.name`               | At most 70 characters, aim for 60. Google removed the old 110-character headline limit in January 2025, but SERP truncation did not move. |\n| `description`           | `BlogPosting.description`                            | 50 to 160 characters. Must be byte-identical to the meta description.                                                                     |\n| `answerCapsule`         | none                                                 | Renders visibly under the H1. Not marked up, by design: there is no schema.org property for it and inventing one adds noise.              |\n| `datePublished`         | `BlogPosting.datePublished`, `WebPage.datePublished` | ISO 8601 **with a UTC offset**. Without one, Google reads it in Googlebot's timezone.                                                     |\n| `dateModified`          | `BlogPosting.dateModified`, `WebPage.dateModified`   | Same rule. Must match the visible \"Updated\" date exactly.                                                                                 |\n| `author`                | `BlogPosting.author` as `{ \"@id\": … }`               | Never a bare string. See section 5.                                                                                                       |\n| `category`              | `BlogPosting.articleSection`                         | Also drives the breadcrumb trail and the category hub page.                                                                               |\n| `tags`                  | `BlogPosting.keywords`                               | Largely ignored for ranking, harmless to include.                                                                                         |\n| `heroImage` + `heroAlt` | `BlogPosting.image` as a linked `ImageObject`        | `heroAlt` is required whenever `heroImage` is set. The image needs `width` and `height`.                                                  |\n| `relatedPosts`          | none                                                 | Internal link graph only. Used for orphan prevention and the related-posts block.                                                         |\n| `citations[]`           | `BlogPosting.citation[]` as `CreativeWork`           | `name` and `url` are emitted.                                                                                                             |\n| `citations[].kind`      | none                                                 | Ours, for auditing. `peer-reviewed`, `official-docs`, `industry`, `news`, `other`. Never emitted as JSON-LD.                              |\n| `faq[]`                 | `FAQPage.mainEntity[]`                               | Only when the questions render on the page.                                                                                               |\n| `locale`                | `BlogPosting.inLanguage`                             | Falls back to `config.locale`.                                                                                                            |\n| `draft`                 | none                                                 | Excluded from every query, the sitemap, and the feed.                                                                                     |\n\n### Author fields\n\n| Frontmatter  | Schema.org target    | Notes                                                                                                                                |\n| ------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |\n| `name`       | `Person.name`        | The person's name and nothing else. No job title, no honorific, no publisher name. Google's Article guidance is explicit about this. |\n| `jobTitle`   | `Person.jobTitle`    | Exists so the correct shape of `name` is the only constructible one.                                                                 |\n| `bio`        | `Person.description` | Required. This is the E-E-A-T lookup surface, and the Search Quality Rater Guidelines direct raters to look authors up.              |\n| `avatar`     | `Person.image`       | Absolute URL.                                                                                                                        |\n| `worksFor`   | `Person.worksFor`    | Emitted as `{ \"@id\": \"…/#organization\" }` when it matches the configured brand.                                                      |\n| `knowsAbout` | `Person.knowsAbout`  | Topics this author is credible on.                                                                                                   |\n| `alumniOf`   | `Person.alumniOf`    |                                                                                                                                      |\n| `sameAs`     | `Person.sameAs`      | Absolute profile URLs. The strongest entity signal in the whole graph.                                                               |\n\n### Config to `Organization` and `WebSite`\n\n| Config path                     | Schema.org target                                                 |\n| ------------------------------- | ----------------------------------------------------------------- |\n| `brand.name`                    | `Organization.name`, `WebSite.name`                               |\n| `siteUrl`                       | `Organization.url`, `WebSite.url`, and the base of every `@id`    |\n| `brand.logo.{url,width,height}` | `Organization.logo` as a linked `ImageObject`                     |\n| `brand.sameAs[]`                | `Organization.sameAs`                                             |\n| `locale`                        | `WebSite.inLanguage`, and the `inLanguage` fallback on every post |\n\n## 5. Property weight\n\nGoogle's Article documentation states there are **no required properties**. That is\nnot permission to omit them.\n\n| Category                                                                        | Properties                                                                                                                                                               |\n| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Highest weight for rich results                                                 | `headline`, `image`, `author` as a linked `Person` with a `url`, `datePublished`, `dateModified`                                                                         |\n| High value for entity resolution, even where Google ignores it for rich results | `sameAs` (the single strongest property here), `knowsAbout`, `about`, `mentions`, `citation`, `worksFor`, `isPartOf`, `mainEntityOfPage`, and the `@id` links themselves |\n| Largely ignored for ranking, harmless                                           | `wordCount`, `keywords`, `articleSection`                                                                                                                                |\n\n`sameAs` is the property that lets an engine decide that the \"Jane Doe\" on this page\nis the same Jane Doe it saw on LinkedIn and in a conference programme. Handles do\nnot do that. Absolute URLs do.\n\n## 6. Markup errors that actually happen\n\n| Error                                                                  | Why it breaks                                                                                        | Fix                                                                                                 |\n| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| JSON-LD injected by client-side JavaScript                             | Never reaches a crawler that does not execute JS, which is all of them except Googlebot and Applebot | Render from a Server Component, which is what `lib/schema.ts` and the `JsonLd` component already do |\n| `author` as a bare string                                              | Loses the entity link that E-E-A-T depends on                                                        | Linked `Person` node with `@id` and `url`                                                           |\n| `author.name` containing a job title, honorific, or the publisher name | Explicit violation of Google's Article guidance                                                      | Put the title in `jobTitle`                                                                         |\n| `dateModified` not matching the visible date                           | Trust-destroying inconsistency, and one of the most commonly flagged errors                          | Single source of truth in frontmatter. The block renders both from it.                              |\n| Dates without a UTC offset                                             | Google falls back to Googlebot's timezone, silently shifting the date                                | `IsoDateTime` in the schema rejects these at parse time                                             |\n| `sameAs` containing a handle instead of a URL                          | Disambiguates nothing                                                                                | Always absolute URLs                                                                                |\n| `Organization.logo` missing `width` and `height`                       | Incomplete required shape                                                                            | Config carries both                                                                                 |\n| `FAQPage` markup with no visible FAQs                                  | Structured data policy violation, and the most common way blogs earn one                             | Remove the markup or render the FAQs                                                                |\n| Marking up any fact not visible on the page                            | The single most enforced structured data policy                                                      | Mark up what renders, nothing else                                                                  |\n| Validating the rendered DOM instead of the raw HTML                    | A DOM-based validator passes markup a crawler never receives                                         | Validate `curl` output, not DevTools                                                                |\n| Two `<script type=\"application/ld+json\">` tags with overlapping claims | The graph contradicts itself and neither node is trustworthy                                         | One `@graph`, one serialization point                                                               |\n\n## 7. Validating\n\nTwo tools, two different questions. Run both and report both.\n\n- [Rich Results Test](https://search.google.com/test/rich-results) answers \"is this\n  eligible for a rich result\".\n- [Schema Markup Validator](https://validator.schema.org/) answers \"is this valid\n  schema.org vocabulary\".\n\nFeed both the **raw HTML** from a `curl`, not a URL the tool will render with\nJavaScript, and not a copy-paste from the browser inspector.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/write-blog-post/references/schema-reference.md"
    },
    {
      "path": "registry/agent/skills/write-blog-post/references/voice.md",
      "content": "# Voice\n\nThe revision pass. Load this after a draft exists, not before: writing while\nscanning a list of forbidden patterns produces prose that avoids them and says\nnothing.\n\nThe goal is not to evade a detector. Detectors are unreliable and optimising for\none produces worse writing, not better. The goal is that a competent reader\nfinishes the post without once thinking about how it was produced.\n\n> **License.** This file is prose documentation, licensed CC BY 4.0. See\n> `LICENSE-CONTENT` in the AgentBlog repository.\n\n## Contents\n\n- How to run the pass\n- Empty importance and abstraction\n- Stock rhetorical moves\n- Mechanical diction\n- Rhythm and structure\n- Endings\n- What not to fake\n- The five questions\n\n---\n\n## How to run the pass\n\nRead the draft top to bottom as an editor who did not write it. Mark every place\nthe eye slides off. Then work the catalogue below against the marks.\n\nTwo rules govern the whole pass:\n\n- **Every pattern here is a warning, not a ban.** A construction that carries real\n  meaning stays. \"It is not a cache, it is a queue\" is a real distinction and\n  survives. \"It is not just fast, it is transformative\" is decoration and goes.\n- **Do not flatten.** A pass that normalises every paragraph to the same shape\n  and polish has replaced one machine signature with another. Leave strong\n  sentences alone.\n\n## Empty importance and abstraction\n\n| Pattern              | What it looks like                                                                                                            | Fix                                                                                                          |\n| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |\n| Importance puffery   | \"plays a vital role\", \"marks a pivotal moment\", \"underscores the significance of\"                                             | State the supported fact. Let the reader decide it matters.                                                  |\n| Promotional language | \"powerful\", \"groundbreaking\", \"cutting-edge\", \"game-changing\"                                                                 | Replace with what the thing measurably does.                                                                 |\n| Superficial analysis | a trailing clause that pretends to explain: \"highlighting the importance of\", \"showcasing how\", \"reflecting the shift toward\" | State the mechanism or the consequence, or delete the clause.                                                |\n| Weasel attribution   | \"studies show\", \"experts agree\", \"industry reports suggest\", \"it is widely believed\"                                          | Name the study and link it, or cut the claim. This one is also a citation failure, not only a style failure. |\n| Formulaic outlook    | a closing \"Despite these challenges\" or \"Looking ahead\" paragraph with no specific content                                    | Keep only concrete problems, plans, and unknowns the post actually establishes.                              |\n\nWeasel attribution is the pattern to hunt hardest, because it is the one that\nsurvives every other check. It reads like evidence and carries none.\n\n## Stock rhetorical moves\n\n| Pattern            | What it looks like                                                                | Fix                                                                               |\n| ------------------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |\n| Binary contrast    | \"It is not X, it is Y\", \"not only X but Y\", \"the question is not X, it is Y\"      | State the point. Keep only when the contrast is a real distinction.               |\n| Throat-clearing    | \"Here is the thing\", \"The truth is\", \"It is worth noting that\", \"Let us be clear\" | Delete the setup. The next sentence works alone.                                  |\n| Faux insight       | \"What nobody tells you\", \"the part everyone misses\", \"what most people get wrong\" | Make the claim stand on its own.                                                  |\n| Colon reveal       | \"The reason: retrieval.\", \"The best part: it is free.\"                            | Write the sentence. Keep the colon for real lists and labels.                     |\n| Rhetorical setup   | \"What if I told you\", \"Think about it\", a question answered in its own paragraph  | State the point. (Question-format H2 **headings** are required and are not this.) |\n| Negative listing   | \"Not a tool. Not a feature. A shift.\"                                             | Say what it is.                                                                   |\n| Dramatic fragments | \"That is it. That is the whole thing.\" \"And speed. And scale.\"                    | Join them when the fragments are decoration rather than emphasis.                 |\n| Forced trio        | three items chosen for cadence when two carry the meaning                         | Cut the filler item. Lists of any natural length are fine.                        |\n| False range        | \"from startups to enterprises\", \"from A to Z\" where the endpoints are not a scale | Name the actual cases.                                                            |\n\n## Mechanical diction\n\n- **Banned outright**, because `agentblog audit` fails the post on them: \"delve\",\n  \"leverage\", \"robust\", \"seamless\", \"landscape\", \"tapestry\". A legitimate\n  technical use of \"landscape\" almost never appears in a blog post. Rewrite.\n- **Fake-strong verbs**: \"serves as\", \"stands as\", \"boasts\", \"features\", \"offers\".\n  Usually \"is\" or \"has\" is clearer, and often a specific verb is better than both.\n- **Synonym cycling**: rotating \"crawler\", \"bot\", \"agent\", \"system\" for one thing\n  because repetition feels wrong. Repeat the clearest term. Section 5 of the\n  writing procedure requires this anyway, since a retrieved chunk arrives without\n  the sentence that established the synonym.\n- **Swollen phrases**: \"in order to\" is \"to\". \"due to the fact that\" is \"because\".\n  \"has the ability to\" is \"can\". \"at this point in time\" is \"now\".\n- **Stacked hedging**: \"could potentially\" is \"could\". Keep exactly the\n  uncertainty the evidence supports, and no layers on top of it.\n- **Chatbot residue**: \"Of course\", \"I hope this helps\", \"Let me know if\", a note\n  about a knowledge cutoff. None of it belongs in a published post.\n\n## Rhythm and structure\n\nUniform sentence length is the most reliable signal that nobody read the draft\naloud. Human paragraphs vary because meaning varies: a complicated idea runs\nlong, and the sentence that lands the point is short.\n\nDo not alternate lengths mechanically. That produces a different pattern, not an\nabsence of one. Instead:\n\n- Read each paragraph aloud in your head. Where you run out of breath, split.\n  Where three sentences in a row have the same shape, rewrite the middle one.\n- End a section on its shortest sentence when the section has a point to land.\n- Keep fragments and long sentences that carry voice. Fix the ones that are\n  accidents.\n\nStructure carries the same risk. If every H2 section opens with a capsule, then a\ndefinition, then an example, then a caveat, the post reads as generated even when\nevery sentence is fine. The capsule is required. Everything after it should follow\nthe material.\n\n## Endings\n\n- **No fake-profound closer.** A final metaphor or aphorism that inflates the\n  preceding point is the single most common tell in a post that is otherwise good.\n- **No summary recap.** \"In conclusion\" and a paragraph repeating what the reader\n  just read. Cut it.\n- End on the strongest concrete thing the post established: the number, the\n  finding, or the next action. If the post has an FAQ, the FAQ is the ending.\n\n## What not to fake\n\nThe failure mode of trying to write like a person is inventing a person.\n\nNever manufacture any of the following to make prose sound human:\n\n- A personal anecdote, a first-person experience, or a story about \"a client we\n  worked with\".\n- An opinion, a preference, or a reaction the source material does not support.\n- Humour, self-deprecation, or an aside about the writing process.\n- A specific detail added for texture. \"On a Tuesday in March\" is a fabrication\n  when nothing establishes the date.\n\nA post can be direct, concrete, and confident without any of that. The\ncredibility this product sells comes from verified evidence and a named author\nwith a real bio, not from a voice pretending to have lived something.\n\nIf the user supplies real experience, use it, and attribute it to them.\n\n## The five questions\n\nRun these against the finished draft. A \"no\" is a revision, not a note.\n\n1. Does every claim, number, quotation, and source come from something actually\n   fetched, and is every one of them in `citations[]`?\n2. Would the named author recognise this as their own writing?\n3. Does each paragraph carry information, reasoning, or necessary transition, and\n   would deleting it lose something?\n4. Read aloud, does any run of three sentences share a shape?\n5. Does the post end on a fact rather than on a flourish?\n",
      "type": "registry:file",
      "target": "~/.claude/skills/write-blog-post/references/voice.md"
    },
    {
      "path": "registry/agent/skills/write-blog-post/references/checklist.md",
      "content": "# Pre-publish checklist\n\n**Run `npx agentblog audit <slug> --verbose` first.** This file holds only what that\ncommand cannot check: judgment, truthfulness, and anything that needs a rendered\npage. Duplicating a mechanical check here would give you two answers to one\nquestion and invite you to trust the one you produced by reading.\n\nReport each item as pass or fail **with the observed value**. \"Sections: 190, 240,\n310 words, one fail\" is a report. \"Sections checked\" is not.\n\nDo not report the post as ready while any item fails. List the failures, say what\neach would take to fix, and stop.\n\n> **License.** This file is prose documentation, licensed CC BY 4.0. See\n> `LICENSE-CONTENT` in the AgentBlog repository.\n\n---\n\n## Evidence, which is the part that matters\n\n- [ ] Every source in `citations[]` was **actually fetched during this session**.\n      Name each one and say what it said. A citation copied from memory is a\n      fabrication with a URL attached.\n- [ ] Every number in the post appears in the source it is attributed to, at the\n      precision stated. Quote the sentence you read it in.\n- [ ] Every quotation is attributed to a named person or organisation, and appears\n      on the page you fetched.\n- [ ] Each `citations[].kind` matches what the source actually is:\n      `peer-reviewed`, `official-docs`, `industry`, `news`, `other`.\n- [ ] The evidence grade is carried in the prose as well as the frontmatter, so a\n      reader knows a correlational figure is correlational.\n- [ ] No claim is phrased as evidence without a source (\"studies show\", \"experts\n      agree\", \"it is widely believed\"). Report any you removed.\n\n## Structure and retrieval\n\n- [ ] Each H2 section is 150 to 300 words. Report the count for each.\n- [ ] Each H2 section makes complete sense read on its own, with no reliance on a\n      definition, table, or antecedent from an earlier section.\n- [ ] Entity names are repeated rather than replaced with pronouns across section\n      boundaries.\n- [ ] Heading levels descend without skipping. No H2 followed directly by an H4.\n- [ ] A table of contents renders if the post exceeds roughly 1,200 words.\n- [ ] Comparison or specification data is in a real markdown table, not narrated\n      in prose.\n- [ ] Every chart or diagram image is paired with its underlying numbers in a\n      table nearby.\n- [ ] No article body content sits behind a JavaScript-mounted accordion or tab.\n\n## Frontmatter the audit cannot judge\n\n- [ ] The file name matches the slug the post publishes at. Report both values.\n      The adapter derives the slug from the file name, and a `slug` in frontmatter\n      silently overrides it.\n- [ ] `description` reads as a search result, not as a summary of a summary.\n- [ ] `relatedPosts` names posts that genuinely belong, in the order they should\n      appear.\n- [ ] `faq` entries are questions a reader would actually ask, and they render\n      visibly in the article. FAQ markup on invisible questions is a structured\n      data policy violation.\n- [ ] `heroAlt` describes what the image shows in plain language rather than\n      naming keywords.\n- [ ] The post is something the named author could credibly have written, given\n      the `bio` and `knowsAbout` in `content/authors.json`.\n\n## Links\n\n- [ ] Anchor text is descriptive and names the target topic. No \"click here\", no\n      \"read more\". Quote any anchor you rewrote.\n- [ ] The inbound link added to an existing post reads naturally in that post\n      rather than being bolted on. Name the post you edited and quote the sentence.\n- [ ] No internal link resolves through a redirect. Single hop or none.\n\n## Voice\n\nRun the five questions at the end of `voice.md` and report each. Summarised here so\nthis file is complete, answered there:\n\n- [ ] Every claim traces to something fetched.\n- [ ] The named author would recognise this as their own writing.\n- [ ] Every paragraph carries information, reasoning, or a necessary transition.\n- [ ] No run of three sentences shares a shape.\n- [ ] The post ends on a fact rather than on a flourish.\n\n## After deploy\n\nThese need a live URL, so they belong to `agentblog-audit` and `publish-blog-post`\nrather than to writing. Listed here so nobody assumes writing covered them.\n\n- [ ] `curl -s -A \"GPTBot\" \"$URL\"` returns a distinctive sentence from the article\n      body.\n- [ ] The JSON-LD `@graph` validates against the **raw HTML**, not the rendered DOM.\n- [ ] Core Web Vitals: LCP at or under 2.5s, INP at or under 200ms, CLS at or\n      under 0.1.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/write-blog-post/references/checklist.md"
    },
    {
      "path": "registry/agent/skills/refresh-blog-post/SKILL.md",
      "content": "---\nname: refresh-blog-post\ndescription: >\n  Refreshes an existing blog post: re-verifies every statistic and citation against\n  its source, replaces facts that have moved, and updates dateModified only when\n  the content actually changed. Use when asked to update or refresh a post, when a\n  post is stale or its stats are out of date, when a cited source has been revised,\n  or when agentblog audit --stale flags it.\nargument-hint: '[post slug]'\nallowed-tools: Read Write Edit Glob Grep WebSearch WebFetch Bash(npx agentblog *)\nlicense: MIT\ncompatibility: A Next.js project with AgentBlog installed. Needs web access to re-verify sources.\nmetadata:\n  package: agentblog\n  homepage: https://agentblog.dev\n---\n\n# Refresh an existing blog post\n\nRefreshing is not rewriting. The job is to find what has changed in the world since\nthe post was published and correct the post to match, then leave everything else\nalone. A refresh that rewrites prose which was already correct produces a large\ndiff with no information in it, and makes the real corrections harder to review.\n\n## The rule this skill exists to enforce\n\n**Touch `dateModified` only if the content actually changed.**\n\nBold, because it is the whole discipline. A `dateModified` that does not correspond\nto a real change is a trust-destroying signal, and a refresh tool that bumps the\ndate unconditionally is a machine for manufacturing exactly that signal at scale.\n\nFreshness is widely reported to correlate with citation. The specific percentages\nin circulation do not survive being traced, so do not quote one: the most repeated\nof them comes from a study whose publisher's domain no longer resolves. The\nqualitative claim is still a reason to genuinely update posts on a schedule. It is\nnot a reason to restamp them. The engines that reward freshness are the same ones\nthat can compare the date you claim against the content they already have.\n\nConcretely:\n\n- Fixed a number, replaced a dead citation, added a new section, corrected a claim:\n  **update `dateModified`**.\n- Fixed a typo, reflowed a paragraph, changed a hyphen, reformatted a table with\n  the same contents: **do not update `dateModified`**.\n- Verified every fact and found nothing had changed: **do not update\n  `dateModified`**, and say so in the report. \"Nothing needed changing\" is a\n  successful outcome of this skill, not a failure.\n\nIf you are unsure whether a change counts, ask whether a reader who had already\nread the post would want to know about it. If not, the date does not move.\n\n## The other rules, unchanged from writing\n\nThese apply to everything you add during a refresh:\n\n- **Never fabricate a statistic, a quotation, or a source.** If a number has moved\n  and you cannot verify the new one at a real source you fetched, remove the\n  precision and state the claim qualitatively. Do not update a figure to a\n  plausible newer figure. That is worse than leaving the old one, because the old\n  one at least has a source.\n- **Never invent experience.** No anecdote, no first-person story, no opinion the\n  sources do not support, added to make a rewritten passage read as human.\n- **Never use an em dash.** Not in new prose, not in a corrected sentence, not\n  anywhere. Use a comma, a colon, parentheses, or a full stop. Do not use a double\n  hyphen as a substitute.\n- No keyword stuffing, no padding, and none of \"delve\", \"leverage\", \"robust\",\n  \"seamless\", \"landscape\", \"tapestry\". `agentblog audit` fails the post on all of\n  them.\n\n## Procedure\n\n### 1. Read the post and its provenance\n\n- Read the post file and its frontmatter.\n- Note `datePublished`, `dateModified`, and how long ago that was.\n- List every `citations[]` entry, and every number, date, version, price, and\n  proper-noun claim in the body. That list is your work queue, and you will report\n  against it.\n- Check `content/research/` for this post's URL. If `dataforseo-research` has run,\n  it may already say what position this post holds, whether it fell without the\n  post changing, and which competitor page took the slot. A refresh aimed at a\n  measured decline is a different edit from a refresh aimed at stale citations,\n  and knowing which one this is before starting saves rewriting the wrong half.\n\n### 2. Re-fetch every cited source\n\nFor each entry in `citations[]`, `WebFetch` the URL and check three things:\n\n- **Does it still resolve?** A 404 or a redirect to a homepage means the citation\n  is dead. Find the current location of the same source, or replace the source, or\n  remove the claim. Do not leave a dead link.\n- **Does it still say what the post says it says?** Documentation gets rewritten,\n  studies get corrected, vendors quietly restate numbers. This is the check that\n  matters most and the one that is easiest to skip. Quote the sentence you read the\n  number in.\n- **Has it been superseded?** A newer edition, a follow-up study, a newer version\n  of the same document.\n\nRecord the outcome for each source.\n\n### 3. Re-run the post's searches\n\n`WebSearch` the post's target query and its H2 questions again. You are looking for\nfacts in the post that are now wrong, sub-questions that did not exist when the\npost was written and now do, and better sources for claims the post already makes.\n\n### 4. Apply the smallest correct change\n\n- Update the numbers that moved, with the new source.\n- Replace dead or superseded citations, and keep `citations[].kind` accurate to\n  what the replacement actually is.\n- Add a section only if a genuinely new sub-question needs answering, and write it\n  to the same standard as a new post: a 40 to 60 word capsule under the heading,\n  150 to 300 words, self-contained, entity names repeated rather than pronouns.\n- Leave prose that is still correct exactly as it is.\n\nDo not improve the writing while you are here. If the post needs a rewrite, say so\nand stop, rather than smuggling one in under a refresh.\n\n### 5. Decide the date, deliberately\n\nLook at the diff. If it contains only formatting, whitespace, or typo fixes, leave\n`dateModified` alone. Otherwise set it to now, in ISO 8601 **with a UTC offset**.\n\n`dateModified` must be greater than or equal to `datePublished`, and it must match\nthe visible `<time dateTime>` and the JSON-LD exactly. The block renders all three\nfrom frontmatter, so editing frontmatter is the only edit needed.\n\n### 6. Re-run the audit\n\n```bash\nnpx agentblog audit <slug> --verbose\n```\n\nA refresh can break what the original passed: a replaced link can be broken, a\nremoved paragraph can drop the internal link count below five, a new section can\narrive without a capsule. Report the output. Do not restate its checks by reading.\n\n### 7. Report\n\nState plainly:\n\n- Every source re-checked, with its outcome: unchanged, updated, dead, superseded.\n- Every claim that changed, with the old value, the new value, and the source.\n- Whether `dateModified` was touched, **and why or why not**.\n- Anything you could not verify, and what you did about it.\n\n## When to escalate instead of refreshing\n\nSay so and stop, rather than refreshing, when:\n\n- More than roughly half the post's claims are now wrong. That is a rewrite, and\n  `write-blog-post` owns it.\n- The post's central premise has been invalidated. Refreshing the numbers around a\n  dead premise produces a well-cited wrong article.\n- The post targets a query nobody asks any more. Consider a redirect to the post\n  that replaced it, rather than an update.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/refresh-blog-post/SKILL.md"
    },
    {
      "path": "registry/agent/skills/agentblog-audit/SKILL.md",
      "content": "---\nname: agentblog-audit\ndescription: >\n  Runs the AgentBlog pre-publish gate on a post or a deployed URL. Delegates the\n  deterministic checks to the agentblog CLI, then covers the four things no\n  script can: what a crawler literally receives, whether the JSON-LD graph is valid\n  against the raw HTML, whether every cited source actually says what the post\n  claims, and whether the prose reads as written by a person. Reports pass or fail\n  per assertion with the observed value. Use before publishing a post, before a\n  release, or when asked to audit, gate, or verify a post.\nargument-hint: '[post slug or URL]'\ndisable-model-invocation: true\nallowed-tools: Read Glob Grep WebFetch Bash(curl *) Bash(npx agentblog *)\nlicense: MIT\ncompatibility: A Next.js project with AgentBlog installed. The live sections need a deployed URL.\nmetadata:\n  package: agentblog\n  homepage: https://agentblog.dev\n---\n\n# Pre-publish audit\n\nManual invocation only, because an audit that runs opportunistically is an audit\nnobody reads. Run it when you mean to gate a publish.\n\nEvery assertion below reports **pass or fail with the observed value**. \"JSON-LD\nvalidates\" is a wish. \"`author` is `{ \"@id\": \"https://…#person\" }`, pass\" is a\ncheck.\n\n**Do not report the post as ready while any assertion fails.**\n\n## 1. Run the deterministic half first\n\n```bash\nnpx agentblog audit <slug> --verbose\nnpx agentblog doctor --verbose\n```\n\nBetween them these cover the answer capsule and its length, links inside capsules,\nquestion-format headings, heading ids, title and description lengths, date offsets\nand ordering, evidence presence, internal link counts, broken internal links,\norphan status, hero alt text, copy style, frontmatter validity, and every install\nand route check.\n\nPaste the observed output. **Do not re-check any of it by reading.** A second,\nsofter answer to a question a script already answered is how a failing check gets\nreported as a pass, and reading is the softer answer every time.\n\nBoth exit non-zero on an error finding and zero on a warning, so read the findings\nrather than the exit code. A clean exit with three warnings is not a pass.\n\nNote what `audit` has no flags for. Every check runs on every post, on purpose:\nthe checks a writer would switch off are the ones that catch the expensive\nmistakes. Narrow the input with a slug or `--dir`, never the checks.\n\nSections 2 through 6 are what those commands cannot reach.\n\n## 2. The raw crawler fetch, which nothing replaces\n\n```bash\ncurl -s -A \"GPTBot\" \"$URL\" | grep -q \"$DISTINCTIVE_SENTENCE\"\ncurl -s -A \"GPTBot\" \"$URL\" | head -c 4000 | grep -q \"<title>\"\n```\n\nKeep this check exactly as it is, with no tooling around it. Its entire value is\nthat it uses none: it tests what a non-JavaScript crawler literally receives, with\nno bundler, no browser, and no framework in the path. Every other instrument in\nthis file tells you what the system believes. This one tells you what went over the\nwire.\n\nPick the distinctive sentence from the middle of the article body, not from the\ncapsule or the title, so a page that renders only its shell fails.\n\nThe second assertion, `<title>` inside the first 4000 bytes, is checking placement\nrather than existence. Next.js appends deferred metadata into `<body>` for user\nagents it does not classify as HTML-limited, so a `<title>` that appears late in\nthe document is a `<title>` the crawler read as body text.\n\nFor the multi-bot sweep and CDN detection, `npx agentblog doctor --url $URL` already\nprobes GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot, and Googlebot and names the\nCDN. Run it from outside the deployment's own network: a request originating inside\ncan bypass the CDN rule the check exists to find. A 403, a 429, or a challenge page\nis a **blocking** failure, not a warning.\n\n## 3. Better instruments than a full build\n\nDo not shell out to `next build` to answer \"does this compile\" or \"is the article in\nthe first response byte\". Two faster instruments exist:\n\n- **The Next.js MCP server at `/_next/mcp`** exposes the running dev server's\n  routes, server logs, and compilation issues. Its `get_compilation_issues` and\n  `compile_route` tools answer the compilation question in the time a build spends\n  starting up.\n- **`agent-browser`** (https://github.com/vercel-labs/agent-browser) exposes DOM,\n  console, network, and Web Vitals as structured text, including which Suspense\n  boundaries are still pending. That is a better instrument for the Core Web Vitals\n  thresholds and for \"what is actually in the first chunk\" than anything we would\n  write.\n\nUse them. Keep the curl.\n\n## 4. Schema assertions\n\nRun these against the **raw HTML** from the curl above, never against the rendered\nDOM. A DOM-based validator passes markup a crawler never receives.\n\n| Assertion                                                                                     | Why it is here                                                                                                                                                                                       |\n| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Every marked-up fact is visible on the page                                                   | \"Don't mark up content that is not visible to readers of the page\" is the single most enforced structured data policy, and a violation can earn a manual action that removes rich-result eligibility |\n| If `FAQPage` is present, the FAQs render in the HTML                                          | Same policy, and the most common way blogs trip it                                                                                                                                                   |\n| `author` is a linked `Person` node with `@id` and `url`, never a bare string                  | A bare string loses the entity link that E-E-A-T depends on                                                                                                                                          |\n| `author.name` contains no job title, honorific, or publisher name                             | Explicit in Google's Article guidance. `Author.jobTitle` exists for exactly this                                                                                                                     |\n| Every `sameAs` entry is an absolute URL, not a handle                                         | A handle disambiguates nothing                                                                                                                                                                       |\n| `Organization.logo` has `width` and `height`                                                  | Required shape, and the config carries both                                                                                                                                                          |\n| `datePublished` and `dateModified` carry a UTC offset and match the visible `<time dateTime>` | Three sources of the same date is three chances to disagree. Report the three observed values side by side, not a boolean                                                                            |\n| `image` is at least 50,000 pixels and supplied at 16:9, 4:3, and 1:1                          | Google's stated recommendation for Article images                                                                                                                                                    |\n| Exactly one `<script type=\"application/ld+json\">` on the page, containing one `@graph`        | Two serialization points is how a graph starts contradicting itself                                                                                                                                  |\n| `BlogPosting`, `WebPage`, `Person`, and `BreadcrumbList` are all present and linked by `@id`  | A disconnected node describes an unrelated thing rather than this page                                                                                                                               |\n| The final `BreadcrumbList` item has no `item` property                                        | Correct for the current page, and flagged as an error by validators when present                                                                                                                     |\n\nThen run both external validators and report both, because they answer different\nquestions:\n\n- Rich Results Test (https://search.google.com/test/rich-results): rich-result\n  eligibility.\n- Schema Markup Validator (https://validator.schema.org/): full vocabulary validity.\n\n## 5. Evidence, which is the assertion with no instrument\n\n`agentblog audit` can tell you a number has no citation. It cannot tell you a\ncitation is wrong, and a confidently wrong citation is worse than a missing one.\n\nFor each entry in `citations[]`:\n\n- **Fetch the URL.** Report whether it resolves, and whether it redirects.\n- **Find the claim in it.** Quote the sentence the post's number came from. If you\n  cannot find it, the assertion fails, regardless of how plausible the number is.\n- **Check the grade.** `kind` should match what the source actually is:\n  `peer-reviewed`, `official-docs`, `industry`, `news`, `other`. An industry blog\n  filed as `peer-reviewed` is a misrepresentation the reader cannot see.\n\nReport every source with its outcome. This section is slow and it is the reason the\naudit exists.\n\n## 6. Copy style and voice\n\n`agentblog audit` covers the mechanical bans: the em dash, the double hyphen used\nas a dash, \"delve\", \"leverage\", \"robust\", \"seamless\", \"landscape\", \"tapestry\", the\nstock opener, and the \"it is not just X, it is Y\" construction. Report its result\nand move on.\n\nWhat is left needs reading:\n\n- No claim phrased as evidence without a source. \"Studies show\", \"experts agree\",\n  \"industry reports suggest\".\n- No invented experience: no anecdote, no first-person story, no opinion the\n  sources do not support.\n- No closing flourish. No summary recap, no final metaphor inflating the point.\n- No run of three sentences sharing a shape.\n\nThe full catalogue is in the `write-blog-post` skill's `references/voice.md`.\n\n## 7. Publish-path assertions\n\n- The publish webhook revalidates `/sitemap.xml` and `/feed.xml` as well as the\n  post and index paths. Both are cached route handlers, so a publish that skips\n  them pings IndexNow for a URL the site's own sitemap does not list.\n- `revalidateTag` on the publish path uses `{ expire: 0 }`, not `'max'`. `'max'` is\n  stale-while-revalidate, which invites the crawler you just summoned to be the\n  visit that receives the stale body.\n- No internal link resolves through a redirect. AI crawlers handle redirect chains\n  poorly: Vercel and MERJ measured ChatGPT spending 14.36% of its fetches following\n  redirects and 34.82% of them on 404 pages\n  (https://vercel.com/blog/the-rise-of-the-ai-crawler, 17 December 2024).\n\n`publish-blog-post` owns the rest of the publish sequence, including the IndexNow\nresponse code. Hand off rather than duplicating it.\n\n## 8. Fleet-level checks\n\n```bash\nnpx agentblog audit --stale --days 90\nnpx agentblog audit --crawlers ./access.log\n```\n\n`--stale` ranks posts by `dateModified` age weighted by inbound internal links, so\nthe highest-authority stale posts surface first. Hand those to `refresh-blog-post`,\nand note that skill's rule: a refresh updates `dateModified` only when the content\nactually changed.\n\n`--crawlers` parses a server or CDN access log and reports hits per bot per week.\nA post nothing fetched is not a content problem.\n\n## Reporting\n\nGroup findings by severity. A finding that is silently wrong outranks a finding\nthat is loudly wrong, because on this product every failure worth catching is\nsilent.\n\n1. **Blocking**: a crawler receives no body text, a CDN returns 403, the article\n   body is client-rendered, marked-up content is not visible on the page, a cited\n   source does not contain the claim.\n2. **Error**: schema assertions, date integrity, orphan post, missing capsule,\n   anything `agentblog audit` reports as an error.\n3. **Warning**: capsule length off by a few words, link count outside the range,\n   copy style, voice.\n\nReport every assertion, including the ones that passed. An audit that lists only\nfailures gives no evidence it ran the rest.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/agentblog-audit/SKILL.md"
    },
    {
      "path": "registry/agent/skills/publish-blog-post/SKILL.md",
      "content": "---\nname: publish-blog-post\ndescription: >\n  Publishes a finished AgentBlog post and proves it landed: gates on agentblog\n  audit, ships the change, revalidates the post, index, sitemap, and feed, submits\n  to IndexNow, reports the real response code, then verifies as a crawler that the\n  live URL serves the article body. Use before publishing, shipping, or going live\n  with a post, when asked to submit a post to IndexNow, or when a published post is\n  missing from the sitemap or serving stale content.\nargument-hint: '[post slug]'\ndisable-model-invocation: true\nallowed-tools: Read Glob Grep Bash(curl *) Bash(npx agentblog *) Bash(git status *) Bash(git diff *)\nlicense: MIT\ncompatibility: A deployed AgentBlog site. Needs INDEXNOW_KEY and AGENTBLOG_REVALIDATE_SECRET.\nmetadata:\n  package: agentblog\n  homepage: https://agentblog.dev\n---\n\n# Publish a post, and prove it published\n\nManual invocation only. Publishing pings an external service and puts a URL in\nfront of crawlers, and an agent should not decide on its own that a draft looks\nready.\n\nEverything in this sequence has a silent failure mode. IndexNow answers `403` for\nan invalid key and `422` for a host mismatch, and from the caller's side both look\nexactly like success. A sitemap that was not revalidated still returns `200`, just\nwithout the new post in it. The whole skill is the habit of reading the code\ninstead of the absence of an error.\n\n```\n- [ ] 1. Gate\n- [ ] 2. Confirm the post is actually publishable\n- [ ] 3. Ship it\n- [ ] 4. Revalidate and submit\n- [ ] 5. Read the IndexNow code\n- [ ] 6. Verify as a crawler\n- [ ] 7. Report\n```\n\n## 1. Gate\n\n```bash\nnpx agentblog audit <slug> --verbose\nnpx agentblog doctor --verbose\n```\n\n**Both must be clean, warnings included.** They exit non-zero on an error finding\nand zero on a warning, so a successful exit code with three warnings under it is\nnot a pass. Read the findings.\n\nDo not publish past a finding by deciding it is minor. Publishing is the step that\nmakes a mistake expensive: once a URL is submitted, a correction needs a second\nsubmission and the first version may already have been read.\n\nIf the post has not been through `agentblog-audit`, run that first. It covers the\nassertions the CLI cannot make, including whether the cited sources actually say\nwhat the post claims.\n\n## 2. Confirm the post is actually publishable\n\n- `draft` is `false` or absent. A `draft: true` post is excluded from every query,\n  the sitemap, and the feed, so publishing it does nothing and reports success.\n- `datePublished` is not in the future.\n- `dateModified` is greater than or equal to `datePublished`, and both carry a UTC\n  offset.\n- The slug matches the file name. Report both, because a `slug` in frontmatter\n  silently overrides the file name, and you are about to submit a URL built from\n  the frontmatter value.\n- `git status` is clean apart from this post and the file you edited to add an\n  inbound link. Publishing sweeps up whatever else is staged.\n\n## 3. Ship it\n\nMerge or deploy by whatever route the project uses. Wait for the deployment to\nfinish before step 4. Revalidating a route the new build has not replaced yet\ncaches the old body, and the next crawler visit is the one that reads it.\n\nIf `agentblog.config.ts` sets a `deployHook`, the adapter's `prerenderStrategy` is\n`'deploy-hook'` and the deploy is what regenerates the static pages. Without the\nhook configured, publishing without a rebuild serves stale content and reports\nnothing.\n\n## 4. Revalidate and submit\n\n```bash\nnpx agentblog ping <slug>\n```\n\nOne command does the whole publish path. It revalidates `/blog/<slug>`, `/blog`,\n`/sitemap.xml`, and `/feed.xml`, then submits the post URL to IndexNow and prints\nthe real response code with its meaning and a remedy.\n\nThe two metadata routes are in that list because they are the ones that get\nforgotten. `sitemap.xml` and `feed.xml` are cached route handlers, and\n`generateStaticParams` does not re-run during ISR, so a publish path that skips\nthem pings IndexNow for a URL the site's own sitemap does not list. That is the\nworst possible combination: you have invited a crawler to a page your own site\ndoes not claim to have.\n\nIt exits non-zero when any step you asked for did not happen, including a missing\ncredential. A missing `AGENTBLOG_REVALIDATE_SECRET` or `INDEXNOW_KEY` is an error\nrather than a warning, because a publish step that silently submits nothing and\nreports success is the failure this command exists to make loud. Use\n`--skip-revalidate` or `--skip-indexnow` only when you actually mean to skip one.\n\n## 5. Read the IndexNow code\n\n`ping` prints it. Report it verbatim rather than reporting \"submitted\".\n\n| Code  | Meaning                            | What to do                                                                    |\n| ----- | ---------------------------------- | ----------------------------------------------------------------------------- |\n| `200` | Submitted                          | Nothing.                                                                      |\n| `202` | Accepted, key validation pending   | Confirm the key file is actually deployed at the domain root. Re-check later. |\n| `400` | Bad payload format                 | A bug in the tooling. Report it.                                              |\n| `403` | Key invalid or missing at the root | The key file is not reachable at `https://<host>/<key>.txt`. Deploy it.       |\n| `422` | URL and host do not match          | The submitted URL is not on the host that owns the key. Check `siteUrl`.      |\n| `429` | Rate limited                       | Wait, then submit fewer URLs.                                                 |\n\n`403` and `422` are the two that matter, because they are indistinguishable from\nsuccess unless somebody reads the number. The IndexNow limit is 10,000 URLs **per\nrequest**, not per domain per day, so batching is rarely the problem.\n\n## 6. Verify as a crawler\n\nThe publish is not finished until a crawler can read the post.\n\n```bash\ncurl -s -A \"GPTBot\" \"https://<host>/blog/<slug>\" | grep -q \"$DISTINCTIVE_SENTENCE\"\ncurl -s \"https://<host>/sitemap.xml\" | grep -q \"/blog/<slug>\"\ncurl -s \"https://<host>/feed.xml\" | grep -q \"/blog/<slug>\"\n```\n\nPick the distinctive sentence from the middle of the article body, not from the\ncapsule or the title, so a page that serves only its shell fails.\n\nRun these **from outside the deployment's own network**. A request originating\ninside can bypass the CDN rule that would block a real crawler.\n\nThen:\n\n```bash\nnpx agentblog doctor --url https://<host>/blog/<slug>\n```\n\nThat probes the URL as GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot, and\nGooglebot and names any CDN in front of it. A 403 or a challenge page for any of\nthem is a blocking failure, and it is the single most common reason a correctly\nbuilt blog gets no citations.\n\nIf the sitemap does not contain the slug, the revalidation did not take. Re-run\nstep 4 rather than assuming propagation.\n\n## 7. Report\n\n- The audit and doctor results, with observed values.\n- The IndexNow response code and its meaning.\n- Whether `/sitemap.xml` and `/feed.xml` now contain the URL, quoted.\n- The crawler fetch result per user agent, with the sentence you tested with.\n- Anything skipped, and why.\n\n**Do not report the post as published while any of those is unverified.** \"Deployed\"\nand \"published\" are different claims, and only one of them has been tested here.\n",
      "type": "registry:file",
      "target": "~/.claude/skills/publish-blog-post/SKILL.md"
    },
    {
      "path": "registry/agent/AGENTS.agentblog.md",
      "content": "<!-- agentblog:start -->\n\n## Blog (AgentBlog)\n\nPosts live in `content/blog/*.mdx`. Config: `agentblog.config.ts`. Authors:\n`content/authors.json`. Categories: `content/categories.json`.\n\nSeven AgentBlog skills cover the lifecycle. Use them by name rather than working\nfrom memory: they carry the schema contract, the citation rules, and the checks,\nand hand-doing any of these steps silently skips all three.\n\n| Task                                     | Skill                 |\n| ---------------------------------------- | --------------------- |\n| Finish the install, make the blog ours   | `agentblog-setup`     |\n| Find out what to write, with real data   | `dataforseo-research` |\n| Decide what to write and how it links up | `plan-blog-content`   |\n| Write a post                             | `write-blog-post`     |\n| Update an existing post                  | `refresh-blog-post`   |\n| Gate a post before it ships              | `agentblog-audit`     |\n| Ship it and confirm it landed            | `publish-blog-post`   |\n\n- Never fabricate a statistic, a quotation, or a source. If a number cannot be\n  verified at a real source that was actually fetched, state the claim\n  qualitatively instead. Never invent an anecdote, a first-person story, or an\n  opinion to make prose read as human.\n- Never use an em dash, in a post or anywhere else in this repository. Use a comma,\n  a colon, parentheses, or a full stop. `agentblog audit` fails on the em dash\n  character `U+2014` and on a double hyphen used as a dash.\n- Never remove or narrow `htmlLimitedBots` in `next.config.ts`. The value replaces\n  Next.js's default bot list rather than extending it, so it must stay a superset of\n  that list plus the AI crawlers. Narrowing it breaks Google, Bing, and social\n  previews as well as AI citation.\n- Never add `'use client'` to anything in the article render path. Only\n  `TableOfContents` and `ShareButtons` may be client components, and both render\n  meaningful content server-side first.\n- `generateStaticParams` in `app/blog/[slug]/page.tsx` must return every slug, never\n  a slice and never a page.\n- `dateModified` changes only when the content actually changed. An unearned date\n  bump is a trust-destroying signal, not a freshness signal.\n- Every route that sets `openGraph` or `robots` must spread the shared defaults from\n  `lib/metadata.ts`. Metadata merge is shallow, so defining the object at all\n  replaces the parent's entire object.\n- JSON-LD is built only in `lib/schema.ts` and serialized only by `renderJsonLd`.\n  Do not add a second `<script type=\"application/ld+json\">`.\n- Run `npx agentblog audit` before committing a post, and `npx agentblog doctor`\n  after changing config. Both exit non-zero on an error finding, so read the exit\n  code rather than the absence of a stack trace.\n\n<!-- agentblog:end -->\n",
      "type": "registry:file",
      "target": "~/AGENTS.agentblog.md"
    }
  ],
  "docs": "Skills installed. AGENTS.agentblog.md is a fragment, not a replacement for your AGENTS.md. Run `npx agentblog@latest doctor --fix` to merge it into your real AGENTS.md, outside the block Next.js manages, and to finish wiring next.config.ts. Then ask your agent to finish the setup.",
  "categories": [
    "blog",
    "agents",
    "claude-code"
  ],
  "type": "registry:block"
}