面向 ADK 技能写作的 On-Page SEO 清单：content-research-writer 的 SEO 优化实战指南-平芜编程栈

面向 ADK 技能写作的 On-Page SEO 清单：content-research-writer 的 SEO 优化实战指南

【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples

导读

在 agent-skills-tutorial 项目中，content-research-writer技能为 Agent 提供了一套「内容调研 + SEO 优化写作」的完整方法论，而本文要深入讲解的正是该技能在写作阶段必须遵守的核心规范文件——seo-guidelines.md。这份参考文档定义了页面 SEO（On-Page SEO）的完整检查清单与关键词策略，覆盖标题标签、元描述、标题层级、内容结构、内外链与图片优化六大维度。读完本文，你将掌握一套可直接落地到任何技术博客、产品文档或教程写作流程中的 SEO 优化检查表，并理解它是如何通过 ADK 的load_skill_resource机制在 Agent 运行时被动态加载和执行的。

一、这份文档在技能体系中的角色

content-research-writer技能（SKILL.md）把一次完整的内容生产拆解为五个阶段：主题调研（Topic Research）、内容规划（Content Planning）、SEO 优化（SEO Optimization）、写作（Writing）与质量检查（Quality Check）。其中第三阶段明确要求：

Readreferences/seo-guidelines.mdfor detailed SEO rules usingload_skill_resource.

也就是说，seo-guidelines.md是技能在「写作前」必须查阅的领域知识库。它与blog-writer技能的 style-guide.md 形成互补：前者负责「内容在搜索引擎中的可见性与排名」，后者负责「行文风格与排版规范」。

从实现层面看，该文件之所以能按需被读取，依赖的是 ADK 的渐进式披露（progressive disclosure）机制：在 agent.py 中，content_researcher_skill通过load_skill_from_dir从本地目录加载，最终与其他三个技能一起打包进SkillToolset。运行时 Agent 只先看到技能的元数据（L1），需要时再加载完整指令（L2），只有真正进入 SEO 优化阶段才会调用load_skill_resource拉取本参考文件（L3），从而在控制上下文窗口的同时保证规则完整可用。

二、On-Page SEO 检查清单（完整解析）

seo-guidelines.md将页面 SEO 拆成六个可逐项打勾的维度，下面逐一展开，并补充可执行的具体标准。

1. 标题标签（Title Tag）

长度控制在 50-60 个字符：过短浪费展示空间，过长会被搜索引擎在结果页截断；
主要关键词尽量靠近标题开头：提升相关性信号，也让用户在扫读搜索结果时第一时间看到核心词；
包含一个力量词（Power Word）：文档给出了Build、Master、Complete、Essential等示例，这类动词能提高点击率（CTR）；
推荐格式：[Action] [Topic] with [Technology] — [Benefit]，例如 "Build Production-Ready RAG with Vertex AI — Complete Guide"。

这一格式与blog-writer技能 style-guide.md 中「标题要面向行动、包含技术名（如 Building X with Y）」的规则完全一致，说明标题规范在技能间是统一对齐的。

2. 元描述（Meta Description）

长度 150-160 个字符：这是搜索结果摘要的典型展示区间；
自然地融入主要关键词：而非机械堆砌；
以行动号召（CTA）或价值主张收尾：让用户明确「读完能获得什么」；
必须是一个完整、有说服力的句子：元描述会被直接展示在搜索结果中，质量直接影响点击率。

在content-research-writer的 SKILL.md 第三阶段，这一条被落实为「Meta description draft (150-160 chars)」的输出要求，即写作前先起草元描述。

3. 标题层级（H2/H3）

H2 用于主要章节，每篇文章 5-8 个：这个数量既能保证内容有足够的模块划分，又不会让文章碎片化；
H3 用于 H2 内部的子小节：形成清晰的层级树；
在 2-3 个标题中自然地融入关键词：帮助搜索引擎理解文章主题分布；
标题必须可扫读（scannable）：理想状态下，读者只读各级标题就能把握全文脉络——这与 style-guide.md 中「每个 H2 章节都应独立有价值」的要求相辅相成。

4. 内容结构（Content Structure）

前 100 词必须包含主要关键词：让读者与搜索引擎第一时间确认主题；
短段落，每段不超过 2-3 句：降低移动端阅读负担；
每 300-400 词插入一个项目符号或编号列表：打断纯文本墙，提升可读性与信息提取效率；
超过 2000 词的文章建议加目录（Table of Contents）：改善长文导航体验；
对关键术语与定义加粗：突出信息重心。

