AI Coding 中的 Skill 最佳实践：如何做出团队真正能用的 Skill

面向开发人员的实战报告｜资料检索截至 2026 年 10 月 28 日

很多团队开始为 AI Coding 创建 Skill：代码审查、数据库迁移、排查 CI、编写测试……但建好一个 SKILL.md，并不意味着团队获得了一项可靠的能力。

一个 Skill 是否好用，真正要看的是：

• 遇到合适的任务时，Agent 能否找到并使用它？
• 换一个项目、换一个开发者，它是否仍然有效？
• 它能否改善任务结果，而不是增加步骤和成本？
• 任务超出适用范围时，它是否会乱触发？
• 团队能否发现它失效，并安全地更新或回退？

本文结合 Agent Skills 开放规范、OpenAI 和 Anthropic 的英文文档，以及 Skill 工程化研究，给出一套面向团队的设计、验证和维护方法。

核心观点：把 Skill 当成一个有接口、有边界、需要测试和维护的软件组件。

一、先理解：Skill 解决的是什么问题？

假设团队经常让 AI 帮忙处理数据库迁移。每次开发者都要补充：

先检查当前数据库类型和迁移框架；如果涉及删除字段，考虑线上旧版本是否还在使用；给出回滚方案，并运行项目现有的迁移检查。

如果这些要求反复出现，就可以整理成一个 Skill。

Skill 通常包含：

database-migration/
├── SKILL.md
├── references/
│   └── rollout-patterns.md
└── scripts/
    └── validate_migration.py

其中：

• SKILL.md：说明什么时候使用、要完成什么、如何判断完成。
• references/：放按需读取的细节、案例或规范。
• scripts/：放确实需要稳定执行的工具，例如校验器。

Agent Skills 开放规范定义了以 SKILL.md 为中心的基础格式；不同 Agent 产品还可能提供自己的扩展字段和行为。因此，格式兼容不等于实际行为完全一致。跨工具使用时仍需要测试。Agent Skills Specification

Skill 与其他机制的分工

这里有一个重要边界：Skill 是指导 Agent 的指令，不是权限系统。

如果某件事绝对不能发生，例如直接删除生产数据，不能只在 SKILL.md 里写一句“不要删除”。还应该通过权限、隔离环境、审批或程序化检查来限制。

二、什么样的工作值得做成 Skill？

不是每个 Prompt 都值得沉淀成 Skill。

一个任务适合做成 Skill，通常满足下面几个条件：

1. 反复出现：不同人或不同项目都会遇到。
2. 存在可复用经验：专家知道哪些步骤容易遗漏。
3. 边界能够说清楚：可以判断什么时候该用、什么时候不该用。
4. 结果可以评估：能判断它是否真的改善了任务。
5. 维护成本值得：它带来的收益大于编写、测试和更新成本。

例如：

OpenAI 的建议也是让每个 Skill 聚焦一项工作，描述清楚适用时机，并测试实际触发行为。OpenAI：Build skills

不要把 Skill 当成知识垃圾桶

团队写 Skill 时很容易出现这种情况：

“我们做后端开发，这些规范都挺重要，全部放进一个 Skill。”

最后得到一个几百行的 backend-expert，既管 API，又管数据库、日志、测试、部署和监控。

问题在于：Agent 处理一个小 API 修改时，也可能加载大量无关规则；不同规则还可能互相冲突。

更好的拆法是按任务边界划分：

review-api-change
review-database-migration
investigate-ci-failure
prepare-release

但也不要拆得过细。判断标准不是文件数量，而是：

这个 Skill 是否有独立的触发场景、明确的职责，以及可验证的价值？

三、团队通用的关键：抽象稳定方法，保留项目差异

“通用”不是让所有项目都执行同一套固定命令。

真正可复用的 Skill 应该把内容分成两层：

第一层：跨项目稳定的方法

以数据库迁移为例，稳定的方法包括：

• 确认迁移影响的数据和应用版本。
• 判断变更是否向后兼容。
• 检查锁表、长事务或数据回填风险。
• 确认验证方式和回滚限制。
• 区分已经验证的结果与尚未执行的计划。

这些原则可以跨多个项目复用。

第二层：项目自己的事实

项目差异包括：

