Home
Softono
seo-geo-skills

seo-geo-skills

Open source Python
GitHub
32
Stars
0
Forks
0
Issues
0
Watchers
3 weeks
Last Commit
AI Agents SEO Tools

About seo-geo-skills

# SEO GEO Skills Claude Code skill for sampled SEO + GEO audits of public sites. - Crawl up to 50 pages, template-aware sampling - Raw Googlebot baseline vs browser-rendered evidence - Local Lighthouse (no remote API) - Final polished HTML report from the same payload as the chat audit 中文版见[下方](#seo-geo-skills-中文)。 ## Install Paste this into a Claude Code session: ```text Install this skill: https://github.com/iklynow-hue/seo-geo-skills ``` Claude reads this README and runs the install. Open a fresh Claude Code session afterward so the skill is picked up. ### Manual install **Prerequisites:** `git`, `python3`, `node` + `npm`. Chrome is downloaded by `chrome-launcher` on first Lighthouse run if not present. Clone the repo **anywhere you keep code** (the source location is your choice), then create a symlink at the **fixed** path Claude Code reads from. ```bash # 1. Clone wherever you want — pick your own path. REPO_DIR=~/Projects/seo-geo-skills git clone https://github.com/iklynow-hue/seo-g ...

Platforms

Web Self-hosted

Languages

Python

Links

Source Code
i
Published by
iklynow-hue
Visit View Profile

README.md

View on GitHub

SEO GEO Skills

Claude Code skill for sampled SEO + GEO audits of public sites.

  • Crawl up to 50 pages, template-aware sampling
  • Raw Googlebot baseline vs browser-rendered evidence
  • Local Lighthouse (no remote API)
  • Final polished HTML report from the same payload as the chat audit

中文版见下方。

Install

Paste this into a Claude Code session:

Install this skill: https://github.com/iklynow-hue/seo-geo-skills

Claude reads this README and runs the install. Open a fresh Claude Code session afterward so the skill is picked up.

Manual install

Prerequisites: git, python3, node + npm. Chrome is downloaded by chrome-launcher on first Lighthouse run if not present.

Clone the repo anywhere you keep code (the source location is your choice), then create a symlink at the fixed path Claude Code reads from.

# 1. Clone wherever you want — pick your own path.
REPO_DIR=~/Projects/seo-geo-skills
git clone https://github.com/iklynow-hue/seo-geo-skills "$REPO_DIR"

# 2. Symlink the skill into the path Claude Code scans (this path is fixed).
mkdir -p ~/.claude/skills
ln -s "$REPO_DIR/skills/seo-geo-site-audit" ~/.claude/skills/seo-geo-site-audit

# 3. Install the Lighthouse runner's npm deps (~120 MB, one-time).
cd "$REPO_DIR/skills/seo-geo-site-audit/scripts" && npm install

Why a symlink? Claude Code auto-discovers skills from ~/.claude/skills/. Your source can live wherever you keep code; the symlink bridges the two paths so edits in your repo show up immediately in any new Claude Code session.

Per-project install instead: replace ~/.claude/skills/ with .claude/skills/ inside the project root.

Update

cd "$REPO_DIR" && git pull
# If scripts/package.json changed:
cd skills/seo-geo-site-audit/scripts && npm install

Optional fetchers

urllib works alone, but SPA accuracy improves with one of these. Skip initially; the wrapper detects what's available at run time. Add --auto-install-prereqs later if you want.

  • scrapling[fetchers] — pip install "scrapling[fetchers]" && scrapling install
  • lightpanda — ~/.local/bin/lightpanda on first auto-install
  • agent-browser — npm install -g agent-browser && agent-browser install

Use it

The skill runs immediately on the URL. No setup questions. Defaults:

Setting Default
Mode Light template audit (10 pages)
Output style Operator
Performance Local Lighthouse — homepage, mobile + desktop
HTML report On
Output language English

Example prompts

You say The skill does
Audit https://example.com Defaults
Conduct an SEO and GEO audit for https://example.com Defaults (any audit-like phrasing triggers the skill)
Quick check on https://example.com, skip Lighthouse Fast mode (1 page) + --skip-pagespeed
Run a 50-page audit for https://example.com, output in Chinese Template mode + Chinese report
Audit https://example.com with specialist depth Specialist output style
审核 https://example.com 50 页 用中文 Template mode + Chinese report
Audit my site (no URL) Skill asks for the URL — the only hard requirement

When the agent asks

Three cases only:

  • The URL is missing.
  • The prompt is in a non-English language but the report language wasn't stated — one confirmation: "Report in English or <other>?".
  • --auto-install-prereqs would download network binaries — consent first.

