跳到主要内容

第 4 章 · 创作经验、巧妙之处、边界与横向对比

前三章覆盖了格式、实现、集成。本章是“带走的精华”:怎么写出真正有用的 skill、这套设计妙在哪、它刻意不做什么、以及和 MCP / 普通系统提示的取舍。来源:docs/skill-creation/。

4.1 写好 skill:工程经验​

从真实专长出发,别让 LLM 凭空编​

创作 skill 最常见的坑:直接让 LLM“生成一个 skill”,结果全是“妥善处理错误”“遵循最佳实践”这类空泛废话,而非真正有价值的具体 API 模式、边界情况、项目约定(docs/skill-creation/best-practices.mdx:9-12)。有效 skill 都扎根于真实专长,两条来路:

  • 从一次实操中提炼:和 agent 一起真做一遍任务,记录“哪些步骤成功了、你纠正了什么、输入输出长什么样、你提供了哪些项目特定语境”,再抽成 skill(:14-21)。
  • 从既有资料合成:喂给 LLM 你团队真实的事故报告、runbook、schema、代码评审意见、补丁历史——这些项目特定材料远胜泛泛的“最佳实践文章”(:23-33)。

省着花上下文:补模型缺的,删模型已会的​

skill 激活后整篇正文和对话历史、其他 skill 抢同一个上下文窗口。原则:只写 agent 不写就会做错的东西(docs/skill-creation/best-practices.mdx:47-52)。不用解释“PDF 是什么、HTTP 怎么工作”。对每段内容自问:“没这条指令 agent 会做错吗?”答否就删。

description 是触发的全部赌注​

description 决定 skill 会不会被激活,所以(docs/skill-creation/optimizing-descriptions.mdx:19-26):

  • 用祈使句:“Use this skill when…”而非“This skill does…”——你在告诉模型何时该动手。
  • 聚焦用户意图,不写内部实现。
  • 宁可“推”一点:显式列出适用场景,包括用户没点名领域的情况(“即使没明说 CSV 或 analysis”)。

docs/skill-creation/optimizing-descriptions.mdx:176-189 的 before/after 很典型:从 Process CSV files. 改成同时说清“做什么(统计/派生列/图表/清洗)+ 何时用(CSV/TSV/Excel,即使没点名)”。

一个反直觉的点:单步简单任务可能不触发 skill——“read this PDF”这种 agent 用基础工具就能干,哪怕 description 完美匹配也未必激活;skill 真正发光是在需要专门知识的任务上(docs/skill-creation/optimizing-descriptions.mdx:17)。

校准控制力:脆弱的步骤才写死​

不是每段都要同样强硬(docs/skill-creation/best-practices.mdx:92-141):

  • 多种做法都行、容许变化 → 给 agent 自由,讲清为什么比硬规定更有效。
  • 操作脆弱、必须按序 → 强约束,例如“严格按此命令、别加 flag”。
  • 给默认值,别给菜单:多个工具能用时,挑一个默认 + 简短提逃生口,别并列罗列(:126-141)。

最高价值内容:Gotchas​

很多 skill 里最值钱的是一份 gotchas 清单——“违反合理假设的环境特定事实”(docs/skill-creation/best-practices.mdx:166-185),例如:

## Gotchas
- users 表用软删除。查询必须带 WHERE deleted_at IS NULL,否则会含停用账号。
- 同一个值:数据库叫 user_id,认证服务叫 uid,计费 API 叫 accountId。
- /health 只要 web 起着就返回 200(哪怕数据库挂了)。要查整体健康用 /ready。

这些必须放在 SKILL.md 里(agent 在遇到情况之前就读到),而非藏在 reference 文件——否则 agent 可能根本认不出该去读它(:181)。

用脚本固化重复逻辑 + plan-validate-execute​

若发现 agent 每次都重新发明同一段逻辑(建图、解析某格式、校验),就写一个测试过的脚本放进 scripts/(docs/skill-creation/best-practices.mdx:264-268)。对批量/破坏性操作,推荐 plan-validate-execute:先生成结构化计划 → 用脚本对“真相源”校验 → 再执行(:245-262)。关键是那个校验脚本,它给出的报错信息要足够 agent 自我纠正。

4.2 巧妙之处(可借鉴)​

① 把“能力扩展”降维成“一个文件夹”。 没有插件 API、没有注册中心、没有运行时——一个目录 + 一个带 YAML 头的 Markdown 就是全部。极低门槛带来极强可移植性:同一个 skill 跨产品复用——README.md:28(Cross-product reuse:“Build a skill once and use it across any skills-compatible agent”)是这条断言的总纲,quickstart 进一步点名“同一个 skill 在任何兼容 agent 里都能用,包括 Claude Code 和 OpenAI Codex”(docs/skill-creation/quickstart.mdx:13)。注意:VS Code 在 quickstart 里只是教程宿主编辑器,并非与前两者并列的可移植目标。

② 渐进式披露把“规模”和“成本”解耦。 传统做法是“想让模型懂什么就全塞进系统提示”,skill 多了上下文就爆。三层加载让“挂 20 个 skill”的常驻成本约等于“20 条一句话简介”,正文只在命中时才付费(docs/specification.mdx:214-222)。这是整个格式的核心创新。

