26. Agent Skill：从长 Prompt 到可复用能力包

本章是 v1.2 新增内容。它不是替代前面 Prompt、Workflow、Tool、MCP、Agent 的章节，而是补齐一个关键问题：当某类任务需要被反复执行、反复校验、跨会话复用、跨团队共享时，应该如何把它沉淀成 Agent 可调用的“能力包”。

26.1 Skill 是什么

Agent Skill 是面向 Agent 的可复用任务能力包。它通常以文件夹形式存在，核心入口是 SKILL.md，并可附带参考资料、脚本、模板、示例、评测用例等资源。

产品视角定义：

Skill 是把某类任务的操作流程、领域知识、模板、校验规则和可选脚本封装起来，让 Agent 在需要时按需加载并稳定执行的能力单元。

它适合解决的问题：

任务经常重复，但每次输入不同。
任务有明确步骤和质量标准。
单靠一次 Prompt 容易漏项、跑偏或格式不稳定。
需要配套模板、参考资料、示例文件或脚本。
希望沉淀为团队可复用的 Agent 能力。

26.2 Skill 不是 Prompt，也不是 Tool

对象	解决的问题	典型形式	产品经理判断
Prompt	本次任务怎么问、怎么答	一段提示词	一次性、轻量任务
System Prompt	当前 Agent 的长期行为边界	系统级指令	全局语气、身份、原则
Instruction / Manifest	项目级长期上下文和规则	AGENTS.md、CLAUDE.md、GEMINI.md、Cursor Rules	项目规则、构建测试、架构约束
Skill	某类任务的可复用执行方法	SKILL.md + references + scripts + assets	稳定复用的任务流程
Tool	一个可调用动作或函数	API、MCP Tool、CLI 命令	给 Agent 外部动作能力
MCP	工具和数据接入标准	MCP Server / Client	标准化连接外部系统
Workflow	固定业务流程编排	节点、条件、人审	路径相对固定的流程
Hook	生命周期中的确定性控制点	PreToolUse、PostToolUse、Stop 等	必须强制执行的校验或拦截
Harness	Agent 运行时控制系统	状态、上下文、权限、日志、回滚	让 Agent 可控、可观测、可恢复

一句话区分：

Prompt 是“这次怎么做”；Instruction 是“在这个项目里长期遵守什么”；Skill 是“这类任务以后都按这个方法做”；Tool 是“能调用什么动作”；Hook 是“关键节点必须检查什么”；Harness 是“整个执行过程如何受控运行”。

26.3 Skill 的标准目录结构

建议产品经理理解的 Skill 目录结构：

bid-document-skill/
├─ SKILL.md
├─ references/
│  ├─ writing-rules.md
│  ├─ scoring-checklist.md
│  └─ compliance-requirements.md
├─ scripts/
│  ├─ validate_schema.py
│  └─ check_required_sections.py
├─ assets/
│  ├─ proposal-template.docx
│  └─ response-matrix.xlsx
└─ evals/
   ├─ trigger_cases.jsonl
   ├─ non_trigger_cases.jsonl
   └─ output_cases.jsonl

不同目录的产品含义：

目录 / 文件	作用	适合放什么
`SKILL.md`	Skill 入口说明	名称、描述、触发条件、执行步骤、边界、输出要求
`references/`	复杂背景资料	规范、模板说明、业务规则、术语表、案例
`scripts/`	高确定性处理逻辑	校验、转换、解析、批处理、生成固定结构
`assets/`	可复用素材	模板文件、表格、图示、样例文件
`evals/`	测试与回归	触发测试、非触发测试、输出质量测试

26.4 SKILL.md 应该写什么

SKILL.md 不是越长越好。它应该让 Agent 快速知道三件事：什么时候用、怎么做、什么时候停止。

建议结构：

---
name: bid-document-preparation
description: Use this skill when the user needs to analyze tender documents, identify required response materials, ask for missing information, and generate structured bid/proposal documents.
allowed-tools: [read_file, create_docx, validate_schema]
version: 1.0.0
owner: product-team
---

# Bid Document Preparation Skill

## When to use
- 用户提供招标文件并要求分析投标响应材料。
- 用户要求生成标书、响应矩阵、偏离表或商务技术响应文件。

## When not to use
- 用户只是询问普通写作建议。
- 用户没有提供任何招标资料，也没有要求生成标书。

## Workflow
1. 读取招标文件。
2. 识别资格、商务、技术、报价、格式、签章、截止时间要求。
3. 输出缺失资料清单。
4. 收集用户补充资料。
5. 生成响应矩阵。
6. 按模板生成文档。
7. 执行 Schema 与完整性校验。
8. 输出交付物和风险提示。

## Output requirements
- 必须输出资料清单、缺失项、风险项、生成文件、校验结果。
- 不得编造未提供的资质、业绩、授权文件。

产品经理要把 SKILL.md 当作“Agent 任务操作手册”，不是当作宣传文案。

26.5 Description 与触发机制

Skill 的 description 极其重要，因为 Agent 通常先看到 Skill 的名称和描述，再决定是否读取完整 Skill 内容。

好的 description 应该具备：

明确任务类型。
明确输入条件。
明确输出结果。
明确领域边界。
避免过宽的营销词。

对比：

类型	示例	问题
过宽	`Helps with documents.`	几乎所有文档任务都会误触发
过窄	`Use only for Guangzhou 2026 property firefighting bid technical proposal chapter 3.2.`	稍微换个场景就不会触发
推荐	`Use when analyzing tender documents, extracting bid requirements, identifying missing response materials, and generating structured proposal documents.`	任务、输入、输出、边界都较清楚

