qiaomu-seo: an Agent Skill that audits SEO layer by layer instead of scoring pages

The problem qiaomu-seo targets: SEO tools that score instead of diagnose

Most SEO checkers count title characters, H1 tags and keyword density, then hand back a number. qiaomu-seo's README draws the line explicitly: it is not that kind of scorer. It models the search pipeline as an ordered chain, crawler access and URL discovery, then fetching and JavaScript rendering, then indexability, then canonical and hreflang, then page relevance and search intent, then internal linking and information architecture, then measurement of search performance. The claim is that a failure anywhere in that chain produces the same symptom (a page missing from results) and that only the layer tells you which fix matters.

That framing sets the audience. It is for engineers and technical marketers who can act on a diagnosis: someone with repository access to a Next.js site, someone holding a Search Console export, someone planning a domain migration. It is not for a store owner looking for a monthly ranking report, because the skill does not produce one and says so.

The README lists the concrete problem classes the skill is built around. Pages that will not index or index abnormally, where it checks robots, status codes, rendering, index directives, canonical tags, sitemap entries, internal-link discovery and Search Console evidence to locate which layer is blocking. Organic traffic declines, sliced by page, query, country, device, search type and time, to separate technical faults from demand shifts, content decay, migration effects and measurement-definition problems. Keywords with no landing page, handled by intent research that produces a keyword-to-page map and content briefs so two pages stop competing for one query. Technical fixes to canonical, redirects, sitemap, robots, metadata, JSON-LD, hreflang, pagination, internal links and JavaScript rendering. Site relaunches and migrations, with a URL inventory, redirect map, consistency checks across canonical, hreflang and sitemap, launch monitoring and rollback boundaries. Ecommerce, international and large sites, where it samples templates to report actual coverage of product variants, category and filter pages, and programmatic pages. And AI-search visibility, checked separately for Google AI Overviews and AI Mode, ChatGPT Search, Copilot and Perplexity.

What ties these together is a refusal to merge categories. Traditional SEO, model training and AI citation are treated as different things, and the README says the skill will not conflate them. That is a narrow position, and it is the reason the output is a ranked problem list rather than a score.

How the skill reasons: observation, inference, and missing evidence are labelled separately

The mechanism is a set of rules about what may be asserted. Every conclusion the skill reaches is tagged as directly observed, reasonably inferred, or lacking evidence. Impact and confidence are expressed as separate dimensions rather than collapsed into a single priority score. The README states plainly that the skill does not invent search volume, keyword difficulty, rankings, traffic or competitor data, and does not promise rankings, indexing, rich results or AI citations.

The repository layout backs this up. There is a data/ directory holding something the README calls data/seo-source-registry.json, described as a registry of 33 official sources from Google, Bing, IndexNow, Schema.org, web.dev, OpenAI, Microsoft and Perplexity, each with a source, a review date and a feature lifecycle. There is a scripts/ directory with Python validators, a schemas/ directory that the audit validator presumably checks against, and an evals/ directory with trigger cases. The knowledge base is not free text the model can drift away from; it is a registry with dates that a script can reject.

One design choice worth noting: the skill treats Schema.org syntax validity, eligibility for a Google search feature, and actual rich-result display as three separate levels. That distinction is where a lot of SEO advice quietly goes wrong, and putting it in the README rather than in a footnote is a deliberate position. The same separation appears for IndexNow, where the README distinguishes notification receipt, crawling, and indexing outcome. A third appears for AI crawlers, where OAI-SearchBot, GPTBot, ChatGPT-User and other agents are given different purposes and control boundaries.

The inputs and outputs are stated as a table. Given a site URL, code, rendered page, sitemap or crawl file, the skill returns a technical SEO issue list ranked by impact, confidence, effort and dependencies. Given Search Console, Bing Webmaster Tools, analytics or server logs, it returns a segmented traffic and index diagnosis with candidate causes, missing evidence and the next verification step. Given a migration plan or old and new URL inventories, it returns a URL map plus redirect, canonical, hreflang and sitemap consistency checks and a monitoring plan. Given explicitly authorized site code, it returns a minimal fix, a change log, test results, rollback information and a recheck point.

