Skill 位于意图与底层能力之间
| 资产 | 主要责任 | 谁拥有控制流 | 典型证据 |
|---|---|---|---|
| Tool | 一个原子动作与输入输出契约 | Runtime/调用者 | Schema、契约测试 |
| Prompt | 一段指令或消息资产 | 调用代码/模型 | 版本、Eval |
| Workflow | 明确步骤、分支和恢复 | 确定性编排 | 状态机、Trace |
| Skill | 某类任务所需知识、步骤、Tool、资源和完成标准 | Agent 选择；Runtime 约束执行 | 触发集、执行记录、产物验收 |
Skill 可引用 Tool，也可包含确定性脚本或模板；但它不能绕过 Tool 的服务端鉴权、Runtime 的 Permission Scope 或人工审批。一个 Skill 如果只有几句通用写作建议，且没有明确触发边界和结果差异，通常不值得独立封装。
一个 Skill 需要回答什么
公开 Agent Skills 规范要求目录至少包含带 YAML Frontmatter 的 SKILL.md，其中 name 与 description 是必需字段；scripts/、references/、assets/为可选约定。allowed-tools 当前仍是实验字段，客户端支持并不一致。
格式合法只是下限。业务契约还要明确：解决什么问题、何时触发、何时拒绝；输入和前置环境；硬约束与可变策略；需要的 Tool、文件、网络和凭据；输出 Artifact、验收规则；失败后重试、升级或人工接管。
---
name: review-api-change
description: Review an API change for compatibility and migration risk. Use when an API schema or diff is provided.
compatibility: Requires git and repository read access
metadata:
owner: platform-architecture
version: "2.3"
---
# Goal
Produce an evidence-backed compatibility report.
# Stop conditions
- Missing baseline schema: report BLOCKED.
- Write access is never required.示例中的 Owner、版本和停止条件属于组织设计，不是规范强制字段。应明确区分标准要求、客户端扩展和企业治理元数据，避免把某个实现习惯包装为通用标准。
渐进加载控制 Context 成本
Agent Skills 的核心机制是三阶段披露：启动时只加载名称和描述；确认触发后加载完整 SKILL.md；执行到具体步骤才读取 References、Scripts 或 Assets。这样既保留大能力目录，又不把所有说明塞进每次请求。
Description 既要覆盖正确触发语义，也要包含排除信号。写成“帮助处理文档”会与大量 Skill 冲突；写清输入对象、动作和使用条件，才能提升发现准确率。渐进披露不是隐藏关键安全约束：权限和高风险行为必须在安装/启用前可见。
Skill 组合需要显式依赖
组合时要区分“调用另一个 Skill”和“读取另一个 Skill 的产物”。前者可能形成递归和预算放大，后者需要 Artifact Schema、Owner 和版本。依赖图应声明前置、可并行步骤、共享 Artifact、失败传播、最大嵌套深度和总预算。
不要让多个 Skill 隐式修改同一文件或外部对象。确定写入所有权、冲突策略和提交边界；子 Skill 失败时，上层只能根据结构化状态选择重试、降级或终止，不能用一段模糊摘要掩盖部分完成。
写给 Agent 的说明必须可执行
每一步用可观察动作和终止条件表达，例如“读取 Schema 后列出所有 breaking fields；若缺少 baseline，输出 BLOCKED 并停止”，而不是“仔细全面地分析”。硬约束、默认建议、示例和解释要标明层级，避免模型把示例误当唯一答案。
稳定、确定、可测试的逻辑优先写入脚本，例如 Schema 校验、格式转换、文件扫描；模型负责语义判断和不确定分支。模板应允许删除不适用部分，不能反过来要求所有任务凑齐固定章节。
| 弱写法 | 可执行写法 | 验证方式 |
|---|---|---|
| 全面检查安全性 | 按威胁清单检查输入、权限、秘密和副作用；逐项给证据 | 缺陷注入样本 |
| 必要时运行测试 | 修改实现后运行指定最小测试；失败则保留日志并停止发布 | 故障分支 Trace |
| 输出高质量报告 | 每个结论含严重级别、证据、影响、建议和未验证项 | Schema + 人工 Rubric |
Skill 也是供应链与权限载体
Skill 目录可以含可执行脚本、外部引用和模板，因此安装它等同于引入一份“指令 + 代码 + 数据”依赖。应记录来源、许可证、Owner、内容哈希/签名、依赖锁、所需权限和审查时间。升级 Diff 必须突出新增 Tool、网络、文件、命令和凭据权限。
风险不仅是恶意脚本：描述投毒可劫持触发，Reference 可包含间接注入，模板可泄露敏感字段，依赖更新可改变行为。OWASP Agentic AI 风险分类可用于查漏，但最终控制仍要来自本系统的威胁模型和实际权限路径。
| 阶段 | 关键控制 | 失败动作 |
|---|---|---|
| 获取 | 可信来源、哈希/签名、许可证 | 隔离，不加载 |
| 安装 | 静态扫描、权限差异、依赖审计 | 要求 Owner 审批 |
| 执行 | 沙箱、最小权限、网络/文件策略、审计 | 中止并保留证据 |
| 升级 | Diff、回归、渐进发布 | 回滚已知版本 |
| 撤销 | 禁用、凭据轮换、缓存清理 | 阻止新 Run，处置在途 Run |
分别评估发现、执行和产物
发现评估同时包含正样本、近邻负样本和应澄清样本；只测“该触发时触发”会把过度触发漏掉。执行评估检查步骤遵循、Tool 选择、停止条件、权限和失败恢复。产物评估用确定性 Schema、测试、人工 Rubric 或业务状态验证结果。
升级不能只看平均成功率。按输入类型、权限级别、模型版本和环境分层比较，关注错误从“未触发”迁移为“错误执行”这类风险转移。发布记录应含版本、触发集、失败样本、权限变化、回滚版本和 Owner。
主动提取：一个 Skill 执行步骤全部完成，为什么仍可能评估失败？
架构判断：什么时候应把一段逻辑从 SKILL.md 移到脚本？
资料与事实边界
以下以官方文档、标准、论文和原始工程资料为主。厂商 API、价格、限额与模型能力会变化，落地时仍需按目标版本做能力探测和回归。
- Agent Skills Specification — SKILL.md、Frontmatter、目录结构与渐进披露规范
- Agent Skills Client Implementation — 客户端发现与渐进加载的官方实现指导
- Agent Skills reference validator — 格式验证参考实现
- OWASP Agentic AI Security — Agent 供应链、身份、工具与执行风险的治理参考