从零编写可跨平台复用的代理技能

Agent Skills 值得学的地方，是把反复交代给 AI 的团队流程，整理成可以按需加载的文件。原文以生成 PR 描述为例，从目录、触发说明写到验证方法，给出了一份能照着改的 SKILL.md。

作者还引入了一个变化：据文中转述，Anthropic 已将 Agent Skills 捐赠给基金会。格式走向开放标准，增加了学习它的长期价值；但对程序员更直接的问题是：怎样让技能在该用时被找到，并且按规则做事。

开放标准解决了什么，没解决什么

按原文说法，Anthropic 在 10 月 22 日将 Agent Skills 捐赠给 Agentic AI Foundation。该基金会属于 Linux Foundation 项目，也承载 MCP 和 AGENTS.md。文章援引 Anthropic 公告称，自 2025 年 12 月发布以来，已有超过 70 个 Agent 平台集成该标准，包括 ChatGPT、Cursor、GitHub Copilot 和 VS Code。

这些信息来自原文转述，文章没有提供独立核验过程。

开发者现有文件不用迁移：格式保持不变，规范仍位于 agentskills.io，也不需要加入组织才能使用。作者的判断是，投入编写技能的价值，不再完全依赖某一家厂商的路线。

不过，格式通用不等于使用方式完全一致。原文明确提醒，各工具的技能目录要查各自文档，部分字段的支持情况也有差异。

一个技能就是包含 SKILL.md 的文件夹。文件开头是 YAML frontmatter，至少提供 name 和 description，后面用 Markdown 写指令；目录还可以放 scripts/、references/ 和 assets/。

它通过渐进式披露（progressive disclosure）控制上下文开销：启动时只读名称和描述，规范估算每个技能约占 100 tokens；任务匹配后才加载正文，需要时再读取附带文件。因此，装了几十个技能，并不代表每次都要把几十份完整流程塞进上下文。

技能没触发，先看 description

适合做成技能的任务，需要同时满足三个条件：经常重复、有模型猜不到的约定、结果能够检查。作者选择的 pr-description 就符合：读取当前分支变化，按团队固定格式生成 PR 描述。

在 Claude Code 中，运行 mkdir -p ~/.claude/skills/pr-description 可以创建个人技能目录，对所有项目可用。团队共享则放在仓库的 .claude/skills/pr-description/ 中提交。

名称最多 64 个字符，只能使用小写字母、数字和连字符，不能以连字符开头或结尾，不能出现连续的 --，还必须与文件夹同名。pr-description 合规，PR-Description 和 pr--description 不合规。

但名称正确，只解决了格式问题。

description 决定技能有没有机会被使用，正文决定加载之后怎样执行。

作者建议先写描述，包含「做什么」和「什么时候用」，并覆盖用户实际会说的表达，比如「写 PR 描述」「总结这个分支供评审」「起草 pull request」。

规范对 description 的限制是 1,024 个字符。Claude Code 还会把每项技能的列表文本截断到 1,536 个字符；技能很多时，为了适应预算，可能移除使用较少技能的描述。因此，主要用途应放在前面。原文引用的 Anthropic 最佳实践还建议使用第三人称，比如 Writes...，因为描述会被注入系统提示。

这套写法有实际原因：Agent 选择技能时，尚未读到正文。触发条件只写在正文里，可能根本没有被看到的机会。

一份能用的 SKILL.md，要把哪些约束写死

规范没有强制正文结构，但建议提供步骤、输入输出示例和边界情况，并把 SKILL.md 控制在 500 行以内，长参考材料另放文件。按原文引用的 Claude Code 文档，技能加载后会跨轮次留在上下文中，冗长内容会持续占用空间。

下面是原文完整示例，保存到 ~/.claude/skills/pr-description/SKILL.md，解决「根据分支变化填写团队 PR 模板」的问题：

---
name: pr-description
description: "Writes a pull request description from the current branch's changes, using the team template (summary, changes, testing, risks). Use when the user asks for a PR description, a pull request summary, or wants to open a PR."
---

## PR description

## Steps
1. Run `git log --oneline main..HEAD` and `git diff main...HEAD --stat` to see what changed.
2. Read the diff of the files that changed most.
3. Fill in the template below. Keep each section short.
4. If the branch has no commits ahead of main, say so and stop.

## Template
### Summary
One or two sentences: what this PR does and why.

### Changes
- Bullet per meaningful change, grouped by area.

### Testing
How it was tested. If no tests were added, write "No new tests" and say why.

### Risks
Anything a reviewer should look at closely: migrations, config changes, removed code, public API changes. Write "None found" only if you checked.

## Rules
- Do not invent test results. Only report tests you ran or that exist in the diff.
- Do not mention files that did not change.

重点看最后两条规则：测试结果必须有依据，描述只能涉及实际变化的文件。前面的命令、模板和「没有领先提交就停止」则把执行路径与边界情况固定下来。

随后要分别验证两件事：自然语言请求能不能触发，以及直接输入 /pr-description 能不能运行。原文称，Claude Code 会监听技能目录，新增或修改文件无需重启当前会话。

如果直接调用成功，自然请求失败，作者建议依次检查描述关键词、询问 What skills are available? 确认技能是否列出，再用更接近描述的请求测试。还有一个容易漏掉的原因：按文中说法，YAML 格式错误时，Claude Code 仍可能加载正文，但元数据为空，导致直接调用可用、自动匹配失败。使用 --debug 可以查看解析错误。

误触发则应收窄描述，或在 frontmatter 添加 disable-model-invocation: true，改为仅允许直接调用。项目提供的参考验证器可以检查格式：

skills-ref validate ~/.claude/skills/pr-description

注意这里验证的是规范符合性，不能据此判断 PR 描述是否准确。

我的判断

我认同作者把重点放在描述、执行步骤和验证上。相比每次粘贴长提示词，技能更适合保存稳定的团队约定，也便于随仓库一起维护。

但这是一篇入门教程，作者给出了完整示例和排查路径，没有展示多次运行记录、触发成功率，也没有与普通提示词做对照。标题里的「15 分钟」适合作为上手预期，不能当成效果保证。

示例也有明显前提。它固定以 main 为基准，团队若向其他分支提 PR，就需要调整；只要求读取变化最多文件的 diff，也可能漏掉改动很少却影响很大的配置或公共 API。Testing 部分还应区分「diff 中有测试代码」与「测试已经运行通过」，两者不能混写。

第三方技能的风险同样不能忽略。作者要求检查全部文件，包括脚本、图片和其他资源，留意意外网络请求、异常文件访问和外部 URL 获取的内容。依赖变化也可能改变技能行为。规范中的 allowed-tools 仍是实验字段，各 Agent 支持不同，不能把它当成统一的权限边界。

开放标准降低了格式绑定的顾虑，实际采用时仍需核对工具行为。文章末尾的 6 页速查表，以及包含五个构建教程、十个模板和 30 天计划的 49 页指南，属于延伸材料推广，不能作为上述效果的证据。

能拿来做什么

• 从团队反复使用的 PR 模板开始，把摘要、变更、测试和风险的填写规则写进技能，并按实际目标分支调整示例命令。
• 为前端或 Node 仓库补上能检查的边界规则，例如涉及公共 API、配置和删除代码时必须说明风险，测试执行状态必须有依据。
• 每次修改描述后，都用自然语言请求和 /pr-description 各测一次；触发失败先排查描述、技能列表和 YAML，再修改正文。
• 安装第三方技能前阅读整个目录，确认脚本、外部请求和工具权限与声明用途一致，再决定是否采用。