Harness工程之道：Skill原理与最佳实践指南

Agent Skills 正逐步演变为提升 AI Agent 智能水平与运行效率的核心组件。本文将从基础理念切入，深入工程实践层面，系统拆解 Skill 的运行机制与最佳实现路径。

一、Skill 的起源与设计思想

1.1 从 Prompt 工程迈向 Skill 工程

当前主流大语言模型普遍存在一个共性缺陷：每次对话都处于“失忆”状态，必须重新构建完整的上下文信息。为应对这一挑战，Prompt 工程应运而生。以 CLAUDE.md 为代表的方案，将团队的技术选型、编码规范、架构约束等内容固化为 Agent 可解析的配置文档。每当新会话启动，Agent 自动加载这些信息，迅速进入高效协作状态，无需重复交代背景信息。

然而，这种方式也逐渐暴露出新的问题。传统做法将所有领域知识统一塞入提示词，随着项目复杂度提升，Prompt 愈发臃肿。上下文窗口被占满后，模型注意力被分散，真正关键的信息反而被“淹没”。更严重的是，这些知识与具体项目深度绑定，切换场景便需要重写，几乎不具备复用价值。

Agent Skill 正是为破解上述难题而生。它将领域知识与工作流封装为可移植、可版本控制的文件夹，用以“教导”Agent 处理特定任务或工作流程，实现按需加载。我们可以将 Skills 类比为新员工入职手册——正如 Anthropic 官方博客所述，Skills 是提供给 AI Agent 的“入职指引”，将领域知识打包为可发现、模块化的能力单元。

Agent Skills 的官方定义如下：

"Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows."

1.2 核心理念：渐进式信息披露

Skill 体系最核心的设计哲学是渐进式信息披露（Progressive Disclosure）。简而言之：仅在需要时才加载对应知识，而非一次性全量加载。

Skill 的渐进式信息披露主要分为三个阶段：

• 发现（Discovery）阶段：会话启动时仅加载每个 Skill 的 name 和 description，这部分以常驻形式注入 Agent 上下文。
• 激活（Activation）阶段：当任务与 description 匹配时，读取完整的 SKILL.md，加载其中的路由表和全局规则，但暂不加载子模块。
• 执行（Execution）阶段：依据路由表加载对应模块文件，按需读取参考文档，仅加载当前任务真正需要的知识内容。

该模型在实际应用中带来了显著的性能提升。绝大多数请求仅需动用部分资源。渐进式信息披露以最小的上下文成本换取了最大的知识覆盖范围，确保上下文窗口留给真正重要的信息——这正是“按需投放知识”所蕴含的核心效率优势。同时，它也保障了决策的精准性以及 Skill 的可扩展能力。

1.3 System Prompt 与 Skill 的本质区别

简单记忆方式：System Prompt 是“这个项目的规矩”，Skill 是“一种可复用的专业能力”。一个项目可以同时配备 System Prompt 与多个 Skill，二者协同运作——System Prompt 中的规则对所有 Skill 生效，而 Skill 内部的规则仅在激活时叠加应用。

二、Skill 的构成结构

2.1 目录结构规范

一个 Skill 的核心就是一个包含 SKILL.md 的文件夹：

my-skill/             # 必需：skill名称，短横线分隔
├── SKILL.md          # 必需：主文件，包括元信息 + 指令，文件名需全大写
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
├── assets/           # 可选：模板、资源
└── ...               # 任意额外文件

这一格式已被 Claude Code、Cursor、GitHub Copilot、Gemini CLI 等 40 余款主流 Agent 产品采纳，成为事实上的开放标准。一个设计合理的 Skill 目录结构，是渐进式信息披露能否有效落地的基础。核心思路是：主文件承担路由职责，模块文件负责具体执行。

2.2 SKILL.md 文件结构

SKILL.md 是每个 Skill 的唯一入口，也是唯一的“触发器”。其结构分为两部分：frontmatter 元信息与正文指令。

frontmatter 是 YAML 格式的元信息区块，最核心的两个字段是 name 和 description：

---
name: trade-ab-skill
description: 为用户提供 AB 实验的创建与修改能力，支持实验创建、调流量、
  加桶删桶、实验下线等操作。当用户提到创建实验、修改实验、调流量、加桶删桶、
  实验下线等场景时触发。
