Agent Skills

Skill（技能）本质上是一个打包好的标准作业程序（SOP），Agent 在遇到匹配任务时能发现并加载它。通用规范围绕目录结构和 SKILL.md 定义了一套可移植的核心标准；在这之上，各宿主（Host）在发现机制、元数据解析、激活逻辑、工具调用及代码执行权限上各有做法。

技能能不能被用上，取决于一两句描述。Agent 启动时只把每个技能的 name 和 description 放进上下文；你的请求和某条描述对上了，它才去读整份 SKILL.md；references/ 里的文件要等正文让它读时才打开。以下文的 verify-release 为例，平时常驻上下文的只有“Check a release candidate after code is already staged; do not deploy.”这一句；你说“帮我检查一下这个发布候选版本”，Agent 才加载它的五个步骤。这种分层按需加载叫渐进式披露（Progressive Disclosure），它让装了几十个技能的 Agent 默认只多背几十句描述。

需要明确：Skill 是一套约定和内容包，它不是隔离沙箱，也不代表该流程一定有效。

包结构

典型的 my-skill/ 目录包含以下部分：

• SKILL.md：定义触发条件、边界、工作流及检查项；
• scripts/：存放确定性脚本（仅在必要时使用）；
• references/：按需加载的详细参考资料；
• assets/：模板或非敏感示例文件；
• 可选的宿主特定元数据。

截至 2026 年 10 月 1 日，Claude Code、ChatGPT 与 Codex、Gemini CLI、Cursor 和 GitHub Copilot 都在文档中写明支持这一开放格式，差别恰好出现在列出描述、加载正文和激活这几步。

最能说明后果的是 Codex。它给初始技能列表的默认上限是模型上下文窗口的 2%，窗口大小未知时为 8,000 个字符；装的技能多了，它会先缩短描述，还可能干脆不列出一部分技能，所以描述写得含糊的技能可能根本不会被发现。这个上限可以用 skills.max_context_tokens 调整，最多 10,000 个 Token；它只管初始列表，选中某个技能后仍会读完整份 SKILL.md。

其余几家的差别在激活和扩展上。Gemini CLI 在加载技能前会请用户确认，确认后把技能目录加入 Agent 可读取的路径。Claude Code 在格式之上加了自己的字段：disable-model-invocation: true 让技能只能手动调用，context: fork 让技能在子 Agent 里执行。OpenAI 则会从可选的 agents/openai.yaml 读取外观、调用策略和依赖设置。依赖某个宿主扩展功能的技能，只有核心部分能跨宿主使用。

第一个技能放在哪，名字和描述有什么限制

技能文件夹放对位置，宿主才会扫描到它：

宿主	项目里的位置	个人位置	手动调用	关掉自动加载
Claude Code	.claude/skills/<name>/SKILL.md，从启动目录往上找到仓库根	~/.claude/skills/<name>/SKILL.md	/name	disable-model-invocation: true
Codex	.agents/skills，从当前目录往上逐层扫描到仓库根	$HOME/.agents/skills	$name	agents/openai.yaml 里设 allow_implicit_invocation: false
Pi	.agents/skills/，从当前目录往上找到仓库根	~/.agents/skills/	/skill:name	disable-model-invocation: true

SKILL.md 的前置元数据按规范只有两项必填：

• name 最多 64 个字符，只能用小写字母、数字和连字符，不能以连字符开头或结尾，不能出现 --，还必须和文件夹同名。
• description 最多 1,024 个字符，写清它做什么、什么时候用。
• 可选字段有 license、compatibility、metadata 和 allowed-tools，最后一项标为实验性。
• 正文建议不超过 500 行、5,000 个 Token，长的参考资料拆到 references/ 里。

写完可以用规范提供的 skills-ref validate ./my-skill 检查格式。Claude Code 还有自己的限制：列表里 description 加 when_to_use 超过 1,536 个字符的部分会被截掉，所以关键用途要写在最前面。它原来的 .claude/commands/ 自定义命令也已并入技能，同名时技能优先。

什么内容适合封装为 Skill

• 跨会话或跨仓库重复使用的方法；
• 显著影响安全执行的领域规则；
• 具有明确输入、输出、停止条件和检查项的有限序列；
• 比重新生成更安全的确定性脚本。

稳定的权威规则应保留在仓库或用户指令中。普通事实应放入文档。若缺失的是实时连接而非操作流程，就接一个 Model Context Protocol (MCP) 服务器或其他集成。两者也可以一起用。MCP 的官方 Skills 扩展（io.modelcontextprotocol/skills，SEP-2640 已定稿）让服务器把技能文件夹和它描述的服务一起分发。客户端通过 Resources 发现和读取这些技能，宿主加载前仍可要求用户批准。宿主对这个扩展的支持还在陆续实现。

示例骨架

---
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

测试范围应超出文件夹有效性验证：

测试类型	关键问题
正向触发	匹配请求是否能加载该技能？
负向触发	相近但不适用的任务，是否会避免加载该技能？
边界案例	是否在未经授权的工作前停止？
正向任务	Agent 能否生成预期的产物和检查项？
过时引用	移动的命令或 API 是否可见地失败？
可移植性	在另一宿主、模型或工具集下有何变化？

保留激活失败的示例。否则，由于仅观察到成功演示，描述范围会随时间推移而变得过于宽泛。

风险与权衡

• 指令可能与更高优先级的策略或仓库规则冲突；
• 脚本和包可能以完整用户权限执行；
• 冗长的技能会消耗上下文，导致机械执行取代判断力；
• 描述太宽会在不相关的任务上误加载，太窄又会该用时没用上；
• 宿主特定功能可能使名义上便携的技能失去可移植性；
• 复制的技能会老化、分叉并引入供应链风险。

将第三方技能视为代码进行审查，在必要时固定来源，将密钥保留在包外，并在隔离工作区中测试。技能应减少重复推理同时保持决策可见，而非成为隐藏在 Markdown 中的第二个应用程序。

回到阅读路线