26.6 Progressive Disclosure：按需加载

Progressive Disclosure 的核心思想是：不要把所有 Skill 的完整内容一次性塞进上下文，而是分阶段加载。

Discovery：启动时只看到 Skill 名称、description、路径
→ Activation：任务匹配时读取完整 SKILL.md
→ Execution：执行时按需读取 references、scripts、assets、evals

产品价值：

减少上下文浪费。
避免多 Skill 互相干扰。
让 Agent 只在需要时读取复杂规则。
支持团队维护大量可复用能力包。

26.7 references / scripts / assets 怎么设计

references：放稳定知识，不放临时指令

适合放：

标准作业流程。
行业术语表。
写作规范。
评分规则。
合规要求。
示例与反例。

不适合放：

当前用户的一次性需求。
未确认的临时资料。
与 Skill 无关的大段背景。

scripts：确定性任务交给脚本

适合脚本处理：

JSON Schema 校验。
Excel / CSV 字段检查。
文档目录完整性检查。
重复文件检测。
批量命名、格式转换、统计。
固定模板填充。

原则：

模型擅长理解、归纳、生成；脚本擅长确定性校验、格式转换、批处理。能确定性执行的，不要交给模型自由发挥。

assets：沉淀模板和样例

适合放：

Word 模板。
Excel 模板。
PPT 模板。
图片素材。
示例输入 / 示例输出。

26.8 allowed-tools 与权限边界

Skill 不是越强越好。每个 Skill 都应该限制可以使用的工具。

示例：

Skill 类型	允许工具	禁止工具
文档分析 Skill	读取文件、生成文档、Schema 校验	删除文件、发送邮件、执行系统命令
代码审查 Skill	读取代码、运行测试、生成报告	自动合并、发布生产、删除分支
财务测算 Skill	读取表格、计算、生成报表	自动付款、修改正式财务系统
客服回复 Skill	检索知识库、生成草稿	自动承诺赔付、自动修改客户资料

产品经理在 PRD 中应明确：

Skill 权限要求：
1. 只读工具有哪些？
2. 可写工具有哪些？
3. 哪些动作必须人工确认？
4. 哪些工具调用需要审计日志？
5. 哪些失败必须中止，不能重试？

26.9 Skill 设计原则

单一职责：一个 Skill 只解决一类任务，不做万能助手。
触发清晰：description 能准确描述该触发和不该触发的边界。
流程明确：步骤能被 Agent 按顺序执行。
输入可校验：缺资料时先提问，不直接编造。
输出结构化：能被后续系统读取、校验、归档。
风险可控：高风险动作必须人审。
可评测：有触发测试、输出测试、回归测试。
可版本化：变更可追踪，失败可回滚。
可组合：能和 MCP、Workflow、Hook、Subagent 协同。
可移交：其他人能看懂、维护、复用。

26.10 Skill 评测方法

Skill 也需要评测，不然它只是换了位置的长 Prompt。

评测类型	目的	示例
Trigger Eval	应该触发时是否触发	用户说“帮我分析招标文件并列缺失资料”
Non-trigger Eval	不该触发时是否误触发	用户说“帮我润色一段宣传文案”
Output Eval	输出是否满足要求	是否包含缺失项、风险项、响应矩阵
Tool Eval	工具使用是否正确	是否调用了文档解析和校验脚本
Safety Eval	是否越权或编造	是否编造资质、业绩、报价
Regression Eval	新版本是否破坏旧能力	v1.1 用例在 v1.2 是否仍通过
With / Without Skill 对比	Skill 是否真的提升效果	同一任务有无 Skill 的质量差异

26.11 Skill 版本治理

Skill 应该像产品能力一样治理。

治理项	要求
命名规范	名称表达领域和任务，不用泛化词
版本号	建议语义化版本，例如 1.2.0
维护人	明确 owner 和评审人
适用范围	写清楚适用业务、工具、数据边界
变更记录	每次修改说明改了什么、为什么改
测试集	Trigger / Non-trigger / Output / Regression
权限	allowed-tools、禁止动作、人审节点
发布	先灰度，再全量
回滚	新版误触发或输出下降时能回退
外部 Skill 审查	第三方 Skill 视为不可信代码和不可信指令

26.12 Skill 安全风险

Skill 的风险主要来自四类：

误触发风险：不该启用 Skill 时启用，导致输出跑偏。
越权风险：Skill 调用了超出任务所需的工具。
供应链风险：第三方 Skill 中夹带恶意指令、脚本或隐性触发词。
维护风险：Skill 过期、规则冲突、没人维护，导致 Agent 行为不可控。

安全原则：

外部 Skill 先审查再启用。
高风险 Skill 默认禁用写操作。
Skill 触发和工具调用必须留痕。
Skill 更新必须跑回归测试。
任何涉及资金、权限、生产系统、合同承诺的动作必须人工确认。

26.13 AI 产品经理如何设计一个 Skill 包

建议流程：

选择重复任务
→ 定义触发条件
→ 定义不触发边界
→ 拆解执行步骤
→ 准备参考资料和模板
→ 判断哪些步骤用脚本
→ 限定 allowed-tools
→ 设计输出 Schema
→ 编写 Trigger / Non-trigger / Output 测试
→ 灰度试用
→ 收集错误样本
→ 版本迭代

一个合格的 Skill 交付包至少包括：

SKILL.md
触发与不触发样例
输入 / 输出样例
权限清单
风险边界
测试用例
变更记录
使用说明