11
1
1

AI 总记不住你的规矩?一个 SKILL.md 把它调教成老员工

文章摘要
|

深色终端界面上的 AI agent 输出

不知道你有没有这种体验:每次开新会话,都得把同一套规矩重新交代一遍——「commit message 用 Conventional Commits 格式」「周报按这个模板写」「部署前先跑测试」。AI 一边点头一边忘,下个会话照样我行我素。把提示词存成备忘录反复粘贴,治标不治本。

这个问题在去年十月被 Anthropic 用一个相当优雅的方案解决了:Agent Skills。它的思路简单到离谱——把某个场景的完整操作手册写成一个 Markdown 文件,放进约定目录,AI 自己判断什么时候该翻它。这个格式后来开放成了标准(agentskills.io),GitHub 上的 anthropics/skills 官方仓库和社区的 awesome-agent-skills 收集了成百上千个现成技能,B站和各大技术社区今年的讨论热度也一直没降过。

这篇文章带你从零写一个能用的 Skill,所有格式约束都来自官方规范原文,抄作业即可。

一、本质上就是一个文件夹

终端与代码的赛博风格插画

一个 Skill 长这样:

my-skill/
├── SKILL.md        # 必须:元数据 + 指令正文
├── scripts/        # 可选:可执行脚本
├── references/     # 可选:参考文档
└── assets/         # 可选:模板等资源

没有 JSON,没有注册中心,没有上传接口(对 Claude Code 而言)。SKILL.md 是唯一必须的东西,其余目录按需加。指令写得再长都不怕,因为 AI 只在任务匹配时才会去读全文——这个机制后面细说。

二、动手写一个:Git 提交信息管家

拿一个几乎人人用得上的场景练手:让 AI 按你团队的规范写 commit message。新建文件夹 commit-butler,写入 SKILL.md:

---
name: commit-butler
description: 按团队 Git 提交信息规范生成和改写 commit message。当用户要求写提交信息、检查提交格式或抱怨 commit 不规范时使用。
---

# Commit Butler

## 格式规范
- 标题行不超过 50 字符,使用祈使句(如 "Add login page")
- 标题与正文之间空一行,正文每行不超过 72 字符
- 类型前缀从这些里选:feat / fix / docs / refactor / test / chore

## 工作流程
1. 先跑 `git diff --cached --stat` 看暂存区的变更概览
2. 判断本次变更属于哪种类型,说明选择理由
3. 给出草稿,等用户确认
4. 确认后才执行 `git commit`,禁止擅自提交

## 特殊情况
- 同一次提交混了多种类型时,建议用户拆分提交而不是硬凑前缀
- 涉及数据库迁移的变更,提醒在正文中注明回滚方案

就这么多。保存文件,这个 Skill 就已经「存在」了。

frontmatter 有几条硬性约束,来自规范原文,写错了轻则不触发、重则直接校验失败:

  • name(必填):最多 64 字符,只能用小写字母、数字和连字符,不能以连字符开头或结尾
  • description(必填):最多 1024 字符,非空,要说清「这个技能做什么、什么时候用」
  • 可选字段:license、compatibility(环境要求)、metadata、allowed-tools,一般用不上

三、放到哪,怎么触发

以 Claude Code 为例,位置有两个,对应两种作用范围:

# 个人技能:所有项目共享
~/.claude/skills/commit-butler/SKILL.md

# 项目技能:只对当前仓库生效,可以提交进 git 给团队共用
你的项目/.claude/skills/commit-butler/SKILL.md

放好后不用任何注册命令。下次你在这个环境里说「帮我写个提交信息」,AI 会自己发现有个叫 commit-butler 的技能跟当前任务对得上,主动加载它、照着手册干活。用 claude.ai 网页版的话,则是 Settings → Capabilities → Skills 里上传打包好的文件夹。

这里就轮到 Agent Skills 最值得称道的设计了——渐进式加载(progressive disclosure),官方把它拆成三个阶段:

  1. 发现:会话启动时只加载每个技能的 name 和 description,占用极小
  2. 激活:任务描述和某个技能对上了,才把完整的 SKILL.md 读进上下文
  3. 执行:按指令干活,必要时才去执行 scripts/ 里的代码、翻 references/ 里的文档

换句话说,你可以在手边囤几十个技能,平时它们只是几十行「名片」,context 几乎不涨;哪个技能被用上,哪个才展开全文。这也是它比「把所有规矩塞进 system prompt」高明的地方——后者是常驻开销,前者按需付费。

四、description 写不好,技能就是摆设

技能的触发判断完全依赖 description——AI 在「发现」阶段看不到正文,只能靠这段话决定要不要翻开手册。所以它是整个 Skill 里最值得反复打磨的一行字。

一个对比例子:

❌ description: 处理提交 —— 没说处理什么、没说何时用,AI 根本不知道该不该调它
✅ description: 按团队 Git 提交信息规范生成和改写 commit message。当用户要求写提交信息、检查提交格式或抱怨 commit 不规范时使用。

写法上记住三点:用第三人称描述(「生成和改写」而不是「我可以帮你」);先说做什么,再说什么时候用;把用户可能的口语化说法也塞进去,比如「抱怨 commit 不规范」这种,触发命中率会明显变高。

五、想直接抄作业

官方仓库 anthropics/skills 里有一批成品:处理 docx / xlsx / pptx / pdf 的文档技能(解包、改 XML、再打包的老套路都替你封装好了),还有若干示例技能可以当范文。社区维护的 awesome 列表更是覆盖了代码审查、数据处理、部署流程各种场景。

看别人的 SKILL.md 时可以留意一个规律:写得好的技能往往正文很短、references/ 很厚——高频指令放正文,低频细节放参考文档,这本身就是渐进式加载思想的延续。

写在最后

Agent Skills 满一年了。回头看它流行起来的原因,可能恰恰是反直觉的那一点:它没有发明任何新东西,只是把「给 AI 的知识」还原成了文件系统里的一个文件夹——可版本管理、可 code review、可团队共享。提示词工程折腾了这几年,最后发现 git 才是提示词最好的归宿。

下次再发现自己第 N 次向 AI 重复同一段要求时,停一下,花十分钟把它写成 SKILL.md。这十分钟是复利的开始。


以上内容为 GLM 5.3 Agent 整合定时发布。

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或者给予支持!

AI 总记不住你的规矩?一个 SKILL.md 把它调教成老员工
/archives/tech-blog-2026-10-15
作者
番茄酱唉
发布于
2026-10-15
许可协议
CC BY-NC-SA 4.0

评论

欢迎来到我的博客!