很多人第一次编写 Skill 时往往只关注一件事把一段操作说明写进SKILL.md。但一个真正好用的 Skill并不是简单的提示词集合而是一套可以被重复调用、稳定执行、持续维护的工作流程。它既要让 AI 理解“什么时候使用”也要明确“应该怎么做”还要考虑脚本、文件、权限、安全和异常情况。本文将从实际编写角度介绍 Skill 设计中容易被忽略的细节点。一、先理解 Skill 到底解决什么问题Skill 的本质是为 AI 增加某一类任务的专业操作能力。例如编写并发布 CSDN 学习文章创建和修改 Word 文档处理 Excel 表格生成演示文稿按企业内部规范撰写报告使用固定脚本完成重复性操作。普通提示词通常只对当前一次对话有效而 Skill 更像一份长期可复用的“操作手册”。一个好的 Skill 至少应该回答以下几个问题什么情况下应该使用这个 Skill使用 Skill 后要完成哪些步骤哪些事情必须由用户确认出现异常时应该如何处理是否需要调用脚本、模板或参考资料如何避免误操作和不可逆操作如果这些问题没有写清楚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_dirrC:\Users\张三\Desktop\csdn更推荐使用参数和环境变量parser.add_argument(--profile-dir)parser.add_argument(--profile-name,defaultdefault)然后根据参数计算目录rootPath(os.environ.get(CSDN_PROFILE_ROOT,Path.home()/.profiles))profile_dirroot/profile_name这样可以实现跨电脑使用、不同账号隔离、登录状态复用以及将数据放到其他磁盘。八、登录状态和账号切换要分开设计涉及账号的 Skill不能只考虑“自动登录”还要考虑“切换账号”。一个合理的设计是default - 账号 A account-b - 账号 B account-c - 账号 C同一个 profile 再次使用时复用已有登录状态切换到新的 profile 时首次登录一次即可。不建议直接复制普通 Chrome 正在使用的 Cookie因为可能造成配置文件占用、登录失效和账号数据泄露。更稳妥的方式是为每个账号创建独立的持久化浏览器 profile。九、所有不可逆操作都应该增加确认发布文章、发送邮件、删除文件、提交代码等操作都属于不可逆或高风险操作。Skill 不应该因为用户之前说过一次就永久默认执行。例如发布文章时可以设置双重条件--publish --confirm-publish还可以增加人工确认answerinput(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 精益数字员工也能实现类似的能力帮助团队将重复性工作标准化、流程化。