SEO Content QA
Use this skill to audit content reliability before or after publishing.
Requirements
- - Python 3.10+ (scripts use modern type syntax)
- INLINECODE0 available in PATH (for HTTP HEAD checks)
- No pip dependencies — standard library only
- Network access to
r.jina.ai — used as a fallback for SERP search and competitor page fetching (bypasses Cloudflare / anti-bot). Pass --no-jina to disable if needed.
Quick start
Run the unified runner for normal draft review:
CODEBLOCK0
If you know the site's main domain, pass it so internal vs external links are counted correctly:
CODEBLOCK1
If you want project defaults, pass a lightweight JSON config:
CODEBLOCK2
Standard workflow
- 1. Run
seo_qa_runner.py on the draft. - Read the markdown report for the human audit trail.
- Use the JSON report for automation or later aggregation.
- Fix critical issues first.
- Re-run until the article reaches PASS (or REVISE in writer mode).
- After publishing, run
post_publish_check.py on the live URL.
Lower-level tools
Use these only when debugging a specific failure mode.
Link/source verification
CODEBLOCK3
SERP gap analysis
CODEBLOCK4
How the SERP search works:
- 1. Tries DuckDuckGo's HTML endpoint via direct HTTP (fast path)
- If blocked or returns no results, falls back to Jina Reader (
r.jina.ai) which renders the page with a real browser and decodes DDG's redirect links - Competitor pages are always fetched via Jina first (bypasses Cloudflare), then falls back to direct HTTP
Post-publish page check
CODEBLOCK5
Report persistence
The runner writes timestamped markdown + JSON reports by default.
Default behavior:
- - saves to
qa-reports/<article-slug>/ next to the article - does not overwrite old reports
- uses markdown for human review and JSON for machine state
Override with --report-dir or config.
Configuration
Read references/configuration.md when you need project-level defaults.
Source quality
Read references/source-tiers.md when you need to decide whether a citation is acceptable.
Verdict rules
Read references/verdict-rules.md when you need to tune PASS / FAIL / REVISE behavior.
Example output
Read references/example-report.md for a real QA report with annotations on how to interpret each section.
Design intent
This skill is not a writing assistant. It is a reliability layer.
Use scripts for deterministic checks.
Use AI judgment for tone, search intent, framing, and final editorial decisions.
技能名称: seo-geo-qa
详细描述:
SEO 内容质量审核
使用此技能在发布前后审核内容的可靠性。
要求
- - Python 3.10+（脚本使用现代类型语法）
- 环境变量 PATH 中包含 curl（用于 HTTP HEAD 检查）
- 无需 pip 依赖——仅使用标准库
- 可访问 r.jina.ai 网络——作为 SERP 搜索和竞品页面抓取的备用方案（绕过 Cloudflare / 反爬机制）。如需禁用，可传入 --no-jina 参数。
快速开始
运行统一执行器进行常规草稿审核：
bash
python3 skills/seo-geo-qa/scripts/seoqarunner.py path/to/article.md --keyword best email apps
如果已知网站主域名，可传入该参数以便正确区分内链与外链：
bash
python3 skills/seo-geo-qa/scripts/seoqarunner.py path/to/article.md --keyword best email apps --site-domain example.com
如需使用项目默认配置，可传入轻量级 JSON 配置文件：
bash
python3 skills/seo-geo-qa/scripts/seoqarunner.py path/to/article.md --keyword best email apps --config path/to/seo-geo-qa.json
标准工作流程
- 1. 对草稿运行 seoqarunner.py。
- 阅读 Markdown 格式报告以获取人工审核记录。
- 使用 JSON 格式报告进行自动化处理或后续汇总。
- 优先修复关键问题。
- 重新运行直至文章达到 PASS（或在写作模式下达到 REVISE）状态。
- 发布后，对线上 URL 运行 postpublishcheck.py。
底层工具
仅在调试特定故障模式时使用以下工具。
链接/来源验证
bash
python3 skills/seo-geo-qa/scripts/verify_links.py path/to/article.md
python3 skills/seo-geo-qa/scripts/verify_links.py path/to/article.md --json
SERP 差距分析
bash
自动搜索（使用 DuckDuckGo + Jina Reader 作为反爬备用方案）
python3 skills/seo-geo-qa/scripts/serp
gapanalyzer.py best email apps path/to/article.md
直接提供竞品 URL（跳过搜索，仍使用 Jina 抓取页面）
python3 skills/seo-geo-qa/scripts/serp
gapanalyzer.py best email apps path/to/article.md --urls https://competitor1.com https://competitor2.com
禁用 Jina（仅使用直接 HTTP，速度更快但可能无法访问受 Cloudflare 保护的网站）
python3 skills/seo-geo-qa/scripts/serp
gapanalyzer.py best email apps path/to/article.md --no-jina
SERP 搜索工作原理：
- 1. 首先尝试通过直接 HTTP 访问 DuckDuckGo 的 HTML 端点（快速路径）
- 如果被拦截或未返回结果，则回退到 Jina Reader（r.jina.ai），该工具使用真实浏览器渲染页面并解码 DDG 的重定向链接
- 竞品页面始终优先通过 Jina 抓取（绕过 Cloudflare），然后回退到直接 HTTP
发布后页面检查
bash
python3 skills/seo-geo-qa/scripts/post
publishcheck.py https://example.com/blog/post
python3 skills/seo-geo-qa/scripts/post
publishcheck.py https://example.com/blog/post --json
报告持久化
默认情况下，执行器会生成带时间戳的 Markdown 和 JSON 报告。
默认行为：
- - 保存到文章所在目录的 qa-reports// 子目录中
- 不会覆盖旧报告
- Markdown 格式用于人工审查，JSON 格式用于机器状态记录
可通过 --report-dir 参数或配置文件覆盖。
配置
如需项目级默认配置，请阅读 references/configuration.md。
来源质量
如需判断引用是否可接受，请阅读 references/source-tiers.md。
判定规则
如需调整 PASS / FAIL / REVISE 行为，请阅读 references/verdict-rules.md。
示例输出
如需查看包含各章节解读说明的真实 QA 报告，请阅读 references/example-report.md。
设计意图
此技能并非写作辅助工具，而是一个可靠性保障层。
使用脚本进行确定性检查。
使用 AI 判断语气、搜索意图、框架构建及最终编辑决策。
