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

一、Skill 的产生与核心理念

从 Prompt 工程到 Skill 工程的演进

当前大模型都存在一个共性：每轮对话都是"失忆"的，必须从零开始构建上下文，由此发展出了 Prompt 工程。比如 CLAUDE.md 将团队的技术选型、编码规范、架构约束等都固化为一份 Agent 可读的配置文档。

但随着复杂性增加，问题逐渐暴露：传统 Prompt 工程将所有领域知识一股脑塞进提示词，项目越复杂，Prompt 越臃肿。上下文窗口被撑满，模型的注意力被稀释，真正关键的信息反而容易被"淹没"。并且这些知识和具体项目深度耦合，换个场景就得重写一遍，几乎没有复用性。

Agent Skill 将领域知识和工作流封装为可移植、可版本控制的文件夹，用来"教"Agent 如何处理特定任务或工作流，Agent 按需加载。类比：新员工手册。

核心理念：渐进性披露（Progressive Disclosure）

只在需要时才加载需要的知识，而非一次性加载全部。分三阶段：

Discovery（发现）：会话启动时仅加载每个 Skill 的 name 和 description，常驻注入 Agent 上下文
Activation（激活）：任务匹配 description 时，读取完整 SKILL.md，加载路由表和全局规则，但不加载子模块
Execution（执行）：按路由表加载对应的模块文件，按需读取参考文档，只加载当前任务真正需要的知识

用最小的上下文成本，换取最大的知识覆盖范围，确保上下文窗口留给真正重要的信息。

System Prompt 与 Skill 的区别

System Prompt：项目级全局规则、会话启动时全量加载、恒定占用上下文、当前项目生效、单文件扁平组织
Skill：特定领域能力封装、渐进式按需加载、命中时才消耗、可跨项目跨会话、多文件模块化

简单记法：System Prompt 是"这个项目的规矩"，Skill 是"一种可复用的能力"。两者协同——System Prompt 中的规则对所有 Skill 生效，Skill 内部的规则仅在激活时叠加。

二、Skill 的结构组成

目录结构规范

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

这种格式已被 Claude Code、Cursor、GitHub Copilot、Gemini CLI 等 40+ 主流 Agent 产品采纳，成为事实上的开放标准。核心思想是主文件做路由，模块文件做执行。

SKILL.md 文件结构

分为 frontmatter 元信息和正文指令两部分。frontmatter 核心字段：

name（必填）：唯一标识符，小写字母+数字+连字符，最长 64 字符
description（必填）：能否被正确触发的关键，需写清 WHAT（做什么）+ WHEN（什么时候用），最长 1024 字符
argument-hint（可选）：参数提示格式
disable-model-invocation（可选）：设为 true 禁止模型自动调用
user-invocable（可选）：设为 false 禁止用户手动调用
allowed-tools（可选）：工具白名单，精确控制可调用的工具
model（可选）：指定模型（简单任务用 Haiku 降本提速）
context: fork（可选）：在隔离子智能体中执行
hooks（可选）：生命周期事件钩子
version（可选）：语义化版本号

三、触发机制

自动触发：靠 description 语义匹配，用户无感。Agent 判断"这个任务我有现成的专业流程可以用"，主动加载对应 Skill
手动触发：用户通过 /skill-name 显式调用

description 书写规范：功能定义 + 触发场景 + 核心能力。需同时回答 WHAT 和 WHEN，枚举具体触发词（含口语化说法），用第三人称，可标注排除场景。

四、作用域与优先级

作用域分四级：企业配置中心（全员生效）> 用户主目录全局配置（个人所有项目）> 项目根目录（仅当前项目）> Plugin 内置资源。当多个 Skill 的 description 都匹配时，按此优先级决定触发哪个。

五、最佳实践

1. SKILL.md 是路由器而非知识仓库

SKILL.md 只保留路由表和全局规则，业务细节下沉到模块文件。控制在 500 行以内（约 2000-3000 token）。引用辅助文件时建立明确契约：触发时机 + 资源位置 + 预期产出。

2. 知识分层策略

拆分信号：文件超过 300 行，或某个 Step 的规则超过 100 行。组织原则：越频繁用到的知识离入口越近，越偶尔查阅的往深处放。

trade-ab-skill 的分层示例：

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

3. 安全实践：工具权限隔离

模块级工具隔离——每个模块只能调用白名单中的接口，权限最小化：

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

trade-ab-skill 实践：实验创建接口仅在 creator 白名单中；modifier 只能用实验修改接口；审批/发布接口在所有模块中均禁止。

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

将确定性计算逻辑封装为脚本，由 Agent 调用执行而非自行推导。判断标准：如果让 LLM 做有概率出错，但脚本能 100% 确定性完成，就该封装成脚本。

脚本设计四原则：

自愈性：内部处理所有异常，始终正常退出，绝不阻断主流程
结构化输出：统一输出 JSON，方便 Agent 解析
幂等性：多次执行结果一致
安全边界：只操作指定文件，不触碰其他系统资源

5. 参数传递与动态注入

采用快照（Snapshot）机制作为跨阶段参数传递载体。每个阶段将产出写入快照，下一阶段从快照读取。阶段门卡确保参数完整性。

用户偏好持久化：成功操作后将关键参数写入 user-prefs.json，下次执行时自动注入。

6. 测试与迭代

三类核心测试：

触发测试：准备 10 个自然语言变体验证 description 匹配率，同时验证不相关输入不会误触发
功能走查：不只跑 happy path，故意输入边界值、模拟工具不可用、尝试调用禁止接口
性能对比：有/无 Skill 各跑 5 次，对比 Token 用量和完成质量

迭代方法：观测驱动迭代——通过日志埋点收集每次执行的状态、耗时、调用的工具列表，用数据定位薄弱环节。

六、用 skill-creator 创建 Skill

skill-creator 本身也是一个 Skill，可协助从零搭建。流程：初始化目录 → 编写 SKILL.md + references → 打包验证 → git 提交推送 → 迭代修改。整个流程无需手动执行任何命令，只需描述意图。