K
Kael Skills
agent skills, published as repos
Skills/site-geo-optimizer
SEO & GEOPythonMIT

site-geo-optimizer

GEO for a static tool-site cluster

Built for generative-engine visibility rather than classic SEO. Each article gets a 40–80 character definitional answer and three FAQs written at draft time, carried through translation, injected as YAML block scalars so no other byte moves, then checked for frontmatter drift, fence loss and mid-document truncation before it ships. At site level, every page carries a Person entity with a stable @id and sameAs links. Written against kael-site's Astro content collections; the scripts assume that frontmatter schema.

Short answer

site-geo-optimizer — The workflow that made these seven sites quotable: answer blocks, FAQ schema, five-language carry-through, post-deploy checks. It ships as a folder containing SKILL.md, installs by copying into ~/.claude/skills/, and runs in any agent that loads skill folders.

Reposite-geo-optimizer
LanguagePython
LicenceMIT
Last push2026-09-21
Size5.9 KB SKILL.md

What it does

  • geoAnswer plus three faq entries written in Chinese at final-draft stage, translated along with the rest of the frontmatter.
  • Batch injection for legacy articles: scripts/geo-batch.py, 8 threads, idempotent, about 15 minutes for 334 posts.
  • Block-scalar injection that survives colons, quotes and Chinese punctuation without touching the rest of the file.
  • Translation QA: quote repair, enum drift, fence parity, H2 count and a 60% length floor to catch plausible-length truncation.
  • Site-level entity GEO: Person JSON-LD with @id https://kaelzhang.com/#person and sameAs profiles.
  • Post-deploy verification of answer cards, FAQ sections and FAQPage JSON-LD.
Written for one site, portable in parts

The scripts assume kael-site’s Astro content collections and its frontmatter schema. The article-level answer/FAQ rules and the translation QA checks transfer to any Astro blog.

When it triggers

“给这篇新文章写 geoAnswer 和 FAQ”
“批量给老文章补 GEO 段落”
“这篇译文长度够但中间少了一节,查一下”

Inside SKILL.md

SKILL.md 95 lines · click to read
# kael-site GEO 优化全栈

面向 Perplexity / ChatGPT / AI Overviews / Google AI Mode 的引用优化。目标:让 AI 引擎能直接引用站点的「一句话答案」和 FAQ,并把作者钉成跨平台单一实体。

三层结构:**内容数据层**(frontmatter 字段)→ **模板渲染层**(已上线,勿重建)→ **验证层**;外加**站点级实体 GEO**。

## 一、文章级 GEO(geoAnswer + FAQ,核心)

### 流程 A:新文章(2026-09-19 起标准流程,零额外 API 调用)

1. **zh mdx 定稿时手写进 frontmatter**(成稿阶段顺手产出,别等翻译后再补):
   - `geoAnswer`:40-80 字定义式一句话答案。口径与正文严格一致——估算数字带「据媒体报道」类 hedge、实体名/数字与正文完全相同,AI 引擎引用的是这句。
   - `faq`:3 条问答。`q` 用自然问句(就是用户在 AI 引擎会问的原话),`a` 用完整句作答,可带正文锚点链接。
2. **整文件翻译一次带走**:geoAnswer/faq 随 frontmatter 被译走,`column`/`tags` 等枚举值保持英文原值不译。
3. 落盘后跑 QA(见第三节)。

### 流程 B:存量/补漏(老文章批量补)

```bash
python3 <skill目录>/scripts/geo-batch.py            # 全量扫,幂等跳过已注入
python3 <skill目录>/scripts/geo-batch.py zh/xxx.mdx # 只处理指定文件(相对 src/content/blog/)
```

8 线程并行,glm-4-flash 主力、解析失败自动降级 glm-4.6。全站 334 篇实测约 15 分钟。

### 注入格式(block scalar,勿手写裸引号)

追加在 frontmatter 末尾,天然免疫冒号/引号/中文标点,不动文件其余字节:

```yaml
geoAnswer: >-
  一句话定义式答案
faq:
  - q: >-
      问题
    a: >-
      回答
```

schema(`src/content.config.ts` blog collection):

```ts
geoAnswer: z.string().optional(),
faq: z.array(z.object({ q: z.string(), a: z.string() })).optional(),
```

## 二、渲染层(2026-09-11 上线 commit 3bd9b04,勿重复建)

`src/layouts/BaseLayout.astro` 三个挂载点:

1. **答案卡片**(`<main>` 内、slot 之前):`article.geoAnswer` 存在时渲染「AI 速览 · 一句话答案」卡片(sky/violet 蓝紫体系);五语言标签在 `geoLabels` 常量(zh/en/ja/de/fr)。
2. **FAQ 折叠区**(slot 之后):`<details>/<summary>` 原生折叠,无 JS。
3. **FAQPage JSON-LD**(`<head>`):`article.faq` 存在时注入。