注意「前 100 词」与「标题层级」两条规则共同构成了关键词在页面中的「黄金分布」：标题、首段、若干副标题各出现一次，避免过度集中或缺失。

5. 内部链接与外部链接（Internal & External Links）

2-3 个指向站内相关内容的内链：传递权重并提升站内导航；
3-5 个指向权威来源的外链：增强内容可信度；
使用描述性锚文本：明确禁止 "click here" 这类无信息量的链接文字；
外链建议在新标签页打开：避免用户离开当前阅读上下文。

content-research-writer在内容规划阶段（Phase 2）就要求提前「Identify internal links to related content and external links to authoritative sources」，说明链接策略应当在动笔前规划好，而不是写完后补救。

6. 图片优化（Images）

Alt 文本必须包含相关关键词：既是无障碍需求，也是图片搜索的重要信号；
使用描述性文件名：明确反对IMG_001.png这类无意义命名，应采用如adk-skill-progressive-disclosure.webp的风格；
压缩到 200KB 以下：控制页面加载体积；
优先使用 WebP 格式：在同等画质下体积更小。本仓库的 assets 目录中大量使用.webp截图与示意图，正是这一规范的直观示范。

三、关键词策略（Keyword Strategy）

文档在检查清单之外单独定义了四层关键词体系：

主要关键词（Primary keyword）：全文自然使用 3-5 次——对应前文「标题、首段、2-3 个副标题」的黄金分布；
次要关键词（Secondary keywords）：每个使用 1-2 次，覆盖主题的相关侧面；
LSI 关键词：即与主题语义相关的同义/近义表达，好内容中会自然涌现，无需刻意堆砌；
绝对禁止关键词堆砌（keyword stuffing）：文档给出的判断标准非常朴素——「如果读起来别扭，就删掉这个词」。

与 agent.py 中内联技能seo-checklist的指令对照可以发现，两者对关键词密度的要求完全一致：「Natural keyword density (1-2%, never forced or awkward)」。这份seo-guidelines.md正是对内联技能九条检查项中「关键词密度」「首段关键词」「标题关键词」等条目的详细展开版。

四、把规范嵌入 AI 写作工作流的实践建议

基于content-research-writer的五阶段方法论与本文解析的检查清单，一个可复制的「SEO 化内容生产流水线」如下：

调研阶段（对应 Phase 1）：确定主主题并拆解子主题，列出受众会问的 3-5 个关键问题，锁定目标关键词与 3-5 个相关关键词；
规划阶段（对应 Phase 2）：明确内容类型（教程/深度长文/对比/观点），设定目标字数（教程类 1500-2500 词，观点类 800-1500 词），规划 2-3 个代码示例与内外链清单；
SEO 优化阶段（对应 Phase 3）：通过load_skill_resource加载本参考文档，逐项套用检查清单，先产出标题草案（50-60 字符）、元描述草案（150-160 字符）与 URL slug 建议（短、含关键词、连字符分隔）；
写作阶段（对应 Phase 4）：先写 2 句话的 hook，用倒金字塔结构（每个小节最重要的信息前置），以可立即执行的要点收尾；
质检阶段（对应 Phase 5）：回到检查清单逐项核对——每个章节是否有独立价值、所有论断是否有证据或代码支撑、前 100 词是否包含主关键词、每 300-400 词是否有列表打断、标题是否可仅凭扫读理解全文。

当这份规范与 blog-writer 的排版规则、style-guide.md 的文体规则组合使用时，Agent 可以同时满足「搜索引擎友好」与「读者体验友好」两个目标——这也是 agent.py 中根 Agent 指令「Apply multiple skills together when appropriate」所鼓励的多技能协同用法。

五、可复用的速查清单

将seo-guidelines.md压缩为一张写作前必须完成的核对表：

维度	硬性标准	快速自检
标题标签	50-60 字符，主关键词靠前，含力量词	格式是否为 Action + Topic + Technology + Benefit
元描述	150-160 字符，含主关键词，以 CTA 结尾	是否是一句完整、有说服力的句子
标题层级	H2 5-8 个，H3 分层，2-3 个标题含关键词	只读标题能否理解全文
内容结构	前 100 词含主关键词，段落 ≤2-3 句，每 300-400 词有列表	长文是否加了目录、术语是否加粗
内外链接	内链 2-3 个 + 外链 3-5 个，描述性锚文本	是否还有 "click here" 式锚文本
图片	Alt 含关键词，文件名描述性，<200KB，优先 WebP	是否还存在 IMG_001 式命名
关键词	主词 3-5 次，次词 1-2 次，密度 1-2%	是否有读起来别扭的强行植入