基于 Claude Code 与 Agent Skills 的营销技能包实战：SEO 内容生成与 FAQ 结构化数据落地

1. 从 "marketingskills" 这个标题说起：它到底想解决什么问题

第一次看到 "marketingskills" 这个标题，我脑子里蹦出来的不是某个具体工具，而是一类很典型的需求：把营销这件事里那些重复、琐碎、又必须做对的活儿，交给一套可复用的技能包去处理。它不是一个单点脚本，更像是一组围绕营销场景沉淀下来的能力集合——SEO 内容生成、结构化数据补全、落地页文案、关键词聚类、竞品拆解、FAQ 页面搭建等等。而它之所以最近被反复提起，是因为它和 Claude Code、AI agents、Agent Skills spec 这几个词绑在了一起。

说白了，marketingskills 想干的事，是把"营销人脑子里的经验"翻译成"AI agent 能直接调用的技能"。以前你要让 AI 帮你写一篇符合谷歌 SEO 规范的落地页，你得在 prompt 里把标题层级、关键词密度、FAQ 结构化数据、内链逻辑全交代一遍，每次都得重来。现在有了 Agent Skills 这套规范，你可以把这些规则固化成一个 skill，agent 每次执行任务时自动加载，输出质量稳定得多。

这套东西适合谁？三类人最该关注。第一类是独立站运营和做谷歌 SEO 的人，尤其是那种一个人要管内容、技术、外链的全栈选手；第二类是把 Claude Code 当日常生产力工具的开发者，想把自己的工作流封装成可复用技能；第三类是正在研究 AI agents 落地的人，想看看"技能规范"这种抽象概念到底怎么变成能跑的东西。不管你是刚听说 Claude Code 的新手，还是已经在用 agent 干活的老手，理解 marketingskills 背后的设计思路，都比单纯抄一个配置文件有价值得多。

我下面会从整体设计、核心细节、实操落地、问题排查四个层面，把这件事拆开讲。中间会穿插我自己踩过的坑和一些不太写在官方文档里的经验，尽量让你看完能直接动手，而不是看完还得再去搜一遍。

2. 内容整体设计与思路拆解

2.1 为什么是"技能包"而不是"一个大 prompt"

很多人第一反应是：我写一个超长的 system prompt 不就行了，把所有营销规则塞进去。我试过，结论是行不通，原因有三个。

第一是上下文污染。一个 prompt 里同时塞 SEO 规则、文案风格、结构化数据模板、内链策略，agent 在执行"写 FAQ"这个子任务时，会被无关的"标题层级规则"干扰，输出容易跑偏。技能包的核心价值就是按需加载——写 FAQ 的时候只加载 FAQ 相关的 skill，上下文干净，模型注意力集中。

第二是可维护性。营销规则是会变的，谷歌的 FAQ 结构化数据规范这两年就调整过展示逻辑。如果全塞在一个 prompt 里，改一处要重新测全流程。拆成 skill 之后，你只改 FAQ 那个文件，其他技能不受影响。

第三是复用性。同一个"关键词聚类"skill，可以同时被"写落地页"和"做内容日历"两个任务调用。这种组合能力是大 prompt 给不了的。

Agent Skills spec 本质上定义了一套约定：一个 skill 是一个目录，里面有描述文件（说明这个技能干什么、什么时候触发）、指令文件（具体怎么做）、以及可选的脚本和资源。agent 在运行时根据任务描述匹配对应的 skill，加载它的指令。这个设计思路和传统软件里的"模块化"是一回事，只不过模块的边界从函数变成了自然语言指令。

2.2 marketingskills 的能力边界怎么划

划边界这件事，直接决定了你这套技能包好不好用。我见过两种极端：一种是粒度过粗，一个 skill 叫"做营销"，里面啥都有，结果和写大 prompt 没区别；另一种是粒度过细，把"写标题"和"写副标题"拆成两个 skill，调用起来累死。

我的经验是，按"交付物"划边界最稳。一个 skill 对应一个明确的产出物，比如：

• 一篇符合 SEO 规范的博客文章
• 一个带 FAQ 结构化数据的页面
• 一份关键词聚类表
• 一套落地页文案（含标题、卖点、CTA）