---

下面以 Claude Code 为例的完整 frontmatter 字段：

正文部分可以直接参考 Skill 例子的正文内容，此处不再展开详述。

三、触发机制

Skills 的触发机制是整个体系中最为关键的环节，它直接决定了 Skill 能否在恰当的时机被激活。这一点甚至比 Skills 内容本身的质量更为重要。

3.1 自动触发与手动触发

Skills 同时支持自动触发（语义匹配）和手动触发两种模式。

自动触发依赖于 description 字段。当用户意图与 Skill 描述产生语义匹配时，Agent 会自动判断“此任务我有现成的专业流程可以处理”，进而主动加载对应的 Skill。整个过程对用户无感知，就像一位资深员工听到需求后自动翻出了相应的标准作业流程。

手动触发则通过用户输入斜杠命令（如 /skill-name）进行显式调用。这种方式适用于用户明确知道自己需要调用哪个 Skill 的场景，相当于直接指示“用这套流程来执行”。

两种机制互为补充：自动触发降低了使用门槛，让 Skill 对新用户实现“隐形”生效；手动触发则为资深用户提供了精确的控制能力。

3.2 description 书写规范

语义匹配机制完全依赖于 description 字段，它是 Skill 能否被正确触发的核心要素。Claude Code 推荐的书写公式为：功能定义 + 触发场景 + 核心能力。

写好 description 需要遵循以下几项原则：

• 同时回答 WHAT 和 WHEN。不能仅说“处理文档”这样模糊，要清晰说明这个 Skill 负责什么、在何种场景下应当被调用。
• 枚举具体的触发词汇。Agent 进行语义匹配时，关键词越具体命中率越高。在 description 中显式列出用户可能使用的关键词——不仅包括专业术语，还应涵盖口语化表达。“创建实验”、“新建”、“做个实验”、“建个AB”——这些都需要写进去。
• 采用第三人称表述。description 会被注入系统提示词，因此要写成客观描述而非对话语气。应写“Generates API documentation from source code”，而不是“I can help you generate docs”或“You can use this to...”。
• 划定排除边界（可选）。在描述中明确标注不适用的场景，以降低误触发的概率。

四、作用域与优先级

Skill 的作用域决定了它在哪些场景下可用。主流 Agent 产品通常支持两级作用域：

当多个 Skill 同时存在时，可能会出现触发冲突——两个 Skill 的 description 都匹配用户输入。优先级规则通常遵循以下层级：企业策略 > 个人配置 > 项目配置 > Plugin 内置。

五、Skill 最佳实践

5.1 Skill 正文即路由器：编排而非堆砌

核心理念：

• SKILL.md 的正文应当扮演“路由器”角色而非“知识仓库”，其职责是将任务分发到正确的模块，而非容纳所有相关信息和业务细节。
• SKILL.md 应控制在 500 行以内，500 行文本约等于 2000～3000 token，这是单个 Skill 激活后较为合理的上下文开销。
• 在 SKILL.md 中引用辅助文件时，应建立一份明确的契约：触发时机 + 资源位置 + 预期产出，不能仅给出路径。

最佳实践：SKILL.md 只保留路由表和全局规则，业务细节下沉到模块文件。

# ✅ 最佳实践：SKILL.md 是路由器
## 意图路由表
| 场景示例          | 路由模块   | 加载文件                      |
|-----------------|-----------|------------------------------|
| "创建实验"       | creator   | modules/creator/creator.md   |
| "实验XX调流量"     | modifier  | modules/modifier/modifier.md |
## 全局安全红线
1. 禁止调用万能工具
2. 禁止编造数据
3. 写模块限定接口

5.2 知识分层策略：何时拆分与如何组织

什么时候该拆文件？一条经验法则：当一个文件超过 300 行，或某个步骤的规则超过 100 行时，就是拆分的信号。文件过长不仅浪费 token，还会导致 Agent 的注意力在大段文本中迷失方向。

如何组织知识分层？根据使用频率对知识进行分层组织。越频繁使用的知识，离入口越近；越偶尔查阅的知识，越往深处放置。这样 Agent 每次只加载当前步骤真正需要的内容，不会把上下文窗口塞满无关信息。