• 使用 PostgreSQL、MySQL，还是其他数据库。
• 使用 Flyway、Prisma、Alembic，还是自研迁移工具。
• 测试命令是什么。
• 发布方式是否支持新旧版本同时运行。
• 是否允许执行真实数据库操作。

这些信息不应该被一个“通用 Skill”硬编码。

不够通用的写法：

运行 npm run db:migrate，然后执行 npm test。
所有字段删除必须分三次发布。

更通用的写法：

先识别项目使用的数据库、迁移工具和已有验证命令。

按照项目现有约定验证迁移。对于删除、重命名或类型变化，
检查应用新旧版本是否可能同时运行，并说明兼容性风险。

如果无法确定发布方式或验证环境，明确说明缺失信息，
不要声称迁移已验证。

后者保留了工程判断，又不会假设所有项目都使用相同技术栈。

一个实用的分层方式

团队通用 Skill
  ├── 任务边界
  ├── 通用工作方法
  ├── 必须关注的风险
  └── 完成标准

项目文档 / AGENTS.md
  ├── 项目架构
  ├── 实际命令
  ├── 使用的技术栈
  └── 项目特有规则

本次任务
  ├── 用户目标
  ├── 变更范围
  └── 用户给出的特殊要求

OpenAI 的工程工作流示例也明确提醒：不要把某个仓库的结构误认为所有项目都必须遵循的规则。OpenAI：Iterating Development Workflows with Codex

如何判断有没有过拟合？

拿掉原项目名称后问自己：

如果换一个仓库，这个 Skill 是否仍然能指导 Agent 找到正确做法？

如果答案是否定的，检查它是不是写入了：

• 特定用户的本地绝对路径。
• 某一个仓库的固定文件名。
• 默认存在的环境变量或内部服务。
• 只有创建者知道的团队术语。
• 原项目专用的测试和部署命令。
• 没有说明来源的阈值和限制。

这些内容不一定不能存在，但需要明确：它们究竟属于团队共享 Skill，还是属于某个项目的配置和文档。

四、写好 Skill 的入口：Description 决定它能否被正确发现

一个 Skill 的内容再好，如果 Agent 不知道什么时候应该使用，价值也发挥不出来。

通常，Agent 会先看到 Skill 的名称和描述，再决定是否加载更多内容。因此，描述需要回答两个问题：

1. 它做什么？
2. 什么任务应该使用它？

模糊的描述

description: 帮助开发者处理数据库相关任务。

问题是“数据库相关任务”太宽泛：

• 写一条查询算不算？
• 修改 ORM 模型算不算？
• 查看数据库文档算不算？
• 做数据库迁移才算吗？

更好的描述

description: >
  Review database schema migrations for compatibility, rollout risks,
  validation, and rollback considerations. Use when creating or reviewing
  a database migration or its deployment plan.

这段描述同时说明了职责和触发场景。

如果团队成员主要使用中文，也应当用中文任务实际测试触发效果；不要假设英文描述天然能够覆盖所有语言表达。

防止触发过宽

OpenAI 给出的一个典型例子是：描述里写“数据库、查询、模型或持久化”过于宽泛，会让数据库迁移 Skill 在普通数据库任务中也被触发；更好的写法是限定在创建、修改或审查迁移时使用。OpenAI：Rethinking skills and prompts

因此，写描述时建议同时列出正反例：

应该触发：

• “帮我检查这个数据库迁移是否安全。”
• “这个字段要从字符串改成整数，上线有什么风险？”
• “审查这次 schema migration 的发布方案。”

不应触发：

• “帮我优化这条 SQL 查询。”
• “解释一下什么是数据库索引。”
• “给这个页面增加一个筛选条件。”

反例和正例一样重要：它们能发现 Skill 是否太容易被误用。

五、写正文：给 Agent 决策依据，不要把它变成机械流程

好的 Skill 正文，不需要把 Agent 已经会做的基础动作重新教一遍。

例如：

1. 打开终端。
2. 使用 ls 查看文件。
3. 使用 cat 读取文件。
4. 思考问题。
5. 给出回答。

这些步骤既冗长，也没有贡献团队特有知识。

更有价值的是写清楚：

• 任务需要检查哪些容易遗漏的问题。
• 不同情况应该如何判断。
• 什么信息需要从项目中获取。
• 哪些结果必须有证据。
• 遇到缺失信息或验证失败时如何处理。
• 最终需要向开发者交付什么。

