摘要
AI Agent 的能力，不只来自模型本身，还来自围绕模型构建的 Skill Library。
过去我们总在优化 Prompt，希望模型一次性理解更多上下文。
但真正稳定的做法，不是不断写更长的提示词，而是把团队的经验、工具、脚本、验证方法、踩坑记录和操作规范，封装成 Agent 可以主动发现、调用和执行的能力模块。
这就是从 Prompt Engineering 进入 Context Engineering 的关键一步。
团队经验从一次性 Prompt，沉淀为可发现、可调用、可验证的 Skill Library。
01. Skill 不是 Prompt，而是能力模块
很多人会误解 Skill，以为它只是一个更长、更复杂的提示词。
这个理解太浅。
Prompt 解决的是：
这一次怎么做。
Skill 解决的是：
以后遇到这类任务都怎么做。
一个真正有价值的 Skill，不只是写几段说明，而是把一类任务所需的上下文、工具、脚本、参考文件、验证方式、异常处理和团队经验放在一起，让 Agent 在需要时可以自动调用。
所以，Skill 的本质不是“提示词模板”，而是：
把团队反复使用、容易出错、依赖工具、需要验证的经验，沉淀成 AI Agent 可复用、可执行、可迭代的能力包。
这也是 Agent 从“会聊天”走向“能干活”的关键。
02. 什么任务值得做成 Skill？
不要为了写 Skill 而写 Skill。
一个任务是否值得封装成 Skill，可以看它是否满足以下几个条件：
- Agent 经常在这里犯错
- 团队已经有固定 SOP，但 Agent 不知道
- 任务依赖内部工具、API、CLI、数据库或监控系统
- 输出质量不能只靠模型自信，必须验证
- 同类任务反复发生，值得标准化
- 操作有风险，需要 guardrails
- 任务需要跨多个工具、文件、系统执行
一句话：
Skill 最适合封装“模型默认不会、团队反复在做、出错代价高、需要稳定复用”的能力。
如果一个任务只是偶尔做一次，或者模型默认已经能处理得很好，就没有必要做成 Skill。
真正值得做成 Skill 的，通常是团队里那些“老员工知道，但新人不知道；人类知道，但 Agent 不知道”的隐性经验。
03. 最值得建设的 9 类 Skill
Anthropic 在 Claude Code 的内部实践中，把常见 Skills 总结成 9 类。对任何想建设 Agent 能力库的团队，都很有参考价值。
先从高频、高错、高价值场景开始，而不是一次性规划大而全的 Skill 平台。
1. Library / API Reference Skill
用于封装内部库、CLI、SDK、API 的正确用法。
适合内容包括：
- 内部 API 使用方式
- CLI 命令
- SDK 示例
- 参数说明
- 常见误用
- 废弃接口提醒
- 内部库的边界条件
适用场景：
Agent 会写代码，但不知道你们公司内部库怎么用。
比如公司内部有 billing library、model router、sandbox proxy、deployment CLI，这些东西模型默认不知道。如果不做 Skill，Agent 只能猜。
这类 Skill 的价值，是把“内部工具的正确用法”交给 Agent。
2. Product Verification Skill
这是最值得优先建设的一类 Skill。
Agent 最大的问题不是“不会做”，而是“做完以后不知道是否真的对”。
Verification Skill 的价值在于：
让 Agent 不只是完成任务，而是证明任务真的完成了。
适合内容包括：
- Playwright 测试
- UI 自动验证
- 登录流程检查
- 注册流程检查
- 支付流程检查
- Smoke Test
- 状态断言
- 录屏验证
- CLI 验证脚本
例如：
signup-flow-driver：自动跑注册、邮箱验证、onboarding 流程checkout-verifier：自动验证支付流程和订单状态tmux-cli-driver：验证需要交互式终端的 CLI 工具
这类 Skill 是 AI 编程从 Demo 走向生产的关键。
因为生产环境不只需要“代码看起来对”，而需要“结果真的被验证过”。
3. Data Fetching / Analysis Skill
用于封装数据查询、监控分析、指标口径和业务看板。
适合内容包括：
- 数据表说明
- 指标定义
- Dashboard 地址
- Grafana 查询方式
- Datadog 查询方式
- 用户转化漏斗
- Cohort 分析方法
- Trace ID / Request ID 查询路径
适用场景：
Agent 不只是写代码，还能自己查数据、看监控、定位问题。
比如你问：
为什么昨天注册转化率下降？
如果没有 Data Skill，Agent 只能泛泛分析。
如果有 Data Skill，它可以知道去哪里查数据、哪些表是事实来源、哪些指标口径不能混用、哪个 dashboard 对应哪个问题，以及哪些字段在不同系统里叫法不同。
这会让 Agent 从“回答问题”变成“调查问题”。
4. Business Process / Team Automation Skill
用于封装团队日常重复流程。
适合内容包括：
- 站会总结
- 周报汇总
- Ticket 创建
- Slack 通知
- GitHub 活动汇总
- Release Note 生成
- 历史执行记录
这类 Skill 的价值，不只是自动化流程，还可以形成轻量记忆。
例如 weekly-recap Skill 可以读取本周合并的 PR、关闭的 ticket、发布记录和上一次周报内容，然后生成一份只包含增量变化的周报。
这意味着 Skill 不只是“执行一次流程”，还可以让 Agent 记住过去的执行结果，下一次运行时知道发生了什么变化。
5. Code Scaffolding / Templates Skill
用于封装代码模板、项目脚手架、迁移文件和服务初始化。
适合内容包括：
- 新服务模板
- Migration 模板
- Auth 模板
- Logging 模板
- Deploy 配置
- 目录结构规范
- 框架最佳实践
适用场景：
让 Agent 不要每次重新发明项目结构，而是按团队标准生成。
比如新建一个内部 App，团队通常会有固定要求：认证怎么接、日志怎么打、配置怎么放、部署文件怎么写、错误处理怎么做、权限边界在哪里。
这些都可以封装成 Skill。
这样 Agent 生成的不是“能跑的代码”，而是“符合团队规范的代码”。
6. Code Quality / Review Skill
用于封装代码审查、测试规范、风格要求和质量门禁。
适合内容包括：
- Code Review Checklist
- Testing Practice
- 安全检查
- Lint
- Typecheck
- Unit Test
- Adversarial Review
- GitHub Action 集成
这类 Skill 可以进一步和 CI、hooks 结合，变成自动化质量控制层。
例如：
- 修改代码后必须跑 typecheck
- 涉及支付必须补充测试
- 涉及权限必须做安全审查
- 涉及 UI 必须跑视觉验证
- 涉及数据库必须检查 migration 风险
Code Quality Skill 的价值，是让 Agent 不只是“写代码”，而是按团队质量标准写代码。
7. CI/CD / Deployment Skill
用于封装 PR、部署、灰度、回滚和上线验证流程。
适合内容包括：
- 监控 PR
- 修复 flaky CI
- 解决 merge conflict
- Smoke Test
- 灰度发布
- 错误率对比
- 自动回滚
核心价值：
Agent 不只是写代码，还能推进代码进入生产，但必须带验证和回滚机制。
比如 deploy-service Skill 可以定义：
- 构建服务
- 运行测试
- 执行 smoke test
- 小流量灰度
- 对比错误率
- 检查核心指标
- 异常时自动回滚
- 输出部署报告
这类 Skill 是 Agent Ops 的关键部分。
8. Runbook Skill
用于封装故障处理、告警排查、日志关联和服务调试路径。
适合内容包括：
- 告警排查流程
- 服务异常定位
- Slack Thread 分析
- Request ID 全链路追踪
- 日志查询路径
- 常见故障处理步骤
Runbook Skill 的本质是：
把资深工程师的排障路径，变成 Agent 可以执行的调查流程。
比如用户给 Agent 一个错误日志，Agent 可以根据 Skill 自动知道先查哪个服务、再查哪个 dashboard、哪些日志字段能关联、哪些错误是已知问题、哪些异常需要升级给人类、最终如何输出调查报告。
这会让 Agent 在 incident 处理里变得更有价值。
9. Infrastructure Operations Skill
用于封装基础设施维护、成本排查、资源清理等高风险操作。
适合内容包括：
- 孤儿资源清理
- 依赖升级
- Kubernetes 操作
- 成本异常调查
- 数据迁移
- 回滚操作
- 高危操作确认机制
这类 Skill 必须非常谨慎。
因为它可能涉及删除、迁移、回滚、生产环境变更等高风险动作，必须配套 guardrails。
比如：
- 删除前必须 dry-run
- 操作生产环境前必须确认
- 高危命令必须拦截
- 回滚前必须生成影响说明
- 资源清理前必须保留观察期
Infrastructure Skill 的原则不是“不让 Agent 执行”，而是让 Agent 在明确边界内执行。
Agent 越能干活，越需要边界。
04. 写好 Skill 的 8 条原则
原则一：不要写显而易见的内容
不要在 Skill 里写：
先阅读代码，再修改代码，再运行测试。
这种内容模型本来就知道。
Skill 应该写模型不知道、但团队知道的东西：
- 哪个字段容易误解
- 哪个 API 文档已经过时
- 哪个环境会返回假成功
- 哪个数据表才是真实来源
- 哪个命令不能在生产环境乱用
- 哪个测试必须补充人工断言
如果 Skill 只是重复模型默认会做的事情，它只会增加上下文成本，不会增加能力。
好的 Skill 应该提供“模型不知道的关键上下文”。
原则二：一定要写 Gotchas
Gotchas 是 Skill 里最高价值的部分。
所谓 Gotchas，就是：
Agent 最容易踩坑的地方。
例如：
subscriptions 是 append-only，不能直接取最新 created_at，要取最高 version。API Gateway 里叫 request_id，Billing Service 里叫 trace_id。Staging 返回 200 不代表 Stripe webhook 真的处理成功，还要查 payment_events。一个判断标准：
没有 Gotchas 的 Skill，通常不是好 Skill。
因为真正的组织经验，往往就藏在这些“别人不知道但你踩过坑”的地方。
Gotchas 不应该一次写完，而应该从 Agent 的真实失败中不断补充。
每次 Agent 出错，都要问一句：
这个错误是不是下次还可能发生？
如果是，就写回 Gotchas。
没有 Gotchas 的 Skill，通常只是更长的提示词。
原则三：用文件系统做 Progressive Disclosure
不要把所有内容都塞进一个巨大的 SKILL.md。
更好的方式是把 Skill 拆成多层结构：
my-skill/
SKILL.md
gotchas.md
config.json
references/
api.md
cli.md
data-model.md
scripts/
verify.ts
fetch-data.py
examples/
happy-path.md
edge-cases.md
assets/
report-template.mdSKILL.md 只负责做总入口：
- 这个 Skill 什么时候用
- 先读哪些文件
- 哪些情况要读 reference
- 哪些脚本可以调用
- 最后按什么格式输出
这样做的好处是：
既能提供丰富上下文，又不会一次性把上下文撑爆。
这就是 Context Engineering 的关键：
不是把所有信息一次性塞给 Agent，而是让 Agent 按需读取正确的信息。
不是一次性塞满上下文，而是让 Agent 按需读取正确的信息。
原则四：不要把 Agent 管死
Skill 不是死板 SOP。
如果写得太细、太硬，Agent 会被迫照着错误路径执行，反而失去判断能力。
好的 Skill 应该提供背景、约束、工具、常见坑、验证方法和输出标准，但不要把所有步骤写成绝对命令。
更好的写法是：
在这些情况下优先这样做；如果上下文不匹配，先检查并解释原因。
给 Agent 边界，而不是给 Agent 上枷锁。
Skill 的目标不是让 Agent 机械执行，而是让 Agent 在正确上下文里做更好的判断。
原则五：把 Setup 信息配置化
很多 Skill 都需要初始化配置。
例如：
- Slack 频道
- GitHub Repo
- Dashboard 地址
- 环境变量
- API Key
- 默认项目
- 数据库连接
- 部署环境
这些信息不要全部写死在说明里，建议放进 config.json：
{
"slack_channel": "",
"default_repo": "",
"dashboard_url": "",
"environment": "staging"
}原则是：
能配置的不要写死；缺配置时再让 Agent 向用户确认。
这样 Skill 才能在不同团队、不同项目、不同环境里复用。
原则六：Description 是给模型看的，不是给人看的
Skill 的 description 不是宣传文案。
它的真正作用是：
帮助模型判断什么时候应该触发这个 Skill。
不好的写法：
description: Help with deployment.更好的写法：
description: Use this skill when the user asks to deploy a service, monitor a rollout, run smoke tests, compare error rates, or rollback a failed release.核心规则：
Description 不要只写“这个 Skill 是什么”，要写“什么情况下应该用它”。
因为 Agent 会通过 description 判断当前任务是否需要调用这个 Skill。
如果 description 写得太泛，Skill 容易误触发。
如果 description 写得太窄，Skill 又可能该用时没有被调用。
原则七：给 Agent 脚本，不要只给文字
好的 Skill 不只是说明文档，还应该提供可执行工具。
比如数据分析 Skill，不要只写：
查询用户事件表，然后分析转化率。
更好的方式是提供脚本：
scripts/
fetch_events.py
compare_cohort.py
generate_report.pyAgent 可以直接组合这些脚本完成任务。
这就是 Skill 和 Prompt 的关键区别：
Prompt 让 Agent 想办法。 Skill 给 Agent 现成工具。 好 Skill 让 Agent 少猜、多执行。
代码、脚本、模板、测试文件，都是 Skill 的一部分。
不要只给 Agent 文字，要给它可以直接使用的工具。
原则八：高风险任务要有 Guardrails
涉及生产环境、数据库、部署、删除、迁移、回滚的 Skill，必须有安全边界。
例如：
- 禁止直接删除生产数据
- 禁止未经确认执行 DROP TABLE
- 禁止 force push
- 禁止直接操作生产 Kubernetes
- 禁止修改非目标目录
- 删除前必须 dry-run
- 回滚前必须生成影响说明
高风险 Skill 的核心原则：
不是不让 Agent 执行，而是让 Agent 在边界内执行。
Agent 越能干活，越需要边界。
没有 guardrails 的 Agent Automation，很容易从效率工具变成生产风险。
05. 一个标准 Skill 应该长什么样？
推荐结构：
skill-name/
SKILL.md
gotchas.md
config.json
references/
api.md
data-model.md
cli.md
scripts/
verify.sh
smoke-test.ts
fetch-metrics.py
examples/
success-case.md
failure-case.md
assets/
output-template.md
logs/
history.log其中：
SKILL.md：入口说明，告诉 Agent 什么时候用、怎么用gotchas.md：常见坑和失败经验config.json：项目、环境、频道、repo 等配置信息references/：API、数据模型、CLI、内部规范scripts/：验证脚本、查询脚本、执行脚本examples/：成功案例和失败案例assets/：报告模板、输出模板logs/：历史执行记录，形成轻量记忆
06. SKILL.md 推荐模板
可以直接参考这个结构：
# Skill Name
## When to use this skill
Use this skill when the user asks to...
## What this skill helps with
- ...
- ...
- ...
## Required setup
Read `config.json`.
If required fields are missing, ask the user before continuing.
## Workflow
1. Understand the user request
2. Check relevant references
3. Run the required scripts
4. Verify the output
5. Produce the final report
## Gotchas
Read `gotchas.md` before making changes.
## Verification
Use scripts in `scripts/` to verify the result.
## Output format
Use `assets/output-template.md`.这个模板的重点不是格式，而是思路：
先让 Agent 判断什么时候用，再让 Agent 按需读取上下文，最后让 Agent 执行并验证。
07. Skill 从 0 到 1 的建设流程
Step 1：从失败中找 Skill
不要先规划一个庞大的 Skill Library。
先问团队几个问题：
- Agent 最近在哪些任务里反复失败？
- 哪些地方总需要人类提醒？
- 哪些任务每次都要复制同一套说明？
- 哪些内部工具 Agent 经常不会用？
- 哪些输出看起来完成了，但其实没有验证？
这些地方就是第一批 Skill 候选。
Skill 不应该从“我们想建设什么能力”开始。
而应该从“Agent 现在在哪里反复失败”开始。
Step 2：只做一个窄 Skill
不要一开始写一个巨大的：
frontend-engineering-master-skill更好的方式是写具体、窄、可触发的 Skill：
checkout-verifier
signup-flow-driver
billing-lib-reference
new-migration
deploy-payment-serviceSkill 越具体，触发越稳定。
越大的 Skill，越容易让 Agent 困惑。
好的 Skill 应该解决一个明确场景，而不是试图覆盖整个工程体系。
Step 3：先写最小版本
第一版 Skill 不需要复杂。
可以只有：
SKILL.md
gotchas.md
scripts/verify.sh不要追求一次写完。
Skill 是随着真实使用不断进化的。
第一版只要能解决一个真实问题，就值得存在。
Step 4：让 Agent 在真实任务中使用
Skill 写出来以后，必须进入真实任务。
例如：
- 写代码
- 修 bug
- 查日志
- 做验证
- 跑部署
- 生成报告
- 创建 ticket
- 处理 incident
只有真实执行以后，才知道这个 Skill 哪些地方有效，哪些地方会误导模型。
Skill 不是文档资产，而是运行资产。
不用起来，就没有价值。
Step 5：把失败沉淀回 Gotchas
每次 Agent 出错，不要只修这一次。
要问：
这个错误是不是下次还可能发生？
如果是，就把它写回：
gotchas.md
references/
scripts/
config.jsonSkill 的进化，不靠一次写完，而靠持续吸收失败。
真正优秀的 Skill，往往不是第一版写得多完整，而是经历过真实任务、真实错误、真实修正。
Step 6：加入验证脚本
当一个 Skill 开始稳定使用后，必须加入验证。
最低要求是：
- 是否能自动检查输出？
- 是否能断言关键状态？
- 是否能跑测试？
- 是否能生成可复查日志？
- 是否能留下执行证据？
因为 Agent 最大的问题不是“不会做”，而是“做完后不知道是否真的对”。
所以，Verification 不是锦上添花，而是 Agent 进入生产环境的基本条件。
Step 7：记录 Skill 的使用情况
Skill 一旦变多，就需要运营。
团队应该记录：
- 哪些 Skill 被频繁调用
- 哪些 Skill 很少触发
- 哪些 Skill 调用后失败率高
- 哪些 Skill 经常被错误触发
- 哪些 Skill 明显提升了效率
这会让 Skill Library 从“经验库”变成“可运营资产”。
未来团队管理 Agent，不只是看模型效果，也要看 Skill Library 的质量。
08. 团队应该优先建设哪 5 类 Skill？
如果一个团队从 0 开始建设 Agent Skill Library，不建议先做大而全的知识库。
应该从高频、高错、高价值场景开始。
P0：Verification Skill
因为它决定 Agent 输出能不能进入生产。
示例：
web-ui-verifier
checkout-verifier
api-smoke-test
tmux-cli-driver优先级最高。
因为没有验证，Agent 做得越多，风险越大。
P1：Gotchas Skill
把团队最容易踩坑的经验先沉淀下来。
示例：
billing-gotchas
database-gotchas
deployment-gotchas
model-routing-gotchas这类 Skill 成本低、收益高。
只要把团队过去踩过的坑写进去，Agent 下次就可能少犯一次错。
P2：Internal API / CLI Skill
让 Agent 会用内部系统。
示例：
internal-platform-cli
billing-lib-reference
sandbox-proxy
model-router-api这类 Skill 可以显著降低 Agent 对内部系统的误解。
P3：Runbook Skill
让 Agent 能处理线上问题。
示例：
service-debugging
oncall-runner
log-correlator
cost-investigation这类 Skill 的价值在于把资深工程师的排障路径标准化。
P4：Business Automation Skill
让团队日常工作自动化。
示例：
weekly-recap
standup-post
create-ticket
release-note-generator这类 Skill 适合快速提高团队日常效率。
09. 判断一个 Skill 好不好：7 个标准
一个 Skill 是否有效，可以用这 7 个问题判断：
- 触发条件是否明确？
- 是否解决了模型默认不知道的上下文？
- 是否包含真实 Gotchas？
- 是否提供可执行脚本？
- 是否有验证方法？
- 是否能按需读取细节，而不是一次性塞满上下文？
- 是否能从真实使用中持续更新？
如果一个 Skill 只有说明，没有 Gotchas、脚本、验证、配置、日志，那它大概率只是一个“更长的提示词”。
真正的 Skill 应该是：
指令 + 上下文 + 工具 + 验证 + 记忆 + 约束。
10. 最终方法论：Skill 是 Agent 的组织记忆
这篇文章真正重要的地方，不是 Claude Code 多了一个功能。
而是它揭示了 AI Native 组织的一个底层趋势：
未来团队的经验，不会只沉淀在文档里。
它会沉淀成 Agent 可以调用的 Skill。
过去团队资产主要是：
- 文档
- SOP
- 代码库
- Wiki
- Runbook
- 老员工经验
现在这些资产需要被重新组织成：
- 可发现
- 可调用
- 可执行
- 可验证
- 可迭代
- 可分发
这就是 Skill Library 的战略意义。
它不是知识管理工具。
它是 Agent 时代的能力管理系统。
行动清单
如果你今天就要开始，不要先做一个宏大的 Skill 平台。
先做 3 件事：
- 找出 Agent 最近 10 次失败记录
- 把最高频的 3 个失败写成 Gotchas
- 为其中 1 个任务加上验证脚本
第一批 Skill 不需要完美。
它只需要让 Agent 下次少犯一个真实错误。
这就是 Skill 进化的起点。
一句话总结
别再只写 Prompt 了。
真正能让 Agent 稳定变强的，是把团队经验封装成可发现、可执行、可验证、可迭代的 Skill。