Skip to content
从零手写第 5 / 5 节

技能: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:

markdown
---
name: weekly-report
description: 把一个文件夹里的工作记录整理成一份周报
---

# 写周报

1. 用 list_dir 看看给定文件夹里有哪些记录文件,用 read_file 逐个读。
2. 按“本周完成 / 进行中 / 下周计划 / 需要协助”四个小标题整理,每条一句话,写明是哪天的事。
3. 不要编造记录里没有的内容;记录里没写的小标题就写“无”。
4. 用 write_file 把结果写到 周报.md,写之前把全文给用户看一眼。

规范里的两个必填字段:

字段要求
name不超过 64 个字符,只能用小写字母、数字和连字符,必须和所在文件夹同名
description1 到 1024 个字符,写清“做什么”和“什么时候用”

可选字段有 license、compatibility、metadata,以及实验性的 allowed-tools。

渐进式披露:不用一次全读 ​

如果有几十个技能,全塞进提示词太浪费。规范的做法分三层:

  1. 启动时只读元数据:每个技能的 name 和 description,约 100 个 token;
  2. 用到时再读正文:整个 SKILL.md,建议少于 5000 个 token、500 行以内;
  3. 需要时才读资源:附带的脚本和参考文件。

让自己的 Agent 支持技能 ​

规范网站上专门有一篇“给你的 Agent 加上 Skills 支持”。核心就两件事:把技能目录放进系统提示,提供一个读取技能的办法。我们的实现:

python
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/ 正在成为跨不同客户端通用的技能目录约定。

跑一下 ​

bash
python agent.py "用写周报的技能,把 worklog 文件夹整理成周报"

我们在 qwen3:8b 上的真实运行:

text
  [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:写一个服务器并接上。

搞懂AI关于我们怎么写隐私说明联系我们

独立的第三方教程,与文中提到的任何产品及其公司没有隶属或合作关系;产品名称和商标归各自所有者。价格和政策以官方页面为准。