这样划分的好处是，每个 skill 的"完成标准"很清晰，agent 知道自己什么时候算干完了，你验收的时候也有明确依据。反过来，如果按"动作"划分（比如"分析关键词""写文案"），边界就模糊，因为分析和写作往往是交织的。

2.3 和 Claude Code 的关系：为什么选它做载体

marketingskills 这类技能包，理论上可以跑在任何支持工具调用的 agent 框架上。但实际社区里大家普遍用 Claude Code 来承载，原因很实际。

Claude Code 本身是一个能在终端里直接读写文件、执行命令的 agent。这意味着 skill 里的指令可以直接操作你的项目文件——读现有的页面、改标题标签、生成新的 markdown、跑一个脚本校验结构化数据。这种"能落地到文件系统"的能力，是纯对话式 agent 给不了的。你让一个只会聊天的模型写 SEO 文章，它给你一段文本，你还得自己复制粘贴；Claude Code 能直接把文件写到你指定的目录，甚至顺手把 sitemap 更新了。

另外 Claude Code 对 Agent Skills spec 的支持比较完整，skill 的加载、触发、组合都有明确的机制。这也是为什么热词里 "claude code 使用教程""claude code 安装" 这类搜索量一直很高——大家不是单纯想学一个工具，而是想借它把技能包跑起来。

2.4 方案选型背后的取舍

这里有个很多人纠结的点：skill 里的逻辑，到底用自然语言写，还是用脚本写？

我的判断标准是看确定性。如果一件事有明确的、不会变通的规则，用脚本。比如"检查页面是否包含 FAQ 结构化数据"，这是个 JSON-LD 格式校验，写个脚本几行搞定，比让模型去判断靠谱得多。如果一件事需要判断和生成，用自然语言。比如"根据产品特点写三个卖点"，这个没法用脚本，只能靠模型。

实际项目里通常是混合的：skill 的指令文件用自然语言描述整体流程，关键校验步骤调用脚本。这样既保留了灵活性，又在关键节点上有确定性保障。我见过有人把所有逻辑都写成脚本，结果 skill 变得极其僵硬，稍微换个产品类型就报错；也见过全用自然语言的，输出质量忽高忽低。混合方案是踩过坑之后比较稳的选择。

3. 核心细节解析与实操要点

3.1 一个 skill 目录到底长什么样

按 Agent Skills spec 的常见实践，一个 skill 目录结构大致是这样：

marketingskills/ seo-article/ SKILL.md # 技能描述 + 指令 scripts/ check_schema.py # 结构化数据校验脚本 resources/ tone-guide.md # 文案风格参考 faq-page/ SKILL.md scripts/ validate_faq.py

SKILL.md是整个技能的核心，它通常分两部分。前半部分是元信息，说明这个技能叫什么、什么时候该被触发、需要什么输入。这部分写得好不好，直接决定 agent 能不能在对的时候找到这个技能。后半部分是指令正文，一步步告诉 agent 怎么做。

元信息里的"触发条件"是最容易被写砸的地方。很多人写成"当用户需要写文章时触发"，太宽泛了，agent 一看到"写"字就加载，结果写邮件也加载这个 skill。好的触发条件应该具体到场景特征，比如"当任务涉及为独立站生成面向搜索引擎的博客内容，且需要包含标题层级和关键词布局时触发"。

3.2 指令正文怎么写才不跑偏

指令正文我一般按"目标—步骤—验收"三段式写。

目标段用一两句话锁定产出物。比如"生成一篇 1500 到 2000 字的博客文章，包含 H1 到 H3 的层级结构，主关键词自然出现在标题、首段和至少两个小标题中"。

步骤段是重点，要拆到 agent 能执行的程度。我通常拆成：先读什么（现有内容、关键词表）、再做什么（列大纲、写正文、补内链）、最后检查什么（关键词密度、层级、结构化数据）。每一步都尽量给出判断依据，而不是笼统的"写好一点"。

验收段列出完成标准。这一步很多人省略，结果 agent 干到一半就停了，因为它不知道什么算完成。明确写"文章必须包含至少 3 个 H2 和 6 个 H3，FAQ 部分至少 4 个问答对"，agent 就有了明确的停止条件。

提示：指令正文里避免用"尽量""适当""合理"这类模糊词。模型对模糊词的理解每次都不一样，输出就不稳定。能用数字就用数字，能用具体例子就用具体例子。

