如何写好一个 AI Skill —— 从设计到发布的完整指南

如何写好一个 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 确定 type（feat/fix/chore/docs/refactor/test） 3. 用一句话概括变更（不超过 72 字符） 4. 如有必要，在 body 中补充细节 ## Output 按以下格式输出：

  <type>(<scope>): <description>

  <body（可选）>

  <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 只做一件事
• [ ] 接口清晰：输入、输出、行为边界明确定义
• [ ] 用户视角：针对目标用户调整深度和语气

• 编写阶段

• [ ] 结构化 Prompt：Role → Context → Process → Output → Constraints
• [ ] 精简上下文：只包含当前任务必需的信息
• [ ] 完整错误处理：校验输入、优雅降级、友好提示
• [ ] 示例引导：至少一组 good/bad 示例

• 测试阶段

• [ ] Happy Path 测试
• [ ] Edge Case 测试
• [ ] Error Case 测试
• [ ] 真实场景验证

• 发布阶段

• [ ] 语义化版本号
• [ ] 完善的文档（快速开始 + 参数 + 示例 + FAQ）
• [ ] 建立反馈渠道
• [ ] 持续迭代

• 附：常用 Skill 设计模式

  | 模式 | 适用场景 | 核心思路 |

  |------|---------|---------|

  | Pipeline | 多步骤处理任务 | 分解为有序步骤，每步输出是下一步的输入 |

  | Review | 审查/评估类任务 | 关注点逐一检查，输出结构化报告 |

  | Generator | 内容生成任务 | 模板 + 参数 + 约束，产出标准格式 |

  | Assistant | 交互式辅助任务 | 多轮对话，保持状态，渐进式引导 |

  ---

  写好一个 Skill 是一项需要不断打磨的技能。**好的设计 + 严格的测试 + 持续的迭代**，是创建高质量 AI Skill 的不二法门。希望本文能帮助你在 AI Agent 的开发道路上走得更远。

  *（完）*