.agents/skills 目录：把技能写进仓库

各家编码代理曾经各有一套技能目录：.claude/skills、.cursor/skills、用户级路径也五花八门。技能写进仓库之后，换一个工具就要复制或软链一遍。.agents/skills 正在变成跨客户端的约定目录：把技能放这里，兼容的代理都能扫到。

为什么要单独搞一个目录

技能（Skill）本质上是一个带 SKILL.md 的文件夹：frontmatter 里至少有 name 和 description，正文是步骤说明，旁边可以挂 scripts/、references/。代理启动时只读名称和描述，任务对上了再加载全文，这叫渐进披露，避免把几十个技能一次塞进上下文。

目录约定解决的是「放哪」：

项目级通常优先于用户级。同名冲突时只生效一个，实现一般会打日志提醒你被盖住了。

不少客户端还会继续扫自家目录（例如 .claude/skills），但新技能优先写进 .agents/skills，别的工具才不用再迁一次。

最小可用结构

在仓库根建一个技能就够起步：

.agents/skills/deploy-check/
├── SKILL.md
└── scripts/          # 可选
    └── smoke.sh

SKILL.md 大致长这样：

---
name: deploy-check
description: 上线前跑冒烟检查时用。包含健康检查 URL 与回滚口令。
---

# 步骤
1. 读环境变量里的健康检查地址，curl 确认 200。
2. 失败则按仓库约定触发回滚，不要自己发明流程。

要点：

• description 是路由键。 写「什么时候该用」，不要写空泛摘要。代理靠这句话决定要不要打开全文。
• 正文按意图写。 别把某次 MCP 工具的参数写死进 skill；接口会变，目标不会。
• 能短就短。 代理已经会的事别复述；只写你们团队特有的规矩和验收标准。

怎么接到常用代理

不同产品对「项目技能目录」的支持进度不一，但方向一致：扫 .agents/skills，或从规范目录软链到自家路径。

实操建议：

1. 新技能只落一份到 .agents/skills/。 不要同时维护三份拷贝。
2. 旧目录用软链过渡。 例如把 .claude/skills/foo 指到 ../../.agents/skills/foo，确认代理能发现后再删重复副本。
3. 提交进 Git。 技能跟代码一样过 PR：有人改了 description 或脚本，review 一眼，避免「本地能用、同事仓库没有」。
4. 敏感信息不进 skill。 密钥、内网地址走环境变量或本机配置；skill 只写怎么读它们。

Cursor、Claude Code、Codex、Gemini CLI、VS Code Copilot、OpenHands 等已在生态里支持或兼容 Agent Skills 形态；以你当前客户端文档为准打开「项目技能」开关即可。Lee 那条帖子的背景，正是 Cursor 把 Agent Skills 做成可发现、可执行的工作流之后，再往跨代理目录靠拢。

和 AGENTS.md 怎么分工

别什么都塞进 skill：

• AGENTS.md（或同类仓库说明）：短、全局、几乎每次对话都相关的约定（分支策略、测试命令、禁止事项）。
• .agents/skills/*/SKILL.md：按需加载的专项流程（发版检查、某 SDK 接入、设计规范落地）。

全局说明太长会占上下文；专项流程塞进 AGENTS.md 又会让无关任务背负噪音。拆开之后，代理只在用得到时才打开技能全文。

落地检查清单

放进仓库前过一遍：

1. 路径是不是 .agents/skills/<kebab-name>/SKILL.md。
2. frontmatter 有没有可触发的 description。
3. 引用的脚本是否可执行、依赖是否写明。
4. 有没有密钥或仅本机可用的绝对路径。
5. 换一个支持 Skills 的客户端，能否仅凭 description 被选中。

做完这些，技能就不再是某个 IDE 的私货，而是仓库资产：clone 下来，兼容代理都能用同一套流程。