很多人第一次编写 Skill 时，往往只关注一件事：把一段操作说明写进SKILL.md。

但一个真正好用的 Skill，并不是简单的提示词集合，而是一套可以被重复调用、稳定执行、持续维护的工作流程。它既要让 AI 理解“什么时候使用”，也要明确“应该怎么做”，还要考虑脚本、文件、权限、安全和异常情况。

本文将从实际编写角度，介绍 Skill 设计中容易被忽略的细节点。

一、先理解 Skill 到底解决什么问题

Skill 的本质，是为 AI 增加某一类任务的专业操作能力。

例如：

• 编写并发布 CSDN 学习文章；
• 创建和修改 Word 文档；
• 处理 Excel 表格；
• 生成演示文稿；
• 按企业内部规范撰写报告；
• 使用固定脚本完成重复性操作。

普通提示词通常只对当前一次对话有效，而 Skill 更像一份长期可复用的“操作手册”。

一个好的 Skill 至少应该回答以下几个问题：

1. 什么情况下应该使用这个 Skill？
2. 使用 Skill 后要完成哪些步骤？
3. 哪些事情必须由用户确认？
4. 出现异常时应该如何处理？
5. 是否需要调用脚本、模板或参考资料？
6. 如何避免误操作和不可逆操作？

如果这些问题没有写清楚，Skill 就可能出现“有时触发、有时不触发”“步骤执行不一致”“擅自发布或修改文件”等问题。

二、description决定 Skill 能不能被正确触发

Skill 的前置元数据通常类似下面这样：

---name:learning-article-csdn-publisherdescription:生成中文学习文章并将 Markdown 预览或发布到 CSDN。---

其中，name是 Skill 的名称，而description是非常重要的触发描述。

1. description 不要只写功能名称

不推荐这样写：

description:CSDN 文章工具

这个描述过于模糊，AI 很难判断什么时候应该使用它。

更好的写法应该包含：

• Skill 能做什么；
• 面向什么任务；
• 什么时候应该调用；
• 是否包含预览、发布或文件处理能力。

例如：

description:生成适合 CSDN 阅读的中文学习文章，并支持 Markdown 预览和人工确认后的发布。

2. description 要简洁明确

description不是完整使用说明，而是 Skill 的“简介和触发条件”。具体步骤应该写在SKILL.md的正文中。

3. description 要覆盖真实使用场景

如果 Skill 既支持“生成文章”，又支持“预览和发布”，那么 description 最好同时体现出来。否则用户说“帮我把这篇文章填入 CSDN”时，AI 可能无法判断是否应该使用这个 Skill。

三、SKILL.md 不要写成流水账，要写成决策流程

很多 Skill 的问题不是内容少，而是内容太杂。整篇文档如果从头到尾都是点击步骤，一旦遇到不同输入、页面变化或异常情况，AI 就不知道该如何处理。

更好的写法是把流程分成几个阶段：

# Skill 名称 Skill 的总体目标和使用边界。 ## 适用场景 说明什么时候使用。 ## 工作流程 ### 1. 判断素材来源 说明有资料和无资料时分别怎么处理。 ### 2. 生成内容 说明内容结构、质量要求和格式要求。 ### 3. 执行操作 说明何时调用脚本，哪些步骤需要用户确认。 ### 4. 异常处理 说明登录、验证码、文件冲突等问题如何处理。 ## 输出要求 说明最终输出什么内容。

这种结构包含了“判断条件”和“处理原则”，比单纯罗列操作步骤更稳定。

四、把“必须做”和“可以做”区分开

Skill 中最容易产生歧义的地方，是没有区分强制要求和建议要求。

例如：

• 必须先预览，不能直接发布；
• 建议生成 3 个标题；
• 可以添加对比部分；
• 需要保留推广内容；
• 遇到验证码时必须交给用户处理。

可以使用下面几种表达方式：

必须先完成预览，只有用户明确确认后才能执行发布。 默认面向初学者撰写文章。 可以根据主题增加案例分析或常见误区。 不要绕过验证码，也不要擅自使用用户账号发布内容。

如果不做区分，AI 可能把建议误当成硬性规则，也可能忽略真正重要的安全限制。

五、渐进式披露：不要把所有内容塞进一个文件

Skill 的内容通常可以分成三层：

第一层：SKILL.md

放最核心的内容：用途、总体工作流程、关键约束、脚本调用时机和安全规则。

第二层：references 参考资料

放不需要每次都读取的详细内容，例如平台发布说明、页面操作规则、数据格式说明、行业规范和故障处理手册。

第三层：scripts 脚本

放适合交给程序执行的重复工作，例如解析 Markdown、提取标题、处理标签、打开浏览器、填充网页表单和保存诊断截图。

这样做可以避免主 Skill 文件过于臃肿，让 AI 根据任务需要读取相关参考资料。

六、什么时候应该使用脚本

适合使用脚本的场景包括：操作步骤固定、需要重复执行、容易出现格式错误、需要批量处理文件，或需要与浏览器和外部工具交互。

