如果说 MCP 解决了 Agent「用什么工具」那么 Agent Skills 解决的是「如何专业地做一件事」。它被业界称为「AI 领域的 Dockerfile」——用一个带 SKILL.md 的文件夹把散落的 Prompt、脚本、领域规范打包成可复用、可版本控制、可测试的数字资产。这篇文章带你彻底搞懂它的底层机制并手把手开发你的第一个 Skill。过去两年大家给大模型「注入能力」的手段主要有两种系统提示词System Prompt把规则一股脑塞进去能力一多就臃肿、Token 暴涨而且信息越多越难检索工具调用 / MCP让 Agent 能「动手」但工具是零散的Agent 并不知道「何时该用、按什么顺序用、做到什么程度算完成」。Agent Skills 要填补的正是这两者之间的空白——「专业流程」的沉淀与复用。一、Agent Skills 是什么Agent Skills 是 Anthropic 在 2025 年 10 月随 Claude 发布的能力封装机制同年 12 月被升格为开放标准agentskills.io并开源。截至目前已被33 个 Agent 产品采纳包括 Claude Code、OpenAI Codex、GitHub Copilot、Cursor、VS Code、Gemini CLI 等。它的核心形态非常简单一个包含SKILL.md的文件夹。组成作用指令说明Prompt定义做什么、怎么做、何时停配套脚本Scripts确定性、可重复执行的代码参考资源References领域知识、规范、schema一句话概括Skill 不是 Prompt而是围绕任务、工具、流程和输出边界的「结构化行为设计」。它不直接让模型更聪明而是让专业经验可以被结构化地沉淀、复用和测试。二、核心机制渐进式披露Progressive Disclosure这是 Agent Skills 最精妙的设计。Anthropic 工程团队的原话是“Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable.”它借鉴 UI/UX 领域「按需展开信息」的思想把 Skill 分成三层加载层级加载内容加载时机Token 成本L1 目录层所有 Skill 的namedescription会话启动时每个约 50–100 tokensL2 指令层完整SKILL.md正文Skill 被激活时建议 5000 tokensL3 资源层scripts/、references/、assets/指令引用时按需视文件大小关键价值在于即使安装 20 个 Skill启动时的初始上下文也只有 1000–2000 tokens相比单体提示词减少约 90%。这里有一个最常见的误区必须点破很多人以为 Agent 选 Skill 时会细读全文。实际上L1 层的入口信号只有description它像一个目录/索引帮助模型快速判断「要不要深入读」。由此引出两条黄金法则description的目标是「提高被选中的概率」而不是塞入执行细节Skill 让信息更聚焦、更容易被检索而非让模型更聪明。三、解剖一个 Skill目录结构与 SKILL.md 规范3.1 目录结构一个 Skill 的最小形态只需要一个文件skill-name/ ├── SKILL.md # 必需YAML 元数据 Markdown 指令 ├── scripts/ # 可选可执行脚本Python/Bash/JS ├── references/ # 可选按需加载的参考文档 └── assets/ # 可选模板、图标、字体等静态资源工程规范要点主文件必须命名为SKILL.md区分大小写文件夹名必须用kebab-case如my-skill-name。这套约定已被 Claude Code.claude/skills/、CodeBuddy.codebuddy/skills/等环境统一采纳。3.2 SKILL.md 的两部分与 Frontmatter 字段SKILL.md由YAML Frontmatter元数据Markdown 正文指令组成。最小示例只需name和description---name:pdf-processingdescription:Extract PDF text,fill forms,merge files. Use when handling PDFs.---完整字段一览字段是否必填约束说明name✅ 必需唯一标识见下方命名规则description✅ 必需1–1024 字符说明功能 触发时机license❌ 可选许可证名称或文件引用compatibility❌ 可选最多 500 字符环境/依赖要求metadata❌ 可选任意键值对自定义扩展allowed-tools❌ 可选预授权工具列表实验性3.3name字段的严格命名规则长度 1–64 字符仅允许小写字母、数字、连字符-不能以连字符开头或结尾不允许连续连字符--必须与所在文件夹名一致。✅ name: pdf-processing ✅ name: code-review ❌ name: PDF-Processing # 不允许大写 ❌ name: -pdf # 不能以连字符开头 ❌ name: pdf--processing # 不允许连续连字符3.4description整个 Skill 的「命门」官方只给了硬约束1–1024 字符、非空、含关键词但真正的门道在于它是模型做「是否激活」决策的唯一依据。一个高质量的description要同时回答三件事——做什么、什么情境下用、有无硬限制。推荐模板Verb object. Use when specific user intent. critical constraint.✅ 优秀示例Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.❌ 糟糕示例Helps with PDFs.再强调一个来自实战的关键发现description只应描述「触发条件」绝不要总结 Skill 的工作流程。测试发现当 description 总结了工作流时Agent 可能直接按 description 执行而跳过阅读完整的 Skill 正文。四、五种设计模式来自 Google ADK 团队规范只告诉我们「Skill 长什么样」没告诉我们「内部逻辑该怎么设计」。Google ADK 团队研究了生态中大量实现总结出 5 种反复出现的设计模式模式核心逻辑适用场景1. Tool WrapperSKILL.md 不存完整知识只告诉 Agent 去哪加载references/框架/库编码规范、团队风格指南2. Generator模板 风格指南强制输出一致性缺信息主动问标准化文档生成、脚手架3. Reviewer「查什么」和「怎么查」分离清单独立维护自动 PR 审查、安全扫描4. InversionAgent 先「采访」用户收集需求再动手需求不明时的需求澄清5. Pipeline严格顺序步骤 检查点不跳步从代码生成文档等复杂流程模式选择指南不确定时从Tool Wrapper开始——它最通用也最符合「渐进式披露」的本意。五、实战从零开发一个 Git 工作流 Skill下面以Git 工作流 Skill为例完整走一遍开发流程这套流程同样适用于 Claude Code、Codex、CodeBuddy 等环境。第 1 步明确场景与边界先问清四个问题触发条件用户说什么话该激活、工作流步骤标准操作是什么、依赖项需要哪些知识/脚本/工具、验收标准怎样算成功。第 2 步初始化目录结构git-workflow/ ├── SKILL.md ├── references/ │ └── commit-spec.md └── scripts/ └── check_branch.sh第 3 步编写 SKILL.md--- name: git-workflow description: 当需要进行 Git 操作创建分支、提交代码、同步仓库、解决冲突、准备 PR时使用。 涉及关键词git、commit、branch、push、pull request、rebase、merge。 --- ## 1. 分支命名规范 - feat/ 新功能 - fix/ 修复 Bug - docs/ 文档变更 - refactor/ 代码重构 - chore/ 构建或辅助工具变动 ## 2. 提交规范 必须遵循 Conventional Commits 格式。提交前参考 references/commit-spec.md 获取完整 type 说明。 基本格式type(scope): description ## 3. 核心工作流 1. 同步基准开发前从 main 拉取并 rebase 2. 变更原子化每个 Commit 保持单一目的 3. 前置校验提交前运行 lint 或 test 4. 清理历史推送前用 rebase -i 合并 WIP 提交 ## 4. 冲突处理 1. 停止操作并列出冲突文件 2. 分析冲突原因 3. 向用户建议保留方案确认后再继续 ## 5. 成功验收标准 - [ ] 分支名符合前缀规范 - [ ] 所有提交信息通过 commitlint 校验 - [ ] 本地 Lint 和单元测试全部通过第 4 步编写参考文档与脚本references/commit-spec.md按需加载保持聚焦# 详细提交规范 | Type | 说明 | | :--- | :--- | | feat | 新功能 | | fix | 修补 Bug | | docs | 文档 | | refactor | 重构 | | test | 增加测试 | | chore | 构建或辅助工具变动 | ## 描述要求 - 使用祈使句首字母小写结尾不加句号scripts/check_branch.sh确定性任务交给脚本Token 更省、更可靠#!/usr/bin/env bash# 校验当前分支名是否符合前缀规范branch$(gitrev-parse --abbrev-ref HEAD)if[[!$branch~^(feat|fix|docs|refactor|chore)/]];thenecho错误分支名 $branch 不符合规范前缀exit1fiecho分支名校验通过$branch第 5 步测试与迭代最关键的一步Skill 功能容易做出来难的是长期维护时「能不能被正确选中」以及「选中后能不能稳定执行」。建议引入两类评估Selection accuracy选中准确率准备 10–30 条用户意图标注「应选哪个 Skill / 不应选任何 Skill」对比不同版本description的 precision/recallExecution correctness执行正确率选中后是否照规则执行且结果正确。一个实用的迭代闭环写 description SKILL.md ↓ 跑 selection eval触发测试 ↓ 对照误选案例调整用词与约束条款 ↓ 每次新增 Skill 或大改 description 都回归测试更重型的方案是 Anthropic 官方的 skill-creator它把「做机器学习」的方法搬到 Skill 开发训练/测试集分割、A/B 对比、Grader/Comparator/Analyzer 三个子 Agent 协作评估。适合复杂 Skill简单 Skill 直接手写更快。第 6 步打包发布用规范校验工具验证后打包成 zip即可分享给他人安装skills-ref validate ./git-workflow六、最佳实践与常见反模式四个最佳实践简洁是关键默认 Agent 已经很聪明只添加它不知道的信息——上下文窗口是公共资源设置合适的自由度操作脆弱、一致性关键的场景用低自由度强约束多种方法都有效的场景给高自由度工作流 反馈循环复杂任务用可勾选的 checklist「运行验证器 → 修复 → 重复直到通过」的模式能显著提升输出质量用绝对语气写约束Agent 是「扫描式」读指令的强语气才能形成稳定行为约束。✅Never .../You may only ...❌Please avoid .../You should not ...。四个常见反模式反模式表现危害百科全书型内容像 Wiki未拆分为小文件上下文膨胀全都要型适用于所有任务的「技能」那是规则不是 Skill暗号型描述太抽象Agent 从来不加载它脆弱型硬编码细节过多仓库一变就失效七、生态与展望Agent Skills 生态正在快速成型已形成一条清晰的知识链规范标准agentskills.io→构建方法论Anthropic skill-creator、Superpowers→设计模式Google ADK→市场社区skills.sh、skillsmp.com以及收录 1000 Skills 的 awesome-agent-skills。从「提示词工程」到「面向工作流编排」Agent Skills 标志着大模型应用开发的一次范式跃迁。它让个人和团队第一次能把「专业经验」以可版本控制、可复用、可测试的方式沉淀下来。八、Skill 再强也离不开便宜的 Token有一点必须提前说清楚开发、调试 Agent Skill 的过程本身就是一场 Token 消耗战。Claude Code、Codex、CodeBuddy 这些 Coding Agent 每执行一步都要调用模型——读文件、写代码、跑脚本、A/B 对比测试一次 skill-creator 的评测可能就要几十上百次模型调用Token 消耗比普通聊天高出一个量级。怎么把成本打下来通过向量云 ark.tokenrize.cn 获取字节跳动火山方舟官方 API 和 Key给你的 Coding Agent 接入模型天然享受三样东西官方真实 Keyark-****-****-****-****-****-88888格式请求直连ark.cn-beijing.volces.com火山方舟官方接口不经中转延迟、稳定性、计费标准与官方完全一致ark.tokenrize.cn低折扣 Token 价格注册即享按量计费、即用即扣、不设账期低门槛起步注册、充值10 元、创建 Key三步搞定几分钟就能跑起来。一把 Key 还能覆盖 Agent 的不同强度需求深度推理用DeepSeek V4 Prodeepseek-v4-pro-ga-260813日常快速任务用DeepSeek V4 Flashdeepseek-v4-flash-ga-260731。用好 Skill 沉淀专业能力再用低成本官方 API 把每次调用压到最低才是 Agent 玩家的省钱正道。写在最后回顾全文有三个认知值得带走Skill 不是 Prompt而是围绕任务、工具、流程和输出边界的结构化行为设计渐进式加载是灵魂它解决了 Agent 系统的上下文膨胀问题——装 20 个 Skill启动也只占一两千 Tokendescription比正文更重要写好触发条件是决定你的 Skill「是资产还是废品」的关键。现在你可以动手了从一个每天重复的小流程开始建一个文件夹写一个SKILL.md。当 Agent 第一次在合适的时机自动加载你的 Skill 并漂亮地完成任务时你会真正理解「给 AI 装技能」这件事的分量。