如何写好一个 AI Skill —— 从设计到发布的完整指南一、引言随着 Claude Code Skills、GPT Actions、Cursor Rules 等 AI Agent 工具的普及**Skill技能** 正在成为 AI 时代最核心的「可复用能力单元」。一个 Skill 本质上是一组精心设计的指令和配置让 AI 能够以可预测、高质量的方式完成特定任务。然而写好一个 Skill 并非简单地把需求写进 Prompt。差的 Skill 会出现指令冲突、边界模糊、输出不稳定等问题好的 Skill 则像精密的 API —— 输入明确、行为可预测、错误处理优雅。本文将从设计原则、编写规范、测试验证、发布维护四个维度系统性地讲解如何打造高质量的 AI Skill。二、设计原则2.1 单一职责原则**一个 Skill 只做一件事且做好。**这是最重要的一条原则。如果你的 Skill 既要做代码审查又要生成文档那它很可能两样都做不好。当任务变复杂时拆分为多个 Skill通过组合来解决问题。**反例**你是一个全能助手可以帮助用户写代码、审查代码、写文档、部署……**正例**# Code Review Skill 仅审查 Pull Request 中的代码变更关注安全性、性能、可维护性。 不负责生成新代码、不负责写文档。2.2 输入明确输出可预测Skill 的「接口」应该像函数签名一样清晰。用户或调用方不需要猜测应该提供什么信息。**输入声明**明确列出需要用户提供的参数或上下文**输出格式**指定输出结构Markdown、JSON、代码块等**行为边界**什么情况做什么什么情况拒绝## 输入 - 代码文件路径必填 - 审查重点可选默认全部 - 可选值security / performance / style ## 输出 返回 Markdown 格式的审查报告包含 1. 问题摘要 2. 严重等级CRITICAL / WARNING / INFO 3. 修复建议含代码示例2.3 用户优先Skill 是为人服务的不是为技术服务的。设计时始终站在最终用户的角度思考**新手也能用**提供默认值降低使用门槛**专家也有用**提供高级参数允许精细控制**失败时友好**错误信息告诉用户「怎么修」而不是「哪里炸了」2.4 显式优于隐式不要依赖 AI 的「常识」去猜测意图。显式说明规则、边界和约束避免歧义。## 重要规则 - 不要在代码审查中提出风格偏好如缩进、命名除非项目有明确规范 - 如果发现安全问题必须标记为 CRITICAL 并附上 CVE 编号如有 - 如果无法理解代码意图标记为 INFO 并说明原因而不是跳过三、编写规范3.1 Prompt 工程Skill 的核心是 Prompt而高质量的 Prompt 需要结构化设计**结构模板**# Role明确角色 你是一个 [具体角色]擅长 [具体领域]。 # Context背景说明 你正在处理 [具体场景]。项目背景[描述]。 # Input输入说明 用户将提供[输入格式和内容] # Process处理流程 1. 首先理解 [步骤一] 2. 然后分析 [步骤二] 3. 最后输出 [步骤三] # Output输出格式 按以下格式输出[模板] # Constraints约束 - 不要 [禁止行为] - 必须 [强制要求] - 如果 [边界条件]则 [处理方式] # Examples示例可选 ## 好的示例 [示例] ## 不好的示例 [反例]3.2 上下文管理AI 的上下文窗口是有限的合理的上下文管理直接影响 Skill 的可靠性**精简上下文**只加载当前任务必需的信息不把整个代码库塞进去**分层引用**用 file:path 或 read: 指令引用外部资源而不是内联**状态提示**在多轮交互中每轮开头用一句话总结当前状态帮助 AI 保持方向# 当前状态 已完成代码差异分析 进行中生成审查报告 下一步等待用户确认是否提交评论3.3 错误处理好的 Skill 不仅要处理「正常路径」还要优雅地处理异常**输入校验**检查必要参数是否提供格式是否正确**不可能任务**当用户请求超出 Skill 能力范围时明确拒绝并建议替代方案**降级策略**当依赖的服务不可用时提供降级输出而非完全失败## 错误处理 - 如果未提供代码路径返回错误「请提供待审查的代码路径」 - 如果文件不存在返回错误「文件 [path] 不存在请检查路径」 - 如果文件超过 1000 行输出「文件过长建议拆分后逐一审查」 - 如果审查过程中遇到无法解析的语法跳过该文件在报告中标记为「解析失败」3.4 参数设计如果需要参数化 Skill遵循以下原则**参数命名**简短、自文档化如 --lang 而非 --target-language-code**默认值**始终提供合理的默认值让用户不加参数也能用**参数校验**在 Prompt 层面就声明合法值范围可选参数: --depth basic|detailed 审查深度默认: detailed --format markdown|json 输出格式默认: markdown --focus security|performance|style 审查重点默认: 全部四、测试与验证4.1 单元测试思维每个 Skill 都是一个函数应该有对应的测试用例| 测试类型 | 说明 | 示例 ||---------|------|------|| Happy Path | 正常输入期望正常输出 | 提交合法代码 → 收到审查报告 || Edge Case | 边界条件 | 空文件 → 返回「无变更」 || Error Case | 非法输入 | 不提供必要参数 → 返回错误提示 || 拒绝测试 | 超出范围的任务 | 让代码审查 Skill 写测试 → 拒绝 |4.2 回归测试Skill 修改后之前能通过的测试应该仍然通过。建立测试集test/ happy-path.input.md happy-path.expected.md edge-case-empty.input.md edge-case-empty.expected.md error-no-input.input.md error-no-input.expected.md用自动化脚本批量运行测试比较实际输出和期望输出。4.3 真实场景验证模拟测试覆盖不到的地方真实场景验证至关重要**多轮对话**测试 Skill 在多轮交互中的状态保持**干扰输入**故意提供不完整或有歧义的输入观察 Skill 是否引导用户补充**性能测试**大文件、长上下文下 Skill 是否仍然稳定五、发布与维护5.1 版本管理给 Skill 一个版本号遵循语义化版本**主版本**不兼容的 Prompt 重写**次版本**新增功能或参数**补丁版本**修复错误或改进稳定性在 Skill 文件中声明版本--- name: code-reviewer version: 2.1.0 description: 自动审查 Pull Request 代码变更 ---5.2 文档编写好的文档让用户「拿来就能用」**快速开始**三步骤让用户跑起来**参数参考**完整参数列表和说明**示例**不少于 3 个常见使用场景**常见问题**预计用户可能遇到的坑5.3 用户反馈迭代通过以下渠道收集反馈并持续改进**错误报告**记录无法处理的输入案例补充到测试集**误判分析**当 Skill 输出不符合预期时分析是 Prompt 问题还是边界情况**使用数据**哪些参数最常用哪些场景使用最多据此优化默认行为六、实战案例编写一个「Commit Message 生成器」Skill下面通过一个完整案例串联上述所有原则。6.1 需求定义功能根据 git diff 生成符合 Conventional Commits 规范的提交信息 输入git diff 输出 输出符合规范的 commit message 约束只生成 message不提交代码不侵入业务逻辑6.2 完整实现--- name: commit-message-generator version: 1.0.0 description: 根据 git diff 生成 Conventional Commits 提交信息 --- ## Role 你是一个专业的 Git Commit 信息生成器精通 Conventional Commits 规范。 ## Input 用户会提供 git diff 的输出或者粘贴代码变更内容。 ## Process 1. 分析变更内容理解修改的实质 2. 根据 Conventional Commits 确定 typefeat/fix/chore/docs/refactor/test 3. 用一句话概括变更不超过 72 字符 4. 如有必要在 body 中补充细节 ## Output 按以下格式输出type(scope): descriptionbody可选footer可选## Constraints - 不得在 commit message 中包含 issue 编号除非用户提供了 - 如果变更涉及多个 type只选最主要的一个 - 如果无法判断 type使用 chore - 描述使用英文body 可使用中文 ## Examples ### 输入diff --git a/src/auth/login.ts b/src/auth/login.ts const token await authenticate(email, password);### 输出feat(auth): add email/password authentication新增基于邮箱密码的身份认证方式作为现有 OAuth 登录的补充。## 错误处理 - 如果未提供 diff提示用户运行 git diff 并粘贴结果 - 如果 diff 为空提示没有未提交的变更 - 如果变更超过 500 行建议用户分多次提交6.3 测试验证# 测试 1正常场景 输入新增一个 API 端点 期望输出feat(api): add xxx endpoint # 测试 2边界场景 输入仅修改 README 期望输出docs: update README # 测试 3拒绝测试 输入「帮我提交代码」 期望输出拒绝执行「此 Skill 仅生成 commit message不执行提交操作」七、总结最佳实践清单设计阶段[ ] 单一职责一个 Skill 只做一件事[ ] 接口清晰输入、输出、行为边界明确定义[ ] 用户视角针对目标用户调整深度和语气编写阶段[ ] 结构化 PromptRole → Context → Process → Output → Constraints[ ] 精简上下文只包含当前任务必需的信息[ ] 完整错误处理校验输入、优雅降级、友好提示[ ] 示例引导至少一组 good/bad 示例测试阶段[ ] Happy Path 测试[ ] Edge Case 测试[ ] Error Case 测试[ ] 真实场景验证发布阶段[ ] 语义化版本号[ ] 完善的文档快速开始 参数 示例 FAQ[ ] 建立反馈渠道[ ] 持续迭代附常用 Skill 设计模式| 模式 | 适用场景 | 核心思路 ||------|---------|---------|| Pipeline | 多步骤处理任务 | 分解为有序步骤每步输出是下一步的输入 || Review | 审查/评估类任务 | 关注点逐一检查输出结构化报告 || Generator | 内容生成任务 | 模板 参数 约束产出标准格式 || Assistant | 交互式辅助任务 | 多轮对话保持状态渐进式引导 |---写好一个 Skill 是一项需要不断打磨的技能。**好的设计 严格的测试 持续的迭代**是创建高质量 AI Skill 的不二法门。希望本文能帮助你在 AI Agent 的开发道路上走得更远。*完*