怎么写一个规范标准的skill

写一个规范的 skill 其实就三件事：触发描述准、说明书自足、只在真的需要复用时才做。

写一个规范的 skill 其实就三件事：触发描述准、说明书自足、只在真的需要复用时才做。下面按顺序讲，最后给一个完整可复制的模板。

一、skill 到底是什么

一个 skill 就是一个文件夹，里面必有 SKILL.md，可选带脚本、模板、示例数据。当用户的问题匹配上 description 里描述的场景时，SKILL.md 的正文会被自动加载进对话，作为一份"专项操作手册"指导后续动作。

结构：

your-skill-name/
├── SKILL.md          # 必需：触发条件 + 操作指令
├── scripts/          # 可选：可执行的辅助脚本
│   └── helper.py
└── templates/        # 可选：模板、示例
    └── example.docx

二、SKILL.md 的规范

头部 frontmatter（必需，字段就这两个是关键的）：

---
name: your-skill-name
description: 一句话说清楚"什么时候用它、什么时候别用它"
---

name

• kebab-case，全小写，短横线分隔（如 weekly-report、code-review-cn）。
• 就是文件夹名，别放空格、别放中文。

description（最关键的字段）

它是系统决定"要不要激活这个 skill"的唯一依据，写不好等于白做。三个要素缺一不可：

1. 场景动词 ：用户在什么情况下会触发。
   • ✅ "when the user wants to create/edit/read a Word document..."
2. 触发关键词 ：具体到能命中的名词、后缀、动词。
   • ✅ "mentions .docx, .dotx, Word doc, word template, report, memo, letter..."
3. 反向边界 ：什么情况不 用它，避免误触。
   • ✅ "Do NOT use for PDFs, spreadsheets, or general coding tasks."

对比一下：

• ❌ 差的："Helps with documents." ------ 没关键词、没边界，模型永远不确定要不要激活。
• ✅ 好的：官方 docx skill 那种写法 ------ 场景、动词、后缀、反例全都有。

正文（skill 的操作手册）

正文写给"未来的自己（一个冷启动的 Claude）"看的，遵循几个原则：

• 自足：不能引用"上面说过""当前会话"这类相对语境，未来运行时看不到。
• 动作导向：多写"这一步做什么、用哪个命令、怎么验证"，少写背景介绍。
• 踩坑清单要显眼：把最容易出错的点单独列出来（docx skill 那个 "gotchas" 表就是典范）。
• 给验证方法：产出之后怎么确认没错。
• 相对路径引用脚本 ：python scripts/xxx.py，别写绝对路径。

三、写作时容易踩的坑

1. description 只写"做什么"没写"什么时候用"：模型激活率极低。
2. description 写太长又没有关键词：一段模糊的介绍不如一串精确的触发词。
3. 正文塞大量原理解释：skill 是操作手册不是教程，把"为什么这么做"压到一句话，把"怎么做"展开。
4. 把可以放脚本里的东西写成散文 ：能封装成脚本调用的（比如 XML 处理、格式转换），写成 scripts/xxx.py 让正文只调用，一是更短，二是可测试。
5. 忽视"什么时候别用"：反例句能大幅降低误触，务必加上。

四、写完之后怎么保存

你有两个选择：

A. 落地到磁盘手动维护

按上面的目录结构自己建文件夹。但注意：本系统里 skill 是从缓存目录读的，直接改磁盘文件不会持久化到你的账户，重启会丢。

B. 用 save_skill 工具保存 （推荐）

它会把你的 skill 存到账户级别，跨会话都能用。调用形式：

save_skill(
  name="your-skill-name",
  description="一句话触发描述",
  content="完整的 SKILL.md 正文（不含 frontmatter，工具会自动加）"
)

如果是更新已存在的同名 skill，加 overwrite: true。

五、一份可以直接改的最小模板

---
name: weekly-report
description: "Use when the user asks to generate or refresh a weekly work report. Triggers: '周报', 'weekly report', 'this week's summary', 'write up my week'. Also use when the user wants to fill in an existing weekly report template. Do NOT use for daily standup notes, monthly reviews, or one-off status updates --- those are different formats."
---

# Weekly Report Generation

Goal: produce a concise weekly report in the user's preferred format from a list of accomplishments and next-week plans.

## Steps

1. Ask the user for (only what's missing):
   - Time range (default: last Monday--Sunday, in the user's local timezone)
   - Accomplishments this week
   - Plans for next week
   - Blockers / risks (optional)

2. Draft using this structure:
   - 本周完成 (bulleted, past tense, one line each)
   - 下周计划 (bulleted, future tense)
   - 风险与需支持 (only include if user provided any)

3. Save to `weekly-report-{YYYY-MM-DD}.md` in the outputs folder.

## Style rules

- Each bullet ≤ 25 汉字 or ≤ 20 English words.
- Lead with the outcome, not the activity ("完成 X 上线" not "跟进 X 项目").
- No filler words like "积极"、"深入"、"扎实".

## Verify

Before returning: check that every "下周计划" item has an owner or clear deliverable --- if not, ask the user to sharpen it.

---

想的话可以告诉我你想做的是哪一类 skill（周报、代码规范、某个特定工具的操作流程 ...），我直接帮你按这个格式写一版，你稍微改一下就能用。