技能:SKILL.md
读完这一节,你能写一个 SKILL.md,并让自己的 Agent 在需要时自动加载它。我们会用“写周报”这个技能实际跑一遍。
技能是什么
工具解决“能做什么”(读文件、跑命令),技能解决“这件事该怎么做”。
好比公司给新员工的一本操作手册:写周报要分哪几个小标题、不能编造、存成什么文件名……这些不是能力,是做法。把做法写进一个文件,Agent 需要时读一下就会了。
Agent Skills 就是这样一种格式:一个技能就是一个文件夹,里面有一个 SKILL.md(开头一段 YAML 元数据,后面是 Markdown 写的步骤),还可以带脚本、参考资料等。
来历:Anthropic 在 2025 年 10 月 16 日发布了 Skills,2025 年 12 月 18 日把 Agent Skills 作为开放标准发布在 agentskills.io。2026 年 11 月 4 日,项目通过了治理文件,按文件的说法将作为 Linux 基金会旗下的项目设立,许可证 Apache-2.0。
写一个 SKILL.md
我们的“写周报”技能,放在 skills/weekly-report/SKILL.md:
---
name: weekly-report
description: 把一个文件夹里的工作记录整理成一份周报
---
# 写周报
1. 用 list_dir 看看给定文件夹里有哪些记录文件,用 read_file 逐个读。
2. 按“本周完成 / 进行中 / 下周计划 / 需要协助”四个小标题整理,每条一句话,写明是哪天的事。
3. 不要编造记录里没有的内容;记录里没写的小标题就写“无”。
4. 用 write_file 把结果写到 周报.md,写之前把全文给用户看一眼。规范里的两个必填字段:
| 字段 | 要求 |
|---|---|
name | 不超过 64 个字符,只能用小写字母、数字和连字符,必须和所在文件夹同名 |
description | 1 到 1024 个字符,写清“做什么”和“什么时候用” |
可选字段有 license、compatibility、metadata,以及实验性的 allowed-tools。
渐进式披露:不用一次全读
如果有几十个技能,全塞进提示词太浪费。规范的做法分三层:
- 启动时只读元数据:每个技能的 name 和 description,约 100 个 token;
- 用到时再读正文:整个 SKILL.md,建议少于 5000 个 token、500 行以内;
- 需要时才读资源:附带的脚本和参考文件。
让自己的 Agent 支持技能
规范网站上专门有一篇“给你的 Agent 加上 Skills 支持”。核心就两件事:把技能目录放进系统提示,提供一个读取技能的办法。我们的实现:
def load_skills():
skills = {}
for f in sorted((HERE / "skills").glob("*/SKILL.md")):
meta = dict(re.findall(r"^(\w+):\s*(.+)$", f.read_text(encoding="utf-8").split("---")[1], re.M))
skills[meta["name"]] = (meta["description"], f)
return skills
SKILLS = load_skills()
def load_skill(name): # 用到时才把完整说明读进来(渐进式披露)
return SKILLS[name][1].read_text(encoding="utf-8") if name in SKILLS else f"没有叫 {name} 的技能"
SYSTEM = ("……\n可用技能(需要时先 load_skill):\n"
+ "\n".join(f"- {n}:{d}" for n, (d, _) in SKILLS.items()))再把 load_skill 加进工具列表。规范还给了两个建议:工具的 name 参数最好做成枚举(只允许已有的技能名),防止模型编出不存在的技能;没有任何技能时,就不要放空目录、也不要注册这个工具。另外,.agents/skills/ 正在成为跨不同客户端通用的技能目录约定。
跑一下
python agent.py "用写周报的技能,把 worklog 文件夹整理成周报"我们在 qwen3:8b 上的真实运行:
[1] load_skill({"name": "weekly-report"})
[2] read_file({"path": "/worklog/11-16.txt"})
[3] list_dir({"path": "./worklog"})
[4] read_file({"path": "./worklog/11-16.txt"})
[5] read_file({"path": "./worklog/11-18.txt"})
[6] read_file({"path": "./worklog/11-20.txt"})
Agent:周报整理结果:
# 周报
## 本周完成
- 周一:修复登录页在 Safari 上的样式错位
……
## 需要协助
- 无
确认内容后我会生成周报.md 文件。注意它做到了技能里写的两件事:四个小标题齐全、没写的就写“无”;写文件前先把全文给你看。这些都不是代码规定的,是 SKILL.md 里写的。
考考你技能和工具的区别是什么?
检查一下
- 我能说出 SKILL.md 的两个必填字段和它们的要求
- 我能解释渐进式披露的三层
- 我跑通了写周报的技能,并写了一个自己的技能
下一章接入生态:MCP:写一个服务器并接上。