Agent技能渐进式披露：从新手到专家的完整教程指南

在AI智能体开发中，技能模块化与复用是提升效率的核心。Skills标准的提出，为此提供了系统化的解决框架。OpenClaw项目正是这一框架的典范实践，其成功很大程度上源于Skills标准对几个关键挑战的应对：

1. 能力固化：智能体习得的新功能，如何转化为可持久化、可迭代的资产？
2. 生态互通：开发者构建的专用能力，怎样以标准化接口被其他项目直接调用？
3. 资源优化：如何规避将所有技能描述一次性载入上下文导致的令牌浪费？Skills标准通过索引常驻、内容动态加载的机制解决了这一问题。

Skills生态的成熟，为OpenClaw这类项目的快速发展铺平了道路。分析其代码实现后，你会发现其核心架构非常清晰，构建一套类似的系统，技术门槛并不高。

一、什么是Skills

首先明确定义：Skills是一套面向智能体的、模块化且可插拔的能力组件。

一个符合规范的Skill通常包含以下要素：

• 元数据：技能标识、功能描述、适用场景等基础信息。
• 核心指令：定义技能主要逻辑与调用入口的提示词部分。
• 依赖模块：被核心指令调用的子提示词片段，或需要执行的工具脚本。

在标准工作流中，仅轻量的技能元数据会预加载至LLM上下文。当LLM判定当前任务需要调用特定Skill时，才会触发加载其核心指令，并根据任务推进情况，按需加载其引用的子模块。

这种“按需加载”的策略，有效解决了传统冗长提示词带来的两个主要问题：一是避免突破模型上下文长度限制，二是减少无关信息对模型核心任务判断的干扰。

关于引用文件与工具的规范

Agent Skills规范推荐采用明晰的目录结构。通常，一个Skill目录下包含必需的SKILL.md文件（内嵌YAML元数据和Markdown指令），以及可选的scripts/（存放可执行脚本）、references/（补充文档）、assets/（资源文件）等子目录。

规范建议使用相对路径进行引用，并保持一级引用深度，避免复杂嵌套。这能确保SKILL.md文件本身保持精简（建议控制在500行以内），将详细实现剥离到引用文件中，实现真正的按需加载。

当然，这套规范并非强制约束。你可以根据项目实际情况，采用更扁平的结构，例如将所有引用文件直接置于Skill根目录。关键在于保证引用路径的准确性和加载逻辑的一致性。

那么，如何从零实现一套Skills系统？概念可能有些抽象，但OpenClaw的源码给出了答案——其核心机制设计得相当简洁。

二、思路梳理与设计

实现一套支持渐进式加载的Skills系统，可以分解为四个逻辑阶段：

1. Skills读取模块：扫描技能目录，结构化解析每个Skill的元数据与核心指令入口。
2. 元数据注入：将Skill元数据（主要是名称和描述）嵌入系统提示词，让LLM知晓可用技能及其用途。
3. 核心内容加载：当LLM决策使用某个Skill时，通过工具调用，定位并将其核心指令内容注入当前上下文。
4. 引用内容按需加载：依据核心指令内的引用标记，逐步加载更深层的提示词片段或执行相应工具。

下面，我们按这四个阶段，拆解其中的关键实现细节。

三、Skills读取模块

读取模块的核心逻辑非常直观：

1. 遍历预设技能目录，识别所有*/SKILL.md文件作为Skill入口点。
2. 读取SKILL.md文件内容。
3. 解析文件头部的YAML格式元数据（通常由---分隔符包裹），将Skill的索引信息结构化存储，供后续查询。

首先，定义一个基础的Skill索引类：

class SkillIndex:
    """Skill 索引"""
    def __init__(self, name: str, description: str, location: str):
        self.name = name
        self.description = description
        self.location = location

解析YAML元数据的函数同样直接：

def _parse_frontmatter(self, content: str) -> Dict[str, str]:
    """解析 YAML frontmatter"""
    pattern = r'^---\n(.*?)\n---'
    match = re.match(pattern, content, re.DOTALL)
    if not match:
        return {}
    try:
        return yaml.safe_load(match.group(1)) or {}
    except:
        return {}

至此，我们获得了所有可用Skill的索引列表。下一步是让LLM能够感知到它们。

四、能识别Skills的系统提示词

这是整个系统的“决策引擎”。我们需要构建一段系统提示词，将Skill索引有机整合，并明确指导LLM的行为逻辑。

首先，将Skill索引数组转换为结构化的文本格式，例如XML：

