基于Agent Skills spec的营销技能库：从SEO内容简报、FAQ结构化数据到Claude Code实操

1. 从marketingskills这个仓库名说起它到底想解决什么问题第一次看到marketingskills这个名字我的直觉是这大概率是一个把营销领域里那些高频、重复、有固定套路的活儿封装成可复用技能模块的项目。后来翻了一圈资料结合它出现在 Claude Code、AI agents、Agent Skills spec 这些关键词的语境里基本可以确认——它是一套面向 AI 智能体的营销技能包用一套约定好的规范Agent Skills spec把营销工作流拆成一个个可被 AI 调用的技能单元。说白了过去我们用 AI 做营销相关的事情基本是一次性对话写个文案、想个 slogan、列个投放渠道聊完就散了下次还得重新描述背景、重新喂资料。marketingskills想干的事情是把这些营销动作沉淀成结构化的技能让 AI agent 在需要的时候能自动识别、加载、执行而不是每次都靠人肉 prompt 去堆。这件事的价值在哪我举个自己踩过的例子。之前帮一个做独立站的朋友做 SEO 内容规划每次让 AI 写文章都要重复交代目标关键词是什么、站点的调性是什么、内链规则是什么、FAQ 结构化数据要不要加、加几条。重复了十几次之后我就烦了——这明明是可以固化下来的东西。marketingskills这类项目的核心思路就是把这些每次都要交代的上下文变成技能定义的一部分让 agent 自己知道做 SEO 内容时该遵守哪些规则。它适合谁三类人最该关注一是做独立站、做谷歌 SEO 的运营和站长二是用 Claude Code 这类工具搭自动化工作流的开发者三是想把团队营销经验沉淀成可复用资产的市场负责人。哪怕你暂时不写代码理解这套技能化的思路对你组织自己的营销工作也有帮助。需要说明的是marketingskills这个项目本身在公开渠道的完整文档并不算多下面很多内容是我基于 Agent Skills spec 的通用规范、Claude Code 的实际使用经验以及营销场景的常见实践做的合理补全。我会明确标注哪些是通用规范、哪些是我的实操推断你照着落地时按自己项目的实际情况调整。2. Agent Skills spec 到底规定了什么技能包的骨架长什么样2.1 一个技能的最小构成元数据 指令 资源Agent Skills spec 这类规范核心思想其实很朴素一个技能就是一个文件夹里面至少有一个描述文件通常是SKILL.md或类似的 markdown开头用 YAML frontmatter 声明元数据正文写清楚这个技能是干什么的、什么时候用、怎么用。旁边可以挂脚本、模板、参考文档等资源。我把它类比成给新员工写的岗位操作手册元数据是岗位名称和适用场景正文是操作步骤附件是模板和工具。AI agent 在接到任务时先扫一遍所有技能的元数据判断这个活儿该用哪个技能然后才把对应技能的完整内容加载进上下文。这个先看目录、再翻正文的机制很关键——它让 agent 不用一次性把所有技能细节都塞进上下文省 token 也更精准。一个典型的技能目录结构大概是这样marketingskills/ ├── seo-content-brief/ │ ├── SKILL.md │ ├── templates/ │ │ └── brief-template.md │ └── references/ │ └── keyword-research-guide.md ├── faq-schema-generator/ │ ├── SKILL.md │ └── scripts/ │ └── build_faq_jsonld.py └── landing-page-copy/ ├── SKILL.md └── examples/ └── good-vs-bad.md每个技能独立成目录互不干扰这样你可以按需增删也方便团队协作——不同人负责不同技能最后拼成一个完整的营销技能库。2.2 元数据字段里最容易被写错的三个地方元数据看着简单但我在实际配置时发现有三个字段最容易出问题而且一出问题 agent 就装死或者乱用技能。第一个是name。规范一般要求用小写字母加连字符比如seo-content-brief不要用空格、下划线或者中文。我见过有人写成SEO Content Brief结果 agent 匹配时死活对不上。名字还要足够具体seo 这种太宽泛的名字会让 agent 在多个场景下都想调用它反而降低准确率。第二个是description。这是整个技能里最重要的一句话因为它决定了 agent 在目录扫描阶段能不能判断出该不该用你。写法上要包含做什么 什么时候用 触发关键词。比如description: 为独立站生成谷歌 SEO 内容简报包含目标关键词、搜索意图、H 标签结构、内链建议和 FAQ 结构化数据规划。当用户需要规划 SEO 文章、做关键词布局或生成内容大纲时使用。对比一下反例description: 帮助做 SEO。这种描述 agent 根本没法判断边界最后要么不用要么滥用。第三个是version和allowed-tools如果规范支持。版本号方便你迭代时追踪allowed-tools用来限制这个技能能调用哪些工具比如一个纯文案技能就不该有执行 shell 命令的权限。这是安全边界别偷懒不写。2.3 为什么技能比长 prompt更适合营销场景有人会问我把这些规则写成一个超长 prompt 不就行了何必搞技能包我实测下来的体会是长 prompt 有三个绕不过去的坑。第一上下文污染。你为了做 SEO 写了一大段规则结果这次任务只是想让 AI 改个标题那一大段规则全成了噪音还可能干扰判断。技能机制是按需加载用不到就不进上下文。第二复用困难。长 prompt 通常散落在各个聊天记录、文档、笔记里想复用就得翻找复制。技能包是文件可以进 Git、可以版本管理、可以团队共享。第三无法组合。营销任务往往是复合的——写一篇 SEO 文章可能同时需要关键词研究内容简报FAQ 结构化数据内链规划好几个技能。技能机制天然支持组合调用长 prompt 只能越堆越长。提示如果你现在还在用一份几千字的长 prompt 做营销自动化建议先挑一个最高频的场景比如 SEO 内容简报拆成独立技能跑通之后再逐步迁移其他场景。一次性全拆容易翻车。3. 把营销工作流拆成技能我的拆分逻辑和踩坑记录3.1 拆分粒度太粗没用太细累死拆技能最难的不是技术是拆多细。我一开始犯的错是拆太细把写标题写 meta description写 H1拆成三个技能结果 agent 每次写文章要连续调用七八个技能上下文来回切换反而慢且容易乱。后来我调整成按交付物拆分一个技能对应一个可独立交付的成果。比如技能名交付物触发场景keyword-cluster关键词聚类表拿到一批种子词需要分组seo-content-brief内容简报文档确定要写某篇文章前的规划faq-schema-generatorFAQ 结构化数据 JSON-LD文章写完需要加 FAQ 标记internal-link-planner内链建议清单文章发布前做站内链接优化landing-page-copy落地页文案做独立站产品页/活动页这个粒度下每个技能都有清晰的输入和输出agent 判断起来也容易。太粗的技能比如一个做 SEO技能包打天下会导致技能内部逻辑复杂、维护困难太细的技能则会让调用链变长。3.2 我踩过的坑技能之间抢活拆完技能后我遇到一个典型问题seo-content-brief和landing-page-copy两个技能都包含写标题的能力结果 agent 在写落地页时有时候会错误地调用 SEO 简报技能里的标题规则导致标题写得像博客文章标题不像转化型落地页标题。根因是 description 边界没划清。修复方法是在两个技能的 description 里明确写不适用场景# seo-content-brief 的 description 补充 description: ...适用于博客文章、资讯页的内容规划。不适用于产品落地页、活动页的转化型文案。# landing-page-copy 的 description 补充 description: ...适用于产品页、活动页、注册页等以转化为目标的页面。不适用于博客文章的 SEO 内容规划。加上不适用的负向描述后误调用率明显下降。这个经验我觉得挺重要——写技能描述时不光要说我是什么还要说我不是什么。3.3 技能内部的指令怎么写才不容易被 AI 忽略技能正文SKILL.md 的 body是给 agent 看的操作手册。我观察下来AI 对结构化、带示例的指令执行得最好对一大段散文式描述执行得最差。我的写法是三段式先写何时使用再写执行步骤最后写输出格式和示例。执行步骤用有序列表每步尽量是动词开头、可验证。比如faq-schema-generator的正文## 何时使用 当文章内容已完成需要为页面添加 FAQ 结构化数据以争取搜索结果中的富摘要展示时。 ## 执行步骤 1. 从文章正文中提取 3-6 个用户最可能提问的问题优先选择正文已明确回答的。 2. 每个问题的答案控制在 40-60 字直接回答不要绕。 3. 按 schema.org 的 FAQPage 规范生成 JSON-LD。 4. 校验 JSON 合法性确保没有尾逗号、引号转义正确。 ## 输出格式 输出一段可直接嵌入 head 或 body 的 script typeapplication/ldjson 代码块。这里有个细节步骤 2 里我特意写了40-60 字。为什么因为 FAQ 答案太短信息量不够太长在搜索结果里会被截断40-60 字是我实测下来比较舒服的区间。这种具体数字比答案要简洁有用得多——AI 对模糊形容词的理解很不稳定。4. 在 Claude Code 里跑通第一个营销技能完整实操链路4.1 环境准备别在第一步就卡住要用 Claude Code 跑技能前提是你本地能正常使用 Claude Code。安装方式按官方文档来就行Mac、Ubuntu、Windows 各有对应流程。这里我不展开安装细节官方文档写得很清楚只提醒几个我踩过的点。第一Windows 用户注意 64 位兼容性问题有些老版本环境会报不兼容建议用较新的系统版本。第二VS Code 里配置 Claude Code 插件时注意工作区目录要指向你的技能库根目录否则 agent 扫不到技能。第三如果你所在环境对账号有访问限制可能会遇到订阅访问被禁用之类的提示这种情况按官方支持渠道确认不要去找来路不明的绕过方案——既不安全也不稳定。注意任何涉及绕过账号限制、使用非官方渠道的做法我都不建议。技能库本身是纯本地的文件跟账号体系无关你完全可以在合规前提下先把技能文件组织好。4.2 目录放哪、怎么让 agent 发现技能技能库的存放位置一般有两种约定一种是放在项目根目录下的特定文件夹比如.claude/skills/或项目自定义的skills/另一种是放在用户级配置目录全局可用。我建议营销技能库放在项目级因为营销内容通常跟具体站点/品牌强相关放项目里方便跟内容一起版本管理。放好之后验证 agent 能不能发现技能最直接的办法是问它你现在有哪些可用的技能如果它能列出你定义的技能名和描述说明扫描成功。如果列不出来八成是目录层级不对或者元数据格式有误。我遇到过一次扫描失败排查了半天最后发现是 YAML frontmatter 的---前后多了空行导致解析器没识别出来。这种低级错误特别浪费时间建议写完技能文件后先用一个 YAML 校验工具过一遍。4.3 一次真实的调用从关键词到内容简报假设我要给一个做户外装备的独立站规划一篇 SEO 文章。我的操作流程是这样的第一步把种子关键词丢给 agent触发keyword-cluster技能。输入大概是露营帐篷、轻量帐篷、双人帐篷、四季帐篷、帐篷推荐这几个词。技能会按搜索意图和主题相关性聚类输出分组表。第二步选定一个聚类比如轻量双人帐篷触发seo-content-brief技能。技能会输出目标主关键词、次要关键词、搜索意图判断信息型/商业型、建议的 H1/H2/H3 结构、需要覆盖的子话题、内链建议、FAQ 问题清单。第三步文章写完后触发faq-schema-generator把 FAQ 部分转成 JSON-LD。第四步发布前触发internal-link-planner检查站内链接是否合理。整个链路跑下来我最大的感受是技能把我脑子里的营销经验变成了agent 能执行的规则。以前这些判断全靠我临场发挥现在固化下来了换个人来操作产出质量也不会差太多。4.4 关于 FAQ 结构化数据几个容易搞错的点既然热词里提到了谷歌 SEO 的 FAQPage 结构化数据我多说几句实操中容易翻车的地方。FAQPage 结构化数据的本质是用 JSON-LD 告诉搜索引擎这个页面有一组问答。它不保证一定展示富摘要但它是争取展示的前提。常见错误有这么几个一是答案和页面上可见内容不一致。搜索引擎要求结构化数据必须对应页面上真实可见的内容你 JSON-LD 里写了但页面上没有属于违规可能被惩罚。二是问题数量堆太多。我一般控制在 3-6 个太多反而稀释相关性。而且问题要选用户真会搜的不是自己硬凑的。三是 JSON 格式错误。尾逗号、中文引号、转义没处理好都会导致解析失败。我建议用脚本生成而不是手写faq-schema-generator技能里挂一个 Python 脚本就是干这个的import json def build_faq_jsonld(faqs): faqs: list of dict, each with question and answer data { context: https://schema.org, type: FAQPage, mainEntity: [ { type: Question, name: item[question], acceptedAnswer: { type: Answer, text: item[answer] } } for item in faqs ] } return json.dumps(data, ensure_asciiFalse, indent2) if __name__ __main__: sample [ {question: 轻量双人帐篷一般多重, answer: 主流轻量双人帐篷重量在 1.5 到 2.5 公斤之间具体取决于面料和帐杆材质。}, {question: 四季帐篷能夏天用吗, answer: 可以但四季帐篷通风较差夏天使用可能闷热建议根据实际气候选择。} ] print(build_faq_jsonld(sample))用ensure_asciiFalse是为了让中文正常显示而不是变成\uXXXX这个细节很多人会忽略结果生成的 JSON 里全是转义字符虽然合法但没法读。5. 技能库的维护与迭代让它越用越值钱5.1 用版本管理管技能别用网盘技能库本质是文本文件天生适合 Git。我强烈建议用 Git 管理原因有三个一是能追踪每次修改出问题能回滚二是能分支实验新技能在分支上跑通了再合并三是团队协作时能 review。我见过有人把技能文件放在网盘同步结果两个人同时改冲突了都不知道谁覆盖了谁。营销技能是团队资产别用这种土办法。5.2 技能迭代的触发信号技能不是写完就完事了它需要跟着业务迭代。我总结了几个该迭代的信号agent 频繁误调用某个技能说明 description 边界不清某个技能的输出老是要人工大改说明指令不够具体或缺少示例业务规则变了比如站点改了内链策略技能里的规则没同步同一个技能被反复追加补充说明说明该重构了。每次迭代我都会在技能文件里加一行 changelog 注释记录改了什么、为什么改。半年后回头看这些记录能帮你快速回忆当时的决策逻辑。5.3 团队协作技能库怎么分工如果是一个小团队用我建议按技能负责人分工每个人认领几个技能负责维护和迭代。同时约定一个 review 机制——新技能或重大修改至少一个人过一遍。另外技能库最好配一份技能索引文档列出所有技能、用途、负责人、最近更新时间。这份索引不用很正式一个 markdown 表格就够但能省掉大量这个技能谁在管的沟通成本。5.4 一个我反复强调的原则技能要可验证技能写得好不好最终要看输出能不能验证。我在每个技能里都会加一段验收标准比如seo-content-brief的验收标准是输出的简报必须包含主关键词、至少 3 个次要关键词、完整的 H 标签结构、至少 3 条内链建议、至少 3 个 FAQ 问题。有了验收标准agent 自己也能对照检查人工 review 也有依据。这个习惯是从写代码的单元测试里学来的——没有验收标准的技能就像没有测试的代码你不知道它什么时候会悄悄坏掉。6. 关于本地模型接入和工具链选择的一些个人看法热词里出现了Claude Code 调用 LM Studio 本地模型接入 DeepSeek、Qwen、GLM 等模型这类话题我顺带聊聊技能库和模型选择的关系。技能库本身是模型无关的——它就是一堆 markdown 和脚本理论上任何支持 Agent Skills spec 的 agent 都能加载。但实际体验上不同模型对技能指令的遵循程度差别挺大。我的观察是指令遵循能力强的模型对结构化技能的执行更稳定能力弱一些的模型容易忽略技能里的细节规则或者把多个技能的规则混在一起。所以如果你打算用本地模型或第三方模型跑技能库建议先做个小测试拿一个规则明确的技能比如faq-schema-generator看模型能不能严格按步骤输出。如果连这种确定性高的技能都跑不稳那复杂的营销规划技能就更别指望了。另外工具链的选择上我的原则是够用就好别为了新而新。VS Code 插件、桌面版、命令行选一个你顺手的就行技能库的迁移成本很低不用被工具绑定。7. 最后分享几个我压箱底的小技巧写到这里技能库的搭建、拆分、调用、维护基本都覆盖了。最后分享几个我实操中攒下来的小技巧都是文档里不太会写、但用起来很爽的。第一个给技能加反例。在技能正文里放一段错误示范 vs 正确示范的对比AI 对反例的学习效果出奇地好。比如落地页文案技能里我会写错误这款帐篷采用先进材料品质卓越空洞正确这款帐篷 1.8 公斤单手可撑暴雨天实测不漏具体。加了反例之后输出质量肉眼可见地提升。第二个技能描述里埋触发词。用户实际说话时用的词跟技能名往往对不上。比如用户说帮我搞个文章大纲技能名却是seo-content-brief。在 description 里把文章大纲内容规划选题结构这些口语化触发词都写进去命中率会高很多。第三个定期做技能体检。每隔一两个月把所有技能过一遍删掉不再用的合并重复的更新过时的规则。技能库跟衣柜一样不定期清理就会越来越乱最后你都不想打开它。第四个把技能库当成团队知识资产而不是个人工具。我见过太多人把营销经验存在自己脑子里人一走经验就没了。技能库的价值恰恰在于它把隐性经验显性化、可传承。哪怕你明天换工具、换模型这套技能文件还在换个 agent 照样能用。marketingskills这个方向我觉得最值得关注的不是它具体实现了哪些技能而是它代表的一种思路把营销工作中那些可复用的判断和流程沉淀成 AI 能理解和执行的技能模块。这个思路一旦跑通你的营销效率提升不是线性的而是复利的——每沉淀一个技能后面所有相关任务都受益。