如果说 AGENTS.md 解决的是“这个仓库希望 Agent 长期遵守什么”，那么 Agent Skill 解决的是另一个问题：
当 Agent 遇到某类重复任务时，如何把组织经验、操作步骤、参考资料和验证方式按需交给它？
Skill 不是普通 prompt。
也不是传统 API tool。
它更像一种给 Agent 使用的“上下文包 + 工作流包”：
skill/
SKILL.md
references/
scripts/
assets/
examples/SKILL.md 告诉 Agent：
- 什么时候使用这个 Skill；
- 当前任务应该怎么做；
- 需要哪些输入；
- 应该产出什么；
- 哪些步骤不能跳；
- 遇到边界情况怎么处理；
- 需要运行哪些验证脚本；
- 最终如何报告结果。
references、scripts、assets 则让 Skill 不只是说明文档，而是可执行、可复用、可验证的任务资产。
这篇文章基于 OpenAI Codex、Claude Code 和 Agent Skills 开放标准的公开资料整理，重点讨论一个产品和架构问题：
Skill 为什么会成为 Agent 工程里的重要抽象？
Skill 的本质：按需加载的任务能力
一个普通 prompt 是一次性指令：
请按我们的发布流程生成 release notes。一个 Skill 则把这套流程沉淀成可复用目录：
release-notes/
SKILL.md
references/
changelog-format.md
scripts/
collect_commits.py
assets/
release-template.md从用户体验看，Skill 减少了重复提示。
你不需要每次都告诉 Agent：
- 我们团队怎么写 release notes；
- commit 怎么收集；
- changelog 格式是什么；
- 哪些变更要突出；
- 哪些输出不能出现；
- 生成后怎么校验。
从系统设计看，Skill 是一种上下文治理机制。
它让 Agent 先知道“有哪些能力可能可用”，但不立即加载所有细节。只有当任务匹配某个 Skill 时，系统才展开完整说明和资源。
这就是 progressive disclosure。
Progressive Disclosure：先发现，再展开
Agent Skills 的关键机制不是“把更多东西塞进 prompt”，而是分阶段加载。
可以把它拆成三层。
Discovery
load name / description / path
Activation
load SKILL.md
Execution
read references or run scripts when needed第一阶段是 Discovery。
Agent 启动或会话初始化时，只需要知道有哪些 Skill 可用，以及它们大概什么时候适用。
第二阶段是 Activation。
当用户任务或当前上下文匹配某个 Skill 的描述时，Agent 才读取完整 SKILL.md。
第三阶段是 Execution。
如果 SKILL.md 指向更多资料或脚本，例如：
For API error handling, read references/api-errors.md.
For migration validation, run scripts/validate_migration.py.Agent 再按需读取或执行。
这个机制非常重要。
因为一个团队可能有几十个 Skill。
如果每个 Skill 都完整进入上下文，模型窗口很快会被挤满，而且大量无关流程会干扰当前任务。
Progressive disclosure 的价值是：
保留能力可发现性，同时控制上下文成本和注意力污染。
Codex 和 Claude 的共同点
Codex 和 Claude Code 对 Skill 的理解很接近。
它们都把 Skill 看作一种文件系统式能力包，而不是模型微调。
典型结构都是：
my-skill/
SKILL.md
scripts/
references/
assets/核心思想也相同：
- Skill 通过描述被发现；
SKILL.md提供任务说明；- supporting files 按需加载；
- scripts 让关键步骤更确定；
- Skill 可以进入个人、项目或插件级分发；
- Skill 可以通过版本管理在团队中复用。
这说明 Agent Skill 已经不是某一家产品的孤立功能，而是正在形成一种跨 Agent 工具的工作流封装方式。
它适合沉淀的不是通用知识，而是：
- 团队流程；
- 项目约束；
- 文件格式；
- 质量标准；
- 常见错误；
- 验证脚本；
- 输出模板；
- 特定领域的操作经验。
一句话：
Skill 把“会做这件事的经验”从聊天历史里拿出来，变成可维护的上下文资产。
Skill 不等于 Tool
Skill 容易和 tool 混淆。
但二者解决的问题不同。
| 抽象 | 解决什么问题 | 例子 |
|---|---|---|
| Tool | Agent 能调用什么能力 | read file、run shell、query API、search docs |
| Skill | Agent 应该如何完成某类任务 | 代码 review 流程、发布说明生成、数据质量检查 |
| MCP | Agent 如何连接外部系统 | GitHub、Slack、Figma、数据库 |
| Hook / Rule | 哪些行为必须被拦截或验证 | 禁止危险命令、工具调用后检查 |
Tool 是能力接口。
Skill 是任务方法。
MCP 是外部连接。
Hook / Rule 是控制面。
例如“生成 release notes”这件事。
Tool 负责读取 git log、打开文件、写 markdown。
Skill 负责告诉 Agent：
- 先检查变更范围；
- 按什么模板归类；
- 哪些 commit 要忽略；
- 如何判断 breaking change；
- 生成后运行哪个脚本校验格式；
- 最终报告包含哪些字段。
如果没有 Skill，用户每次都要重新解释流程。
如果只有 Skill 没有 tool，Agent 也无法实际读取仓库、生成文件或执行校验。
二者是互补关系。
Skill 也不是硬状态机
Skill 的限制也必须说清楚。
SKILL.md 进入的是模型上下文，不是模型权重，也不是传统程序控制流。
这意味着它不能保证：
- 一定触发；
- 一定不误触发；
- 一定逐步执行；
- 一定不受其他上下文干扰；
- 一定不在 compaction 后丢失细节；
- 一定会真的完成验证。
真实执行更接近：
user task
↓
agent checks skill descriptions
↓
loads relevant SKILL.md
↓
model interprets workflow
↓
agent calls tools
↓
tool results return
↓
model continues under the mixed context每一步都可能出现偏差。
所以不能把 Skill 当成流程引擎。
它更像“强上下文约束”。
能显著提高正确概率，但不能替代工程控制面。
真正可靠的 Agent workflow，通常需要：
Skill
说明流程、边界、gotchas
Scripts
执行确定性验证
Sandbox / Approvals
限制行动范围
Rules / Hooks
拦截危险或违规动作
Tests / CI
验证最终结果
Human Review
对高风险输出做责任确认这是 Skill 产品化时最重要的判断。
一个好的 Skill 应该包含什么
高质量 Skill 不是越长越好。
好的 Skill 应该用尽量少的上下文，让 Agent 在关键节点做对。
我认为至少要包含七部分。
1. 清晰的触发描述
description 是 Skill 的入口。
它不应该只写“这个 Skill 是什么”，还应该写“什么时候使用”。
差的写法：
description: Helps with documents.更好的写法：
description: Use this skill when creating, editing, reviewing, or validating product requirement documents, release notes, changelogs, or decision memos. Do not use for general code editing unless the task requires product-document workflow governance.好的 description 应该包含：
- 真实用户会说的触发词；
- 明确任务边界；
- near-miss 场景；
- 不应该触发的情况。
这直接决定 Skill 的召回率和误触发率。
2. 输入、输出和停止条件
很多 Agent 失败，是因为它不知道信息不足时应该停下来。
Skill 里应该明确：
## Inputs
- Target repository or file path
- Requested change
- Relevant issue / PR / design link if provided
## Outputs
- Files changed
- Commands run
- Validation result
- Risks and follow-up items
## Stop conditions
Stop and ask for clarification if:
- Target file cannot be identified
- Required credentials are missing
- Validation fails for reasons unrelated to your change停止条件很关键。
它防止 Agent 在不该猜的时候继续猜。
3. 分阶段 Workflow
Skill 应该把任务拆成阶段，而不是写成散文。
例如：
## Mandatory workflow
### Phase 1: Inspect
- Read relevant files.
- Identify current conventions.
- Do not edit yet.
### Phase 2: Plan
- Summarize intended changes.
- Identify risks.
- Choose validation commands.
### Phase 3: Execute
- Make the smallest necessary change.
- Avoid unrelated refactors.
### Phase 4: Validate
- Run tests and validators.
- Fix failures caused by your change.
### Phase 5: Report
- Summarize files changed, commands run, and unresolved risks.阶段化不是为了显得正式。
而是为了让 Agent 的中间状态更容易检查。
4. Gotchas
Gotchas 是 Skill 里性价比最高的部分。
它记录的是 Agent “合理推测但容易猜错”的地方。
例如：
## Gotchas
- This repo uses pnpm, not npm.
- Do not edit generated files under src/generated/.
- The health endpoint only checks web server liveness; use /ready for DB readiness.
- Customer IDs are named user_id in DB, uid in auth service, and accountId in billing API.这些内容不是通用常识。
它们是组织经验。
而 Skill 的价值恰恰在于保存这些经验。
5. 可执行 Scripts
当步骤需要确定性时，写脚本比写自然语言更好。
scripts/
validate_schema.py
check_component_duplicates.py
generate_release_report.pySKILL.md 中引用：
## Validation
Run:
```bash
python scripts/validate_schema.py --changed-only
```
If it fails, fix the issue and rerun. Do not report success until it passes.脚本让 Skill 从“建议”变成“可验证流程”。
这也是 Skill 和普通 prompt 的差异之一。
6. 输出模板
Agent 对具体格式的模仿通常比对抽象要求的遵守更稳定。
所以 Skill 应该给出最终报告模板。
## Final report template
## Summary
[What changed]
## Files changed
- ...
## Validation
- Command: ...
- Result: pass / fail
## Risks
- ...
## Follow-up
- ...模板能减少输出漂移，也方便后续自动解析。
7. Evaluation Cases
成熟 Skill 不应该只靠感觉维护。
它需要 eval cases。
至少要回答：
- 哪些用户 prompt 应该触发这个 Skill；
- 哪些 prompt 不应该触发；
- 触发后是否读取了正确 reference；
- 是否运行了验证脚本；
- 输出是否符合模板；
- 相比无 Skill 是否更稳定。
这让 Skill 变成可迭代资产，而不是一次性文档。
好的 Skill 不应该包含什么
Skill 也有常见反模式。
第一，不要写模型本来就知道的常识。
例如“写清楚代码”“处理错误”“遵循最佳实践”通常没什么用。
第二，不要放大段背景介绍。
Agent 需要的是执行差异，不是宣传稿。
第三，不要把多个无关任务塞进一个 Skill。
“文档处理 Skill”通常太宽，应该拆成 “release notes”“PRD review”“decision memo”“docx formatting” 等更具体任务。
第四，不要只写原则，不写检查方式。
如果要求“保证质量”，就应该配套测试、validator、review checklist 或脚本。
第五，不要放敏感信息。
Skill 可能被提交到仓库、插件、团队环境或共享目录。不要把 token、密钥、客户数据、私有凭证硬编码进去。
第六，不要让 description 过宽。
过宽会导致误触发，反而污染上下文。
Skill 的产品意义
从产品经理角度看，Skill 最重要的不是文件格式，而是它提供了一种产品化组织经验的方法。
过去，团队经验通常散落在：
- 老员工口头提醒；
- README；
- wiki；
- onboarding 文档；
- Slack 讨论；
- PR review 评论；
- 手动 checklist；
- 个人 prompt 模板。
这些东西对人有用，但对 Agent 不一定可用。
Skill 把它们变成 Agent 可以发现、加载和执行的结构。
这会带来几个产品能力。
第一，降低重复提示成本。
用户不需要每次重新说明同一套流程。
第二，提高任务一致性。
同类任务可以遵循同一套输入、步骤、验证和输出标准。
第三，沉淀团队 know-how。
每次 Agent 犯错后，不只是“下次注意”，而是把经验写回 Skill、script、hook 或 eval。
第四，让 Agent 能力可治理。
哪些 Skill 可用、谁维护、什么版本、是否可信、触发率如何、失败率如何，都可以进入产品管理。
第五，支持跨工具迁移。
如果 Skill 标准足够开放，团队的工作流资产可以从一个 Agent 工具迁移到另一个 Agent 工具，而不是锁死在某个对话框里。
Skill 的风险和治理
Skill 越有用，越需要治理。
因为 Skill 本质上会影响 Agent 行为。
风险至少有五类。
第一，触发风险。
该触发时不触发，会让用户觉得 Skill 无效。
不该触发时触发，会让 Agent 按错误流程行动。
第二，过期风险。
项目命令、接口、目录、业务规则变化后，Skill 可能继续指导 Agent 使用旧流程。
第三，权限风险。
Skill 可能要求 Agent 运行脚本、读取文件、调用工具。它应该和 sandbox、approval、allowed tools、rules 协同。
第四，供应链风险。
团队从外部安装 Skill 时，不能默认完全信任其中的脚本、hooks 或引用资源。
第五，压缩风险。
长任务中，Skill 的细节可能被压缩或被后续上下文稀释。关键约束应该转成脚本、规则、hook 或显式检查点。
所以成熟产品里，Skill 不应该只是“文件夹”。
它需要生命周期：
author
↓
review
↓
install
↓
activate
↓
observe
↓
evaluate
↓
revise
↓
deprecate这也是 Agent 产品可能形成壁垒的地方。
不是谁有更多 Skill，而是谁能更好地管理 Skill 的质量、触发、权限和迭代。
对 Plato 的启发
Plato 面向的是 AI-assisted product workbench。
如果它要承载真实产品工作，Skill 可以成为重要的工作流资产。
例如：
- PRD review skill；
- roadmap planning skill；
- user feedback synthesis skill；
- design critique skill；
- release note skill；
- competitor research skill；
- Agent task packaging skill；
- failure retrospective skill。
但 Plato 不应该只提供一个 Skill 列表。
更有价值的是把 Skill 和 Task Context 结合起来。
Task Context
tells Agent current goal, plan, evidence, permissions
Skill
tells Agent how to perform a recurring task type
Verifier
checks whether the output meets the workflow contract
Trace UI
shows which Skill was activated and why这样，用户看到的不是“又多了一个模板”，而是一套可解释的执行能力：
- 为什么触发这个 Skill；
- Skill 要求 Agent 做哪些步骤；
- 哪些步骤已经完成；
- 哪些验证通过；
- 哪些风险还没解决；
- 下次如何复用这次经验。
这对 Agent 产品经理岗位尤其重要。
因为它把“Prompt 工程”提升成了“工作流产品设计”。
结论
Agent Skill 的核心价值，不是让模型变聪明。
而是让 Agent 能按组织经验工作。
它把：
- 专业知识；
- 操作步骤；
- 项目约束；
- 常见错误；
- 参考资料；
- 脚本；
- 验证标准；
- 输出模板；
打包成可发现、可加载、可复用、可版本化的上下文资产。
但 Skill 不是魔法。
它不是硬状态机，也不是权限系统，更不是测试系统。
真正可靠的 Agent workflow 来自组合：
Skill
提供任务方法
Tool / MCP
提供外部能力
Sandbox / Approval
提供行动边界
Rules / Hooks
提供过程控制
Tests / CI / Review
提供结果验证
Observability
提供触发、执行和失败复盘数据一句话概括：
Skill 是 Agent 使用组织经验的上下文接口；真正的可靠性来自 Skill 与工程控制面的组合。