本节目标:学完你能在本地(或 Claude 产品支持 Skills 的环境里)交出一个可被自动触发的 Agent Skill 目录:含合格的 SKILL.md frontmatter、一段可执行说明,以及至少一次「相关请求会触发 / 无关请求不触发」的自测记录。
最终成品长这样:
weekly-report-from-notes/
SKILL.md
不是写一篇提示词博客,是让代理在对的时候自己把说明书抽出来用。
前置要求

- 有可用的 Claude 环境(claude.ai 自定义 Skill、Claude Code,或其它已支持 Agent Skills 规范的客户端)。
- 会用文本编辑器新建文件夹;不要求会 Python。
- 建议先扫一眼官方概述:Agent Skills overview(核对 2026-10-27)。
没有「第 0 课」硬前置。若你连大模型聊天都没用过,先去随便聊三次再回来。
概念:Skill 不是「更长的系统提示」

我当初卡在这里大概两天:以为把常用提示词塞进 Preferenes 就够了。官方把差异说清楚了——对话级提示适合一次性任务;Skill 是文件系统里的可复用说明书,元数据常驻,正文按需加载(progressive disclosure)。启动时只预载各 Skill 的 name/description;真正匹配到任务,才去读 SKILL.md 正文和其它引用文件(见 overview 与 工程博文)。
生活类比:description 是通讯录备注(「修水管 / 周日急单也接」);SKILL.md 正文是上门维修清单。备注写错,电话永远打不进来;清单写错,人来了也修不好。
分步实操

步骤 1:建目录与最小 frontmatter

做什么:新建文件夹 weekly-report-from-notes,放入 SKILL.md。
为什么:官方要求每个 Skill 必须有带 YAML frontmatter 的 SKILL.md;name 仅小写字母/数字/连字符,最长 64;description 非空、最长 1024,且不要用第一人称(best practices)。
---
name: weekly-report-from-notes
description: Turns messy notes into a concise Chinese weekly report with decisions, blockers, and next actions. Use when the user asks for 周报, 周进展, or pastes unordered work notes.
---
# 周报整理
## 输出
只用:本周完成 / 关键决策 / 阻塞 / 下周计划 / 需要你支持。
禁止把「讨论过」写成「已完成」。
若信息不足,写「待补充」,不要编造。
步骤 2:装进你的客户端并做一次「应触发」测试

做什么:按你使用的产品文档安装/上传该 Skill(各客户端入口不同,以官网「Create custom skills」为准:claude.com/docs/skills/how-to)。然后新开对话,只发:
帮我把这些笔记收成周报:
- 修了支付回调
- 登录改版会议未决
为什么:你要验证的是「discovery」,不是文笔。看它是否加载了该 Skill(有的 UI 会显示所用 Skill;没有就看输出是否遵循你的五段结构)。
步骤 3:做一次「不应触发」反测
新开对话,问一句无关的:
这段 Python 为什么抛 KeyError?
若它仍扯上周报 Skill,说明 description 太宽——把「documents / 帮助写作」这类空词删掉,换成更窄的触发语。
步骤 4:把正文加硬规则(质量层)
在 SKILL.md 正文补上:
- 总字数上限;
- 禁止词(赋能、闭环、抓手…);
- 「未决必须标明未决」。
再拿同一段笔记跑。触发问题靠 description;写虚问题靠正文。
步骤 5:记录一张自测表(交作业用)
| 用例 | 期望 | 实际 | 改动 |
|---|---|---|---|
| 「收成周报」+笔记 | 触发 | ||
| 「周进展」无笔记 | 触发并要求补充 | ||
| 纯代码报错 | 不触发 |
常见报错(≥3)

1. Skill 安装了但从不动。
先查 description 是否第三人称、是否包含用户真实口头禅。官方明确:description 决定选不选得中。把 Helps with documents 这种废句子杀掉。
2. YAML 解析失败 / Skill 不出现。
常见原因:frontmatter 上下 --- 缺失;name 里有空格或大写;description 里出现 XML 尖括号。按 best practices 的字段约束逐项对。
3. 触发对了但输出仍假大空。
这不是 discovery 问题。给正文加「禁止把讨论写成完成」和固定标题;必要时加一节负面示例(贴一段你讨厌的周报,写上「禁止模仿」)。
4. 正文越写越长,反而变笨。
官方建议 SKILL.md 正文尽量控制在约 500 行内,细节拆到同级引用文件且只从 SKILL.md 引用一层。周报 Skill 用不到那么长;如果你开始粘贴公司制度全文,请拆 reference/policy.md。
5. 从不可信来源装了带脚本的 Skill。
工程博文与文档都警告:Skill 可带指令与代码,存在数据外传与误操作风险。只装可信来源;第三方 Skill 先通读再启用。
课后练习

基础题:把本节周报 Skill 的触发词改成适配你团队黑话(例如「周五趴」=周报),完成三行自测表。
进阶题:再做一个 meeting-actions Skill:输入会议纪要,只输出「负责人 / 截止日期 / 验收标准」三列表;与周报 Skill 并存时,确保「整理会议待办」不会误触发周报。
下一课预告
第 2 课:给 Skill 加 reference/ 与「先写计划文件再执行」的校验环——适合开始处理 PDF/表格这类易失手任务。
本系列目录(规划):①自动触发的最小 Skill(本课)→ ②渐进披露与引用文件 → ③带脚本的 Skill 与安全审计 → ④用真实失败用例迭代 description。


Список комментариев (0 записей):
Показать ещё отзывы Загрузка...