seo

SEO 技能（Agentic / Claude / Codex）

以 LLM 为先的 SEO 分析技能，包含 16 个专用子技能、10 个专家 Agent 和 89 个脚本，用于优化网站、博客和 GitHub 仓库。

确定性触发映射

为提高 Codex/Agent IDE 中提示词的可靠性，将常见的用户措辞映射到固定工作流：

• 如果用户说 perform seo analysis on <url>（或提出类似的、带 URL 的通用 SEO 请求），则将其视为单 URL 全面审计。
• 如果未明确指定子技能，则运行全面/页面审计流程，采用以 LLM 为先的推理，并以脚本提供证据。
• 对于全面/页面审计，始终生成：
  • FULL-AUDIT-REPORT.md（详细发现）
  • ACTION-PLAN.md（按优先级排列的修复项）
• 如果运行了 generate_report.py，还要返回已保存的 HTML 路径（例如 SEO-REPORT.html）。

可用命令

命令	子技能	描述
seo audit <url>	seo-audit	对网站进行全面审计并评分
seo page <url>	seo-page	深入分析单个页面
seo technical <url>	seo-technical	技术 SEO 检查
seo content <url>	seo-content	内容质量与 E-E-A-T
seo schema <url>	seo-schema	Schema 检测/验证/生成
seo sitemap <url>	seo-sitemap	站点地图分析与生成
seo images <url>	seo-images	图片优化审计
seo geo <url>	seo-geo	AI 搜索优化（GEO）
seo programmatic <url>	seo-programmatic	程序化 SEO 保障措施
seo competitors <url>	seo-competitor-pages	对比/替代方案页面
seo hreflang <url>	seo-hreflang	国际 SEO 验证
seo plan <url>	seo-plan	SEO 战略规划
seo github <repo_or_url>	seo-github	提高 GitHub 仓库的可发现性，优化 README、主题、社区健康状况，并归档流量数据
seo article <url>	seo-article	文章数据提取与 LLM 优化
seo links <url>	seo-links	外部反向链接概况与链接健康状况
seo aeo <url>	seo-aeo	答案引擎优化（精选摘要、PAA、知识面板）

---

编排逻辑

用户请求 SEO 分析时，按以下方式路由：

步骤 1 — 确定任务

解析用户的请求，以确定要启用哪些子技能：