实践中可以用一棵简单的决策树来判断：

实践：trade-ab-skill 的分层

trade-ab-skill/
├── SKILL.md            ← 意图路由表、全局安全红线（每次激活必读）
├── modules/creator/creator.md           ← 创建流程 Step 编排、scenarioId 对照表（进入创建模块才读）
├── modules/creator/collect-phase.md     ← 参数填充的 11 项执行清单（仅 Step 2 才读）
├── modules/creator/validate-phase.md    ← 校验规则（仅 Step 3 才读）
├── modules/creator/tools.md             ← MCP 工具接口列表（调接口时按需查阅）
└── modules/creator/safety.md            ← 安全约束详细规则（validate 阶段按需加载）

5.3 安全实践 - 工具的权限设计与隔离

这是工程级 Skill 最关键的安全实践之一。当 Skill 涉及多个模块、调用多个 MCP 接口时，必须实施模块级的工具隔离——每个模块只能调用其白名单中的接口，遵循权限最小化原则。

设计原则：

1. 白名单制：每个模块的 tools.md 明确列出可用接口，白名单外一律禁止。
2. 危险接口显式禁用：万能工具（如直接 HTTP 调用）全局禁止。
3. 工具隔离：不同模块使用不同的接口集合，防止误调用。

最佳实践：Claude Code 的 allowedTools 配置，控制 Skill 执行时可调用的工具，支持 Bash 的前缀匹配控制。trade-ab-skill 中的隔离实践：实验创建接口仅在 creator 白名单中；modifier 只能用实验修改接口；审批/发布接口在所有模块中均禁止调用；modifier 模块明确标注易混淆接口的禁止规则。

5.4 脚本增强：扩展 Skill 能力边界

核心理念：将确定性计算逻辑封装为脚本，由 Agent 调用执行而非自行推导。脚本是 Skill 突破 LLM 能力边界的利器。

什么时候需要写成脚本？如果某件事让 LLM 处理有概率出错，但让脚本做能 100% 确定性完成，那就应当封装成脚本。如果发现自己在 SKILL.md 中编写公式让 Agent 运行计算，该逻辑也应该被迁移到脚本中。

脚本的设计遵循四个原则：

1. 自愈性——脚本内部处理所有异常，始终正常退出，绝不阻断 Skill 主流程。
2. 结构化输出——统一输出 JSON，方便 Agent 解析和流转。
3. 幂等性——多次执行结果一致，预检脚本只追加缺失项，不覆盖已有配置。
4. 安全边界——只操作指定文件，不触碰其他系统资源。

最佳实践：trade-ab-skill 内置了两个关键脚本：MCP 预检脚本负责在 Skill 启动前自动检测 MCP 依赖是否就绪；日志采集脚本负责采集实验操作日志。Agent 只需要调用脚本、读取返回的 JSON，不用自己去“猜测”环境状态。

5.5 参数传递与动态注入

Skill 不仅是静态指令，更支持运行时参数传递和上下文预注入。在执行过程中，需要在多个阶段之间传递参数。良好的参数传递机制应满足：

• 显式：参数来源和去向清晰可追溯。
• 可校验：每个阶段有门卡检查参数完整性。
• 防丢失：关键参数在快照中持久化。

最佳实践：trade-ab-skill 的参数传递模型采用快照（Snapshot）机制作为跨阶段参数传递的载体。每个阶段将产出写入快照，下一阶段从快照读取。阶段门卡确保参数完整性。

动态注入：执行中的一些参数可以由用户直接提供，也可以在执行过程中动态获取：

• businessName：通过业务信息查询接口按当前用户工号动态查询。
• scenarioId：根据用户输入的业务关键词，从对照表动态匹配。
• metricBindingBases：固定使用指定模板展开的指标数组。

最佳实践：trade-ab-skill 的用户偏好持久化——成功操作后，将关键参数写入 user-prefs.json，下次执行时自动注入：

{
  "defaultScenarioId": "<场景ID>",
  "defaultMetricTemplateId": "<模板ID>",
  "recentExperimentIds": ["<实验ID1>", "<实验ID2>"],
  "lastUsed": "2026-06-17",
  "usageCount": 2
}

5.6 测试与迭代

测试维度

