怎么写一个规范标准的skill

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

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

一、skill 到底是什么

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

结构:

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

二、SKILL.md 的规范

头部 frontmatter(必需,字段就这两个是关键的):

markdown 复制代码
---
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。

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

markdown 复制代码
---
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(周报、代码规范、某个特定工具的操作流程 ...),我直接帮你按这个格式写一版,你稍微改一下就能用。

相关推荐
wflynn13 小时前
Google 观察到首个全自动化网络攻击,AI 框架已能独立完成漏洞利用
ai·技术
zdr尽职尽责14 小时前
终端工具凭空消失:Codex + GPT-6 的一次完整排障复盘
数据库·gpt·学习·ai
佛系18916 小时前
从服务端日志精确分离搜索抓取、监控探测与真实流量的实操清单
ai·大模型·seo·geo·结构化数据·indexnow
一起学安全技术21 小时前
拆大模型 11|大模型面试拷问:12 问逐层拆
人工智能·ai·语言模型·面试·职场和发展·求职招聘
TomEval1 天前
【测AI】第26篇:线上模型监控与告警体系 — 测试不是终点
人工智能·python·功能测试·ai
AI算力2 天前
企业调研——工业边缘计算隐形黑马,腾视科技以“硬件+算法”加速出海落地!
人工智能·ai·边缘计算·ai算力·无人叉车·物理ai·ainas
真上帝的左手2 天前
26. AI-大语言模型-基础
人工智能·ai·架构·llm·大语言模型
七夜zippoe3 天前
流式输出:让 AI 回答像打字机一样实时返回(SSE 全链路实战)
人工智能·spring·ai·流式输出·ssf
装不满的克莱因瓶3 天前
【AI时代必学】一篇文章教会你从零搭建Serverless架构
java·人工智能·ai·云原生·架构·serverless
七夜zippoe3 天前
多轮对话管理:Session/记忆在 Java 后端怎么存(存储设计实战)
java·开发语言·ai·session·记忆