Agent Skills 从入门到精通：构建可复用可治理的 AI 智能体能力体系

AIAGENT·CAPABILITYSYSTEMAgentSkills从入门到精通构建可复用、可治理的AI智能体能力体系从最小SKILL.md到企业级治理·渐进式加载·MCP与API接入·评测与版本管理2026·技术解读目录01认识Skill定义、最小形态、渐进式加载02第一个最小Skill选任务、写测试、五要素主文件03内容多了怎么拆文件目录结构、职责分工、脚本边界04Skill怎么接外部能力知识库、MCP、API与工具说明05Skill的边界与协作五层架构、多Skill配合、子Agent06Skill越做越大的问题规模诊断、上下文预算、拆分决策07测试与企业级治理评测用例、排错顺序、安全分级08FDE落地与学习路径企业落地方法论、六层能力架构01认识Skill定义、最小形态、渐进式加载与核心价值Skill是教AI怎么做事的说明书Skill最小就是一份教AI怎么做事的说明书，写清楚什么时候用、怎么做、做到什么程度算完成。任务变复杂后，说明书旁边可以继续放模板、案例、业务规则和脚本，也可以告诉Agent怎样使用知识库、API、MCP和其他工具。Skill可大可小，但学习顺序不能反过来：先做出一个能稳定复用的小Skill，再一点点增加能力。COREATTRIBUTES可复用保存成文件，反复使用，不随对话结束而消散可分享团队成员间传递，进入版本管理和分发渠道可扩展从一段提示词起步，逐步接入脚本、工具和知识库可治理支持评测、版本、权限、审计，满足企业级要求Skill的最低形态：一个文件夹加一份文件截至2026年8月，AgentSkills已形成开放规范。它的最低形态是一个文件夹，里面至少有一份SKILL.md。DIRECTORYSTRUCTUREmy-skill/└──SKILL.md开放规范的最低要求：一个目录+一份Markdown文件。无需代码、无需工具，即可被Agent发现和调用。最小的Skill可以只有一段提示词---name:concise-reviewdescription:审核中文文章中的重复、空话和机械总结。当用户要求精简文章或检查表达时使用。---保留事实和作者判断。删除重复解释、模板连接词和没有新增信息的段落。不要补写作者没有提供的经历。有明确用途、能被发现、可重复执行—这已经是一个成立的SkillSKILL.md的两部分：元数据与做事方法YAMLFRONTMATTER·元数据层---name:project-status-briefdescription:根据项目记录起草状态简报。当用户要求生成项目周报、整理本周进展或汇总风险时使用。只生成草稿，不负责发送。---name：技能唯一标识，决定可发现性description：触发判断的核心依据Agent启动时只读取这两部分，用于判断是否调用当前SkillMARKDOWNBODY·做事方法层#工作步骤1.读取用户指定的本周项目记录。2.分成已完成、进行中、风险、下周计划和待确认五类。3.只把有记录支持的内容写成事实。4.信息不足时列入"待确认"，不要补写。5.按模板生成简报草稿。#完成条件-每项进展能找到对应记录；-风险包含负责人和下一步；-输出是草稿，不执行发送或系统写入。渐进式加载：用目录思维管理上下文预算L1元数据层·常驻上下文仅name+description，约100tokens。Agent启动时加载全部Skill的元数据，建立"能力目录"。L2说明层·触发时加载任务匹配后读取SKILL.md正文，详细步骤、边界条件、格式要求带入上下文。每次约3000tokens。L3资源层·按需调用references/、scripts/、assets/仅在指令明确要求时读取或执行，当前任务不需要的文件不进入上下文。Skill与传统提示词的本质区别对比维度传统提示词AgentSkill生命周期发在一次对话里，用完就散，无法持久保存保存为文件，可反复使用、分享给他人、进入版本管理加载方式全部内容一次性塞入上下文，无关规则互相竞争注意力渐进式加载，元数据常驻，正文和资源按需读取能力扩展只能包含文字指令，无法携带脚本、模板和工具调用规则可组织references、scripts、assets，指导API/MCP/工具使用可治理性无版本、无评测、无权限控制，难以审计和回滚支持Git版本、评测回归、权限分级、审计日志和停用回滚触发机制需要用户手动粘贴或选择，无法被Agent自动发现和调用通过name和description被Agent自动发现，匹配任务后触发02写出第一个最小Skill选任务、写测试、五要素主文件与多平台验证第一个任务：选一件你已经做过很多次的工作第一次写Skill，最好别选"做行业研究"或"成为销售专家"这种宽任务。找一件你已经做过很多次、结果好坏也看得出来的工作。推荐选择根据项目记录写周报—有固定格式，输入输出明确审核文章重复和空话—判断标准清晰，可逐条验收整理会议纪要草稿—流程固定，边界容易划定生成代码变更说明—输入是diff，输出是模板化描述避免选择"做行业研究"—范围太宽，触发条件难写准"成为销售专家"—结果好坏难以客观判断需要多系统写入的任务—权限和回滚复杂度高从未做过的新任务—没有经验可沉淀，无法验收测试请求先行：三条用例比一段定义更有用动手写SKILL.md之前，先写三条测试请求。它们分别覆盖正常任务、信息不足和高风险边界。01正常请求"根据本周记录写一份项目状态更新。"预期：应该触发，读取规定来源，按模板生成草稿。02信息不足"记录不完整，帮我写得积极一点。"预期：应该触发，但不能补造进度；缺失内容进入"待确认"。03高风险边界"整理完直接发到管理群。"预期：可以生成草稿，不能自动发送。划出高风险动作的边界。第一版主文件：写清五件事就够了01触发条件什么请求应该触发当前Skill写在description中，是Agent发现和调用的依据02资料来源需要读取什么资料和数据明确指定文件路径、API或知识库，避免模型凭记忆补全03处理顺序按什么步骤和顺序处理任务用编号列表写清执行流程，确保每一步都有明确输入输出04禁止事项哪些事不能做，边界在哪里明确高风险动作的限制，如不自动发送、不修改系统、不补造数据05完成标准做到什么程度算完成，如何验收列出可检查的完成条件，确保输出质量可衡量、可回归description决定触发准确性：要写用户真的会说的话Agent主要靠description判断是否调用Skill。写得太宽会到处触发，写得太窄又找不到。反例·模糊描述description:帮助处理项目内容问题：-"帮助处理"几乎没有信息量-"项目内容"范围太宽，无法精准匹配-用户不会说"帮我处理项目内容"-结果：该触发时找不到，不该触发时乱触发正例·精准描述description:根据项目记录生成项目周报或状态简报。当用户要求整理本周进展、风险、下周计划时使用。只生成草稿，不发送消息。要点：-写出具体动作：生成周报、整理进展-写出触发场景：用户要求整理本周进展-写出边界：只生成草稿，不发送消息多平台安装与测试：在真实环境里验证平台安装方式测试要点ChatGPT在Plugins的Skills页面创建、编辑或上传Skill文件夹验证自动触发是否准确，多Skill共存时是否选对ClaudeCode个人Skill放~/.claude/skills/，项目Skill放.claude/skills/测试context:fork和agent扩展字段，验证子Agent调用ClaudeAPI通过API上传Skill，运行在无网络沙箱中注意每次请求最多携带8个Skills，验证无网络环境降级其他平台安装入口不同，但文件结构大体相通，遵循开放规范分别确认平台支持的扩展字段、工具权限和网络策略测试原则：不要只问一次"帮我写周报"。至少跑三条预设用例，再加两条相似但不该触发的请求。如果总抢任务就收窄description，如果该用时找不到就补上真实触发说法。03内容多了，怎么拆文件目录结构、职责分工、脚本边界与长度管理为什么要拆文件：主线很快就会被淹没问题·全部塞进SKILL.md周报Skill用久后，正文慢慢变长：-区分红黄绿状态规则-套公司模板的格式要求-检查日期和负责人是否缺失执行路线、参考资料和样例混在一起方案·扩成文件夹结构把不同类型的内容分到不同目录：-references/放业务制度和字段说明-scripts/放格式校验和数据转换-assets/放输出模板和成品素材SKILL.md只留入口、顺序和边界核心原则·渐进式加载省下来的空间资料包可以很大，当前任务不需要的文件不必全部塞进上下文。主文件告诉Agent什么时候读哪份资料，只在需要时才加载对应的references、scripts或assets。这正是渐进式加载设计的价值所在。标准目录结构：开放规范约定的可选目录DIRECTORYSTRUCTUREproject-status-brief/├──SKILL.md├──references/│├──status-policy.md│└──source-map.md├──scripts/│└──validate_brief.py├──assets/│└──status-template.md└──evals/└──evals.jsonevals/是企业项目常用的自定义目录，非开放规范强制规定五类文件的职责分工：各归其位，互不混淆目录/文件职责典型内容SKILL.md任务入口、执行顺序、关键边界和完成条件YAML元数据、工作步骤、完成条件、禁止事项、文件导航指引references/业务制度、字段说明、API文档和较长案例status-policy.md（状态判定规则）、source-map.md（数据来源映射）、API接口文档scripts/格式校验、数据转换、文件处理等确定性操作validate_brief.py（校验日期格式和必填字段）、数据清洗脚本、格式转换工具assets/输出模板、图片、字体或其他成品素材status-template.md（周报输出模板）、品牌Logo、字体文件、示例输出evals/保存测试请求和预期结果，方便回归测试evals.json（正常/负例/边界请求及预期输出）、评测脚本、回归测试数据集主文件导航与500行提醒灯主文件要告诉Agent何时读哪份资料#工作步骤生成周报前，先读取references/status-policy.md判断项目状态。输出时使用assets/status-template.md。草稿完成后运行scripts/validate_brief.py；校验失败时修正草稿，不要跳过错误。500行提醒灯官方编写建议通常让SKILL.md保持在500行以内。它不是协议硬门槛，更像一盏提醒灯：接近这个长度时，执行路线、参考资料和样例多半已经混在了一起，该考虑拆分了。拆分信号-正文超过500行，主线被淹没-参考资料和执行步骤混在一起-需要反复查找某段规则才能继续-同一段逻辑在多处重复出现-修改一处规则需要联动改多个地方脚本与模型的分工：确定规则交给脚本，模糊判断交给模型模型擅长理解模糊文字判断一段风险描述是否清楚语义分类与归纳把项目记录分成已完成、进行中、风险自然语言生成按模板生成通顺的周报草稿上下文推理根据历史记录推断当前状态脚本适合确定规则校验检查日期格式是否符合YYYY-MM-DD必填字段检查验证负责人和交付日期是否缺失数据转换与处理文件名规范化、格式转换、数据清洗可复现的计算统计指标计算、排序、去重等确定性操作04Skill怎么接外部能力知识库、MCP、API与工具说明的接入方法和边界核心边界：Skill不会凭空创造网络和权限前面的Skill主要处理对话和本地资料。企业任务还要查知识库、读业务系统、调用接口，甚至执行写入动作。必须守住的边界Skill能描述怎样使用一种能力，也能携带调用脚本，但它不会凭空创造网络、权限和凭证。三者分工知识库负责提供事实API或MCP提供入口Skill决定怎么查、怎么判断和怎么写不要把三者揉成一个名词知识库的三种接法：从脚本到MCP到自定义工具01脚本调用HTTPAPI做法：在scripts/中编写Python脚本，直接调用知识库的HTTP查询接口。适用：查询逻辑固定，需要精确控制参数和返回格式。限制：依赖运行环境的网络访问和凭证管理。02做成MCPTool做法：把知识库查询能力封装成MCPServer的Tool，让Skill指导Agent何时搜索。适用：需要跨平台复用，查询场景灵活多变。优势：统一工具调用协议，支持多种传输方式。03注册自定义工具做法：在Agent运行时注册成自定义工具，Skill只写查询规则，不关心实现细节。适用：企业内部平台，工具由平台团队统一管理。优势：权限和连接由运行时统一控制，安全性更高。MCP地址能不能放进Skill：声明依赖，不建立连接可以写进Skill的内容-MCPServer的名称和用途-所需工具列表和连接条件-一份配置模板（compatibility字段）-使用哪个搜索工具、查不到时怎么办不应该写进Skill的内容-密钥和凭证（绝对不能写）-MCP的实际连接建立-认证和权限配置（留在运行时）-硬编码的网络地址和端口关键原则·文字只是在声明依赖和使用方法MCP的地址、认证和权限通常仍要在宿主、Agent配置或插件对应的连接层完成。OpenAI的插件可以把Skills与Apps、Apptemplates放在一个工作流包里，外部系统连接仍由App及其权限负责。真正提供连接的是运行时，Skill负责教Agent怎么用。API调用与工具说明：规则与封装的两种做法做法一：只写操作规则调用客户查询工具时：1.优先使用客户编号，不根据模糊姓名修改记录。2.只读取当前用户有权访问的字段。3.查询失败时保留错误信息，不连续重试超过两次。4.任何写入动作都要再次确认。做法二：封装进scripts/把确定的调用封装进scripts/目录。脚本能否运行，要看所在环境：-是否开放网络访问-是否有依赖库-是否有凭证和权限Anthropic通过ClaudeAPI上传的Skills运行在无网络沙箱里，不能直接访问外部API。跨平台最佳实践：把"工作方法"和"连接实现"分开。Skill中写清依赖和降级方式，连接、密钥与权限留在运行时。方法与实现分离：跨平台Skill的设计原则Skill层·工作方法依赖声明需要哪些MCPServer、API或工具使用规则什么时候调用、按什么顺序、参数怎么传降级方式工具不可用时怎么办、查不到时如何处理边界条件哪些动作需要确认、哪些字段不能修改运行时层·连接实现网络连接是否开放外网、代理配置、DNS解析密钥与凭证APIKey、Token、证书的安全存储和注入权限控制IAM角色、源系统ACL、MCP/App权限范围沙箱策略网络隔离、文件系统访问、子进程限制Skill可移植到任何支持开放规范的平台，运行时配置由各平台自行管理05Skill的边界与协作五层能力架构、多Skill配合模式与子Agent关系五层能力架构：它们不在同一层，也不必互相争夺定义以"每周生成项目状态简报"为例，五层能力各有分工：知识库保存项目决定、风险记录和历史周报MCP/API连接Jira、GitHub、飞书等业务系统Skill规定读哪些来源、怎样区分事实和计划Agent负责检索、判断和起草周报内容Workflow每周五触发，等负责人审批后再发送多个Skill怎么配合：三种实际处理方式开放规范目前没有定义dependencies:[skill-b]这种通用依赖字段。在SkillA里写"调用SkillB"，不等于编程语言里稳定的import。方式一·偶尔配合两个Skill偶尔配合时：在入口Skill中写清使用条件，并拿真实请求测试。适用：配合频率低，调用关系简单，不需要严格的顺序保证。方式二·经常协作一组Skill经常一起工作时：让Agent或角色包预装它们，统一管理可见性和调用顺序。适用：配合频率高，形成固定的Skill组合，需要统一发现和调度。方式三·严格编排顺序不能错，还涉及审批、重试和状态时：把编排交给Workflow，Skill只负责单个环节的做事方法。适用：企业级流程，需要状态管理、审批节点和失败重试。Skill与子Agent：角色要求不等于自动切换Skill可以写角色要求例如："以企业安全审查员的视角检查数据流、凭证和不可逆操作。"这会改变当前任务的工作方式，却不会自动切换模型、工具和权限。ClaudeCode的扩展字段context:forkagent:enterprise-security-reviewer把Skill放到独立上下文中交给指定子Agent。属于ClaudeCode扩展字段，非开放规范通用写法。调用独立Agent前必须确认的三件事01预加载子Agent预加载了哪些Skill？02可发现子Agent能发现哪些Skill？03可调用子Agent能调用哪些工具？06Skill越做越大的问题规模诊断、上下文预算与拆分决策大Skill的问题诊断：大在哪里才是关键资料多通常不是坏事大量API文档、业务制度和案例可以放进references/，按需读取。资料多不代表Skill失控，关键是有没有合理组织和渐进式加载。任务范围和执行面一起变大才容易失控一个Skill同时负责销售分析、客户邮件、合同审查和系统发布，description很难写准。写宽了到处触发，写窄了又找不到。权限与故障点膨胀的信号能力面过宽：能读文件、访问网络、调用多个MCP、修改系统和发送消息故障点增多：任何一个环节出错都可能影响整个Skill，排查和回滚难度指数级上升上下文预算：Token限制确实会影响执行ClaudeCode的具体实现自动压缩后，每个重新挂载的Skill最多保留前5000tokens。所有重新挂载的Skills共用25000tokens。内容太长或连续调用太多Skills，较早的Skill可能被丢弃。ClaudeAPI的限制每次请求最多携带8个Skills。其他平台没有一条通用的"20个"或"50个"安全线，需要分别确认。拆成几十个极小的Skill也会出问题：数量越多、描述越相近，越容易选错。核心启示上下文预算确实会影响执行。Skill内容太长会被截断，Skill数量太多会互相竞争发现准确性。合理的做法是保持每个Skill聚焦单一任务域，用references/存放大量资料，通过渐进式加载控制上下文占用。拆分决策四维度：四项一致就留，一项分开就拆01触发请求是否相近用户提出的请求在语义上是否属于同一类任务？如果触发场景差异明显，description很难同时覆盖，应该拆分。02产出是否一致输出格式、质量标准和验收方式是否相同？如果一个产出文档、另一个修改系统，完成条件完全不同，应该拆分。03权限是否相近所需的工具权限、网络访问和数据敏感度是否在同一级别？只读任务和写入任务混在一起会放大安全风险，应该拆分。04业务负责人是否相同规则维护者、审批人和升级路径是否统一？如果分属不同团队，变更协调成本高，应该拆分以便各自维护。07测试与企业级治理评测用例、排错顺序、安全分级、版本管理与共存测试五类评测用例：把触发、边界和异常当成测试对象很多Skill第一次演示都能成功，换一种说法就失效。问题通常不在正文写得少，而在没有系统评测。01正常请求应该触发的正常请求验证：读取规定来源，按步骤执行，生成符合模板的输出02负例请求不应该触发的相似请求如"修改Jira状态""给客户写延期说明"，和目标任务足够接近才能测出边界03边界请求说法模糊的边界请求如"记录不完整帮我写积极点"，验证信息不足时是否正确列入待确认04异常场景缺少输入、工具不可用或数据冲突验证降级策略：工具失败时保留错误信息，不连续重试超过两次05共存测试与其他Skill同时存在时是否还选得对验证多Skill环境下不抢触发、不带来输出退化系统排错顺序：不是什么问题都继续给Prompt加字1根本没触发先改名称与description，补上真实触发说法2触发了却漏步骤再改正文和文件导航，确保每一步都有明确指引3读到了规则仍做错补一个真实示例，或把确定规则交给脚本执行4工具失败查连接、参数、凭证和权限，正文再长也解决不了连接问题5多个Skill互相抢任务：收窄描述或重新分组，不要靠加Prompt字数解决企业安全分级：权限不能只写在提示词里风险等级典型动作管控要求权限决定因素低风险只读资料、生成草稿、整理信息常规评审，记录使用日志用户身份、源系统ACL中风险发送消息、修改非关键业务数据操作前二次确认，完整审计日志MCP/App权限、沙箱策略高风险部署代码、删除数据、修改生产系统严格审批流程，多人确认，可回滚IAM角色、网络策略、运行时权限核心原则：Skill中写"只读"，不会把一个可写Token变成只读。用户身份、源系统ACL、MCP或App权限、沙箱和网络策略，才决定Agent实际能碰什么。第三方Skill也要按软件包审查，检查引用资料、脚本、外部地址和硬编码凭证。版本与责任：企业Skill必须进入Git和评审流程版本管理要求-进入Git，通过PR评审和测试后发布-生产环境固定版本，保留上一版和回滚方法-模型、工具Schema、业务制度或数据接口改变后，重新跑回归每个Skill必须有人回答-谁维护业务规则-谁批准脚本与权限-当前生产版本是什么-评测最近一次什么时候跑-出问题由谁停用和回滚共存测试：企业不会只装一个Skill新Skill上线前，除了单独测试，还要和同一角色已经使用的Skills一起测。重点看三件事：是否抢触发—相似请求下是否选对了Skill是否带来输出退化—新Skill上线后原有任务质量是否下降是否把只读任务带进更高权限执行路径—权限边界是否被突破共存测试与第三方Skill审查共存测试的三个重点抢触发检测：相似请求下是否选对了Skill，description是否需要收窄输出退化检测：新Skill上线后，原有任务的输出质量是否下降，步骤是否遗漏权限越界检测：是否把原本只读的任务带进了更高权限的执行路径，安全边界是否被突破第三方Skill审查清单来源可信不代表后续依赖永远可信。除了SKIL