尧图网站建设 
1. 从marketingskills这个仓库名说起它到底想解决什么问题第一次看到marketingskills这个名字我的直觉是这大概率是一个把营销领域里那些高频、重复、有固定套路的活儿封装成 AI Agent 可以直接调用的技能包。事实也确实如此。它不是一个 SaaS 产品也不是一个营销自动化平台而是一套面向Claude Code这类 AI 编程代理的Agent Skills规范实现——用结构化的目录、说明文件和脚本把做 SEO 审计写落地页文案生成 FAQ 结构化数据分析关键词这类任务变成 AI 可以稳定复现的工作流。这件事的价值在哪我举个自己踩过的坑。早两年我用大模型做 SEO 内容每次都要在对话里重新解释一遍标题要控制在多少字符meta description 怎么写FAQ schema 的字段有哪些。模型每次给的格式都不一样有时候 JSON-LD 里少个context有时候acceptedAnswer写成了answer。你没法把它接进流水线因为输出不稳定。Agent Skills 这套东西的核心思路就是把这些隐性知识从你的脑子里、从每次的对话里搬到文件系统里变成模型每次都能读到的显式规范。所以marketingskills适合谁三类人最该关注一是做独立站、需要持续产出 SEO 内容的运营二是想把营销流程自动化的开发者三是已经在用 Claude Code 或类似 AI Agent 工具、但觉得每次都要重复交代背景很烦的从业者。它解决的不是AI 会不会写文案的问题而是AI 能不能按你的标准、稳定地、批量地写文案的问题。这两者之间差着一整个工程化的距离。下面我会从仓库结构、技能设计逻辑、和 Claude Code 的配合方式、SEO 场景的落地细节以及我自己实测中遇到的坑一层层拆开讲。你不需要是程序员但需要有一点把任务拆成步骤的思维习惯。2. Agent Skills 规范下一个技能到底长什么样2.1 为什么是文件夹而不是一段提示词很多人第一反应是不就是提示词吗我写个 system prompt 不就行了我一开始也这么想直到我把一个 3000 字的 SEO 提示词塞进对话发现模型在第 5 轮之后就开始遗忘细节。提示词是易失的它活在上下文窗口里会被后续对话稀释。而 Agent Skills 的做法是把技能落成磁盘上的文件夹模型在需要的时候主动去读。这个区别很关键前者是你喂给它后者是它自己去拿。一个符合 Agent Skills 规范的技能通常长这样marketingskills/ seo-audit/ SKILL.md scripts/ check_meta.py references/ schema-faq.md landing-page-copy/ SKILL.md templates/ hero-section.md核心是那个SKILL.md。它一般包含三部分元信息技能叫什么、什么时候该用、操作指令具体怎么做、资源引用需要哪些脚本或参考文件。模型读到这个文件就知道哦遇到 SEO 审计的活儿我该走这套流程。2.2 SKILL.md 里的元信息为什么决定成败我见过太多人把 SKILL.md 写成一篇教程结果模型根本不知道什么时候该调用它。元信息里的description字段本质上是给模型看的触发条件。写得含糊比如用于营销相关工作模型就懵了——写文案算不算发邮件算不算写得精准比如当用户需要对一个网页进行 SEO 审计检查 title、meta description、heading 结构和结构化数据时使用模型就能准确命中。这里有个我实测出来的经验description 里要包含触发词和排除词。比如 SEO 审计这个技能触发词是SEO 审计页面优化meta 检查排除词可以写不适用于关键词研究那属于另一个技能。这样能大幅降低技能之间的误触发。我在一个项目里同时放了 6 个营销技能没写排除词的时候模型经常把写 FAQ的活儿派给写落地页的技能加了排除词之后准确率肉眼可见地提升。2.3 脚本和参考文件的分工逻辑scripts/目录放的是确定性任务。什么叫确定性就是输入 A 必然得到 B的活儿。比如检查一个 HTML 文件里有没有 canonical 标签、统计 title 的字符数、验证 JSON-LD 是否合法。这些用 Python 脚本做比让模型心算靠谱一万倍。模型擅长的是判断和生成不擅长精确计算和格式校验把这两类活儿分开是整个技能设计的精髓。references/目录放的是知识性内容。比如 FAQ 结构化数据的字段规范、不同搜索引擎对 meta description 长度的偏好、Schema.org 的常用类型清单。这些内容不需要模型执行只需要它查阅。把它们单独放文件里而不是塞进 SKILL.md 正文好处是 SKILL.md 保持精简模型读起来不费劲需要细节时再去读参考文件。提示SKILL.md 正文建议控制在 500 行以内。超过这个长度模型读取时容易抓不住重点。把细节外移到 references是保持技能可维护的关键。3. 把营销任务翻译成技能拆解的颗粒度怎么定3.1 颗粒度太粗和太细都会翻车这是我在实际搭建营销技能库时纠结最久的问题。一个SEO 内容生产技能听起来很完整但它其实包含了关键词研究、大纲生成、正文撰写、meta 优化、结构化数据、内链规划至少六个子任务。如果全塞进一个技能SKILL.md 会变成一本手册模型执行时容易顾此失彼。反过来如果拆成写 title写 meta写 H1这种粒度技能数量爆炸模型在调度时会陷入选择困难。我的经验法则是一个技能对应一个可独立交付的产物。SEO 审计的产物是一份审计报告那它就是一个技能。落地页文案的产物是一整套页面文案那它是另一个技能。FAQ 结构化数据的产物是一段 JSON-LD那它单独成一个技能。判断标准很简单——如果这个任务的输出能直接交给下一个人或下一个环节用它就是一个合格的技能边界。3.2 用输入-处理-输出三段式定义技能我习惯用这个框架来设计每个技能写进 SKILL.md 的正文环节要回答的问题SEO 审计技能的例子输入我需要什么才能开始一个 URL 或一份 HTML 文件处理我按什么步骤做抓取页面、逐项检查、对照规范打分输出我交付什么格式Markdown 报告含问题清单和修复建议这个表格看起来简单但它逼你把模糊的帮我优化一下 SEO变成可执行的流程。我见过的最大的坑就是技能里只写了检查页面的 SEO 问题没写检查哪些项、按什么标准、输出什么格式。结果模型每次检查的维度都不一样有时候查了图片 alt有时候忘了查。3.3 技能之间的依赖关系要显式声明营销任务很少是孤立的。关键词研究的结果要喂给内容撰写内容撰写的结果要喂给结构化数据生成。如果技能之间没有显式的依赖声明模型就不知道先做哪个、后做哪个。我的做法是在 SKILL.md 里加一段前置条件和后续技能的说明。比如 FAQ 结构化数据技能的前置条件是已有 FAQ 问答内容后续技能是页面部署检查。这样模型在调度时就有了拓扑顺序不会出现还没写内容就先生成 schema的荒唐情况。4. 和 Claude Code 配合技能是怎么被调用起来的4.1 Claude Code 读取技能的机制Claude Code 这类工具的工作方式是它在项目目录里扫描发现符合规范的技能文件夹读取 SKILL.md 的元信息建立一个技能索引。当你提出一个需求它先匹配索引找到最合适的技能然后读取该技能的完整指令和资源再执行。这个过程是按需加载的——不是一上来把所有技能都读进上下文而是用到哪个读哪个。这也是为什么技能可以有很多个但不会撑爆上下文窗口。理解这一点很重要因为它决定了你的技能库该怎么组织。如果你把所有技能都堆在一个大文件里就失去了按需加载的优势。正确的做法是每个技能独立成目录元信息写清楚让索引能准确匹配。4.2 本地模型接入时的注意事项热词里提到用 LM Studio 跑本地模型、通过第三方 API 接入其他模型这块我实测过。核心结论是技能规范是通用的但模型能力决定了技能能跑多复杂。Agent Skills 这套东西本质上是给模型看的说明书说明书本身不挑模型但一个需要多步推理、调用脚本、读取多个参考文件的复杂技能小参数量的本地模型可能执行到一半就跑偏了。我的建议是分档简单的格式校验、模板填充类技能本地小模型完全够用涉及多步判断、需要综合多个参考文件的技能还是用能力更强的模型。另外本地模型对 SKILL.md 里指令的遵循度往往不如大模型稳定所以给本地模型用的技能指令要写得更死——少用酌情视情况而定这种模糊表述多用必须如果 X 则 Y这种确定性语言。4.3 在 VS Code 里调试技能的实用姿势我大部分时间是在 VS Code 里调试这些技能的。几个实测好用的习惯第一把技能目录放在工作区根目录下这样 Claude Code 扫描时不会漏掉第二改完 SKILL.md 后新开一个对话测试因为旧对话里模型可能还记着旧版本的指令第三用简单的测试用例先跑通流程比如给一个只有 title 和 meta 的极简 HTML看技能能不能正确识别问题再上真实页面。注意技能文件改动后如果发现模型行为没变化八成是缓存或旧上下文的问题。新开对话是最省事的排查手段别在旧对话里反复追问你为什么没按新规则来。5. SEO 场景深挖FAQ 结构化数据这个技能该怎么写5.1 为什么 FAQ schema 值得单独做成一个技能热词里谷歌 SEO 的 FAQPage 结构化数据出现频率很高说明这是很多人的痛点。FAQPage 结构化数据的坑在于它有一套严格的字段规范type必须是FAQPagemainEntity是个数组每个元素是Question里面又有acceptedAnsweracceptedAnswer里还有type: Answer和text。少一层、错一个字段名搜索引擎就不认。这种格式严格、内容灵活的任务正是技能化的最佳场景——格式部分用脚本校验内容部分让模型生成。5.2 技能里的校验脚本怎么写我在技能里放了一个 Python 脚本专门做 JSON-LD 的合法性校验。核心逻辑是解析 JSON、检查必需的context和type、递归验证mainEntity数组里每个 Question 的结构、检查acceptedAnswer.text是否为空。这个脚本不负责内容好不好只负责格式对不对。模型生成完 JSON-LD 后调用脚本跑一遍不通过就让它改。这个生成-校验-修正的闭环是保证输出质量的关键。import json def validate_faq_schema(data): errors [] if data.get(context) ! https://schema.org: errors.append(context 必须是 https://schema.org) if data.get(type) ! FAQPage: errors.append(type 必须是 FAQPage) entities data.get(mainEntity, []) if not isinstance(entities, list) or not entities: errors.append(mainEntity 必须是非空数组) for i, q in enumerate(entities): if q.get(type) ! Question: errors.append(f第{i}项 type 必须是 Question) if not q.get(name): errors.append(f第{i}项缺少 name 字段) ans q.get(acceptedAnswer, {}) if ans.get(type) ! Answer: errors.append(f第{i}项 acceptedAnswer 的 type 必须是 Answer) if not ans.get(text): errors.append(f第{i}项 acceptedAnswer 缺少 text) return errors这段代码不长但它把最容易出错的几个点全兜住了。我实测下来加了校验脚本之后FAQ schema 的一次通过率从大概六成提到了九成以上。5.3 内容生成部分的分寸把握格式交给脚本内容交给模型但内容也不是随便生成。我在 SKILL.md 里明确写了几条约束FAQ 的问题必须是用户真实会搜的问句答案控制在 40 到 60 字答案里要自然包含目标关键词但不要堆砌每个答案要能独立成立不依赖上下文。这几条约束来自我对搜索引擎偏好的观察——太长的答案在富媒体展示时会被截断太短的又显得信息量不足。还有一个容易被忽略的点FAQ 内容要和页面正文一致。我见过有人为了做 schema 单独编了一套问答和页面正文对不上这种结构化数据和可见内容不一致是明确违反规范的轻则不展示重则被判定为作弊。所以技能里要加一条指令生成 FAQ 前先读取页面正文确保问答内容源于正文。6. 实测中踩过的坑和排查链路6.1 技能不触发从索引到描述的逐层排查最让人抓狂的问题是我明明写了技能模型就是不用。我的排查链路是这样的第一步确认技能目录结构对不对SKILL.md 是不是在正确的位置文件名大小写有没有问题有些系统大小写敏感第二步看元信息里的 description 是不是太模糊模型匹配不上第三步看是不是有另一个技能的 description 更抢眼导致误匹配第四步新开对话排除上下文干扰。这四步走下来九成的不触发问题都能定位。我印象最深的一次是技能死活不触发查了半天发现是 SKILL.md 的元信息用了 YAML 格式但我缩进用了 Tab 而不是空格解析直接失败了。这种低级错误在排查时最容易被忽略因为文件看起来是对的。6.2 技能触发了但执行跑偏指令歧义的识别另一个高频问题是技能被调用了但执行结果不对。这通常是 SKILL.md 里的指令有歧义。比如我写过一句检查页面的标题模型理解成检查 H1而我本意是检查title标签。后来我改成检查 HTMLhead中的title标签内容歧义就消失了。指令里凡是可能有两种理解的词都要用具体的技术名词替换。这个教训我吃了不止一次。6.3 脚本调用失败路径和环境问题技能里的脚本调用失败八成是路径问题。模型执行脚本时工作目录可能和你预期的不一样。我的做法是在 SKILL.md 里明确写脚本的相对路径并且在脚本开头用os.path.dirname(__file__)来定位资源文件而不是依赖当前工作目录。另外脚本依赖的第三方库要在技能文档里写清楚别让模型去猜。我有个技能用了beautifulsoup4解析 HTML没在文档里写换台机器跑就报ModuleNotFoundError排查了半天。问题现象最可能的原因快速验证方法技能完全不触发元信息格式错误或描述模糊检查 YAML 缩进新开对话测试触发了但用错技能技能间 description 重叠给每个技能加排除词执行结果不符合预期指令存在歧义把模糊词换成具体技术名词脚本报错路径或依赖问题用绝对路径定位文档写明依赖7. 把技能库当成产品来维护的几个习惯7.1 版本管理和变更记录技能库一旦超过五个技能就需要版本管理了。我用 Git 管理整个marketingskills目录每次改 SKILL.md 都写清楚改了什么、为什么改。这不是形式主义——当你发现某个技能突然不好用了能快速定位是哪次改动引入的问题。我还会在技能目录里放一个CHANGELOG.md记录这个技能的演进尤其是那些踩坑后修正的条目下次遇到类似问题能直接翻记录。7.2 用真实任务做回归测试技能改完之后别只看它能不能跑要拿真实任务测。我维护了一组测试用例一个结构完整的页面、一个缺 meta 的页面、一个 schema 写错的页面。每次改动技能都拿这组用例跑一遍看输出有没有退化。这个习惯帮我避免了好几次修了一个 bug 引入两个新 bug的情况。回归测试不需要多复杂几个代表性的输入加预期输出就够了。7.3 技能文档要写给未来的自己看最后说个心态问题。写 SKILL.md 的时候别想着模型能看懂就行要想着三个月后的我还能不能看懂。模型是执行者但维护者是你。指令写得清楚不仅模型执行得准你回头改的时候也省事。我现在的习惯是每个技能开头写一段这个技能解决什么问题、不解决什么问题中间写清楚步骤和判断标准结尾写已知限制。这三段下来技能的可维护性会好很多。营销这件事本质上是一堆有套路但需要判断的任务的集合。Agent Skills 的价值就是把这堆任务里套路的部分固化下来让 AI 稳定执行把人的精力留给真正需要判断的部分。marketingskills这个方向我觉得才刚刚开始后面值得深挖的东西还有很多比如技能之间的编排、多技能协作完成一个完整营销活动、技能效果的量化评估。这些我还在摸索有新的心得再聊。 Agent Skills 实战：用 marketingskills 构建稳定的 SEO 营销技能库
1. 从marketingskills这个仓库名说起它到底想解决什么问题第一次看到marketingskills这个名字我的直觉是这大概率是一个把营销领域里那些高频、重复、有固定套路的活儿封装成 AI Agent 可以直接调用的技能包。事实也确实如此。它不是一个 SaaS 产品也不是一个营销自动化平台而是一套面向Claude Code这类 AI 编程代理的Agent Skills规范实现——用结构化的目录、说明文件和脚本把做 SEO 审计写落地页文案生成 FAQ 结构化数据分析关键词这类任务变成 AI 可以稳定复现的工作流。这件事的价值在哪我举个自己踩过的坑。早两年我用大模型做 SEO 内容每次都要在对话里重新解释一遍标题要控制在多少字符meta description 怎么写FAQ schema 的字段有哪些。模型每次给的格式都不一样有时候 JSON-LD 里少个context有时候acceptedAnswer写成了answer。你没法把它接进流水线因为输出不稳定。Agent Skills 这套东西的核心思路就是把这些隐性知识从你的脑子里、从每次的对话里搬到文件系统里变成模型每次都能读到的显式规范。所以marketingskills适合谁三类人最该关注一是做独立站、需要持续产出 SEO 内容的运营二是想把营销流程自动化的开发者三是已经在用 Claude Code 或类似 AI Agent 工具、但觉得每次都要重复交代背景很烦的从业者。它解决的不是AI 会不会写文案的问题而是AI 能不能按你的标准、稳定地、批量地写文案的问题。这两者之间差着一整个工程化的距离。下面我会从仓库结构、技能设计逻辑、和 Claude Code 的配合方式、SEO 场景的落地细节以及我自己实测中遇到的坑一层层拆开讲。你不需要是程序员但需要有一点把任务拆成步骤的思维习惯。2. Agent Skills 规范下一个技能到底长什么样2.1 为什么是文件夹而不是一段提示词很多人第一反应是不就是提示词吗我写个 system prompt 不就行了我一开始也这么想直到我把一个 3000 字的 SEO 提示词塞进对话发现模型在第 5 轮之后就开始遗忘细节。提示词是易失的它活在上下文窗口里会被后续对话稀释。而 Agent Skills 的做法是把技能落成磁盘上的文件夹模型在需要的时候主动去读。这个区别很关键前者是你喂给它后者是它自己去拿。一个符合 Agent Skills 规范的技能通常长这样marketingskills/ seo-audit/ SKILL.md scripts/ check_meta.py references/ schema-faq.md landing-page-copy/ SKILL.md templates/ hero-section.md核心是那个SKILL.md。它一般包含三部分元信息技能叫什么、什么时候该用、操作指令具体怎么做、资源引用需要哪些脚本或参考文件。模型读到这个文件就知道哦遇到 SEO 审计的活儿我该走这套流程。2.2 SKILL.md 里的元信息为什么决定成败我见过太多人把 SKILL.md 写成一篇教程结果模型根本不知道什么时候该调用它。元信息里的description字段本质上是给模型看的触发条件。写得含糊比如用于营销相关工作模型就懵了——写文案算不算发邮件算不算写得精准比如当用户需要对一个网页进行 SEO 审计检查 title、meta description、heading 结构和结构化数据时使用模型就能准确命中。这里有个我实测出来的经验description 里要包含触发词和排除词。比如 SEO 审计这个技能触发词是SEO 审计页面优化meta 检查排除词可以写不适用于关键词研究那属于另一个技能。这样能大幅降低技能之间的误触发。我在一个项目里同时放了 6 个营销技能没写排除词的时候模型经常把写 FAQ的活儿派给写落地页的技能加了排除词之后准确率肉眼可见地提升。2.3 脚本和参考文件的分工逻辑scripts/目录放的是确定性任务。什么叫确定性就是输入 A 必然得到 B的活儿。比如检查一个 HTML 文件里有没有 canonical 标签、统计 title 的字符数、验证 JSON-LD 是否合法。这些用 Python 脚本做比让模型心算靠谱一万倍。模型擅长的是判断和生成不擅长精确计算和格式校验把这两类活儿分开是整个技能设计的精髓。references/目录放的是知识性内容。比如 FAQ 结构化数据的字段规范、不同搜索引擎对 meta description 长度的偏好、Schema.org 的常用类型清单。这些内容不需要模型执行只需要它查阅。把它们单独放文件里而不是塞进 SKILL.md 正文好处是 SKILL.md 保持精简模型读起来不费劲需要细节时再去读参考文件。提示SKILL.md 正文建议控制在 500 行以内。超过这个长度模型读取时容易抓不住重点。把细节外移到 references是保持技能可维护的关键。3. 把营销任务翻译成技能拆解的颗粒度怎么定3.1 颗粒度太粗和太细都会翻车这是我在实际搭建营销技能库时纠结最久的问题。一个SEO 内容生产技能听起来很完整但它其实包含了关键词研究、大纲生成、正文撰写、meta 优化、结构化数据、内链规划至少六个子任务。如果全塞进一个技能SKILL.md 会变成一本手册模型执行时容易顾此失彼。反过来如果拆成写 title写 meta写 H1这种粒度技能数量爆炸模型在调度时会陷入选择困难。我的经验法则是一个技能对应一个可独立交付的产物。SEO 审计的产物是一份审计报告那它就是一个技能。落地页文案的产物是一整套页面文案那它是另一个技能。FAQ 结构化数据的产物是一段 JSON-LD那它单独成一个技能。判断标准很简单——如果这个任务的输出能直接交给下一个人或下一个环节用它就是一个合格的技能边界。3.2 用输入-处理-输出三段式定义技能我习惯用这个框架来设计每个技能写进 SKILL.md 的正文环节要回答的问题SEO 审计技能的例子输入我需要什么才能开始一个 URL 或一份 HTML 文件处理我按什么步骤做抓取页面、逐项检查、对照规范打分输出我交付什么格式Markdown 报告含问题清单和修复建议这个表格看起来简单但它逼你把模糊的帮我优化一下 SEO变成可执行的流程。我见过的最大的坑就是技能里只写了检查页面的 SEO 问题没写检查哪些项、按什么标准、输出什么格式。结果模型每次检查的维度都不一样有时候查了图片 alt有时候忘了查。3.3 技能之间的依赖关系要显式声明营销任务很少是孤立的。关键词研究的结果要喂给内容撰写内容撰写的结果要喂给结构化数据生成。如果技能之间没有显式的依赖声明模型就不知道先做哪个、后做哪个。我的做法是在 SKILL.md 里加一段前置条件和后续技能的说明。比如 FAQ 结构化数据技能的前置条件是已有 FAQ 问答内容后续技能是页面部署检查。这样模型在调度时就有了拓扑顺序不会出现还没写内容就先生成 schema的荒唐情况。4. 和 Claude Code 配合技能是怎么被调用起来的4.1 Claude Code 读取技能的机制Claude Code 这类工具的工作方式是它在项目目录里扫描发现符合规范的技能文件夹读取 SKILL.md 的元信息建立一个技能索引。当你提出一个需求它先匹配索引找到最合适的技能然后读取该技能的完整指令和资源再执行。这个过程是按需加载的——不是一上来把所有技能都读进上下文而是用到哪个读哪个。这也是为什么技能可以有很多个但不会撑爆上下文窗口。理解这一点很重要因为它决定了你的技能库该怎么组织。如果你把所有技能都堆在一个大文件里就失去了按需加载的优势。正确的做法是每个技能独立成目录元信息写清楚让索引能准确匹配。4.2 本地模型接入时的注意事项热词里提到用 LM Studio 跑本地模型、通过第三方 API 接入其他模型这块我实测过。核心结论是技能规范是通用的但模型能力决定了技能能跑多复杂。Agent Skills 这套东西本质上是给模型看的说明书说明书本身不挑模型但一个需要多步推理、调用脚本、读取多个参考文件的复杂技能小参数量的本地模型可能执行到一半就跑偏了。我的建议是分档简单的格式校验、模板填充类技能本地小模型完全够用涉及多步判断、需要综合多个参考文件的技能还是用能力更强的模型。另外本地模型对 SKILL.md 里指令的遵循度往往不如大模型稳定所以给本地模型用的技能指令要写得更死——少用酌情视情况而定这种模糊表述多用必须如果 X 则 Y这种确定性语言。4.3 在 VS Code 里调试技能的实用姿势我大部分时间是在 VS Code 里调试这些技能的。几个实测好用的习惯第一把技能目录放在工作区根目录下这样 Claude Code 扫描时不会漏掉第二改完 SKILL.md 后新开一个对话测试因为旧对话里模型可能还记着旧版本的指令第三用简单的测试用例先跑通流程比如给一个只有 title 和 meta 的极简 HTML看技能能不能正确识别问题再上真实页面。注意技能文件改动后如果发现模型行为没变化八成是缓存或旧上下文的问题。新开对话是最省事的排查手段别在旧对话里反复追问你为什么没按新规则来。5. SEO 场景深挖FAQ 结构化数据这个技能该怎么写5.1 为什么 FAQ schema 值得单独做成一个技能热词里谷歌 SEO 的 FAQPage 结构化数据出现频率很高说明这是很多人的痛点。FAQPage 结构化数据的坑在于它有一套严格的字段规范type必须是FAQPagemainEntity是个数组每个元素是Question里面又有acceptedAnsweracceptedAnswer里还有type: Answer和text。少一层、错一个字段名搜索引擎就不认。这种格式严格、内容灵活的任务正是技能化的最佳场景——格式部分用脚本校验内容部分让模型生成。5.2 技能里的校验脚本怎么写我在技能里放了一个 Python 脚本专门做 JSON-LD 的合法性校验。核心逻辑是解析 JSON、检查必需的context和type、递归验证mainEntity数组里每个 Question 的结构、检查acceptedAnswer.text是否为空。这个脚本不负责内容好不好只负责格式对不对。模型生成完 JSON-LD 后调用脚本跑一遍不通过就让它改。这个生成-校验-修正的闭环是保证输出质量的关键。import json def validate_faq_schema(data): errors [] if data.get(context) ! https://schema.org: errors.append(context 必须是 https://schema.org) if data.get(type) ! FAQPage: errors.append(type 必须是 FAQPage) entities data.get(mainEntity, []) if not isinstance(entities, list) or not entities: errors.append(mainEntity 必须是非空数组) for i, q in enumerate(entities): if q.get(type) ! Question: errors.append(f第{i}项 type 必须是 Question) if not q.get(name): errors.append(f第{i}项缺少 name 字段) ans q.get(acceptedAnswer, {}) if ans.get(type) ! Answer: errors.append(f第{i}项 acceptedAnswer 的 type 必须是 Answer) if not ans.get(text): errors.append(f第{i}项 acceptedAnswer 缺少 text) return errors这段代码不长但它把最容易出错的几个点全兜住了。我实测下来加了校验脚本之后FAQ schema 的一次通过率从大概六成提到了九成以上。5.3 内容生成部分的分寸把握格式交给脚本内容交给模型但内容也不是随便生成。我在 SKILL.md 里明确写了几条约束FAQ 的问题必须是用户真实会搜的问句答案控制在 40 到 60 字答案里要自然包含目标关键词但不要堆砌每个答案要能独立成立不依赖上下文。这几条约束来自我对搜索引擎偏好的观察——太长的答案在富媒体展示时会被截断太短的又显得信息量不足。还有一个容易被忽略的点FAQ 内容要和页面正文一致。我见过有人为了做 schema 单独编了一套问答和页面正文对不上这种结构化数据和可见内容不一致是明确违反规范的轻则不展示重则被判定为作弊。所以技能里要加一条指令生成 FAQ 前先读取页面正文确保问答内容源于正文。6. 实测中踩过的坑和排查链路6.1 技能不触发从索引到描述的逐层排查最让人抓狂的问题是我明明写了技能模型就是不用。我的排查链路是这样的第一步确认技能目录结构对不对SKILL.md 是不是在正确的位置文件名大小写有没有问题有些系统大小写敏感第二步看元信息里的 description 是不是太模糊模型匹配不上第三步看是不是有另一个技能的 description 更抢眼导致误匹配第四步新开对话排除上下文干扰。这四步走下来九成的不触发问题都能定位。我印象最深的一次是技能死活不触发查了半天发现是 SKILL.md 的元信息用了 YAML 格式但我缩进用了 Tab 而不是空格解析直接失败了。这种低级错误在排查时最容易被忽略因为文件看起来是对的。6.2 技能触发了但执行跑偏指令歧义的识别另一个高频问题是技能被调用了但执行结果不对。这通常是 SKILL.md 里的指令有歧义。比如我写过一句检查页面的标题模型理解成检查 H1而我本意是检查title标签。后来我改成检查 HTMLhead中的title标签内容歧义就消失了。指令里凡是可能有两种理解的词都要用具体的技术名词替换。这个教训我吃了不止一次。6.3 脚本调用失败路径和环境问题技能里的脚本调用失败八成是路径问题。模型执行脚本时工作目录可能和你预期的不一样。我的做法是在 SKILL.md 里明确写脚本的相对路径并且在脚本开头用os.path.dirname(__file__)来定位资源文件而不是依赖当前工作目录。另外脚本依赖的第三方库要在技能文档里写清楚别让模型去猜。我有个技能用了beautifulsoup4解析 HTML没在文档里写换台机器跑就报ModuleNotFoundError排查了半天。问题现象最可能的原因快速验证方法技能完全不触发元信息格式错误或描述模糊检查 YAML 缩进新开对话测试触发了但用错技能技能间 description 重叠给每个技能加排除词执行结果不符合预期指令存在歧义把模糊词换成具体技术名词脚本报错路径或依赖问题用绝对路径定位文档写明依赖7. 把技能库当成产品来维护的几个习惯7.1 版本管理和变更记录技能库一旦超过五个技能就需要版本管理了。我用 Git 管理整个marketingskills目录每次改 SKILL.md 都写清楚改了什么、为什么改。这不是形式主义——当你发现某个技能突然不好用了能快速定位是哪次改动引入的问题。我还会在技能目录里放一个CHANGELOG.md记录这个技能的演进尤其是那些踩坑后修正的条目下次遇到类似问题能直接翻记录。7.2 用真实任务做回归测试技能改完之后别只看它能不能跑要拿真实任务测。我维护了一组测试用例一个结构完整的页面、一个缺 meta 的页面、一个 schema 写错的页面。每次改动技能都拿这组用例跑一遍看输出有没有退化。这个习惯帮我避免了好几次修了一个 bug 引入两个新 bug的情况。回归测试不需要多复杂几个代表性的输入加预期输出就够了。7.3 技能文档要写给未来的自己看最后说个心态问题。写 SKILL.md 的时候别想着模型能看懂就行要想着三个月后的我还能不能看懂。模型是执行者但维护者是你。指令写得清楚不仅模型执行得准你回头改的时候也省事。我现在的习惯是每个技能开头写一段这个技能解决什么问题、不解决什么问题中间写清楚步骤和判断标准结尾写已知限制。这三段下来技能的可维护性会好很多。营销这件事本质上是一堆有套路但需要判断的任务的集合。Agent Skills 的价值就是把这堆任务里套路的部分固化下来让 AI 稳定执行把人的精力留给真正需要判断的部分。marketingskills这个方向我觉得才刚刚开始后面值得深挖的东西还有很多比如技能之间的编排、多技能协作完成一个完整营销活动、技能效果的量化评估。这些我还在摸索有新的心得再聊。