The report defaults to English even when the prompt is in another language. Switch only on explicit "in <language>" / "用中文" or the --report-language flag.

Limits

  • Crawl cap 1–50 (fast=1, light=10, template=50).
  • Lighthouse: 1 homepage URL by default (mobile + desktop), max 10 via --max-pagespeed-urls.
  • SPA route expansion is sample-based, not a full app crawler.
  • Routes from dom_route_hint / route_guess are labeled assisted discovery — not crawlability proof.

Terminal usage

Replace ${SKILL_DIR} with ~/.claude/skills/seo-geo-site-audit.

"${SKILL_DIR}/scripts/audit-site" https://example.com \
  --mode template --output-style operator --html-report

Common flags (full list in skills/seo-geo-site-audit/references/cli-flags.md): --mode, --max-pages, --output-style, --max-pagespeed-urls, --skip-pagespeed, --html-report, --report-language, --fetcher, --auto-install-prereqs, --out-dir.

After Claude fills final-report.json, render the polished HTML:

"${SKILL_DIR}/scripts/render-report-html" \
  --report-json "${SKILL_DIR}/runs/site-audit-<host>-<stamp>/final-report.json" \
  --out "${SKILL_DIR}/runs/site-audit-<host>-<stamp>/audit-report.html"

Artifacts

  • crawl.json — per-page signals
  • pagespeed.json — Lighthouse data (unless skipped)
  • audit-run.json — run manifest
  • evidence-report.html — raw evidence (with --html-report)
  • final-report.json — payload Claude fills in
  • audit-report.html — final polished HTML

SPA handling

The crawl keeps two evidence tracks per HTML page:

  • search_engine_visibility — raw Googlebot-style HTTP baseline, no JavaScript.
  • Rendered browser evidence — what the SPA shows after JS runs.

Signals that appear only after rendering are flagged as a JavaScript-dependency risk (not "Google can't see it"). Pages reached only through dom_route_hint / route_guess are audit assistance, not crawlability proof.

Security

The repo is intended to be safe for public cloning.

  • No API keys / tokens / secrets in source, docs, or artifacts.
  • Lighthouse runs locally — no third-party API key required.
  • Chrome's sandbox stays on by default; opt-in via SEO_GEO_ALLOW_NO_SANDBOX=1 only for trusted root / CI / container environments.
  • --auto-install-prereqs is opt-in. Lightpanda binary downloads require a registered SHA256 or explicit SEO_GEO_ALLOW_UNVERIFIED_LIGHTPANDA=1.

Full notes: skills/seo-geo-site-audit/SECURITY.md.

Contributing

Cloning and forking are welcome. Stars are appreciated. Bugs and suggestions → please open an issue.

SEO GEO Skills 中文

Claude Code 技能，对公开网站做采样式 SEO + GEO 审核。

  • 最多抓取 50 页，按模板抽样
  • 对比 raw Googlebot 风格 HTTP 基线和浏览器渲染证据
  • 通过 lighthouse + chrome-launcher 在本地跑 Lighthouse（不需要远程 API）
  • 最终 HTML 报告与终端审核报告共用同一份结构化 payload

安装

在 Claude Code 会话中粘贴：

帮我安装这个 skill: https://github.com/iklynow-hue/seo-geo-skills

Claude 会读取本 README 并执行安装。完成后请开一个新的 Claude Code 会话让 skill 被加载。

手动安装

前置： git、python3、node + npm。首次运行 Lighthouse 时 chrome-launcher 会按需下载 Chrome。

把仓库 clone 到你自己平时放代码的位置（任意路径都行），然后把 skill 软链到 Claude Code 固定查找的目录。

# 1. clone 到你想放的位置（路径你自己决定）。
REPO_DIR=~/Projects/seo-geo-skills
git clone https://github.com/iklynow-hue/seo-geo-skills "$REPO_DIR"

# 2. 软链到 Claude Code 扫描的固定路径。
mkdir -p ~/.claude/skills
ln -s "$REPO_DIR/skills/seo-geo-site-audit" ~/.claude/skills/seo-geo-site-audit

# 3. 安装 Lighthouse runner 的 npm 依赖（约 120 MB，一次性）。
cd "$REPO_DIR/skills/seo-geo-site-audit/scripts" && npm install

为什么用软链？ Claude Code 在 ~/.claude/skills/ 下自动发现 skill。源码可以放在任意路径，软链负责把固定的发现位置指向你的实际仓库，这样你在仓库里改了文件，新开的 Claude Code 会话立刻能看到。

只想项目内用： 把上面的 ~/.claude/skills/ 换成项目根下的 .claude/skills/。