示例：一个精简的迁移审查 Skill

---
name: review-database-migration
description: >
  Review database schema migrations for compatibility, rollout risks,
  validation, and rollback considerations. Use when creating or reviewing
  a database migration or its deployment plan.
---

# Review database migrations

## Scope

Review the migration and its application impact.
Use the repository's existing database and migration conventions.

## Workflow

1. Identify the database, migration tool, affected schema, and application
   code that reads or writes the affected data.
2. Check compatibility between old and new application versions.
3. Assess risks relevant to the change, including data loss, locking,
   data backfill, and migration duration.
4. Find the project's existing validation commands and run the checks
   appropriate to the requested task and available environment.
5. Explain the rollout and rollback considerations. If rollback cannot
   restore lost data, state that explicitly.

## Output

Report:
- Findings and their practical impact.
- Evidence from the migration or application code.
- Checks actually run and their results.
- Unverified assumptions and remaining risks.

Do not claim that a migration is safe merely because it passes a syntax check.

这个示例是一个起点，不是适用于所有团队的最终版本。真实使用前仍需要针对团队的项目和风险进行测试。

什么时候应该使用脚本？

优先考虑用脚本处理以下情况：

• 检查可以被确定性地表达。
• 人工或模型很容易漏掉。
• 相同逻辑需要反复执行。
• 输出格式或操作顺序必须稳定。
• 失败时可以明确返回错误。

例如：

适合脚本：
检查迁移文件是否存在重复编号。

不一定适合脚本：
判断复杂发布方案是否符合业务风险承受能力。

脚本也会带来依赖、兼容性和维护成本，所以不应为了“看起来工程化”而添加。OpenAI 的建议是：默认优先使用指令，仅在需要确定性行为或外部工具时引入脚本。OpenAI：Build skills

六、控制上下文：把 Skill 写成“按需加载”的结构

Skill 可能包含很多背景资料，但 Agent 不一定每次都需要全部读取。

一个实用结构是：

review-database-migration/
├── SKILL.md
├── references/
│   ├── compatibility-patterns.md
│   ├── rollback-examples.md
│   └── database-specific-risks.md
└── scripts/
    └── check_migration_names.py

SKILL.md 只保留：

• 触发范围。
• 核心工作流程。
• 关键判断条件。
• 输出要求。
• 什么时候读取哪些参考资料。

例如：

For destructive changes or irreversible data transformations,
read references/rollback-examples.md.

这样 Agent 执行普通迁移审查时，不必一开始就加载所有案例。

Anthropic 将这种方式称为渐进式披露，并建议保持 SKILL.md 精简，把详细内容拆到直接引用的文件中。其文档给出正文低于 500 行的建议；应把它看作实用参考，而不是“499 行就一定合格”的质量标准。Anthropic：Skill authoring best practices

**需要注意：**引用文件也要测试。文件存在，不代表 Agent 会在合适的时候读取，也不代表不同工具对路径的处理完全一致。

七、如何证明 Skill 好用？必须做对照评估

团队最常见的误区是：

“我试了一次，Agent 回答得不错，所以这个 Skill 已经好了。”

一次成功只能说明它在那一次、那个上下文、那个模型下可能有用。

更可靠的方法是做 Eval（评估）：

真实任务
   ↓
运行 Agent
   ↓
记录过程、结果和产物
   ↓
按明确标准检查
   ↓
比较不同 Skill 版本及无 Skill 基线

OpenAI 对 Skill Eval 的建议也是：同时观察最终结果、执行过程、风格和效率，并用小而明确的检查持续发现回归。OpenAI：Testing Agent Skills Systematically with Evals

1. 先写成功标准

不要只写：

Agent 应该正确审查迁移。

应该拆成可观察的要求：

- 能识别删除字段可能导致的数据丢失。
- 会检查应用代码是否仍然读取该字段。
- 如果没有实际运行迁移测试，不声称测试通过。
- 不直接连接或修改生产数据库。
- 对普通 SQL 优化请求不触发迁移审查 Skill。

其中有些可以自动检查，有些需要人工或评分规则判断。

2. 建立覆盖不同场景的测试集

以迁移审查为例：