3.3 FAQ 结构化数据这块，坑最多

热词里"谷歌 SEO 的 FAQPage 结构化数据是怎么回事"搜索量很高，说明这是大家的痛点。我在 skill 里处理这块时，总结了几条硬规则。

FAQPage 结构化数据本质是一段 JSON-LD，告诉搜索引擎"这个页面上的问答是 FAQ 类型的内容"。它的基本形态是这样：

{ "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "问题文本", "acceptedAnswer": { "@type": "Answer", "text": "答案文本" } } ] }

坑在于：结构化数据里的问答，必须和页面上用户可见的问答完全一致。我见过有人为了 SEO 在 JSON-LD 里塞了一堆页面上根本没有的问题，这种做法一旦被识别，轻则结构化数据不展示，重则影响整站信任度。所以 skill 里我会加一条硬性校验：脚本读取页面可见的 FAQ 文本，和 JSON-LD 里的内容做比对，不一致就报错。

另一个坑是别把 FAQPage 用在非 FAQ 内容上。有些页面其实是产品介绍，硬套 FAQ 结构，搜索引擎能识别出来。skill 的触发条件里要写清楚，只有页面主体确实是问答形式时才生成 FAQPage 数据。

3.4 关键词布局的量化标准

SEO 内容里关键词怎么放，是另一个高频问题。我在 skill 里固化了几个量化标准，避免每次靠感觉。

密度这个数不是拍脑袋来的。1% 到 2% 是长期实践里比较安全的区间，低于 1% 可能主题不够聚焦，高于 2% 就有堆砌嫌疑。计算方式是：关键词出现次数 ÷ 总词数。一篇 1500 词的文章，主关键词出现 15 到 30 次比较合适。skill 里可以让脚本自动统计，超标就提示。

3.5 技能之间的组合与调用顺序

marketingskills 不是孤立技能的堆叠，它们之间有调用关系。典型的一条链路是：先跑"关键词聚类"skill 得到关键词分组，再把分组喂给"SEO 文章"skill 生成内容，最后用"FAQ 页面"skill 补结构化数据。

这里有个实操要点：skill 之间的数据传递要约定好格式。我一般用 markdown 表格或 JSON 作为中间产物，因为这两种格式 agent 读写都不容易出错。如果让上一个 skill 输出一段自由文本，下一个 skill 解析起来就容易出岔子。

调用顺序也不是死的。有时候你已经有现成内容，只需要补 FAQ 数据，那就跳过前面直接调 FAQ skill。所以每个 skill 的输入设计要尽量独立，不要强依赖前一个 skill 的输出格式，否则组合起来会很脆。

4. 实操过程与核心环节实现

4.1 环境准备：把 Claude Code 跑起来

要跑 marketingskills，前提是 Claude Code 能用。安装这块热词里问得最多的是"claude code 安装""ubuntu 配置 claude code""mac 安装 claude code"，我按平台说下要点。

在 macOS 或 Linux 上，通常通过包管理器安装，装完之后在终端里能直接调用。Windows 用户要注意，热词里提到"claude code 由于与 64 位版本的 windows 不兼容"，这类兼容性问题一般出在运行环境上，比较稳的做法是在 WSL 里跑，或者用官方提供的桌面版。安装完成后第一件事是验证版本和登录状态，能正常对话就说明基础环境没问题。

如果你所在的环境访问官方服务受限，热词里也提到了"使用 cc switch 接入 deepseek、qwen、glm 等模型"这类第三方接入方式。这类方案的核心思路是让 Claude Code 通过兼容接口调用其他模型。配置时要注意模型的能力差异——有些模型对长指令和工具调用的支持没那么好，跑复杂 skill 时可能不稳定，建议先用简单 skill 试水。

VS Code 用户可以直接装 Claude Code 插件，在编辑器里调用。插件配置的关键是确认它指向的是你装好的 Claude Code 本体，而不是另起一套环境。热词里"vscode 配置 claude code""claude code for vs code"问的就是这个，配置对了之后，编辑器里改文件、终端里跑 agent 能共享同一套 skill 目录。

4.2 创建第一个 skill：从 SEO 文章开始

我建议第一个 skill 从"SEO 文章生成"入手，因为它最能体现技能包的价值，也最容易验证效果。

第一步，建目录。在你的项目根目录下建marketingskills/seo-article/，里面放SKILL.md。

第二步，写元信息。描述这个技能做什么、什么时候触发、需要什么输入。输入我一般要求三样：主关键词、目标读者、文章大致方向。这三样给齐，agent 就能开工。

第三步，写指令正文。我通常这样组织：

## 目标 生成一篇面向搜索引擎的博客文章，字数 1500 到 2000。 ## 步骤 1. 读取关键词表，确认主关键词和 3 到 5 个长尾词 2. 列出 H2 大纲，每个 H2 下规划 2 到 3 个 H3 3. 按大纲写正文，主关键词在标题、首段、至少两个 H2 中出现 4. 为每个 H3 补充具体案例或数据 5. 生成 FAQ 部分，至少 4 个问答对 6. 调用 check_schema.py 校验结构化数据 ## 验收标准 - H2 不少于 3 个，H3 不少于 6 个 - 主关键词密度在 1% 到 2% 之间 - FAQ 结构化数据校验通过

第四步，写校验脚本。check_schema.py干两件事：统计关键词密度、校验 JSON-LD 格式。关键词密度统计很简单，读文本、分词、计数、算比例。JSON-LD 校验用标准库解析，格式不对就抛错。

第五步，测试。拿一个真实关键词跑一遍，看输出是否符合验收标准。第一次大概率不完美，根据问题回去改指令。我第一版 skill 跑出来关键词密度到了 3.5%，明显堆砌，后来在指令里加了"每个 H2 下主关键词最多出现 2 次"的约束才压下来。

4.3 参数计算：关键词密度怎么算才准

关键词密度这个参数，很多人算错，因为分词方式不一样。中文和英文的处理逻辑不同。

英文相对简单，按空格分词，统计关键词短语出现的次数，除以总词数。注意是短语匹配，不是单词匹配。"digital marketing" 作为一个短语算一次，不能拆成 "digital" 和 "marketing" 各算一次。

中文麻烦在分词。如果按字算，密度会虚高；按词算，又依赖分词工具。我的做法是：中文内容用成熟的分词库切词，然后统计关键词（通常是 2 到 4 个字的词组）出现次数。如果关键词本身是英文混中文，就分别处理再合并。

举个实际例子。一篇 1600 词的文章，主关键词是"独立站 SEO"，出现 24 次。密度 = 24 ÷ 1600 = 1.5%，落在安全区间。如果出现 40 次，密度 2.5%，就偏高了，skill 应该提示精简。

注意：密度只是参考指标，不是硬性 KPI。有些长尾词天然出现频率就高，硬压反而读起来别扭。skill 里把密度作为"预警线"而不是"红线"更合理，超标时提示人工确认，而不是直接判定失败。

4.4 结构化数据的生成与校验闭环

FAQ 结构化数据的生成，我设计成一个闭环：生成 → 校验 → 修正。

生成阶段，skill 指令要求 agent 先从文章里提取问答对，再转成 JSON-LD。提取这一步很关键，要确保问答对确实来自页面可见内容，而不是 agent 自己编的。

校验阶段，脚本做三件事：检查 JSON 语法是否合法、检查必填字段（@context、@type、mainEntity）是否齐全、检查问答对数量和页面可见问答是否一致。

修正阶段，如果校验失败，agent 根据错误信息调整。比如提示"第 3 个问答对的答案文本与页面不一致"，agent 就回去对齐。

这个闭环跑通之后，结构化数据的出错率能降到很低。我实测下来，第一版没有校验的时候，十次里有三四次 JSON 格式有问题；加上校验闭环之后，基本一次过。

4.5 把技能包接入日常工作流

skill 建好之后，怎么用起来是另一回事。我的做法是把它和内容生产流程绑定。

每周做内容规划时，先跑关键词聚类 skill，得到一批分组关键词。然后针对每个分组，调 SEO 文章 skill 生成初稿。初稿出来之后，人工过一遍，重点看逻辑和事实准确性——这部分 AI 替代不了。确认没问题后，调 FAQ skill 补结构化数据，最后发布。

整个流程里，AI 负责的是"量大、规则明确"的部分，人负责"判断、把关"的部分。这个分工是我试了很多次之后定下来的。全交给 AI，质量不稳；全自己做，效率上不去。人机各管一段，是目前比较舒服的状态。

5. 常见问题与排查技巧实录

5.1 skill 不触发或者触发错了怎么办

这是最常见的问题。表现是 agent 该用 skill 的时候没用，或者不该用的时候乱用。

排查思路分三步。先看元信息里的触发条件是不是写得太宽或太窄。太宽会导致误触发，太窄会导致不触发。我一般把触发条件写成"场景 + 产出物"的组合，比如"当需要为电商独立站生成产品分类页的 SEO 文案时"，比单纯写"写文案"精确得多。

再看 skill 目录的位置对不对。Agent Skills spec 对 skill 的存放路径有约定，放错地方 agent 扫描不到。确认你的 skill 在约定的技能目录下，且SKILL.md文件名大小写正确——有些系统对文件名大小写敏感。

最后看描述语言和任务语言是否匹配。如果你的 skill 描述是中文，但任务是用英文下达的，匹配可能失败。统一语言能减少这类问题。

5.2 输出质量忽高忽低

同一个 skill，有时候输出很好，有时候一塌糊涂。这种波动通常来自三个原因。

一是指令里的模糊表述。前面提过，"适当""合理"这类词会让模型每次理解不同。把它们替换成具体数字或例子，波动会明显减小。

二是输入信息不完整。如果 skill 需要关键词表但你没给，agent 可能自己编一个，质量自然不稳。skill 的元信息里要明确列出必需输入，缺了就提示，而不是硬着头皮往下做。

三是上下文太长。如果一次任务里加载了太多 skill，或者对话历史很长，模型注意力会被稀释。解决办法是拆任务，一次只做一件事，做完清空上下文再做下一件。

5.3 结构化数据校验总是不通过

校验不通过，先看错误信息指向哪里。常见的有三类。

JSON 语法错误，通常是引号、逗号、括号的问题。这类错误脚本会直接报出行号，照着改就行。我建议生成 JSON-LD 时用脚本序列化，而不是让模型手写，手写太容易出语法错。

字段缺失，检查 @context、@type、mainEntity 这几个必填项。有时候模型会漏掉 @context，导致整段数据无效。

内容不一致，这是最隐蔽的。JSON-LD 里的问答和页面可见问答对不上，可能是 agent 在生成时改写了措辞。解决办法是在指令里强调"问答文本必须逐字复制页面内容，不得改写"。

5.4 常见问题速查表

5.5 几个不太写在文档里的经验

第一，skill 要小步迭代。别指望一次写出完美 skill，先写个能跑的版本，用真实任务测，根据问题改。我第一个 skill 改了七八版才稳定。

第二，保留失败案例。每次 skill 输出出问题，把那个案例存下来，作为回归测试。改完 skill 之后拿这些案例再跑一遍，确认没退化。这个习惯帮我避免了好几次"改好一个坏了一个"的情况。

第三，别过度依赖自动化校验。脚本能查格式、查密度，但查不了内容是否真的有价值。最终发布前，人工过一遍是省不掉的。我见过有人完全信任 skill 输出，结果文章读起来像机器拼凑的，搜索引擎不买账，读者也不买账。

第四，技能包要跟着规则更新。搜索引擎的规范、结构化数据的支持范围都会变。我一般每季度回顾一次 skill 里的规则，把过时的部分更新掉。这件事不做，技能包会慢慢失效。

6. 关于扩展方向的一点个人想法

这套 marketingskills 的框架，其实不限于营销。同样的思路可以搬到很多场景：客服话术生成、产品文档撰写、代码注释规范、甚至周报整理。核心逻辑是一样的——把重复的、有明确规则的、需要稳定输出的工作，封装成 agent 能调用的技能。

我最近在试的一个方向，是把 skill 和项目里的实际数据打通。比如 SEO skill 不只生成内容，还能读取站点现有的页面列表，自动检查内链是否合理、有没有孤岛页面。这一步做完，skill 就从"内容生成器"变成了"内容运营助手"，价值又上一层。

如果你刚开始接触，我的建议是别贪多。先挑一个你每天都在做的、规则最清晰的活儿，把它做成 skill，跑通，用顺，再考虑第二个。技能包的价值在于积累，一个能稳定用的 skill，胜过十个半成品。