夜雨聆风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.json
YAML前置内容只需要两个字段：一个name（kebab-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：技能发现
第一项工作是扫描目录以查找技能并将其元数据解析到注册表中。
import os
import yaml
from dataclasses import dataclass, field
from pathlib import Path
@dataclass
class SkillMetadata:
name: str
description: str
path: Path
metadata: dict = field(default_factory=dict)
class SkillRegistry:
def __init__(self, skill_dirs: list[str]):
self.skills: dict[str, SkillMetadata] = {}
for directory in skill_dirs:
self._scan_directory(Path(directory))
def _scan_directory(self, base_path: Path):
"""Scan for */SKILL.md files and parse frontmatter."""
for skill_dir in base_path.iterdir():
skill_file = skill_dir / "SKILL.md"
if skill_dir.is_dir() and skill_file.exists():
meta = self._parse_frontmatter(skill_file)
if meta:
meta.path = skill_dir
self.skills[meta.name] = meta
def _parse_frontmatter(self, path: Path) -> SkillMetadata | None:
"""Extract YAML frontmatter from SKILL.md."""
content = path.read_text()
if not content.startswith("---"):
return None
_, fm, _ = content.split("---", 2)
data = yaml.safe_load(fm)
return SkillMetadata(
name=data["name"],
description=data["description"],
path=path.parent,
metadata=data.get("metadata", {})
)
def get_catalog(self) -> str:
"""Return compact catalog for model context (~100 tokens/skill)."""
lines = []
for skill in self.skills.values():
lines.append(f"- {skill.name}: {skill.description}")
return "\n".join(lines)这给了我们一个注册表，在启动时扫描技能目录并构建一个紧凑的目录。注意get_catalog()只返回名称和描述。这是第1级：刚好足够模型知道什么可用。
步骤2：技能激活
有了注册表，我们可以发现技能。但代理需要一种实际加载技能的方法。让我们添加激活，这意味着将完整的SKILL.md正文读取到上下文中。
class SkillRegistry:
# ... previous methods ...
def activate_skill(self, name: str) -> str:
"""Load full SKILL.md body (Level 2 activation)."""
if name not in self.skills:
raise ValueError(f"Unknown skill: {name}")
skill = self.skills[name]
content = (skill.path / "SKILL.md").read_text()
# Strip frontmatter, return body only
parts = content.split("---", 2)
body = parts[2].strip() if len(parts) >= 3 else content
return body
def load_reference(self, name: str, ref_path: str) -> str:
"""Load a reference file from a skill (Level 3 resources)."""
skill = self.skills[name]
full_path = skill.path / ref_path
# Safety: ensure path doesn't escape skill directory
if not full_path.resolve().is_relative_to(skill.path.resolve()):
raise ValueError("Reference path escapes skill directory")
return full_path.read_text()现在我们的注册表处理所有三个级别。get_catalog()用于发现，activate_skill()用于加载指令，load_reference()用于拉入更深层次的资源。注意load_reference()中的路径遍历检查。捆绑可执行代码的技能会引入类似供应链的攻击面，我们需要从一开始就采取防御措施。
步骤3：将其连接到Pydantic AI
有了发现和激活逻辑，让我们将其连接到一个真正的代理框架。Pydantic AI的工具注册和运行图 introspection 使其成为自然的选择。
from pydantic_ai import Agent
# Initialize registry with your skill directories
registry = SkillRegistry(skill_dirs=["./skills", "./org-skills"])
# Create the agent with the skill catalog in its system prompt
agent = Agent(
model="claude-sonnet-4-5-20250929",
system_prompt=(
"You are a helpful assistant with access to specialized skills.\n\n"
"Available skills:\n"
f"{registry.get_catalog()}\n\n"
"When a user's request matches a skill, use the activate_skill "
"tool to load its instructions before proceeding."
),
)
@agent.tool_plain
def activate_skill(name: str) -> str:
"""Load a skill's full instructions into context.
Use when the user's request matches an available skill."""
return registry.activate_skill(name)
@agent.tool_plain
def load_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."""
return registry.load_reference(skill_name, ref_path)
@agent.tool_plain
def run_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."""
import subprocess
skill = registry.skills[skill_name]
full_path = skill.path / script_path
# Safety checks
if not full_path.resolve().is_relative_to(skill.path.resolve()):
return "Error: script path escapes skill directory"
if not full_path.exists():
return f"Error: script not found at {script_path}"
result = subprocess.run(
f"{full_path} {args}",
shell=True, capture_output=True, text=True, timeout=30
)
return result.stdout or result.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使用，沙箱执行，并像审查第三方代码一样审查第三方技能。