③ description 既是文档又是路由键。 同一段文字,对人是“这 skill 干嘛的”,对模型是“要不要激活”的分类特征。所以才有专门的 description 优化方法论(train/validation 切分防过拟合,docs/skill-creation/optimizing-descriptions.mdx:133-160)——把“写文档”变成了可量化的工程问题。

④ i18n 友好做在校验层。 用 str.isalnum() + NFKC 而非 ASCII 正则,让 技能、мой-навык 这类名字天然合法(skills-ref/src/skills_ref/validator.py:37-54)。一个开放标准从第一天就考虑非英语用户,值得借鉴。

⑤ “严格 spec + 宽松集成”分层。 规范本身约束严格(便于工具校验),但建议客户端宽松加载(warn 不拒,容错坏 YAML),以兼容别家写的 skill(docs/client-implementation/adding-skills-support.mdx:128-141)。规范严、运行时松——这是开放生态能互通的关键设计取舍。

4.3 边界与局限(诚实)​

它是约定,不是运行时。 本仓库不提供扫描、激活、把内容塞进模型的引擎;这些全靠客户端实现。规范只定义文件内部,连“skill 放哪个目录”都不规定(docs/client-implementation/adding-skills-support.mdx:54 明说位置不在 spec 管辖内)。.agents/skills/ 只是生态自发约定。

skills-ref 不是生产件。 README 明写“仅供演示、勿用于生产”(skills-ref/README.md:5-6)。它是给客户端开发者看的最小示范,不是要被依赖的库。

激活靠模型判断,本质不确定。 主流实现把激活交给模型自己判断,而非 harness 关键词匹配(docs/client-implementation/adding-skills-support.mdx:238-240)。后果:同一 query 可能这次触发、下次不触发——所以 description 优化要多跑几次算触发率(docs/skill-creation/optimizing-descriptions.mdx:85-89)。skill 触发不是确定性的。

allowed-tools 还是实验性。 规范自己标了实验性,各实现支持程度不一(docs/specification.mdx:166-167)。

安全是天然攻击面。 skill 是“可执行指令载体”,项目级 skill 来自可能不可信的仓库,所以规范要客户端加信任门槛(docs/client-implementation/adding-skills-support.mdx:89-91)。这是格式开放性的代价,需要客户端认真处理。

4.4 横向对比​

Skills vs MCP(Model Context Protocol)​

两者都扩展 agent 能力,但层次不同:

维度Agent SkillsMCP
本质静态知识/指令打包成文件夹运行时协议,agent ↔ 服务器动态通信
载体SKILL.md + 文件工具/资源/prompt 的 JSON-RPC 接口
加载渐进式披露,内容进上下文工具调用,结果返回
解决“agent 不知道该怎么做某类任务”“agent 需要调用外部系统/数据”

直觉:MCP 给 agent “手脚”(调外部系统),Skills 给 agent “知识/手册”(怎么做这件事)。一个 skill 完全可以在正文里指示 agent 去调某个 MCP 工具——二者互补而非竞争。

Skills vs 直接写系统提示​

都是“给模型注入指令”,区别在作用域与加载时机:

  • 系统提示:全程常驻,所有任务都付这笔上下文成本。
  • Skill:按需激活,只有命中的任务才把正文加载进来。

所以当某段专长“只在特定任务用得上”时,做成 skill 比塞进系统提示更省、更可复用(docs/specification.mdx:214-222 的渐进式披露正是为此)。

同 shelf 兄弟​

本库属 ai-protocol-reference(协议库),关切点是“agent 怎么获得能力/知识”。在 prompt-authority / agent-frameworks 这个 area 下,它和

  • MCP(运行时工具协议)互补:Skills 管“知识与流程”,MCP 管“连外部系统”;
  • 各类 agent 框架(如 Letta 等记忆/agent 系统)正交:框架管“怎么跑 agent 循环”,Skills 管“往这个循环里按需注入哪些专长”。

(对比基于本仓库文档与同 shelf 项目的定位;具体兄弟库 doc 以总库 index 为准。)

4.5 代码地图​

主题文件锚点
从真实专长创作docs/skill-creation/best-practices.mdx“Start from real expertise”(:7-33)
省上下文原则docs/skill-creation/best-practices.mdx“Add what the agent lacks…”(:50-76)
校准控制力docs/skill-creation/best-practices.mdx“Calibrating control”(:92-141)
Gotchas 模式docs/skill-creation/best-practices.mdx“Gotchas sections”(:165-185)
plan-validate-executedocs/skill-creation/best-practices.mdx“Plan-validate-execute”(:245-262)
description 优化方法论docs/skill-creation/optimizing-descriptions.mdx“The optimization loop”(:146-160)
触发率多跑docs/skill-creation/optimizing-descriptions.mdx“Running multiple times”(:85-89)
跨产品复用断言README.md“Cross-product reuse”(:28)+ quickstart Note(docs/skill-creation/quickstart.mdx:13)
i18n 校验实现skills-ref/src/skills_ref/validator.py_validate_name(:37-54)