AI Agent技能全指南：用Markdown打造稳健智能体

如果你正在使用 Claude Code、Codex、Copilot 或任何智能体工具开发软件，大概率遇到过这样的场景：智能体在写单元测试时只覆盖了基本行为，完全忽略边界情况；或者在生成数据库迁移文件时，技术上正确却暗藏生产环境风险。Google 开发专家菲利普在最近的技术分享中，系统性地拆解了如何通过「技能」（Skill）机制解决这类问题——本质上，就是用一份 Markdown 文件，把重复性指令和领域约定固化下来，让智能体在恰当时机自动加载。

什么是智能体技能？

技能（Skill）归根结底是一个 Markdown 文件，里面写的是如何执行某项操作的具体指令。它不是一个插件，也不是一段代码，而是一组可以按需加载的提示词。

菲利普指出，在智能体开发中，总有一些指令并非始终适用，但在特定场景下又必不可少。比如项目中关于如何编写测试用例的规范——该选哪些库、断言颗粒度多细、遵循哪些最佳实践。没有技能机制，你就得一遍又一遍地告诉智能体这些要求，而且还得在它即将开始写测试时提醒它。但问题在于，你往往无法预知那个时刻——你可能只是丢给它一个更大的任务，它自己就开始写测试了。技能解决的正是「在正确时机注入正确上下文」的问题。

菲利普以自己编写的 Android 单元测试技能为例：核心方法论是「像一个真正想破坏代码的人那样去测试」。因为他发现，如果只让 Claude 写测试而不给明确指令，它往往只覆盖基本行为，忽略大量边界情况。而采用「如何让这段代码崩溃」的思路后，测试用例的多样性显著提升。

渐进式披露（progressive disclosure）：理解技能机制的关键在于它并非把所有内容一次性塞进提示词，而是分层加载。第一层是常驻上下文的技能名称与简短描述，供模型判断「何时该用」；第二层是命中后加载的 SKILL.md 正文，给出具体流程与规范；第三层是技能目录下附带的脚本、模板、参考文档等资源，仅在需要时由模型主动读取。这种设计让大量知识可以「挂载」在智能体身边而不占用常驻预算，用空间换成本，是技能优于把全部规范写进系统提示词的根本原因。

什么时候才该创建技能？

并非所有场景都适合封装成技能。菲利普给出了一个必要条件加两个可选条件：

必要条件：指令需要被重复使用。 如果只是让智能体做一次性的任务，直接把内容写在提示词里即可，没必要创建技能。但像单元测试这类会在不同代码库中反复出现的任务，就值得花时间把详细要求固化下来。

可选条件一：涉及个人或团队的特定约定。 比如菲利普自己对 Android 单元测试有一套独特规范，这不是公开知识，而是个人偏好。把这类约定编码进技能很有意义。

可选条件二：涉及小众领域知识。 大语言模型基于公开数据训练，但如果你在处理非常细分的领域——比如某种特定机器的电路设计——你的专业知识可能远超模型的训练数据覆盖范围。

反过来，菲利普明确不建议为通用知识创建技能。比如「设计关系型数据库模式」，这类知识公开可查，普通大模型已经能处理得很好，除非你有非常具体的自定义要求，否则创建技能没有意义。

技能存放在哪里？

技能有两种作用域。全局技能放在用户目录下的 ~/.claude/skills/ 文件夹中，每个技能是一个以技能名命名的文件夹，里面包含一个 SKILL.md 文件。这些技能在所有会话中都可使用。项目级技能则放在项目根目录的 .claude/（或 .cursor/ 等）文件夹下，仅在从该根目录启动会话时生效。

一个关键细节：技能的描述（description）始终占用上下文窗口。如果你有十个技能，发一条提示词时，所有技能的描述都会进入上下文并消耗 token。因此，不要用大量技能淹没智能体——描述是智能体判断是否调用该技能的依据，但也是有成本的。