不适合强行使用脚本的场景包括：页面变化频繁、操作需要大量人工判断、任务只有一两步，或者脚本比人工操作更复杂。

脚本的作用应该是减少重复劳动，而不是把所有事情都自动化。

七、脚本参数设计要考虑可复用性

不要把账号、路径和环境写死在代码里：

profile_dir=r"C:\Users\张三\Desktop\csdn"

更推荐使用参数和环境变量：

parser.add_argument("--profile-dir")parser.add_argument("--profile-name",default="default")

然后根据参数计算目录：

root=Path(os.environ.get("CSDN_PROFILE_ROOT",Path.home()/".profiles"))profile_dir=root/profile_name

这样可以实现跨电脑使用、不同账号隔离、登录状态复用，以及将数据放到其他磁盘。

八、登录状态和账号切换要分开设计

涉及账号的 Skill，不能只考虑“自动登录”，还要考虑“切换账号”。一个合理的设计是：

default -> 账号 A account-b -> 账号 B account-c -> 账号 C

同一个 profile 再次使用时，复用已有登录状态；切换到新的 profile 时，首次登录一次即可。

不建议直接复制普通 Chrome 正在使用的 Cookie，因为可能造成配置文件占用、登录失效和账号数据泄露。更稳妥的方式是为每个账号创建独立的持久化浏览器 profile。

九、所有不可逆操作都应该增加确认

发布文章、发送邮件、删除文件、提交代码等操作，都属于不可逆或高风险操作。Skill 不应该因为用户之前说过一次，就永久默认执行。

例如发布文章时，可以设置双重条件：

--publish --confirm-publish

还可以增加人工确认：

answer=input('Type "PUBLISH" only after confirming this exact article may be published: ')ifanswer.strip()!="PUBLISH":print("Publish action cancelled.")

自动化的重点不是完全不让人参与，而是把机器适合做的事情交给机器，把关键决策保留给人。

十、输出内容和发布信息要分离

文章正文和平台发布信息不应该混在一起。

文章正文应该包含标题、正文、代码、图片说明和参考资料；CSDN 分类、标签、发布账号等内容则作为独立发布信息输出。

这样可以避免把标签建议误填进正文，也方便后续切换平台发布。

十一、为异常情况提前设计处理方式

常见异常包括依赖未安装、页面结构发生变化、需要验证码或人工审核，以及浏览器配置目录被占用。

合理的处理方式是：提示安装依赖；页面变化时保留窗口并保存诊断信息；验证码交给账号持有人完成；配置目录被占用时关闭对应浏览器或改用新的 profile 目录。

不要无限重试，也不要误点其他按钮。

十二、写完 Skill 后一定要测试

至少应检查目录结构、frontmatter、脚本语法、帮助信息和典型使用场景。

例如：

python-m py_compile scripts/example.py python scripts/example.py--help

还要测试正常输入、缺少文件、参数为空、同一 profile 重复使用、切换 profile、预览模式和取消发布等情况。

十三、常见的 Skill 编写误区

误区一：内容写得越长越好

过长的 Skill 会增加上下文负担。应该把详细说明拆到references中，把核心决策留在SKILL.md。

误区二：把所有内容写成固定模板

固定模板适合格式要求严格的任务，但不适合文章和报告等需要灵活表达的内容。应该规定目标和质量标准，而不是限制每一段必须使用相同句式。

误区三：只写理想流程，不写异常流程

实际使用中，页面打不开、登录过期、文件不存在和权限不足都很常见。没有异常处理的 Skill，只能在演示环境中工作。

误区四：把本机路径写死

应该优先使用相对路径、Path.home()、环境变量、命令行参数和当前 Python 解释器。

误区五：把发布动作默认打开

涉及发布、删除、发送和提交的操作，都应该采用“预览优先、明确确认后执行”的模式。

十四、总结：一个好 Skill 的判断标准

可以用下面这份清单检查自己的 Skill：

• 是否明确说明了适用场景？
• description 是否足够清晰？
• SKILL.md 是否只保留核心流程？
• 详细资料是否拆到了 references？
• 重复操作是否适合使用脚本？
• 是否支持参数化和跨电脑使用？
• 是否避免写死账号、路径和 Cookie？
• 是否区分默认行为、建议行为和强制行为？
• 是否为高风险操作设置了确认机制？
• 是否写明了异常处理方式？
• 是否通过了语法和实际场景测试？
• 是否考虑了后续维护和页面变化？

编写 Skill 的关键，不是把指令写得越来越多，而是把任务中的判断、边界、步骤和异常情况组织得足够清楚。只有这样，Skill 才能从一次性的提示词，真正变成稳定、可复用的工作能力。

如果你希望把这些编写 Skill 的规范进一步沉淀为团队可复用的流程，我们自主研发的 AI 精益数字员工也能实现类似的能力，帮助团队将重复性工作标准化、流程化。