Installing qiaomu-seo and running a first read-only audit

The README gives a single install line for Codex, Claude Code, Cursor and other clients that support Agent Skills. It requires Node.js and npm/npx; the README tells you to check with node --version and npx --version and to get an LTS build from nodejs.org if Node is missing.

npx skills add joeseesun/qiaomu-seo

After installing, the README offers a second command to confirm the skill has been discovered by the client.

npx skills add joeseesun/qiaomu-seo --list

With the skill visible, the first real use is a prompt rather than a command. The README lists phrasings you can type directly. For a read-only diagnosis of an indexing problem, this is one of them.

抓取并渲染这个网站，找出为什么产品页没有进入 Google 索引。

The README states that audit, diagnosis and comparison requests are read-only by default: the skill will not modify code, index controls, webmaster platforms or live data. Fixes and implementations run only after explicit authorization, and the README says they come with pre-change evidence, test results, rollback information and a monitoring window. So the first session should end with a ranked problem list, not a commit.

Other prompts in the README cover a Search Console export sliced by page and query over a 90-day window, keyword research and a keyword-to-page map for a SaaS product with unknown metrics marked as unknown, a Next.js fix for canonical, sitemap, robots and Product JSON-LD with rendered output verification, a full URL redirect map for a migration, an audit of product variants, faceted navigation, pagination and hreflang on a multilingual ecommerce site, separate crawl and visibility checks for Google AI Overviews, ChatGPT Search and Perplexity, and an SEO experiment design with treatment group, control group, observation window and stop rules. Pick the one that matches your problem; the phrasing signals the mode, which is what keeps the first run read-only.

The verification scripts are the part that keeps the skill honest

A skill that tells a model how to reason about SEO is only as good as the checks around it. The README's validation section lists five Python commands, all run from a checkout rather than through the agent.

python3 scripts/validate_skill.py .
python3 scripts/validate_knowledge.py . --strict-stale
python3 scripts/validate_audit.py path/to/audit.json

The first validates the skill package itself. The second checks the knowledge base and, with --strict-stale, fails on stale entries rather than warning. The third validates an audit document against the schemas. The README also references two scripts from a separate qiaomu-meta-skill package.

python3 ~/.agents/skills/qiaomu-meta-skill/scripts/export_skill_ir.py . --output reports/skill-ir.json
python3 ~/.agents/skills/qiaomu-meta-skill/scripts/trigger_eval.py . --cases evals/trigger_cases.json --output reports/trigger-eval.json

Those two export an intermediate representation and run a trigger evaluation against evals/trigger_cases.json. They live under ~/.agents/skills/qiaomu-meta-skill/, so they are not in this repository and you need that other skill installed to run them.

The strict-stale flag is the interesting one. It implies the knowledge base carries expiry dates and that a rule can be mechanically blocked once its review date passes. That is a stronger claim than most SEO documentation makes, and it is testable: open data/seo-source-registry.json and see what a record contains. If the registry is thin, the flag is decoration. If each record carries a source URL, a review date and a lifecycle state, then a stale assertion fails a build instead of quietly reaching a client deliverable, which is the failure mode that makes SEO advice expensive.

Where qiaomu-seo is the wrong tool

The README's own boundaries section is unusually candid. The skill does not cover paid search campaigns, App Store Optimization, spam link building, hidden content, keyword stuffing, or ranking guarantees. If your problem is one of those, the skill will not help and will say so rather than improvise.

The harder limitation is environmental. This is an Agent Skill, not an application. It has no dashboard, no scheduled crawl and no stored history of its own. Its output lives in the conversation or in files you ask it to write. If you have no Search Console access and no keyword tool, the README's troubleshooting table tells you what happens: the skill falls back to qualitative research and marks search volume, keyword difficulty and coverage as unknown. That is honest, but it also means a team without first-party data gets a smaller deliverable than a team with it, and the gap is not something the skill can close on its own.

