Agent Skills 实战指南：从 SKILL.md 到自定义技能开发

去年还在讨论“提示词工程”今年圈子里的热门词已经变成了“Agent Skills”。如果你最近刷技术社区会发现 Claude Skills、Agent 技能、Agent 能力扩展这些词出现频率越来越高。但很多人的第一反应是这不就是换个名字的提示词模板吗还真不是。先说我的判断Agent Skills 代表的是 AI 编程助手从“会问答”走向“会按专业标准执行任务”的关键一步。它的本质是把某个领域的专家经验、操作步骤、风险提醒写成标准化的技能包让 Agent 在执行任务时自动加载。对开发者来说这意味着一次沉淀、处处复用不再需要在每轮对话里反复交代背景和约束。这篇文章不打算停留在概念层面。我会先理清 Agent、Skill、MCP 这几个容易混淆的词再详细讲 Claude Skills 的目录结构、SKILL.md 文件规范、安装与启用流程最后用一个自定义 Skill 的完整案例带你把“会用”升级成“会造”。读完你至少能解决三个问题知道该把自己的技能放在哪里、知道一份合格的 Skill 长什么样、知道怎么调试和迭代一个 Skill。1. Agent Skills 到底解决了什么问题要理解 Agent Skills 为什么突然重要得先看没有它的时候大家是怎么让 AI 干活的。最原始的方式是聊天。你告诉 AI“帮我写一个 Python 脚本解析这个日志文件统计错误码出现次数。” AI 可以做到但它只用了通用能力不知道你团队内部对日志格式有什么约定、错误码有几个等级、输出结果要落到什么模板里。于是你每次都要补一堆背景信息有时候补得不够AI 给出的结果就不符合预期。后来大家开始用系统提示词或项目文档来解决这个事。把团队的代码规范、项目结构、常见命令全部写进 prompt让 AI 每次对话前先读一遍。这个方法有效但问题也很明显提示词越长越容易互相覆盖文档一多Agent 不知道该优先使用哪一份换一个项目所有提示词又得重写。Agent Skills 的思路完全不同。它不再是“一次性背景说明”而是把某一类任务的完整执行方法做成一个可复用的技能模块。这个模块有名字、有说明、有步骤、有示例甚至还能带上脚本和模板。Agent 在运行过程中会根据任务描述自动判断“当前这个任务应该加载哪个技能”然后按技能里的标准流程去做。这种变化的本质是从“临时指挥”变成“按标准作业”。打个比方以前你请一个实习生干活每次都要交代背景、流程、注意事项。现在你给实习生一份工作手册手册里写清楚了任务分类、操作规范、常见错误和回退方案他拿到新任务后会先翻手册再动手。Agent Skills 就是这份工作手册。从材料来看Agent Skills 已经不只是程序员的工具。热搜词里出现了“agent skills 赋能人文社科混合研究方法论文写作”这说明它正在被用到学术写作、数据分析、文献整理这类场景。你可以把这些技能理解成“会做文本润色”“会按学术规范整理引用”“会执行混合方法研究步骤”的数字化助手。所以不要以为它只属于 AI 工程师。2. Agent 与 Skill先分清三个高频概念2.1 Agent 是什么Agent也就是智能体核心是“自主决策”。它接收目标自己拆解步骤调用工具根据中间结果调整下一步。你在 Claude Code 这类编程助手工具里看到的那个能读文件、执行命令、修改代码的交互对象就是一个 Agent。Agent 的关键不在于“会聊天”而在于“能行动”。它有一定的记忆能力能看到当前工作区的状态能调用外部命令和 API还能在出错时尝试修复。2.2 Skill 是什么Skill 是给 Agent 准备的技能包。它不负责“思考”负责“提供执行某项任务的专业知识”。一个 Skill 通常包含一份说明文件例如 SKILL.md描述这个技能适合做什么、不适合做什么一组操作步骤告诉 Agent 遇到这类任务时按什么顺序执行示例输入输出帮助 Agent 理解任务完成后的结果形态可选脚本、模板、配置文件让技能不只是“嘴上说说”还能真正执行。Skill 的价值在于“标准化”。同一个 Skill换一个 Agent 也能用同一个团队可以共享一套技能库。这样后面接入的新人或者新项目直接就拥有了前面沉淀的经验。2.3 Skill 与 MCP、Function Calling 的区别这三者是最容易混淆的因为它们都涉及“扩展 Agent 能力”。维度Agent SkillsMCPModel Context ProtocolFunction Calling核心机制提示词指令 资源文件标准化协议连接外部工具模型输出结构化调用参数主要目的让 Agent 掌握领域知识和工作方法让 Agent 调用外部系统和数据源让模型参与程序函数的入参匹配是否写代码不一定很多 Skill 就是 Markdown 文档通常需要写服务端代码通常需要定义函数和参数 schema典型场景按团队规范写代码、写文档、做分析查数据库、访问 GitHub、操作浏览器从自然语言提取参数并调用接口复用方式复制到 Skills 目录即可需要运行 MCP Server需要接入模型 API 并传函数定义用一句话总结Skill 是教 Agent 怎么做MCP 是给 Agent 打通外部世界Function Calling 是让模型和代码之间有一个标准的“传话”协议。很多人的误区是觉得“有了 MCP 就不需要 Skill”。实际上MCP 解决的是“能不能访问某个数据源”的问题Skill 解决的是“拿到数据后按什么专业方法来处理”的问题。比如MCP 可以让 Agent 读取数据库里的用户表但如果要做用户分群分析Agent 仍然需要知道分析框架、指标口径、图表规范这些正是 Skill 可以提供的。3. Claude Skills 的核心机制SKILL.md 与目录规范Claude Skills 是 Anthropic 生态里的一种 Agent Skill 实现。从外部分享材料来看它在 Claude Code 等开发者工具中被大量使用。理解 Claude Skills关键是理解它的目录和文件约定。3.1 技能目录一个 Claude Skill 通常是一个独立的目录目录名就是技能名称。推荐放置位置包括个人全局目录例如用户主目录下的.claude/skills/和项目级目录例如项目内.claude/skills/。个人全局目录适合放跨项目通用的技能项目级目录适合放和当前项目绑定紧密的技能。3.2 SKILL.md 文件每个 Skill 目录内部至少有一个SKILL.md文件。这个文件是技能的核心包含两部分YAML Frontmatter用来声明技能的元信息比如name技能名和description技能描述。Agent 会通过description判断什么时候该使用这个技能。正文用来描述技能的完整操作细节包括适用场景、执行步骤、规则、示例以及如何引用目录内的其他资源。3.3 辅助资源技能目录里还可以放多种辅助资源常见的有scripts/存放可执行脚本比如 Python、Shell、Node.js 脚本templates/存放输出模板比如日志分析报告模板、代码提交信息模板references/存放参考资料可以是 Markdown 文档、CSV、JSON 样本等。需要强调的是不要只在 SKILL.md 里堆文字把脚本放进去会让 Skill 真正可执行。拿日志分析来说如果你在 Skill 里只写“请分析日志”Agent 每次都要现场想实现方式但你如果附带一个已经写好的解析脚本Agent 只需要调用并解释结果效率和稳定性会好得多。3.4 执行时机Claude Skills 的执行通常不是“用户手动点击”的形式而是 Agent 根据当前对话和任务描述自动判断。当任务与某个 Skill 的description匹配时Agent 会加载该 Skill 的内容并按照其中步骤执行。这就是为什么description写得好不好直接影响 Skill 会不会被正确启用。4. 环境准备与前置条件不同平台的 Agent Skills 具体实现有差异但当前讨论最多的就是 Claude 生态。下面以 Claude Code 为主讲一套通用的准备流程。4.1 环境清单在开始之前你至少需要准备一个支持 Claude Skills 的 Agent 运行环境。现在大部分案例用的是 Claude Code 桌面版或 CLI 版一个可用的 Claude 模型访问权限一个准备存放 Skills 的目录可以是项目级目录或用户全局目录如果要运行脚本类 Skill还需要对应的运行时比如 Python 3、Node.js 等。不同工具的版本迭代很快具体安装命令以官方文档为准。这里不写死版本号核心是让你理解这个流程而不是绑定某一个具体发布版本。4.2 创建目录结构以项目级目录为例你可以这样准备mkdir -p .claude/skills/example-skill/scripts mkdir -p .claude/skills/example-skill/templates mkdir -p .claude/skills/example-skill/references对个人全局目录逻辑相同只是路径不同。这里要提醒一个细节Skills 目录命名建议全小写用连字符分隔单词。example-skill这样写清晰易读避免在文件名中出现空格或中文否则某些工具在解析路径时容易出问题。4.3 确认 Agent 能读取目录创建目录后可以先用一个最简单的测试在技能目录里放一个SKILL.md然后在 Agent 对话中明确说出技能名字看看 Agent 是否能够根据description加载它。如果 Agent 一直没有反应优先排查路径是否正确、文件权限是否可读。5. 第一个实操安装一个已有 Skill对于大多数入门用户第一步不用急着造 Skill而是先找一个现成的 Skill跑通“安装—启用—验证”的完整流程体验一下它到底是怎么工作的。5.1 获取 Skill常见的获取方式有两种从网上找社区分享的技能仓库或者从自己的项目里提炼一段使用频率最高的操作流程。社区技能仓库通常提供 Git 地址或压缩包。你可以 clone 或下载后将技能目录复制到.claude/skills/下。示例cd your-project git clone https://example.com/someone/awesome-skill.git .claude/skills/awesome-skill注意这里的地址是示例实际操作时应使用真实可访问的仓库地址。如果仓库里已经包含SKILL.md复制到.claude/skills/后就算安装完成。5.2 验证 Skill 是否被识别安装后建议先进入 Agent 交互界面问一个与该 Skill 相关的问题。比如这个 Skill 是“代码提交信息生成”你可以说“请按照项目里的 commit message 规范为当前的改动生成一条提交信息。”如果 Agent 自动采用了该 Skill且生成的提交信息符合里面定义的格式那么说明安装成功。5.3 找不到 Skill 时怎么办很多时候Agent 没有按预期加载 Skill不是安装位置错了而是description与用户提问之间的匹配度不够。你可能需要更直接地提示 Agent“请使用 awesome-skill 技能完成这个任务。”如果提示后仍不生效就需要检查目录名、SKILL.md 文件路径、Frontmatter 中的name字段是否正确。这三个位置如果不一致很容易出现“文件在但 Agent 找不到”的情况。6. 从“会用”到“会造”自己写一个 Skill跑通安装流程后就可以开始做自定义 Skill 了。这一节用一个完整案例带你从零创建“代码审查助手”技能。选择这个场景是因为大部分开发者都有代码审查需求而且 Skill 可以把审查规范统一起来。6.1 定义要解决的问题在写任何文件之前先想清楚三个问题这个技能要处理什么类型的任务Agent 在什么情况下应该加载它这个技能和通用能力相比额外的价值在哪里以代码审查为例任务类型针对一段代码或一次改动的代码审查加载时机用户要求“review 代码”“检查改动”“分析这段代码有什么问题”额外价值按照团队的代码规范、错误等级、性能关注点来输出审查结果而不是给一份泛泛的代码意见。6.2 创建目录与 SKILL.mdmkdir -p .claude/skills/code-reviewer/scripts然后创建.claude/skills/code-reviewer/SKILL.md文件--- name: code-reviewer description: 使用团队代码规范审查代码改动重点检查正确性、性能、可读性和安全性。适合在用户要求 review 代码、检查改动或分析代码质量时使用。 --- # 代码审查助手 在开始审查之前先阅读项目根目录下的代码规范文档如果存在。 ## 审查步骤 1. 获取目标代码或 diff 内容。 2. 按以下维度逐项检查 - 正确性是否存在逻辑错误、边界条件遗漏、空指针风险。 - 性能是否存在明显的循环内重复计算、不必要的大对象复制、SQL 查询过多。 - 可读性命名是否清晰、函数是否过长、注释是否必要。 - 安全性是否有注入风险、敏感信息硬编码、权限校验缺失。 3. 对照团队规范优先级别输出P0必须修复、P1建议修复、P2可选优化。 4. 每条问题必须给出代码位置、原因、修复建议和修改示例。 ## 输出格式 - 问题列表按 P0/P1/P2 排序。 - 每个问题包含位置、问题描述、修复建议。 - 最后给出总体结论通过 / 需修改后通过 / 不通过。这个文件的核心是“把审查专家的判断规则固化下来”。Agent 看到description后会知道何时启用它看到正文后会按步骤执行看到输出格式后会让结果风格一致。这就是 Skill 和普通提示词的区别普通提示词是即时说一次Skill 是长期沉淀。6.3 用脚本补齐能力有些审查问题Agent 靠阅读代码就能发现但有一些问题需要执行工具才能确认比如编译错误、测试失败、依赖漏洞。这时候可以在 Skill 里附带脚本。创建.claude/skills/code-reviewer/scripts/check_deps.sh#!/usr/bin/env bash # 检查项目依赖中是否存在已知的高风险漏洞 # 使用前提项目支持对应的依赖检查命令 cd $(dirname $0)/.. if [ -f package.json ]; then echo 检查 npm 依赖... npm audit --audit-levelhigh elif [ -f pom.xml ]; then echo 检查 Maven 依赖... mvn org.owasp:dependency-check-maven:check elif [ -f requirements.txt ]; then echo 检查 pip 依赖... pip-audit else echo 未识别到项目的依赖管理文件跳过依赖检查。 fi这里要强调SKILL.md中必须告诉 Agent “在什么情况下运行这个脚本”。比如可以在审查步骤中加入一句“如果项目有依赖管理文件先运行 scripts/check_deps.sh 检查依赖风险。” Agent 不能凭空知道脚本存在你需要把它的调用方式和执行条件写清楚。6.4 增加一个模板示例为了提升输出一致性可以增加一个templates/review_template.md# 代码审查结果 ## 总体结论 - 结论通过 / 需修改后通过 / 不通过 - 审查范围XXX ## 问题列表 ### P0必须修复 | 位置 | 问题 | 修复建议 | | --- | --- | --- | | src/xxx.py:42 | 空值未判断 | 增加 null 检查 | ### P1建议修复 ... ### P2可选优化 ...然后在SKILL.md的输出格式部分写明“推荐参考 templates/review_template.md 组织最终输出。”这样整个 Skill 就从“一段描述”升级成了“有规则、有脚本、有模板”的完整技能包。6.5 自定义技能时要注意什么写完一个 Skill 后别急着说“搞定”。建议想一想我把“什么场景启用”写清楚了吗如果一句话说不清楚Agent 很可能用错时机。我把“步骤”写清楚了吗步骤要可执行不能是“进行深度分析”这种废话要说“先做 A再做 B遇到 C 时执行 D”。我把“输出格式”定下来了吗不定格式每次结果都可能长得不一样。我有没有过度设计一个 Skill 只负责解决一大类任务不要试图把“代码审查自动修 bug生成测试发布版本”全揉进去。7. 运行效果与验证7.1 运行方法在 Agent 对话中输入一个明确的任务例如请使用 code-reviewer 技能审查 src/utils/http.ts 这个文件的代码。如果 Agent 确实加载了 Skill它会先读取 SKILL.md再按你的要求读取目标文件最后按格式输出审查结果。7.2 预期结果一个正常工作的 Skill 应该输出类似这样的结构总体结论P0 问题列表带位置和修复建议P1 问题列表P2 问题列表。如果输出结果只是泛泛的意见没有按 SKILL.md 中的维度组织说明 Skill 可能没有被正确加载或者 SKILL.md 中的指令还不够具体。7.3 验证失败时的排查顺序第一步确认路径。.claude/skills/code-reviewer/SKILL.md是否存在 第二步确认 Frontmatter。name和description字段是否填写正确 第三步确认加载。在对话中直接指定技能名看 Agent 是否会引用 SKILL.md 中的内容。 第四步确认指令颗粒度。如果 Agent 没有按步骤走往往是步骤写得不够具体需要拆得更细。8. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 完全不使用已安装的 Skilldescription 与任务描述不匹配检查 SKILL.md 中的 description 是否准确描述了触发场景重写 description把触发关键词和场景写清楚Skill 目录放在项目里但 Agent 不识别放错目录或权限不足确认目录是否为 .claude/skills 且文件可读移动到正确目录修复文件读写权限Agent 加载了 Skill 但输出不符合预期SKILL.md 的步骤不够具体查看输出与 SKILL.md 要求的差异点细化执行步骤增加输入输出示例Skill 中的脚本没有被执行SKILL.md 未说明脚本调用时机检查脚本是否存在、权限是否可执行在 SKILL.md 中显式描述脚本的调用条件和命令同一项目多个 Skill 互相冲突description 有重叠对比各 Skill 的 description 和应用场景收敛技能边界避免一个任务匹配多个技能Skill 在对话历史中表现不稳定上下文过长导致 Agent 遗忘技能拆分任务或缩短对话把大任务拆成多个小任务在关键节点重新提示技能名称还有一个常见问题是团队协作。如果团队里有多个开发者各自在本地编写不同的 Skill 版本很快会出现“同一个技能在不同人机器上效果完全不同”的情况。建议把.claude/skills目录纳入版本管理和项目代码一起提交保证团队所有人的 Agent 行为一致。9. 编写高质量 Skills 的工程建议9.1 命名与描述是第一生产力name要短、紧、准确例如code-reviewer、log-analyzer、api-doc-generator。description要回答三个问题这个技能用在什么任务什么时候不可以用相对通用能力它特别在哪里差的描述帮助审查代码。好的描述使用团队代码规范审查代码改动重点检查正确性、性能、可读性和安全性。适合在用户要求 review 代码、检查改动或分析代码质量时使用。9.2 指令要有“可执行性”“请仔细分析”“请全面检查”这类话没有意义。Agent 需要的是行为指令先读什么文件、执行什么命令、按什么优先级检查、输出什么格式。一个有效的方式是把步骤写成“条件 动作”如果项目存在 README.md先阅读并提取运行方式如果用户给出了 git diff只审查 diff 范围内的代码如果发现 P0 问题输出必须包含具体修复代码。9.3 善用示例Agent 对示例的依赖程度很高。一个 Skill 中如果包含“示例输入”和“示例输出”它的表现会明显更稳定。示例不一定要长。可以是一个 mini 场景## 示例 用户输入请审查下面这段代码 def get_user(user_id): return db.query(SELECT * FROM user WHERE id user_id) 预期输出 - P0SQL 注入风险位置第 2 行建议使用参数化查询9.4 控制 Skill 的边界好的 Skill 是“窄而深”的。一个 Skill 只负责一个领域不要试图成为万能工具。如果你发现 SKILL.md 越来越长步骤越来越复杂通常说明你需要拆成两个 Skill。9.5 安全与权限意识如果 Skill 中需要执行脚本务必注意脚本只在项目目录内运行不要随意读取用户主目录外的文件不要在 Skill 的脚本中硬编码任何密钥或 Token遇到删除文件、修改权限、向远程仓库推送等危险操作时要求 Agent 必须二次确认不要从不可信的第三方仓库直接下载并运行脚本。从材料看Agent Skills 已经进入学术写作场景这同样会涉及隐私和数据安全问题。比如在人文社科研究中原始访谈数据、问卷数据可能包含敏感信息。在编写这类 Skill 时必须有意识地提示 Agent不要将原始数据写入日志、不要上传到外部服务、最终输出要做匿名化处理。这一点在泛化工具类 Skill 中容易被忽略但在实际生产中非常重要。9.6 与 MCP 配合使用Skill 负责“怎么处理数据”MCP 负责“怎么拿数据”。如果你要给 Agent 增加数据库查询能力同时又要让查询结果按固定格式输出最佳实践是用 MCP Server 暴露数据库查询接口用 Skill 编写查询步骤、结果格式和异常处理规则。二者配合Agent 的完整工作流会变成通过 MCP 连接数据源再按 Skill 的规则处理结果最后输出符合标准格式的报告。9.7 版本管理与迭代节奏Skills 不是一次性写好的而是要持续迭代的。建议把 SKILL.md 当作代码来管理每次修改都要有明确目的用 git 记录变更历史修改后至少跑一个真实任务验证效果如果多个 Skill 相互依赖变更时要做回归验证。10. 总结与后续学习方向Agent Skills 解决了两个关键问题一是把专业经验从“对话里的临时交代”变成了“可复用的标准技能”二是让 Agent 的执行结果从“每次都像开盲盒”变成“有稳定预期的输出”。对开发者来说它的学习曲线并不陡核心是要理解 SKILL.md 的机制然后从你的工作流里提炼高频任务把它们沉淀成一个个技能包。下一步的实践建议先找一两个现成的 Skills 跑通流程感受“加载技能”和“不加载技能”的结果差异从你日常重复性最高的任务开始写第一个自定义 Skill不要一上来就追求大而全在团队项目中把 Skills 目录纳入版本管理统一团队成员的 Agent 行为如果你已经在用 MCP找一个合适的场景让 Skill 和 MCP 配合起来形成完整的数据获取-处理-输出链路。写完一个 Skill 之后你可以问自己三个问题它让我重复劳动减少了吗它的输出质量稳定吗换一个不懂这个领域的人使用它也能达到差不多的效果吗如果三问都通过说明这个 Skill 真正合格了。后续可以继续深入的方向是Skill 与多步骤工作流的结合、Skill 的自动编排、以及团队级 Skill 仓库的维护策略。