AI Agent技能开发实战：SKILL.md编写与三级加载系统解析

如果你写过 AI Agent 技能但发现它从不触发，问题几乎从来不在你的指令本身，而在那个看似简单的描述字段。这是大多数人经过一小时挫败后才明白的道理：你写了一个 SKILL.md，放在正确文件夹，让 Agent 使用它，结果什么都没发生。你重写指令，还是没反应。问题从来不在技能内部的内容，而在顶部那两行 Agent 用来决定是否激活它的元数据。

在 AI Agent 时代，Skills 已经超越了传统 Markdown 文档的范畴，成为一种新型的工作组件。它们不是简单的插件或脚本，而是封装了完整工作流程的智能指令集。今天我们就来彻底解析 SKILL.md 模式，看看如何编写真正能工作的 AI Agent Skills。

1. 核心能力速览

2. 什么是真正的 Agent Skill？

Agent Skill 不是插件，也不是连接到 API 的脚本。把它想象成给新团队成员写的入职指南。你不用在每次对话中重新解释工作流程和偏好，而是打包一次，Agent 会在你的请求匹配时自动拾取。

核心上，一个技能就是一个文件夹：

your-skill-name/
├── SKILL.md          # 必需：指令 + 元数据
├── scripts/          # 可选：Agent 运行的可执行代码
├── references/       # 可选：仅在需要时加载的文档
└── assets/           # 可选：模板、图片、字体

唯一必需的文件是 SKILL.md。其他都是可选的，但随着技能复杂性增加而变得重要。

特别有用的是，SKILL.md 格式现在是一个开放标准，由 Anthropic 在 2025 12 月在 agentskills.io 发布。它可以在 Claude Code、OpenAI Codex 和 OpenClaw 之间工作。虽然格式是标准化的，但每个平台在发现和工具方面的实现略有不同。可以理解为共享语言，而不是完全相同的行为。

3. Skills 的存放位置与作用域

在写任何东西之前，你需要知道放在哪里。每个平台从特定位置加载技能，位置定义了作用域。

Claude Code:

• ~/.claude/skills/ - 个人级，在所有项目中可用
• .claude/skills/ - 项目级，通过 git 与团队共享

OpenAI Codex:

• ~/.codex/skills/ - 用户级，适用于你工作的任何仓库
• .codex/skills/ - 仓库级，提交到 git

OpenClaw:

• ~/.openclaw/skills/ - 全局，对所有配置的 Agent 可用
• 每个 Agent 工作空间 - 仅限特定 Agent

当两个技能同名时，优先级更高的位置获胜。项目级技能会覆盖具有相同名称的个人技能。这让团队可以定义默认值，个人可以为自己设置覆盖。

4. 三级加载系统的工作原理

这是大多数人跳过的部分，它解释了技能不触发或消耗太多上下文的几乎所有问题。

技能使用渐进式披露：一个三级加载系统，内容仅在需要时被拉入上下文。

Level 1: 元数据（始终加载，每个技能约 100 tokens） 启动时，Agent 只从每个已安装技能的 YAML 前端元数据读取名称和描述。其他什么都不读。这个紧凑的列表进入系统提示，因此 Agent 知道存在什么技能以及何时使用它们。实际含义：你可以安装许多技能而不会受到上下文惩罚。

Level 2: 指令（触发时加载，低于 5k tokens） 当 Agent 决定某个技能相关时，它使用 bash 调用将 SKILL.md 的完整正文读入上下文。只有此时，你的实际指令才会被加载。

Level 3: 引用文件和脚本（按需加载，实际上无限） 如果技能正文引用其他文件，Agent 只在需要时读取它们。脚本可以在不被读入上下文的情况下执行。这就是技能可扩展的原因：无论你捆绑多少内容，空闲时的 token 成本都是零。

这是在实际请求中的序列样子：

1. 会话开始 --> Agent 加载：每个技能的 name + description（每个约 100 tokens）
2. 用户问："你能为这个项目写个 README 吗？" --> Agent 读取：readme-writer/SKILL.md 完整正文（Level 2）