OpenAI 的实践建议从一组小规模真实 Prompt 开始，例如 10～20 条，再把实际使用中发现的失败持续加入测试集。这个数量是起步建议，不是通用质量门槛。OpenAI：Skill Eval 测试集

3. 与“没有 Skill”比较

这是最容易被忽略的一步。

用同一批任务比较：

A：不使用该 Skill
B：使用 Skill v1
C：使用 Skill v2

尽量保持相同的模型、仓库初始状态、工具权限和任务描述；每次运行使用干净环境。对有随机性的场景，可以重复运行，并记录模型版本、运行次数、时间和成本。

重点比较：

如果使用 Skill 后结果没有变好，反而更慢、产生更多无关文件，或者误触发增加，就需要修改甚至删除这个 Skill。

4. 区分“结果正确”和“过程正确”

例如 Agent 最终说：

这个迁移没有问题。

即使结论碰巧正确，也不能证明它做了可靠审查。可能它没有读应用代码，也没有检查数据回填。

另一方面，如果任务并不需要运行某个具体命令，也不应该因为 Agent 选择了另一种合理验证方式就判定失败。

所以评分建议分两层：

• 结果检查：发现关键风险、修改范围正确、测试结果真实。
• 必要过程检查：只约束真正重要的行为，例如不得修改生产环境、必须检查相关应用代码。

不要把每一次实现细节都固定下来，否则 Skill 和测试会限制 Agent 采用更好的方法。

5. 自动评分与人工评分结合

适合自动检查：

• 是否产生了不应出现的文件。
• 测试命令是否成功。
• 指定校验脚本是否通过。
• 是否修改了允许范围以外的文件。

适合人工或有明确评分标准的模型辅助检查：

• 是否识别真正的上线风险。
• 解释是否清晰。
• 是否区分事实、推测和未验证内容。
• 建议是否适合当前项目。

模型评分可以帮助扩大评估规模，但应定期用人工复核，尤其是高风险场景。

**注意：**自动化运行 Agent 时，应使用隔离的测试仓库和最小权限。评估轨迹可能包含代码、路径或敏感信息，保存和分享前需要检查。

八、团队如何共享：像管理代码一样管理 Skill

当 Skill 要给团队使用时，它就不再只是个人 Prompt，而是一个共享工程资产。

1. 放进版本管理

至少应该能够回答：

• Skill 当前版本是什么？
• 谁修改了它？
• 为什么修改？
• 修改后哪些场景通过或失败？
• 出问题如何回退？

团队可以选择：

• 仓库内管理：适合与项目强相关的 Skill。
• 团队共享仓库或内部插件：适合多个项目使用。
• 个人目录：适合个人实验；成熟后再考虑共享。

不同 Agent 的发现路径、安装方式和扩展元数据可能不同。共享时要写清楚团队实际支持哪些工具，并分别验证，不能只因为都能读取 SKILL.md 就宣布完全兼容。

2. 用真实项目做试点

建议先找少量不同类型的项目：

项目 A：TypeScript + PostgreSQL
项目 B：Python + MySQL
项目 C：Java + PostgreSQL

让实际开发者使用自然语言完成任务，观察：

• Skill 是否触发。
• 它是否理解各项目的真实约定。
• 是否把项目 A 的命令错误地套到项目 B。
• 是否制造额外步骤。
• 开发者是否需要反复纠正它。

这里的关键不是覆盖所有技术栈，而是尽早发现 Skill 的隐含假设。

3. 给每个共享 Skill 一个维护责任人

维护责任不一定意味着一个人写完所有内容，而是有人负责：

• 接收反馈。
• 判断问题属于 Skill、项目配置还是模型能力。
• 维护测试案例。
• 审查变更。
• 判断何时弃用。

Skill 没有人维护，很快就会出现旧命令、失效链接和过时流程。

4. 重大变化后重新评估

以下变化都可能改变 Skill 的表现：

• 模型升级。
• Agent 产品升级。
• 工具权限变化。
• 仓库结构变化。
• 依赖或框架升级。
• Skill 的描述、正文、脚本或引用文件变化。

尤其要注意：模型能力提升后，原来需要的大量细碎步骤可能不再有价值，反而增加干扰。应定期删除没有证据支持的指令。OpenAI：Rethinking skills and prompts

九、安全与可信度：共享 Skill 也是供应链

