5个AI代理必备技能（以及为什么你的巨型提示词正在阻碍你）

5个AI代理必备技能以及为什么你的巨型提示词正在阻碍你从单片提示词到模块化技能架构的转变是2026年生产级AI代理的最大突破。以下是如何在任何框架中实现它。你的代理系统提示词长达50,000个token。它包含了你的组织曾经写下的每一项政策、每一个边缘案例、每一个工作流程。无论用户询问退款政策还是天气你都在每一轮对话中为所有这些内容付费。这就是巨型提示词时代。而且它正在崩溃。不是慢慢崩溃也不是优雅地崩溃。它以最伤人的方式崩溃成本飙升、指令遵循能力下降以及模型神秘失败——比如它完全忽略了你在第847行告诉它要做的事情。有一种更好的方法。它被称为技能架构并且已经在Claude、OpenAI Codex、GitHub Copilot、VS Code以及LangChain的Deep Agents等开源框架中趋于一致。最棒的是你不需要任何特定的供应商就能使用它。本文你将学到巨型提示词问题为什么将所有内容塞进一个巨大的系统提示词既昂贵又不可靠而且随着代理能力的增长而变得更糟技能架构一个简单的文件夹结构如何通过渐进式披露用模块化、可组合的能力取代单片提示词跨框架实现在任何代理框架中构建技能运行时的具体模式包括Pydantic AI演练生产就绪验证、监控、安全缓解措施以及使技能成为持久组织资产的治理模型巨型提示词问题比你想象的更严重让我们谈谈当你将所有内容堆进一个系统提示词时实际发生的情况。首先是成本。Token计费与你发送的文本成正比所以你添加的每一条指令、每一个边缘案例、每一项以防万一的政策都会在每一轮对话中被收费。那个50K token的系统提示词不是一次性投资。它是对每次互动的重复征税。但成本甚至不是最可怕的部分。Liu等人的研究记录的中间丢失效应表明语言模型在长上下文中会形成U形注意力曲线。开头和结尾的指令会被遵循。埋在中间的指令它们会被忽略、权重不足或完全被无视。现在再加上工具模式。在Anthropic工程团队的一个真实例子中58个工具在对话开始前就消耗了大约55K token。加上额外的MCP服务器工具定义的开销可能接近100K token。这意味着在单个用户消息到达之前你的整个上下文窗口就被能力描述占用了。这张图表讲述了整个故事。你的代理始终背着一个图书馆几乎没有思考的空间。工程教训很明确上下文中的不必要token并非中立。它们消耗预算、增加延迟并降低指令遵循能力。我们需要不同的架构。技能登场AI代理的渐进式披露解决方案不是编写更好的巨型提示词。而是完全停止编写巨型提示词。代理技能架构用模块化能力库取代了一个巨大的提示词每个能力都打包为一个简单的文件夹。代理只在需要时加载所需的内容。可以想象一下这就像背着图书馆里的每一本书 versus 背着一个卡片目录当话题出现时从书架上取下书籍。在磁盘上一个技能几乎简单得可笑一个包含必需的SKILL.md文件的文件夹该文件带有YAML前置内容和Markdown正文。你可以选择添加scripts/、references/和assets/目录来存放更深入的资源。my-skill/├── SKILL.md # 必需指令 元数据├── scripts/ # 可选可执行辅助工具│ └── validate.py├── references/ # 可选详细文档、示例│ └── api-guide.md└── assets/ # 可选模板、配置└── template.jsonYAML前置内容只需要两个字段一个namekebab-case与目录名匹配和一个description解释技能的功能和使用时机。这是最小可行技能。但真正的魔力不是格式。而是加载策略。三级渐进式披露模型这是使技能工作的核心架构概念。agentskills.io的开放规范和Anthropic的开发者文档都描述了相同的三级模型。第一级元数据。启动时代理只加载每个技能的name和description字段。每个技能大约100个token。即使你的库中有50个技能发现阶段总共也只有5,000个token。相比之下巨型提示词需要50,000 token。第二级指令。当代理确定技能与当前任务相关时它会将SKILL.md的完整正文加载到上下文中。规范建议将其保持在5,000个token以下和500行以下。任何更深层次的内容都被推送到引用文件中。第三级资源。如果工作需要详细的参考材料、模板或可执行辅助工具代理会从references/或assets/加载文件并可以运行scripts/中的代码。这只在指令明确要求时发生。使这一工作的关键约束是规范指示作者将文件引用保持在SKILL.md的一级深度。没有嵌套检索链。只有当模型在需要时能够可靠地找到下一个文件时渐进式披露才有效。技能在实践中获胜的原因架构很优雅但它在生产中实际给你带来了什么四件事。与相关性成比例的token效率。 instead of paying a permanent “organizational knowledge tax” on every request, you pay small discovery costs upfront and load deep instructions only when needed. A 50-skill library costs ~5K tokens for discovery. Loading one activated skill adds ~3–5K more. That’s 10K tokens versus 50K for the equivalent mega-prompt. On every turn.可组合性。技能设计为共存。品牌声音技能、安全审查技能和发布说明技能可以在不同工作流程中组合而无需将它们合并到单个提示词 blob 中。Anthropic的指南明确指出代理可以同时加载多个技能并且作者应该编写技能以相互配合而不是假设排他性。跨框架和团队的可移植性。这是让人们惊讶的部分。代理技能不是Claude独有的功能。带有SKILL.md和YAML前置内容的相同文件夹结构在OpenAI的Codex、GitHub Copilot、VS Code代理和LangChain的Deep Agents框架中都有文档记录和支持。你关心的工件技能文件夹是模型无关的。只有运行时策略发现如何发生、存在什么沙箱将其绑定到特定的 harness。版本控制和治理。基于文件的技能自然兼容Git工作流程。代码审查、标记、审计、回滚。你的组织可以将程序知识视为审查过的工件而不是粘贴到UI中的非正式行为。在任何框架中构建技能运行时这是实际应用的地方。你不需要特定供应商的SDK来实现技能。通用算法有五个步骤并且可以映射到任何代理框架。在本文的其余部分我们将构建一个工作技能运行时。我们将从发现注册表开始添加激活逻辑最后完成Pydantic AI的完整集成模式。最后你将拥有可以适应自己代理堆栈的代码。步骤1技能发现第一项工作是扫描目录以查找技能并将其元数据解析到注册表中。importosimportyamlfromdataclassesimportdataclass,fieldfrompathlibimportPathdataclassclassSkillMetadata:name:strdescription:strpath:Path metadata:dictfield(default_factorydict)classSkillRegistry:def__init__(self,skill_dirs:list[str]):self.skills:dict[str,SkillMetadata]{}fordirectoryinskill_dirs:self._scan_directory(Path(directory))def_scan_directory(self,base_path:Path):Scan for */SKILL.md files and parse frontmatter.forskill_dirinbase_path.iterdir():skill_fileskill_dir/SKILL.mdifskill_dir.is_dir()andskill_file.exists():metaself._parse_frontmatter(skill_file)ifmeta:meta.pathskill_dir self.skills[meta.name]metadef_parse_frontmatter(self,path:Path)-SkillMetadata|None:Extract YAML frontmatter from SKILL.md.contentpath.read_text()ifnotcontent.startswith(---):returnNone_,fm,_content.split(---,2)datayaml.safe_load(fm)returnSkillMetadata(namedata[name],descriptiondata[description],pathpath.parent,metadatadata.get(metadata,{}))defget_catalog(self)-str:Return compact catalog for model context (~100 tokens/skill).lines[]forskillinself.skills.values():lines.append(f-{skill.name}:{skill.description})return\n.join(lines)这给了我们一个注册表在启动时扫描技能目录并构建一个紧凑的目录。注意get_catalog()只返回名称和描述。这是第1级刚好足够模型知道什么可用。步骤2技能激活有了注册表我们可以发现技能。但代理需要一种实际加载技能的方法。让我们添加激活这意味着将完整的SKILL.md正文读取到上下文中。classSkillRegistry:# ... previous methods ...defactivate_skill(self,name:str)-str:Load full SKILL.md body (Level 2 activation).ifnamenotinself.skills:raiseValueError(fUnknown skill:{name})skillself.skills[name]content(skill.path/SKILL.md).read_text()# Strip frontmatter, return body onlypartscontent.split(---,2)bodyparts[2].strip()iflen(parts)3elsecontentreturnbodydefload_reference(self,name:str,ref_path:str)-str:Load a reference file from a skill (Level 3 resources).skillself.skills[name]full_pathskill.path/ref_path# Safety: ensure path doesnt escape skill directoryifnotfull_path.resolve().is_relative_to(skill.path.resolve()):raiseValueError(Reference path escapes skill directory)returnfull_path.read_text()现在我们的注册表处理所有三个级别。get_catalog()用于发现activate_skill()用于加载指令load_reference()用于拉入更深层次的资源。注意load_reference()中的路径遍历检查。捆绑可执行代码的技能会引入类似供应链的攻击面我们需要从一开始就采取防御措施。步骤3将其连接到Pydantic AI有了发现和激活逻辑让我们将其连接到一个真正的代理框架。Pydantic AI的工具注册和运行图 introspection 使其成为自然的选择。frompydantic_aiimportAgent# Initialize registry with your skill directoriesregistrySkillRegistry(skill_dirs[./skills,./org-skills])# Create the agent with the skill catalog in its system promptagentAgent(modelclaude-sonnet-4-5-20250929,system_prompt(You are a helpful assistant with access to specialized skills.\n\nAvailable skills:\nf{registry.get_catalog()}\n\nWhen a users request matches a skill, use the activate_skill tool to load its instructions before proceeding.),)agent.tool_plaindefactivate_skill(name:str)-str:Load a skills full instructions into context. Use when the users request matches an available skill.returnregistry.activate_skill(name)agent.tool_plaindefload_skill_reference(skill_name:str,ref_path:str)-str:Load a reference file from an activated skill. Only use when skill instructions direct you to a specific file.returnregistry.load_reference(skill_name,ref_path)agent.tool_plaindefrun_skill_script(skill_name:str,script_path:str,args:str)-str:Execute a script bundled with a skill. Only use when skill instructions explicitly require it.importsubprocess skillregistry.skills[skill_name]full_pathskill.path/script_path# Safety checksifnotfull_path.resolve().is_relative_to(skill.path.resolve()):returnError: script path escapes skill directoryifnotfull_path.exists():returnfError: script not found at{script_path}resultsubprocess.run(f{full_path}{args},shellTrue,capture_outputTrue,textTrue,timeout30)returnresult.stdoutorresult.stderr这就是整个技能运行时。代理在其系统提示中以轻量级目录开始在需要时使用activate_skill加载完整指令并可以拉入引用或运行脚本以完成更深层次的任务。每一部分都建立在之前的基础上。跨框架故事这里是关键见解同样的模式在任何地方都有效。发现-激活-执行流程并不绑定到Pydantic AI。LangChain的Deep Agents描述了完全相同的机制启动时解析前置内容匹配时加载完整技能。OpenAI的Codex Skills文档使用相同的SKILL.md结构和相同的渐进式披露行为。将agent.tool_plain装饰器替换为LangChain的tool或OpenAI的函数调用模式或自定义框架中的普通函数。技能文件夹不会改变。使技能生产就绪技能很强大。它们也是影响代理行为的代码这意味着它们需要与任何生产依赖项相同的严谨性。验证要测量什么Anthropic的官方指南推荐三个具体的成功标准这些标准适用于任何框架激活准确性。技能是否在90%的相关查询上触发使用10-20个代表性提示进行测试并测量自动激活与手动调用。工作流程效率。技能是否在合理数量的工具调用中完成任务比较使用和不使用技能的运行跟踪质量和token消耗。可靠性。每个工作流程零或接近零失败的工具调用。跟踪错误、重试和回退率。对于框架特定的可观察性Pydantic AI的评估系统支持基于OpenTelemetry跟踪的基于跨度的评估。这意味着你可以评估内部代理行为工具调用、激活模式、执行流程而不仅仅是最终输出。这正是技能所需要的那种评估。安全技能是依赖项像对待依赖项一样对待它们这是很多团队措手不及的地方。因为技能可以在scripts/中捆绑可执行代码并且可以指示代理加载额外资源它们引入了供应链攻击面。研究支持这一点。一项大规模实证研究发现超过26%的分析技能包含至少一个漏洞模式包括提示注入、数据泄露和权限提升。捆绑可执行脚本的技能包含漏洞的可能性是仅指令技能的2.12倍。具体缓解措施使用规范的实验性allowed-tools前置内容来限制技能可以调用的工具。当技能只需要文件读取时不要授予广泛的执行权限。对于关键验证步骤首选确定性脚本。Anthropic的指南说得很好代码是确定性的而语言解释不是。如果一个步骤必须可靠使其成为脚本。保持执行沙箱化。在技能执行环境中没有网络访问没有运行时包安装。像对待第三方依赖项一样对待第三方技能。这意味着来源跟踪、代码审查、签名和从开发到 staging 到生产的分阶段推出。面向未来的论点关于供应商锁定的底线比你可能预期的更乐观。技能文件夹格式目录 SKILL.md 可选资源在agentskills.io上明确标准化。它不是隐藏在专有UI后面。多个主要平台已经收敛于这个确切的工件边界。Claude、OpenAI Codex、GitHub Copilot、VS Code和LangChain的Deep Agents都记录了相同的结构。所以这是一个可辩护的论点投资于技能文件夹作为组织代理知识的持久单元。根据需要交换运行时。模型和代理harness会改变但你的技能库是一个版本化的资产你可以移植、审计和持续改进。巨型提示词时代给了我们一个开始的方法。技能时代给了我们一个扩展的方法。关键要点巨型提示词的上限是真实的。Token成本与提示词大小线性相关中间丢失效应意味着你精心编写的指令被忽略。渐进式披露解决了这两个问题。技能只是文件夹。一个带有YAML前置内容和Markdown正文的SKILL.md。可选的脚本和引用。就是这样。简单就是特性。模式是框架无关的。发现、激活、执行。五个步骤。在Pydantic AI、LangChain、OpenAI或自定义堆栈中工作。技能文件夹是可移植的工件。将技能视为生产依赖项。验证激活准确性监控token使用沙箱执行并像审查第三方代码一样审查第三方技能。