# 构建 XML 格式的索引
skills_xml = "\n"
for idx in skill_indexes:
    skills_xml += f"""{idx.name}{idx.description}"""
skills_xml += ""

选择XML、JSON或YAML格式均可，核心要求是结构清晰、易于解析。接下来，组装核心系统指令：

# 构建指令 - 让 LLM 知道何时需要读取 skill
instructions = """
你是一个智能 AI 助手。你的职责是帮助用户完成各种任务。当你需要处理特定领域的问题时，可以使用可用的 skills。一般流程：
1. 理解用户请求
2. 判断是否需要使用 skill
3. 如需要，使用工具读取 skill 完整内容
4. 按照 skill 指令执行
如果用户请求不涉及任何已知的 skill 领域，直接回答即可。

## Skills 使用指南 (渐进式披露)
你可以通过 skills 来处理特定领域的任务。

### 可用 Skills
{skills_xml}

### 使用规则
1. **识别时机**: 当用户请求涉及特定技能领域时（如文件操作、Git操作、代码编写等），应考虑使用 skill
2. **按需读取**:
   - 如果某个 skill 明显适用于用户请求 → 使用 `lookup_skill` 工具读取完整内容
   - 如果多个 skill 都可能适用 → 选择最相关的一个读取
   - 如果没有 skill 明显适用 → 不需要读取任何 skill
3. **执行指令**: 读取 skill 后，按照其中的命令和说明执行任务
4. **引用处理**: skill 文档中可能引用其他文档（使用 路径 格式，如 ../docs/xxx.md），如需读取可使用 `read_reference` 工具

### 注意事项
- 不要在初始阶段就读取所有 skill
- 只在确定需要某个 skill 后才读取
- 读取后严格按照 skill 的指令执行
""".format(skills_xml=skills_xml)

这段提示词的设计关键在于“引导”而非“命令”。它清晰列出了可用技能，规定了使用时机和流程（特别是通过特定工具实现按需加载），并强调了“渐进式披露”原则。剩余的工作则交由LLM的理解与推理能力完成。

五、让LLM读取Skill内容

注意到系统提示词中提及的lookup_skill工具了吗？这正是连接“决策”与“执行”的桥梁。

这里需要用到智能体开发的基础设施：通过定义工具（Function），并借助LangChain等框架的反射机制将其schema暴露给LLM，LLM即可在适当时机发起调用。我们需要实现这样一个工具函数：

@tool
def lookup_skill(skill_name: str) -> str:
    """查找并读取指定 skill 的完整内容。"""
    skill_md = find_location_from_indexes(str)
    # 解析 frontmatter 获取 name
    content = skill_md.read_text(encoding='utf-8')
    pattern = r'^---\n.*?\n---\n?'
    return re.sub(pattern, '', content, count=1, flags=re.DOTALL).strip()

此函数的作用是根据技能名称定位对应的SKILL.md文件，读取内容，并剥离顶部的YAML元数据部分，将纯指令内容返回给LLM。随后，LLM的上下文中便包含了执行该技能所需的具体步骤。

六、加载引用

“渐进式披露”不仅适用于Skill主体，也适用于Skill内部的引用。一个Skill的核心指令中，可能会通过类似../docs/example.md的路径引用其他文件。

因此，我们还需要另一个工具read_reference，供LLM在遇到引用时调用，以加载更深层的内容：

@tool
def read_reference(skill_name: str, reference: str) -> str:
    """读取 skill 内部引用的文档。"""
    base_dir = find_location(skill_name)
    target_path = (base_dir / reference).resolve()
    return target_path.read_text(encoding='utf-8')

至此，一个支持动态加载、按需披露的Skills系统核心骨架便搭建完毕。

七、demo与验证

将上述模块组合起来，你就能完整验证LLM如何智能判断任务需求，动态加载并执行特定Skill的全流程。关键在于理解各组件如何通过提示词与工具调用协同工作。

八、小结

深入分析OpenClaw源码，最大的启示在于：许多听起来精巧复杂的设计，其实现内核往往直接而清晰。Skills系统通过“元数据索引+动态加载”的核心设计，配合精心编排的系统提示词，便实现了能力的模块化与弹性扩展。

这正是研究优秀开源项目的价值——它不仅提供现成的解决方案，更拆解了复杂问题，揭示了背后简洁有力的工程逻辑。基于此，我们完全可以构建出更贴合自身业务需求的、强大的智能体能力体系。

来源：互联网