agent-skills

Agent Skills (AI 技能)

摘要：Agent Skills 是一种轻量、开放的能力扩展规范，用于为 AI Agent 扩展专业知识和工作流。被 Claude Code、Cursor、GitHub Copilot 等 40+ 主流 Agent 产品采纳。
来源：raw/摘录/Harness 工程之道：Skill 原理与最佳实践.md
最后更新：2026-07-09

定义

Agent Skills（AI 技能）是一种轻量、开放的能力扩展规范，将领域知识和工作流封装为可移植、可版本控制的标准化模块，用于为 AI Agent 扩展专业知识和工作流。可以把 Skills 类比为 AI Agent 的"入职指南"——将领域知识打包成可发现、模块化的能力。(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

核心理念：渐进性披露

Skill 体系最核心的设计理念是渐进性披露（Progressive Disclosure）——只在需要时才加载需要的知识，而非一次性加载全部。(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

分三阶段：

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

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

System Prompt vs Skill 的区别

维度	System Prompt	Skill
定位	项目级全局规则、编码规范	特定领域能力封装
加载策略	会话启动时全量加载	渐进式按需加载
生效范围	当前项目	可跨项目、跨会话
上下文成本	恒定占用，与任务无关也消耗	仅在命中时加载，未命中零成本
结构化	单文件，扁平组织	多文件模块化，支持脚本和资源

Simple 记法：System Prompt 是"这个项目的规矩"，Skill 是"一种可复用的能力"。(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

目录结构规范

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

my-skill/
├── SKILL.md          # 必需：主文件，含元信息 + 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
├── assets/           # 可选：模板、资源
└── ...               # 任意额外文件

SKILL.md 分为两部分：YAML frontmatter（元信息）和正文指令。核心字段是 name（唯一标识符）和 description（触发匹配的依据）。(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

触发机制

Skills 支持两种触发方式：(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

自动触发（语义匹配）：靠 description 字段。当用户意图与 Skill 描述语义匹配时，Agent 主动加载对应 Skill
手动触发（斜杠命令）：用户通过 /skill-name 显式调用

description 的书写公式为：功能定义 + 触发场景 + 核心能力，需同时回答 WHAT 和 WHEN。

作用域与优先级

位置	生效范围	适用场景
企业配置中心	全员生效	强制执行的企业规范与安全策略
用户主目录下全局配置	个人所有项目	通用工具、个人偏好
项目根目录或 `.skills/`	仅当前项目	项目特定工作流
Plugin 内置资源	Plugin 启动时	社区共享能力包

优先级：企业策略 > 个人配置 > 项目配置 > Plugin 内置(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

最佳实践

SKILL.md 即路由器

SKILL.md 的职责是分发任务到正确模块，而非包含所有细节。应控制在 500 行以内。业务细节下沉到模块文件。(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

知识分层

按使用频率组织知识：越频繁用到的知识离入口越近，越偶尔查阅的越往深处放。文件超 300 行或某步规则超 100 行时，就是拆分的信号。(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

模块级工具隔离

每个模块只能调用其白名单中的接口，遵循权限最小化原则。危险接口（如万能 HTTP 调用）全局禁止。(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

脚本增强

将确定性计算逻辑封装为脚本，由 Agent 调用执行。好脚本的标准：自愈性、结构化输出（JSON）、幂等性、安全边界。(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)

生态地位

Agent Skills 由 Anthropic 官方定义，已被 Claude Code、Cursor、GitHub Copilot、Gemini CLI 等 40+ 主流 Agent 产品采纳，成为事实上的开放标准。(source: 摘录/Harness 工程之道：Skill 原理与最佳实践.md)