一个 Skill 可能包含指令、脚本、外部链接和工具调用。因此，引入第三方 Skill 时，应像引入依赖一样检查来源和内容。

重点关注：

1. 来源是否可信：由谁维护，是否有版本记录？
2. 脚本做什么：会不会读取敏感文件、安装依赖或访问外网？
3. 需要什么权限：是否超出任务所需？
4. 是否包含隐藏假设：例如默认有生产数据库访问权限。
5. 引用是否可控：外部文档变更后，行为会不会改变？
6. 能否回退：出问题时能否定位到具体版本。

团队可以把 Skill 的审查分级：

• 只有文本说明、无外部操作：轻量审查。
• 包含本地脚本或依赖安装：检查代码和依赖。
• 涉及云资源、生产数据或外部写入：结合现有权限与审批流程。

**不要让 Skill 自己声称安全，就成为安全依据。**真正的约束应由运行环境、权限系统、代码审查和必要的自动检查共同承担。

十、常见失败模式

十一、一个团队可以直接采用的落地流程

如果团队准备建设自己的 Skill 库，可以先从一个具体场景开始。

第一步：挑一个反复出现的问题

例如：

AI 排查 CI 失败时，经常直接修改 CI 配置，却没有先确认失败来自测试、依赖还是环境。

第二步：定义 Skill 的职责

名称：investigate-ci-failure

职责：
根据 CI 日志和仓库现状定位失败原因，
提出或实施用户要求范围内的修复，
并验证实际修复结果。

不负责：
自动发布、修改生产环境、跳过失败测试。

第三步：写出 5～10 个真实案例

例如：

• 测试断言失败。
• 依赖安装失败。
• 环境变量缺失。
• CI 服务临时不可用。
• 日志不完整。
• 用户只要求解释失败原因。
• 用户明确要求修复失败。

第四步：先记录无 Skill 的表现

保存每个案例的：

• 输入。
• 仓库初始状态。
• Agent 输出。
• 实际修改。
• 检查结果。
• 运行时间和成本。

第五步：编写最小版本

只加入真正能帮助解决问题的规则，例如：

先根据日志区分失败阶段。

如果日志不完整，说明证据不足，不要把猜测写成根因。

用户只要求分析时，先报告结论，不擅自修改配置。

实施修复后，运行与失败相关的检查；
无法复现时，明确说明验证限制。

第六步：运行对照评估

比较有无 Skill 的结果，再让另一个团队成员在不同项目中使用。

第七步：基于失败修改

例如发现 Agent 过度触发，就调整描述；发现只在某个项目失败，就先判断是 Skill 的通用方法有问题，还是项目文档缺少必要信息。

第八步：进入日常维护

把真实使用中的失败案例加入回归集。模型或工具升级时，重新跑关键案例。

十二、发布前检查清单

团队准备共享一个 Skill 时，可以用下面这份清单做最后检查：

设计

• 能用一句话说清楚它解决什么问题。
• 有明确的适用场景和不适用场景。
• 没有与现有 Skill 重复或明显冲突。
• 核心内容是可复用的方法，而不是某个项目的偶然细节。

实现

• 描述清楚且足够简短。
• 工作流程包含必要的判断依据与完成标准。
• 项目专用命令和配置有明确来源。
• 参考文件能够被找到，并在需要时读取。
• 脚本有必要、依赖清楚、失败行为明确。

验证

• 测试了显式调用和自然语言触发。
• 测试了不应触发的相邻任务。
• 至少在不同项目或不同条件下试用。
• 与无 Skill 的表现做过比较。
• 检查了实际产物和必要过程。
• 未验证的结果不会被表述为已验证。

维护

• 有版本记录和维护责任人。
• 有人知道如何安装、更新和回退。
• 关键失败案例被保留下来。
• 工具、模型或项目发生变化后会重新评估。

结语

团队 Skill 的目标，不是让 AI 每次都执行一份更长的检查清单，而是把团队真正有价值的经验，变成能够被发现、按场景使用、验证效果并持续改进的工作能力。

判断一个 Skill 是否值得保留，可以反复问三个问题：

它解决了什么真实问题？有证据证明它带来了改善吗？换一个项目和开发者，还能否正确使用？

如果这三个问题都有清楚答案，Skill 才开始成为团队资产。