Two more edges matter. The README warns against using site: queries as a complete index report and points to Search Console URL Inspection instead, so anyone expecting a quick index count will be redirected. And it separates Lighthouse, which it calls lab diagnostic data, from Core Web Vitals field data from CrUX, Search Console or real-user measurement. A perfect Lighthouse score with failing field metrics is a case the README names directly, and the skill will not treat the lab number as the answer.

There is also a static-rendering trap the README flags. If a static fetch cannot see JSON-LD, the troubleshooting table says to inspect the rendered DOM or use the Rich Results Test. That means the quality of a qiaomu-seo audit is bounded by the fetching and rendering capability of the client it runs in. An agent that cannot execute JavaScript will produce a different, and weaker, diagnosis than one that can, and the README does not claim otherwise.

How qiaomu-seo differs from commercial SEO crawlers

Tools like Screaming Frog, Sitebulb or Ahrefs Site Audit are crawlers with a user interface. They fetch a site on your behalf, store every URL in a database, apply a fixed rule set, and show you a table. The rule set is theirs, and it changes on their release schedule, which you do not control and usually cannot inspect.

qiaomu-seo inverts that. There is no crawler binary and no stored crawl. The agent does the fetching and rendering through whatever it has available, and the rules live in a registry file in the repository with source URLs and review dates. You can read the rule, check the source, and see when it was last reviewed. You can also run validate_knowledge.py --strict-stale and have stale rules fail the build.

The trade-off is real in both directions. A crawler gives you a reproducible crawl with a timestamp and a diffable URL list; qiaomu-seo does not, because it does not persist a crawl. qiaomu-seo can reason about a Search Console export, a migration plan or a Next.js codebase in the same session; a crawler cannot. If your workflow depends on comparing crawl A to crawl B six months apart, the crawler is the right instrument. If your workflow depends on explaining why a specific page dropped and what to change in the repository, the skill's layer-by-layer model is closer to the question.

There is a second comparison the repository itself invites. The README says the design rationale and a comparison against competing skills live in reports/creation-handoff.md. That file is the place to check before assuming the rule set matches your priorities, because a skill's value is mostly its opinions, and the handoff document is where those opinions are argued rather than asserted.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-08-03. The README documents a 1.2 capability upgrade that added international SEO, ecommerce, image and video search, programmatic SEO, content governance, performance measurement and SEO experiment modules, plus the separation of OAI-SearchBot, GPTBot, ChatGPT-User and other AI crawlers. The design rationale and the comparison against competing skills are said to live in reports/creation-handoff.md, which is worth reading before you decide the rule set matches your priorities.

Upgrade cost is low in the mechanical sense: npx skills add joeseesun/qiaomu-seo re-fetches the skill and there is no server to migrate. The cost that does exist is review. The README registers 33 official sources with review dates and blocks known-stale assertions, so a rule that goes stale shows up as a failing validator rather than as silent bad advice. Budget time for that check, especially if you run --strict-stale in CI, and check data/seo-source-registry.json when a validator fails so you know whether the fix is a rule update or a source change.

Licensing is MIT, per the LICENSE file and the README's licence section. MIT permits commercial use and modification with the copyright notice retained. That is a factual statement about the licence text, not legal advice; if you redistribute the skill inside a product, have counsel read the notice requirements. Note also that the README carries a personal profile block for the author, with links to qiaomu.ai and an X account, and it is embedded between HTML comment markers, which suggests it is generated and may reappear on updates. If you fork the skill, expect to strip that block deliberately rather than have it stay gone.

Editorial conclusion

Adopt qiaomu-seo if you already work inside an Agent Skills client and your SEO problems are layer problems: pages that will not index, traffic drops you cannot attribute, migrations with redirect maps to verify. Skip it if you need ranking guarantees, paid-search work, or a hosted crawler with a dashboard, because the skill explicitly excludes those and ships no UI. Before you rely on it, run the three validators in the README against a real audit file and open data/seo-source-registry.json to see how stale a rule has to be before validate_knowledge.py blocks it.

Frequently asked questions

Official sources

1. Issues
2. joeseesun/qiaomu-seo on GitHub
3. License: MIT
4. README