更新

cd "$REPO_DIR" && git pull
# 如果 scripts/package.json 有变更：
cd skills/seo-geo-site-audit/scripts && npm install

可选爬虫前置依赖

只用 urllib 也能跑，但 SPA 站点上以下任意一个工具在场会更准确。建议先跳过；包装脚本会在运行时检测，需要时再加 --auto-install-prereqs：

  • scrapling[fetchers] — pip install "scrapling[fetchers]" && scrapling install
  • lightpanda — 首次 auto-install 时下载到 ~/.local/bin/lightpanda
  • agent-browser — npm install -g agent-browser && agent-browser install

使用

收到 URL 后 skill 直接开跑，不再追问。默认值：

项 默认
模式 轻量模板审核（10 页）
输出风格 Operator
性能 本地 Lighthouse — 首页，移动 + 桌面
HTML 报告 开
输出语言 English

示例

你说 skill 实际行为
Audit https://example.com 全部默认
帮我对 https://example.com 做一次 SEO 和 GEO 审核 同上（任何"审核"类措辞都会触发）
审核 https://example.com，跑 50 页，用中文输出 Template (50 页) + 中文报告
快速检查 https://example.com，跳过 Lighthouse Fast (1 页) + --skip-pagespeed
深度审核 https://example.com，专家风格 Specialist 输出风格
审核 https://example.com 50 页 用中文 Template + 中文报告（更短的写法）
帮我审核我的站点（没给 URL） 反问 URL — 唯一硬性要求

只在三种情况会问

  • 没给 URL。
  • 请求是非英文写的，但没说"用 X 语言输出"——只确认一次："输出用 English 还是 <其他>？"
  • --auto-install-prereqs 要联网下载二进制（Lightpanda 等）时先确认。

报告默认 English，即使你的请求是中文写的也一样。只有显式说"用中文" / "in Chinese"或加 --report-language flag 才切换。

限制

  • 抓取页数 1–50（fast=1、light=10、template=50；默认 light）。
  • Lighthouse 默认 1 个首页 URL（mobile + desktop），最多 10 个（--max-pagespeed-urls）。
  • SPA 路由扩展仍是采样逻辑，不是完整应用爬虫。
  • 只通过 dom_route_hint / route_guess 找到的路由会被标为辅助发现，不算爬取证据。

终端使用

把 ${SKILL_DIR} 换成 ~/.claude/skills/seo-geo-site-audit。

"${SKILL_DIR}/scripts/audit-site" https://example.com \
  --mode template --output-style operator --html-report --report-language chinese

完整参数列表见 skills/seo-geo-site-audit/references/cli-flags.md。

Claude 补全 final-report.json 后，再渲染最终交付版 HTML：

"${SKILL_DIR}/scripts/render-report-html" \
  --report-json "${SKILL_DIR}/runs/site-audit-<host>-<stamp>/final-report.json" \
  --out "${SKILL_DIR}/runs/site-audit-<host>-<stamp>/audit-report.html"

产物

  • crawl.json — 单页信号
  • pagespeed.json — Lighthouse 数据（除非跳过）
  • audit-run.json — 本次运行 manifest
  • evidence-report.html — 原始证据 HTML（启用 --html-report 时）
  • final-report.json — Claude 补全的种子 payload
  • audit-report.html — 最终交付 HTML

爬虫对 SPA 的处理

每个 HTML 页面保留两条证据线：

  • search_engine_visibility — raw Googlebot 风格 HTTP 基线，不执行 JS。
  • 浏览器渲染证据 — SPA 在 JS 执行后展示给用户的内容。

只在渲染后出现的内容、导航、结构化数据或路由会被标为 JavaScript 依赖风险，而不是"Google 看不到"。只通过 dom_route_hint / route_guess 找到的页面属于审计辅助发现，不会写成搜索引擎可直接爬取。

安全说明

仓库设计为可安全公开克隆。

  • 源码、文档、产物中都不应硬编码 API key / token / 密钥。
  • Lighthouse 在本地运行，不需要第三方 API key。
  • Chrome 沙箱默认开启；只在受信任的 root/CI/容器环境里通过 SEO_GEO_ALLOW_NO_SANDBOX=1 关闭。
  • --auto-install-prereqs 是 opt-in。Lightpanda 二进制下载默认要求注册 SHA256，或显式设置 SEO_GEO_ALLOW_UNVERIFIED_LIGHTPANDA=1。

完整说明见 skills/seo-geo-site-audit/SECURITY.md。

贡献

欢迎 clone / fork。觉得有用的话顺手点个 star 就很感谢。遇到 bug 或有建议，欢迎提 issue。