5 个语言文章页(`src/pages/{,zh,ja,de,fr}/blog/[...slug].astro`)已传 `geoAnswer: post.data.geoAnswer, faq: post.data.faq`——**新增语言页或改 article prop 结构时别丢这两个字段**。

## 三、翻译携带 QA(每篇译稿落盘后,顺序执行)

1. `python3 <astro-blog-sync skill>/scripts/fix-fm-quotes.py <文件>`——GLM 给 frontmatter 值套单引号且内嵌单引号,js-yaml 会静默拼出多余空格;跑完 pyyaml 回验 title/faq/geoAnswer。
2. `python3 <astro-blog-sync skill>/scripts/qa-normalize.py <slug>...`——补 `---` 围栏、pyyaml 回验、column 枚举漂移自动校正回 dialogue/teardown/hot。
3. `python3 <astro-blog-sync skill>/scripts/check-fences.py <slug>`——围栏数与 zh 基准对比,防翻译丢开围栏。
4. `python3 <astro-blog-sync skill>/scripts/check-structure.py <slug>`——H2 数 vs zh + 尾句收尾启发式 + 长度下限 60%,防「plausible-length 截断」(译文长度够但中段被切断缺节)。

参数都是 slug 不是文件路径(传路径会拼进 BLOG 前缀报 MISSING)。

### 语言补丁(每批译稿必查)

- **fr**:全文 `\'` → `'`(GLM 法语转义残留)
- **en**:title 类 `Can''t` 双撇号修回单撇号
- **ja**:frontmatter 禁 `slug:` / `heroImage:` 行(存在即静默跳过不产 dist,sed 删行)

## 四、站点级实体 GEO(2026-09-16 上线)

区别于文章级,把 Kael Zhang/永亮 钉成跨平台单一实体:全站每页注入 Person JSON-LD(`@id: https://kaelzhang.com/#person`,sameAs 挂 X/YouTube/GitHub/Substack/WhatsApp,knowsAbout 挂领域词)。机制细节见 [references/entity-geo.md](references/entity-geo.md)。

## 五、上线验证

1. 全量核验:`grep -rl '^faq:' src/content/blog --include='*.mdx' | wc -l` 应等于总 mdx 数
2. `npm run build` → push → Vercel 约 90 秒 → 线上 `curl <文章页> | grep -E "FAQPage|AI 速览|Quick Answer"` 应命中(en 站无前缀 `https://kaelzhang.com/blog/<slug>/`,其余语言带 `/zh/` `/ja/` `/de/` `/fr/` 前缀)
3. 也可用 Rich Results Test 验 FAQPage 结构化数据

## 坑清单(全部实测踩过)

| 症状 | 处置 |
|---|---|
| js-yaml safeParseFrontmatter 报错 | title/description 里有未转义英文双引号,换中文引号或单引号包裹 |
| frontmatter 值莫名多个空格 | GLM 单引号嵌套单引号,跑 fix-fm-quotes.py |
| tags 含 `l'IA` 类撇号项炸 YAML | 该项用双引号包裹 |
| GLM 429 "Weekly/Monthly Limit Exhausted" | coding plan 端点(api.z.ai)周限额,换官方端点 `https://open.bigmodel.cn/api/paas/v4`(同 key) |
| glm-4.6 并发 429 | 重试改串行 |
| glm-4-flash 输出 JSON 引号未转义 | 脚本已内建指令约束 + glm-4.6 兜底 |
| 单篇顽固 400 | 手动简化 prompt 调一次再 inject |
| Astro 模板表达式不支持内联 `as` 强转 | 多语言映射放 frontmatter 常量 |
| check-structure 尾句 FAIL | 先对读 zh/en 尾段——列表结尾/括号结尾/单引号句尾属正常(09-21 已修启发式) |
| ja 文章不产 dist 无报错 | frontmatter 有 `slug:`/`heroImage:` 行,sed 删之 |

Open the raw file ↗

Common questions

What does site-geo-optimizer do?
The workflow that made these seven sites quotable: answer blocks, FAQ schema, five-language carry-through, post-deploy checks. geoAnswer plus three faq entries written in Chinese at final-draft stage, translated along with the rest of the frontmatter.
How do I install site-geo-optimizer?
Run git clone https://github.com/KaelZhang321/site-geo-optimizer, then copy the skill folder into ~/.claude/skills/. The Install panel on this page has the exact two commands.
Is site-geo-optimizer free to use?
Yes. The repository is public and MIT licensed, so reuse only requires keeping the licence notice.

Install

git clone https://github.com/KaelZhang321/site-geo-optimizer.git cp -R site-geo-optimizer ~/.claude/skills/site-geo-optimizer

Inside the repo

SKILL.md
scripts/geo-batch.py
references/entity-geo.md
LICENSE