• 全面审计：读取 resources/skills/seo-audit.md — 抓取多个页面、委派给 Agent、评分并生成报告
• 单页面：读取 resources/skills/seo-page.md — 深入分析一个 URL
• 特定领域：读取匹配的 resources/skills/seo-*.md 文件
• 战略规划：读取 resources/skills/seo-plan.md，并读取与识别出的行业匹配的 resources/templates/*.md
• GitHub 仓库 SEO：读取 resources/skills/seo-github.md，并使用带有 --provider auto 的 GitHub 脚本，以便在 API 和 gh 之间回退。
• 通用的 perform seo analysis on <url> 请求：将其视为单页面全面审计，读取 resources/skills/seo-page.md，并生成 FULL-AUDIT-REPORT.md + ACTION-PLAN.md。

步骤 2 — 收集证据

主要方法（LLM 优先） — 首先使用内置的 read_url_content 工具：

read_url_content(url)  →  returns parsed HTML content directly

将其作为推理的基准证据。

确定性验证（有脚本执行能力时建议使用）：

# Fetch/parse raw HTML for structured checks
python3 <SKILL_DIR>/scripts/fetch_page.py <url> --output /tmp/page.html
python3 <SKILL_DIR>/scripts/parse_html.py /tmp/page.html --url <url> --json

# Optional: generate shareable HTML dashboard artifact
python3 <SKILL_DIR>/scripts/generate_report.py <url> --output SEO-REPORT.html

当可以直接抓取网站或使用随附脚本时，不要将第三方镜像（例如 r.jina.ai）用作主要证据。 <SKILL_DIR> = 此技能目录的绝对路径（包含此 SKILL.md 的文件夹）。

步骤 3 — 执行 LLM 优先分析

以 LLM 作为主要 SEO 分析工具：

1. 综合页面内容、元数据和可选的脚本输出中的证据。
2. 提出明确列出依据的发现：
   • Finding（发现）
   • Evidence（证据，具体元素、指标或片段）
   • Impact（影响，说明其对排名、索引或用户体验的重要性）
   • Fix（修复，明确的实施步骤）
3. 按影响和实施成本确定优先级。
4. 区分已确认的问题、可能存在的问题和未知项（缺失的数据）。

务必阅读并应用 resources/references/llm-audit-rubric.md，确保不同类型的审计在评分、严重程度、置信度和输出结构方面保持一致。

步骤 4 — 运行基线验证脚本（具备执行能力时）

对于完整审计或页面审计，请运行基线检查，避免仅凭假设生成报告。不要用纯脚本评分取代 LLM 推理。

# Check robots.txt and AI crawler management
python3 <SKILL_DIR>/scripts/robots_checker.py <url>

# Check llms.txt for AI search readiness
python3 <SKILL_DIR>/scripts/llms_txt_checker.py <url>

# Get Core Web Vitals from PageSpeed Insights (free API, no key needed)
python3 <SKILL_DIR>/scripts/pagespeed.py <url> --strategy mobile

# Check security headers (HSTS, CSP, X-Frame-Options, etc.)
python3 <SKILL_DIR>/scripts/security_headers.py <url>

# Detect broken links on a page (404s, timeouts, connection errors)
python3 <SKILL_DIR>/scripts/broken_links.py <url> --workers 5

# Trace redirect chains, detect loops and mixed HTTP/HTTPS
python3 <SKILL_DIR>/scripts/redirect_checker.py <url>

# Analyze readability from fetched HTML (Flesch-Kincaid, grade level, sentence stats)
python3 <SKILL_DIR>/scripts/readability.py /tmp/page.html --json

# Validate Open Graph and Twitter Card meta tags
python3 <SKILL_DIR>/scripts/social_meta.py <url>

# Analyze internal link structure, find orphan pages
python3 <SKILL_DIR>/scripts/internal_links.py <url> --depth 1 --max-pages 20

# Extract article content and perform keyword research for LLM-driven optimization
python3 <SKILL_DIR>/scripts/article_seo.py <url> --keyword "<optional_target_keyword>" --json

# Credentials for paid/auth APIs (PageSpeed, GitHub, GSC, Knowledge Graph)
# are loaded from CLI flags, then env vars, then a `.env` file in the repo
# root / cwd / `~/.agentic-seo/.env`. Copy `.env.example` to `.env` and fill
# in only the keys you have. Never paste secrets in prompts.

# GitHub repository SEO (provider fallback: auto|api|gh)
# Auth setup (choose one):
# export GITHUB_TOKEN="ghp_xxx"   # or export GH_TOKEN="ghp_xxx"
# gh auth login -h github.com && gh auth status -h github.com
python3 <SKILL_DIR>/scripts/github_repo_audit.py --repo <owner/repo> --provider auto --json
python3 <SKILL_DIR>/scripts/github_readme_lint.py README.md --json
python3 <SKILL_DIR>/scripts/github_community_health.py --repo <owner/repo> --provider auto --json
# Benchmark/competitor inputs should be provided by LLM/web-search discovery when possible.
# If omitted, github_seo_report.py auto-derives repo-specific benchmark queries.
python3 <SKILL_DIR>/scripts/github_search_benchmark.py --repo <owner/repo> --query "<llm_or_web_query>" --provider auto --json
python3 <SKILL_DIR>/scripts/github_competitor_research.py --repo <owner/repo> --query "<llm_or_web_query>" --provider auto --top-n 6 --json
python3 <SKILL_DIR>/scripts/github_competitor_research.py --repo <owner/repo> --competitor <owner/repo> --competitor <owner/repo> --provider auto --json
python3 <SKILL_DIR>/scripts/github_traffic_archiver.py --repo <owner/repo> --provider auto --archive-dir .github-seo-data --json
python3 <SKILL_DIR>/scripts/github_seo_report.py --repo <owner/repo> --provider auto --markdown GITHUB-SEO-REPORT.md --action-plan GITHUB-ACTION-PLAN.md --json
# Optional: increase/reduce auto-derived query volume (default: 6)
# python3 <SKILL_DIR>/scripts/github_seo_report.py --repo <owner/repo> --provider auto --auto-query-max 8 --markdown GITHUB-SEO-REPORT.md --action-plan GITHUB-ACTION-PLAN.md --json

如果检查因网络、DNS、权限或 API 速率限制而失败：

• 明确将其报告为环境限制，而非已确认的网站问题。
• 对受影响的类别，将置信度标为 Hypothesis。
• 使用现有证据继续审计，不要因此停止。
• 不要反复进入备用方案循环。对于失败的来源，最多重试一次，然后完成审计。
• 不要针对同一 URL 反复转向网页搜索抓取。

视觉分析（需要 Playwright — 如可用，请使用 conda activate pentest）：

# Capture screenshots (desktop, laptop, tablet, mobile)
python3 <SKILL_DIR>/scripts/capture_screenshot.py <url> --all

# Analyze visual layout, above-the-fold, mobile responsiveness
python3 <SKILL_DIR>/scripts/analyze_visual.py <url> --json

HTML 报告生成器 — 生成独立的交互式 HTML 仪表板：

# Generate full SEO report (runs scripts automatically, saves HTML to PWD)
python3 <SKILL_DIR>/scripts/generate_report.py <url>
python3 <SKILL_DIR>/scripts/generate_report.py <url> --output custom-report.html

步骤 5 — 委派给专业 Agent

对于全面审计，请阅读 resources/agents/ 中相关的 Agent 文件，以采用相应的专业角色：

Agent	文件	关注领域
技术 SEO	seo-technical.md	可抓取性、可索引性、安全性、URL、移动端、CWV、JS 渲染
内容质量	seo-content.md	E-E-A-T 评估、内容指标、AI 内容检测
性能	seo-performance.md	Core Web Vitals（LCP、INP、CLS）、优化建议
Schema 标记	seo-schema.md	JSON-LD 结构化数据的检测、验证和生成
Sitemap	seo-sitemap.md	XML sitemap 验证、生成、质量门槛
视觉分析	seo-visual.md	截图、首屏内容、响应式设计、布局
验证器（全局）	seo-verifier.md	去重发现、消除矛盾，并在最终报告前验证证据的相关性

第 6 步 — 应用质量门槛

参考 resources/references/ 中的质量标准：

• 内容最低要求：阅读 quality-gates.md，了解字数、独特内容占比和标题／元数据要求
• 架构验证：阅读 schema-types.md，了解有效／已弃用／受限类型
• Core Web Vitals：阅读 cwv-thresholds.md，了解当前指标阈值
• E-E-A-T 框架：阅读 eeat-framework.md，了解评分标准
• Google 参考资料：阅读 google-seo-reference.md，以便快速查阅
• LLM 报告评分标准：阅读 llm-audit-rubric.md，了解强制性证据格式、置信度标签和输出规范

第 6.5 步 — 验证发现（所有工作流）

撰写最终报告前，运行验证：

python3 <SKILL_DIR>/scripts/finding_verifier.py --findings-json <raw_findings.json> --json

最终报告表格应使用经过验证的输出，而非原始发现。

第 7 步 — 评分并报告

将数值评分作为参考，而非证据质量和判断的替代品。

默认评分权重（完整审计）

权威信息源 — 此处和 resources/skills/seo-audit.md 中定义了这些权重。 不要修改各子技能文件中的权重；仅更新这两个位置，以保持评分一致。

类别	权重
技术 SEO	25%
内容质量	20%
页面 SEO	15%
架构／结构化数据	15%
性能（CWV）	10%
图片优化	10%
AI 搜索就绪度（GEO）	5%

如果使用 scripts/generate_report.py，自动化仪表板会采用该脚本中定义的脚本级类别权重。叙述式审计应优先采用 LLM 和证据。

第 8 步 — 强制交付项

对于 seo audit、seo page 和通用的 perform seo analysis on <url> 流程：

1. 在审计开始时，于当前工作目录中创建 FULL-AUDIT-REPORT.md，然后随着收集证据不断更新。
2. 在审计开始时，于当前工作目录中创建 ACTION-PLAN.md，然后更新其中的优先修复项。
3. 如果已生成 HTML 仪表板，请提供其准确保存路径（例如 SEO-REPORT.html 或绝对路径）。
4. 在最终回复中明确列出生成的产物及其路径。
5. 如果环境限制导致技术检查无法执行，仍须写入这两个 Markdown 文件，并包含“环境限制”部分。

评分解读

分数	评级
90-100	优秀
70-89	良好
50-69	需要改进
30-49	较差
0-29	严重

---

行业识别

运行 seo plan 时，识别业务类型并加载匹配的模板：

行业	模板文件
SaaS／软件	saas.md
本地服务企业	local-service.md
电子商务／零售	ecommerce.md
出版商／媒体	publisher.md
代理机构／咨询公司	agency.md
其他／通用	generic.md

识别信号：

• SaaS：定价页面、功能页面、/docs、/api、试用／演示 CTA
• 本地业务：地址、电话、Google Business Profile、服务区域页面
• 电子商务：产品页面、购物车、结账、/collections、/categories
• 出版商：文章日期、作者页面、/news、内容量大
• 代理机构：案例研究、/work、/portfolio、团队页面、服务项目

---

架构模板

可在 templates.json 中使用预先构建的 JSON-LD 模板，适用于：

• 常见：BlogPosting、Article、Organization、LocalBusiness、BreadcrumbList、WebSite（含 SearchAction）
• 视频：VideoObject、BroadcastEvent、Clip、SeekToAction
• 电子商务：ProductGroup（变体）、OfferShippingDetails、Certification
• 其他：SoftwareSourceCode、ProfilePage（E-E-A-T 作者页面）

---

验证脚本

提供了两个验证脚本，可用于 CI/CD 集成：

提交前 SEO 检查

bash <SKILL_DIR>/scripts/pre_commit_seo_check.sh

检查暂存的 HTML 文件，包括：架构中的占位文本、标题标签长度、缺少 alt 文本、已弃用的架构类型、FID 引用（应为 INP）、元描述长度。

架构验证器

python3 <SKILL_DIR>/scripts/validate_schema.py <file_path>

验证 HTML 文件中的 JSON-LD 块：JSON 语法、是否存在 @context/@type、占位文本、已弃用/受限类型。

技能清单验证器

python3 <SKILL_DIR>/scripts/validate_skill_inventory.py

根据磁盘上的文件验证文档中记录的子技能、Agent 和脚本数量。CI 使用此工具防止 README/SKILL 清单不一致。

参考资料时效性验证器

python3 <SKILL_DIR>/scripts/reference_freshness.py <SKILL_DIR>/resources/references --max-age-days 90

检查每个参考文件是否包含 `` 标记，并标记超过配置时效窗口的参考文件。

---

输出格式

所有子技能报告都应使用一致的严重级别：

• 🔴 严重 — 直接影响排名或索引（立即修复）
• ⚠️ 警告 — 存在优化机会（1 个月内修复）
• ✅ 通过 — 符合或超过标准
• ℹ️ 信息 — 不适用或仅供参考

报告结构如下：

1. 摘要表，包含元素、值和严重级别
2. 按类别分组的详细发现
3. 按影响排序的可执行建议

---

关键规则

1. 使用 INP，而非 FID — FID 已于 2024 年 9 月 9 日移除。唯一的交互性指标是 INP（Interaction to Next Paint）。切勿引用 FID。
2. FAQ 架构受限 — FAQPage 架构仅限政府和医疗保健权威网站使用（2023 年 8 月）。切勿向商业网站推荐。
3. HowTo 架构已弃用 — 富媒体搜索结果已于 2023 年 9 月全面移除。切勿推荐。
4. 仅使用 JSON-LD — 始终使用 <script type="application/ld+json">。切勿推荐 Microdata 或 RDFa。
5. 处处重视 E-E-A-T — 截至 2025 年 12 月，E-E-A-T 适用于所有竞争性查询，而不仅是 YMYL 查询。
6. 移动优先已全面完成 — 自 2024 年 7 月 5 日起，100% 采用移动优先索引。
7. 地点页面数量限制 — 页面达到 30 个及以上时发出警告，达到 50 个及以上时立即停止。严格执行唯一内容要求。
8. AI 爬虫管理 — 检查 robots.txt 中的 GPTBot、ClaudeBot、PerplexityBot、Applebot-Extended、Google-Extended、Bytespider、CCBot。
9. LLM 优先、弹性处理的流程 — 首先使用 read_url_content 读取页面，然后始终运行相关脚本以获取结构化证据。脚本是首选证据来源，应积极使用。但如果任何脚本失败（超时、网络或解析错误），LLM 仍必须根据自身推理完成分析（置信度：Likely）。切勿因单个脚本失败而阻止生成报告。
10. 审计流程始终生成文件产物 — 对于完整审计/页面审计请求，必须输出 FULL-AUDIT-REPORT.md 和 ACTION-PLAN.md。
11. 限制证据重试次数 — 避免长时间搜索或反复重试。如果核心检查因 DNS/网络问题失败，应尽快完成报告，并标注置信度和生成的文件。
12. 避免冗余的网页回退方案 — 如果直接获取/脚本失败，且一个回退方案也失败，则停止重试，并在报告中明确说明限制。
13. 跟踪信号时效性 — 每个参考文件都应包含 `` 注释。标记所有超过 90 天的参考文件以供审核。Google 宣布算法变更时，应在 7 天内核实受影响的参考文件。需跟踪的关键日期：核心更新（每季度）、架构弃用（schema-types.md）、CWV 阈值变更（cwv-thresholds.md）。

---

依赖项

可选脚本依赖项

• Python 3.8+
• requests（用于网络分析脚本）
• beautifulsoup4（用于 HTML 解析脚本）
• Playwright（用于 capture_screenshot.py 和 analyze_visual.py）

  pip install playwright && playwright install chromium
  

  或者，如果使用 conda：conda activate pentest（如果已预装 Playwright）

安装脚本依赖项

pip install requests beautifulsoup4