Claude Code 官方推荐了三类核心测试方法：

• 触发测试：测试 description 是否能被正确匹配。准备 10 个左右的自然语言变体去触发 Skill，检查是否都能正确激活，同时验证不相关的输入是否会误触发。
• 功能走查：用自然语言驱动完整流程，检查每个阶段的输出是否符合预期。重点关注路由是否准确分发、渐进加载是否按时序工作、红线规则是否被遵守、异常场景是否正确熔断。别只跑 happy path——故意输入边界值、模拟工具不可用、尝试让 Agent 调用禁止接口，才是真正暴露问题的场景。
• 性能对比：针对同一任务，分别用“无 Skill”和“有 Skill”两种方式各跑 5 次，对比 Token 用量和完成质量。

如何高效迭代？

• 与传统软件的 bug 修复逻辑一致：发现问题 -> 定位原因 -> 修复文档 -> 验证效果。
• 较为高效的一种迭代方法是观测驱动迭代——通过日志埋点收集每次执行的状态结果（成功/失败/取消）、耗时、调用的工具列表，用数据定位薄弱环节。

最佳实践：trade-ab-skill 的日志采集机制，采用了两阶段 traceId 配对追踪，保障了日志埋点的采集。

六、用 skill-creator 从零创建一个 Skill

skill-creator 是一个用来创建和打包 Skill 的辅助工具，本身也是一个 Skill。它可以协助你从零搭建一个完整的 Skill。

Step 0：前置准备

确保本地已安装以下工具：

• Git（已配置 SSH Key，可访问公司内部代码仓库）
• 一个可以进行对话的 AI 助手，可以使用支持文件操作的工具

Step 1：初始化目录结构

告诉 AI：

「帮我用 skill-creator 生成一个名为 order-query 的 Skill」

AI 会自动运行初始化脚本，生成标准目录：

order-query/
├── SKILL.md           ← 核心文件（必须）
├── scripts/           ← 可执行脚本（可选）
└── references/        ← 参考文档（可选）

Step 2：编写 SKILL.md

告诉 AI：

「帮我编写 order-query 的详细内容，这个 Skill 的功能是 xxx，主要用于 xxx 场景，触发词包括 xxx、xxx。」

AI 会帮你生成包含 YAML frontmatter 和正文的完整 SKILL.md。写作要点：description 要包含所有可能的触发词；正文只写领域专有知识，不写常识；复杂内容拆到 references/ 目录，SKILL.md 中用相对路径引用；控制在 500 行以内。

Step 3：添加参考文档（可选）

如果有复杂的操作流程或参考资料：

告诉 AI：

「把 xxx 的详细流程整理成 references/workflow.md，并在 SKILL.md 中加上引用。」

Step 4：打包验证

告诉 AI：

「用 skill-creator 打包验证 order-query，检查格式是否合规。」

打包脚本会自动校验：frontmatter 是否完整、name 和 description 是否存在、目录中是否有非法文件。有问题 AI 会直接告诉你哪里不对并帮你修复。

Step 5：推送到远端仓库

告诉 AI：

「帮我把 order-query 初始化为 git 仓库，关联远端地址，提交所有文件并推送到 main 分支。」

Step 6：后续迭代更新

修改 Skill 内容后，告诉 AI：

「帮我提交 order-query 的最新改动，commit 信息是 xxx，然后推送。」

整个流程可以浓缩为一张图：

下载 skill-creator
    ↓
告诉 AI：初始化目录
    ↓
告诉 AI：编写 SKILL.md + references
    ↓
告诉 AI：打包验证
    ↓
告诉 AI：git 提交并推送
    ↓
告诉 AI：迭代修改并推送

从头到尾你不需要手动执行任何命令。你只负责描述意图，AI 负责执行——这也是现代开发方式的魅力所在。

参考文档

[1] Agent Skills 官方文档：https://agentskills.io
[2]《Agent Skills 橙皮书：给AI装技能的完全指南》
[3]《Claude Code 实战 Harness 工程之道》
[4]《Harness 工程：从上下文管理到 Agent 系统构建》

本文以集团内部 trade-ab-skill 项目为真实案例，所有代码示例均来自该项目实际运行的 Skill 文件。

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：Harness工程之道：Skill原理与最佳实践指南要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题