--- title: "万字长文｜Skills 从入门到精通" author: Miles Ma date: 2026-08-19 section: Agent 系统 url: https://immilesma.com/blog/skills-complete-guide/ x: https://x.com/miles_mazy/status/2090076961322479886 description: "从一份最小的 SKILL.md 开始，把重复工作的触发条件、步骤和完成标准写清楚。任务变复杂后，再拆参考资料、接脚本与外部工具，用真实请求评测，并补上企业使用需要的权限、版本和责任。" --- # 万字长文｜Skills 从入门到精通 > 从一份最小的 SKILL.md 开始，把重复工作的触发条件、步骤和完成标准写清楚。任务变复杂后，再拆参考资料、接脚本与外部工具，用真实请求评测，并补上企业使用需要的权限、版本和责任。 Skill 这件事没有看上去那么玄。它最小就是一份教 AI 怎么做事的说明书，写清楚什么时候用、怎么做、做到什么程度算完成。 等任务变复杂以后，这份说明书旁边可以继续放模板、案例、业务规则和脚本，也可以告诉 Agent 怎样使用知识库、API、MCP 和其他工具。Skill 确实可大可小，但学习顺序不能反过来：先做出一个能稳定复用的小 Skill，再一点点增加能力。 下面就从第一个最小 Skill 开始，一路做到文件拆分、工具接入、评测和企业治理。MCP、知识库、Agent 这些问题也会讲，但都放回实际使用的场景里。 ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/01-image-06.jpg) ## Skill 到底是什么 截至 2026 年 8 月，Agent Skills 已经形成开放规范。它的最低形态是一个文件夹，里面至少有一份 SKILL.md： ``` my-skill/ └── SKILL.md ``` SKILL.md 分成两部分。顶部的 YAML frontmatter 写名称和描述，正文写做事方法： ``` --- name: project-status-brief description: 根据项目记录起草状态简报。当用户要求生成项目周报、整理本周进展或汇总风险时使用。只生成草稿，不负责发送。 --- # 项目状态简报 读取指定项目记录，区分已确认进展、风险和待确认事项。 按公司模板生成草稿，所有关键结论保留依据。 ``` Agent 启动时通常只需要知道 Skill 的名称和描述。等任务匹配以后，它再读取正文；正文又可以继续指向其他资料。这种按需读取的方式叫渐进式加载。 它解决的是一个很实际的问题。提示词发在一次对话里，用完就散了；Skill 把一类任务的做法保存成文件，可以反复使用、分享给别人，也可以进入版本管理。 最小的 Skill 完全可以只有一段提示词： ``` --- name: concise-review description: 审核中文文章中的重复、空话和机械总结。当用户要求精简文章或检查表达时使用。 --- 保留事实和作者判断。 删除重复解释、模板连接词和没有新增信息的段落。 不要补写作者没有提供的经历。 ``` 这已经是一个成立的 Skill。它有明确用途，能被发现，也能重复执行。先别急着加代码。 ## 先写出第一个最小 Skill 第一次写 Skill，最好别选“做行业研究”或“成为销售专家”这种宽任务。找一件你已经做过很多次、结果好坏也看得出来的工作。 这里用“根据项目记录写周报”做示范。动手前，先写三条测试请求： ``` 1. “根据本周记录写一份项目状态更新。” 应该触发，读取规定来源，生成草稿。 2. “记录不完整，帮我写得积极一点。” 应该触发，但不能补造进度；缺失内容进入待确认。 3. “整理完直接发到管理群。” 可以生成草稿，不能自动发送。 ``` 这三条比一段宏大的定义有用。第一条确定正常任务，第二条处理信息不足，第三条划出高风险动作的边界。 然后建立目录： ``` mkdir -p project-status-brief touch project-status-brief/SKILL.md ``` 第一版主文件写清五件事就够了： 1. 什么请求应该触发； 2. 需要读取什么资料； 3. 按什么顺序处理； 4. 哪些事不能做； 5. 怎样才算完成。 可以直接写成下面这样： ``` --- name: project-status-brief description: 根据项目记录生成项目周报或状态简报。当用户要求整理本周进展、风险、下周计划时使用。只生成草稿，不发送消息，不修改项目系统。 --- # 工作步骤 1. 读取用户指定的本周项目记录。 2. 分成已完成、进行中、风险、下周计划和待确认五类。 3. 只把有记录支持的内容写成事实。 4. 信息不足时列入“待确认”，不要补写。 5. 按模板生成简报草稿。 # 完成条件 - 每项进展能找到对应记录； - 风险包含负责人和下一步，没有信息时明确留空； - 输出是草稿，不执行发送或系统写入。 ``` description 要认真写。Agent 主要靠它判断是否调用 Skill。“帮助处理项目内容”几乎没有用，“生成项目周报、整理本周进展、汇总风险”才像用户真的会提出的任务。 写完就去真实环境里用。ChatGPT 当前可以在 Plugins 的 Skills 页面创建、编辑或上传 Skill；Claude Code 可以把个人 Skill 放到 ~/.claude/skills//SKILL.md，项目 Skill 放到 .claude/skills//SKILL.md。其他支持 Agent Skills 的产品，安装入口不同，但文件结构大体相通。 测试时不要只问一次“帮我写周报”。至少跑刚才那三条，再加两条相似但不该触发的请求，例如“帮我修改 Jira 状态”和“给客户写一封延期说明”。如果它总抢任务，先收窄 description；如果该用时找不到，就补上真实触发说法。 做到这里，最小版本就算跑通了：能被调用，能按步骤工作，结果也能验收。 ## 内容多了，怎么拆文件 小 Skill 用久以后，正文会慢慢变长。周报可能要区分红黄绿状态，要套公司模板，还要检查日期和负责人是否缺失。继续把所有内容塞进 SKILL.md，主线很快就会被淹没。 这时再扩成一个文件夹： ``` project-status-brief/ ├── SKILL.md ├── references/ │ ├── status-policy.md │ └── source-map.md ├── scripts/ │ └── validate_brief.py ├── assets/ │ └── status-template.md └── evals/ └── evals.json ``` 开放规范明确约定了 scripts/、references/ 和 assets/ 这几类可选目录，也允许放其他文件。上面的 evals/ 是企业项目常用的自定义目录，不是开放规范强制规定的标准目录。 这些文件各有用处： - SKILL.md 留任务入口、执行顺序、关键边界和完成条件； - references/ 放业务制度、字段说明、API 文档和较长案例； - assets/ 放输出模板、图片、字体或其他成品素材； - scripts/ 放格式校验、数据转换、文件处理这类确定性操作； - evals/ 保存测试请求和预期结果，方便回归。 主文件要告诉 Agent 什么时候读哪份资料。例如： ``` 生成周报前，先读取 `references/status-policy.md` 判断项目状态。 输出时使用 `assets/status-template.md`。 草稿完成后运行 `scripts/validate_brief.py`；校验失败时修正草稿，不要跳过错误。 ``` 资料包可以很大，当前任务不需要的文件不必全部塞进上下文。这正是渐进式加载省下来的空间。 官方编写建议通常让 SKILL.md 保持在 500 行以内。它不是协议硬门槛，更像一盏提醒灯：接近这个长度时，执行路线、参考资料和样例多半已经混在了一起。 ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/02-image-07.jpg) 脚本不用急着加。模型擅长理解模糊文字，脚本适合处理确定规则。判断一段风险描述是否清楚，可以交给模型；检查日期格式、文件名和必填字段，用脚本更稳。 ## Skill 怎么接外部能力 前面的 Skill 主要处理对话和本地资料。企业任务还要查知识库、读业务系统、调用接口，甚至执行写入动作，API、MCP 和 Tool 从这里开始派上用场。 这里有一条必须守住的边界：Skill 能描述怎样使用一种能力，也能携带调用脚本，但它不会凭空创造网络、权限和凭证。 ### 知识库怎样接进来 假设公司已经把知识库封装成查询 API，可以有三种接法： - 由 Skill 中的脚本调用 HTTP API； - 把查询能力做成 MCP Tool，让 Skill 指导 Agent 何时搜索； - 在 Agent 运行时注册成自定义工具，Skill 只写查询规则。 对周报 Skill 来说，规则可能是：先查本周项目记录，再查最近一次决策；涉及范围、预算和交付日期时，只使用当前版本的正式文件；查不到就放进“待确认”，不能拿模型记忆补齐。 知识库负责提供事实，API 或 MCP 提供入口，Skill 决定怎么查、怎么判断和怎么写。不要把三者揉成一个名词。 ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/03-image-05.jpg) ### MCP 地址能不能放进 Skill 可以写 MCP Server 的名称、用途、所需工具和连接条件，也可以附一份配置模板。例如： ``` --- name: customer-research description: 查询企业知识库并整理客户研究。当用户要求检索客户案例、产品资料或历史项目时使用。 compatibility: Requires the company-knowledge MCP server and read access --- ``` 正文再说明使用哪个搜索工具、查不到时怎么办。这些文字只是在声明依赖和使用方法，并没有建立连接。MCP 的地址、认证和权限通常仍要在宿主、Agent 配置或插件对应的连接层完成，密钥也不应该写进 Skill。 OpenAI 当前的插件可以把 Skills 与 Apps、App templates 放在一个工作流包里，外部系统连接仍由 App 及其权限负责。其他 Agent 平台也可能在 Agent 配置里同时声明 Skills、Tools 和 MCP Servers。真正提供连接的是运行时，Skill 负责教 Agent 怎么用。 ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/04-image-01.jpg) ### API 调用和工具说明能不能放 可以。一种做法是只写操作规则： ``` 调用客户查询工具时： 1. 优先使用客户编号，不根据模糊姓名修改记录。 2. 只读取当前用户有权访问的字段。 3. 查询失败时保留错误信息，不连续重试超过两次。 4. 任何写入动作都要再次确认。 ``` 另一种做法是把确定的调用封装进 scripts/。脚本能否运行，要看所在环境是否开放网络、是否有依赖和凭证。Anthropic 当前通过 Claude API 上传的 Skills 运行在无网络沙箱里，不能直接访问外部 API；本地 Agent 或企业自建运行时是否能联网，则由自己的环境决定。 跨平台时，最好把“工作方法”和“连接实现”分开。Skill 中写清依赖和降级方式，连接、密钥与权限留在运行时。 ## 到这里，再谈 Skill 的边界 走到进阶阶段，再回头看几个名词就容易多了。它们不在同一层，也没有必要互相争夺定义。 ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/05-image-03.jpg) 拿“每周生成项目状态简报”来说： - 知识库保存项目决定、风险记录和历史周报； - MCP 或 API 连接 Jira、GitHub、飞书等系统； - Skill 规定读哪些来源、怎样区分事实和计划、缺资料时怎么处理； - Agent 负责检索、判断和起草； - Workflow 每周五触发任务，等负责人审批后再发送。 个人临时整理一次，一个小 Skill 足够。给企业几百个项目稳定生成周报，交付物就一定不只是一份 SKILL.md。 我吃过一次很具体的亏。公司讨论 Skills、MCP、Agent 和 Tools 的边界，想先把分级定义得毫无争议。一个月过去，定义还在改，竞品已经拿出了能用的产品。 边界当然要懂，但不必一开始就犯“大厂病”。先选一个真实任务做出来，再从运行结果看哪部分是方法、哪部分是连接、哪部分必须用确定性流程。很多争论到这一步自然就结束了。 ## 多个 Skill 和 Agent 怎么配合 一个 Skill 跑通以后，常见的下一个问题是：能不能让 Skill A 调 Skill B？ 一个任务组合多个 Skills 已经可行。ChatGPT 可以在适合时自动使用一个或多个 Skills；Claude Code 也能让用户或模型调用当前可见的 Skills。不过，开放规范目前没有定义 dependencies: [skill-b] 这种通用依赖字段。 所以在 Skill A 里写一句“调用 Skill B”，不等于编程语言里稳定的 import。它是否执行，取决于宿主有没有开放 Skill 调用、B 是否可见，以及当前 Agent 的配置。 实际项目里常用三种处理方式： - 两个 Skill 偶尔配合，在入口 Skill 中写清使用条件，并拿真实请求测试； - 一组 Skill 经常一起工作，让 Agent 或角色包预装它们； - 顺序不能错，还涉及审批、重试和状态，把编排交给 Workflow。 ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/06-image-10.jpg) Skill 也能写角色要求，例如“以企业安全审查员的视角检查数据流、凭证和不可逆操作”。这会改变当前任务的工作方式，却不会自动切换模型、工具和权限。 调用一个独立 Agent 要看平台是否支持。Claude Code 目前提供 context: fork 和 agent 扩展，可以把 Skill 放到独立上下文中交给指定子 Agent。它们属于 Claude Code 的扩展字段，不是开放规范的通用写法： ``` --- name: security-review description: 对当前方案进行安全审查 context: fork agent: enterprise-security-reviewer --- ``` 换到其他平台，这两个字段可能被忽略，也可能无法上传。这里要分别确认三件事：子 Agent 预加载了哪些 Skill，能发现哪些 Skill，又能调用哪些工具。 ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/07-image-08.jpg) ## Skill 越做越大，会出什么问题 Skill 确实可大可小，但别顺手做成万能包。判断一个大 Skill 是否有问题，要看它究竟大在哪里。 资料多通常不是坏事。大量 API 文档、业务制度和案例可以放进 references/，按需读取。任务范围和执行面一起变大，才容易失控。 一个 Skill 同时负责销售分析、客户邮件、合同审查和系统发布，description 很难写准。写宽了会到处触发，写窄了又找不到。它如果还能读文件、访问网络、调用多个 MCP、修改系统和发送消息，权限与故障点也会一起膨胀。 ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/08-image-09.jpg) ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/09-image-02.jpg) 当前 Claude Code 在自动压缩后，每个重新挂载的 Skill 最多保留前 5000 tokens，所有重新挂载的 Skills 共用 25000 tokens。内容太长或连续调用太多 Skills，较早的 Skill 可能被丢弃。这是 Claude Code 的具体实现，不能当成所有平台的通用限制，但它说明上下文预算确实会影响执行。 反过来，拆成几十个极小的 Skill 也会出问题。每个名称和描述都要参与发现，数量越多、描述越相近，越容易选错。Anthropic 当前的 Claude API 每次请求最多携带 8 个 Skills；其他平台没有一条通用的“20 个”或“50 个”安全线。 我通常看四件事：触发请求是否相近，产出是否一致，权限是否相近，业务负责人是否相同。四项大体一致，可以留在一个 Skill 里；其中一项已经明显分开，就值得拆。 ## 怎么把一个 Skill 测稳 很多 Skill 第一次演示都能成功，换一种说法就失效。这里的问题通常不在正文写得少，而在没有把触发、边界和异常当成测试对象。 给每个 Skill 准备一小组评测，先覆盖五类情况： 1. 应该触发的正常请求； 2. 不应该触发的相似请求； 3. 说法模糊的边界请求； 4. 缺少输入、工具不可用或数据冲突； 5. 与其他 Skill 同时存在时是否还选得对。 一个周报 Skill 的负例，不要只写“今天天气怎么样”。“修改 Jira 状态”“给客户发送进度”“写项目复盘”更有价值，因为它们和目标任务足够接近，能测出边界是否真的写清楚。 排错也按顺序来： - 根本没触发，先改名称与 description； - 触发了却漏步骤，再改正文和文件导航； - 读到了规则仍做错，补一个真实示例或把确定规则交给脚本； - 工具失败，查连接、参数、凭证和权限； - 多个 Skill 互相抢任务，收窄描述或重新分组。 这套顺序能避免一个常见误区：不管什么问题都继续给 Prompt 加字。触发问题、连接问题和权限问题，正文再长也解决不了。 ## 企业级 Skill 多出来哪些工作 个人 Skill 主要看自己用起来顺不顺。企业级 Skill 要能被别人使用、被审查、被升级，也要在出错时找得到责任和退路。 ### 先做安全分级 只读资料、生成草稿的 Skill，风险相对低。会发送消息、修改业务系统、部署代码和删除数据的 Skill，需要更严格的审批、确认与审计。 权限不能只写在提示词里。Skill 中写“只读”，不会把一个可写 Token 变成只读。用户身份、源系统 ACL、MCP 或 App 权限、沙箱和网络策略，才决定 Agent 实际能碰什么。 第三方 Skill 也要按软件包审查。除了 SKILL.md，还要看引用资料、脚本、外部地址、网络调用、子进程、硬编码凭证和数据外传路径。来源可信不代表后续依赖永远可信。 ### 再做版本和责任 企业 Skill 最好进入 Git，通过 PR 评审和测试后发布。生产环境固定版本，保留上一版和回滚方法。模型、工具 Schema、业务制度或数据接口改变后，重新跑回归。 每个 Skill 至少要有人回答下面几个问题： - 谁维护业务规则； - 谁批准脚本与权限； - 当前生产版本是什么； - 评测最近一次什么时候跑； - 出问题由谁停用和回滚。 ### 还要测共存 企业不会只装一个 Skill。新 Skill 上线前，除了单独测试，还要和同一角色已经使用的 Skills 一起测。重点看它是否抢触发、是否带来输出退化、是否把原本只读的任务带进更高权限的执行路径。 ![文章配图](https://immilesma.com/blog/skills-complete-guide/media/10-image-04.jpg) ## FDE 怎样把 Skill 落进企业 FDE 要先跟着一线人员把一项真实工作走完，再决定 SKILL.md 怎么写。哪些判断靠经验，哪些事实来自系统，哪些步骤只是历史习惯，都要在现场看清楚。 然后把东西放回合适的位置： - 事实和正式材料进入知识库； - 系统能力接成 API、MCP、App 或 Tool； - 专家的判断方法写进 Skill； - 角色、模型和工具组合进 Agent； - 定时、状态、审批、重试和补偿交给 Workflow； - 身份与权限留在 IAM、运行时和源系统。 第一版只覆盖最常见、价值也最容易判断的几个用例。拿真实任务试跑，记录它漏读了什么、误用了什么、人工改了多少。证明有用以后，再做团队分发、版本、监控和交接。 一个 Skill 上传成功，不代表企业已经落地。业务人员要知道怎样改规则，技术人员要能跑评测，平台团队要控制权限，出了问题还得有人能停用和回退。 做到这一步，Skill 才不再是一份更长的 Prompt。它成了企业做事方法的一种可维护载体。 ## 从小 Skill 开始 学习 Skills，不需要先把 MCP、Agent、Tool 和 Workflow 的边界研究到毫无争议。 从一项重复工作开始，写出最小 SKILL.md，拿真实请求测试。规则多了再拆 references，确定操作交给 scripts，需要外部数据时再接 API 或 MCP。等它开始影响多人、系统和数据，再补权限、评测、版本和治理。 Skill 的大小没有标准答案。它可以只放一套提示词，也可以组织知识库、工具和 Agent。最后还是看一件事：它能不能让 AI 更稳定地把一项具体工作做好。 ## 我是谁 我是 Miles，一名从大厂转型 FDE 的 AI 算法专家，做过模型优化部署，也做过企业内部沟通与培训。 现在我主要研究怎样把 Agent、Skills、MCP、Workflow 和知识库从演示带进企业的真实流程。后面我会继续把这些东西拆成能直接动手的教程，也会把实际落地中那些靠一段 Prompt 解决不了的问题讲清楚。 --- [在 X 查看原文](https://x.com/miles_mazy/status/2090076961322479886)