Agent Skills 开放标准上手：一个文件夹 + 一份 SKILL.md，让技能在 40+ 客户端通用

一个技能是这样一个目录（只有 SKILL.md 是必需的）：

release-checklist/          ← 技能名（小写字母/数字/连字符）
├── SKILL.md                ← 必需：元数据 + 指令
├── scripts/                ← 可选：可执行代码（Python/Bash/JS）
├── references/             ← 可选：按需加载的参考文档
└── assets/                 ← 可选：模板、图片、数据文件

SKILL.md 顶部是 YAML frontmatter，用 --- 包裹。必填字段只有两个：

---
name: release-checklist
description: 执行发布前的验证清单。在打 release 标签或用户说要
  发布上线时使用。需要 git 和 docker 环境。
---

规则要点：name 只能是小写字母、数字、连字符，最长 64 字符，且必须与文件夹名一致；description 最长 1024 字符，要同时说明「做什么」和「什么时候用」——因为它是 Agent 决定是否加载这个技能的唯一依据。另有四个可选字段：license、compatibility（环境要求）、metadata（自定义键值）、实验性的 allowed-tools（预授权工具）。

正文没有格式限制，官方推荐写成分步指令 + 输入输出示例 + 边界情况。以发布检查清单为例：

# 发布前检查

按以下顺序执行，任何一项失败就停止并报告：

1. 检查 git 工作区是否干净：git status
2. 运行完整测试：pytest（失败则修复后重跑）
3. 核对 CHANGELOG 是否包含本次变更
4. 检查 docker 镜像构建是否通过
5. 全部通过后，输出一行总结，并提示可以打 tag

## 边界情况
- 如果第 2 步有 flaky 测试，重跑一次确认
- 不要执行 git push，只负责检查

Agent Skills 已被主流编码客户端广泛支持，装法大同小异：

1. 把技能文件夹放进客户端的技能目录：
   - Claude Code：项目下 .claude/skills/ 或全局 ~/.claude/skills/
   - Cursor：.cursor/skills/
   - Codex CLI：~/.codex/skills/
   - 其他客户端按各自文档放置
2. 重启或刷新客户端
3. 在对话里说「按发布检查清单走一遍」，
   Agent 会命中 description 并加载完整指令执行

技能本质就是 Markdown 文件夹，直接提交进代码仓库即可团队共享。想锁定版本，可用技能安装 CLI：

npx @skills-hub-ai/cli install release-checklist
# 会写入 .skills.json 锁文件，
# 保证团队所有成员的技能在同一版本

技能加载分三个阶段，这也是「装几十个技能不爆上下文」的秘诀：

跨模型兼容方面，规范提供了校验层（skills-ref），确保技能在不同 Claude 模型乃至其他 LLM 后端上都能工作。实测数据显示：基于技能的多步工作流，任务完成率比「一坨大提示词」高 23%～47%。