Agent Skills
Skill（技能）本质上是一个打包好的标准作业程序（SOP），Agent 在遇到匹配任务时能发现并加载它。通用规范围绕目录结构和 SKILL.md 定义了一套可移植的核心标准，但不同宿主（Host）在发现机制、元数据解析、激活逻辑、工具调用及代码执行权限上可能存在差异。
需要明确：Skill 是一套约定和内容包，它不是隔离沙箱，也不代表该流程一定有效。
包结构
典型的 my-skill/ 目录包含以下部分：
SKILL.md：定义触发条件、边界、工作流及检查项；scripts/：存放确定性脚本（仅在必要时使用）；references/：按需加载的详细参考资料；assets/：模板或非敏感示例文件；- 可选的宿主特定元数据。
这种设计采用渐进式披露（Progressive Disclosure）来降低默认上下文负载：元数据用于发现，SKILL.md 说明执行路径，支持文件仅在需要时加载。注意，各宿主未必以相同方式实现每个阶段。
什么内容适合封装为 Skill
- 跨会话或跨仓库重复使用的方法；
- 显著影响安全执行的领域规则；
- 具有明确输入、输出、停止条件和检查项的有限序列；
- 比重新生成更安全的确定性脚本。
稳定的权威规则应保留在仓库或用户指令中。普通事实应放入文档。若缺失的是实时连接而非操作流程，请使用 MCP 或其他集成方式。
示例骨架
---
name: verify-release
description: Check a release candidate after code is already staged; do not deploy.
---
# Verify release
1. Read the repository release policy completely.
2. Confirm the working tree and target version.
3. Run the smallest checks, then the full offline baseline.
4. Record commands, exit states, and skipped live checks.
5. Stop on credentials, destructive migration, or deployment request.
描述部分需包含触发条件和排除项。正文应提供证据和停止条件，而非激励性文字。
测试 Skill
测试范围应超出文件夹有效性验证：
保留激活失败的示例。否则，由于仅观察到成功演示，描述范围会随时间推移而变得过于宽泛。
风险与权衡
- 指令可能与更高优先级的策略或仓库规则冲突；
- 脚本和包可能以完整用户权限执行；
- 冗长的技能会消耗上下文，导致机械执行取代判断力；
- 描述过浅会导致误报，过窄则会导致漏触发；
- 宿主特定功能可能使名义上便携的技能失去可移植性；
- 复制的技能会老化、分叉并引入供应链风险。
将第三方技能视为代码进行审查，在必要时固定来源，将密钥保留在包外，并在隔离工作区中测试。技能应减少重复推理同时保持决策可见，而非成为隐藏在 Markdown 中的第二个应用程序。