上下文窗口与 token 成本：大语言模型的「上下文窗口」指单次推理时能同时容纳的文本总量，以 token（词元）为单位计量，一个 token 大致对应英文的半个单词或中文的一两个字。窗口容量有限，系统提示词、历史对话、工具定义、文件内容与技能描述都要挤占同一块空间。因此技能描述并非「免费」的元数据，而是常驻开销：技能越多，每次请求可用于实际任务的预算就越少，模型对关键指令的注意力也可能被稀释。这也是实践中常把「描述」写得短而精准、把详细步骤留在技能正文（仅在触发后才加载）的原因。

用「技能创建器」打造稳健技能

菲利普推荐使用来自 AnswerPick 的「技能创建器」（Skill Creator）来生成技能。如果你用 Claude Code，可以直接安装；如果不用，也可以手动复制原始文件到 skills 文件夹中，创建一个名为 SKILL.md 的文件。

在 Claude 桌面端的协作模式中，通过「管理技能」搜索技能创建器即可安装。安装后，当你表达想创建技能的意图时，Claude 会自动调用技能创建器，把如何创建优秀技能的上下文加载进来。

菲利普以创建一个「可扩展架构中关系型数据库安全迁移」技能为例。他通过语音输入详细描述需求：迁移文件在技术上往往正确，但生产环境可能有操作风险——比如在含大量数据的表上添加无默认值的非空列、重命名字段时不用扩展收缩模式、忘记让迁移可逆。他要求技能必须包含：重命名和类型变更时使用扩展收缩模式、始终提供可回滚的向下迁移、当迁移应拆分为多次部署时发出警报、执行前询问表的大小和变更类型。

技能创建器的一个关键动作是主动提问。菲利普特意在提示词末尾要求：「请向我提问任何你需要了解的问题，以确保这个技能足够稳固。」随后 Claude 依次询问了数据库类型（PostgreSQL 和 MySQL）、迁移工具（Flyway）、是否支持多步骤部署、以及表大小的行数基准（十万行以下常规处理，百万行以上分批处理）。

技能需要测试和迭代

技能创建器生成提案后，菲利普强调必须仔细审阅内容是否符合特定需求。保存之后，技能即可使用。但更重要的是测试：如果技能没有带来比不使用技能时显著更好的输出，那这个技能就不值得存在。

Claude 可以生成技能评估，对比使用技能和不使用技能两种情况下的输出。菲利普的测试结果显示，无技能时的迁移质量至少类似，但技能的价值在于「强制执行一致且可检查的推理」——把「什么才算好的迁移」编码一次，反复调用，而不是每次都依赖模型去深入理解细节。

技能的迭代是持续过程。菲利普坦言，不太可能在第一天就得到完美技能。初始版本通常还不错，使用中会发现「这个场景没考虑到」「那个情况没想到」，然后简单更新 Markdown 文件即可。修改技能时通常不需要再次调用技能创建器——直接用普通提示词让模型修改那个 Markdown 文件就行。

扩展收缩模式（expand-contract）：这是数据库模式变更的一种安全演进范式，分三步走。第一步「扩展」：新增字段或新表，同时保留旧结构，让新旧代码可以并行运行；第二步「迁移」：部署读写新结构的代码，并回填历史数据；第三步「收缩」：确认无任何代码依赖旧结构后，再删除旧字段或旧表。直接重命名字段或修改类型会让新旧版本代码在滚动发布期间必然有一方报错，而扩展收缩模式把一次破坏性变更拆成多次向后兼容的部署，从而让迁移过程可回滚、可观测。

核心要点回顾

技能的本质是一份按需加载的 Markdown 提示词文件，解决的是「在正确时机注入正确上下文」的问题。创建技能前先问自己：这个指令会被重复使用吗？它涉及我的特定约定或小众领域知识吗？两个答案都是否，就别创建。技能描述始终占用上下文窗口，技能数量需要克制。用技能创建器生成初版，通过评估对比验证价值，在实践中持续迭代——这才是让 AI Agent 真正稳健的路径。