Skills技能

Skill 可以先理解成“把一类任务的成熟做法外置成说明书”

学习时别只看概念，最好跟着 SKILL.md 的结构想一个你自己的重复任务：什么时候触发、要遵守哪些规则、需要哪些脚本或资料。读完后能判断一件事该写进系统提示、做成工具、放进记忆，还是沉淀成 Skill。

都塞进prompt的弊端：

• Prompt 越来越长，每次调用都浪费上下文。
• 同一套规则到处复制，多个 Agent 很难保持一致。
• 规则、模板、脚本、示例散落在聊天记录、代码注释和文档里。
• 多智能体项目里，每个 Agent 到底掌握哪些能力不清楚。
• 团队成员很难复用彼此已经打磨好的工作流。

Skills 的价值，就是把这些反复使用的经验整理成可复用、可发现、可按需加载的能力包。

先记住一个简化公式：Skill = 可复用提示词 + 专业流程 + 可选脚本 + 可选资源

 

三个关键词

关键词	含义	例子
可复用	一套能力可以给多个任务使用	代码审查标准、报告模板、测试修复流程
可发现	Agent 能先看到技能名和描述	通过 name 和 description 判断要不要用
按需加载	不用一开始把全部内容塞进上下文	任务匹配后再读完整 SKILL.md、模板、脚本和资源

这三个词合起来，就是 Skills 在工程上的核心价值。

skill.md目录结构

一个标准 Skill 通常是一个文件夹，里面至少包含一个 SKILL.md 文件。

示意结构：

skills/
  emoji-translator/
    SKILL.md

• skills/ 是技能目录；
• emoji-translator/ 是某个具体技能包；
• SKILL.md 是这个技能包的说明文件。

元数据字段：

字段	作用	建议
name	技能唯一名称，通常和技能文件夹名保持一致	使用小写字母、数字和短横线，避免空格和中文名
description	告诉模型这个技能什么时候应该被使用	写清楚“做什么”和“什么时候用”

因为模型通常会先看 name 和 description，再决定是否加载完整 Skill。如果描述太模糊，Skill 就可能触发不了；如果描述太宽泛，又可能在不该触发时被错误触发。

扩展字段：

字段	常见用途
license	标记 Skill 的许可证
compatibility	说明依赖环境、网络访问、运行时限制
metadata	放作者、版本、团队、维护信息
allowed-tools	限制 Skill 激活后可用的工具，部分平台支持
module	指向可导入模块或辅助代码，部分 Agent Skills 实现支持

扩展目录结构：

code-reviewer/
  SKILL.md
  requirements.txt
  references/
    java-style-guide.md
    security-checklist.md
  scripts/
    run_static_check.py
  assets/
    review-template.md

路径	作用
SKILL.md	技能说明、触发规则、执行步骤
requirements.txt	这个技能需要的 Python 依赖
references/	技能需要参考的文档、规范和模板
scripts/	技能执行时可能调用的脚本
assets/	样例、图片、表格、素材文件

其中 references/ 可以继续按用途拆分：

子目录或文件	适合存放的内容
templates/	报告模板、代码模板、标准输出模板
examples/	输入输出样例，帮助 Agent 理解预期格式
config/	检查规则、字段映射、默认参数等配置文件
style-guide.md	团队编码规范、写作规范、品牌规范

正文内容：

信息	要回答的问题
角色定位	这个 Skill 让 Agent 扮演什么专业角色
触发边界	什么时候用，什么时候不用
执行步骤	按什么顺序完成任务
资源引用	需要读哪些模板、规范、样例或脚本
输出格式	最终结果应该长什么样

渐进式加载机制

层级	加载内容	什么时候加载
元信息层	name、description 等 Frontmatter	Agent 启动或扫描 Skills 时
指令层	完整 SKILL.md 正文	模型判断当前任务需要这个 Skill 时
资源执行层	references/、scripts/、assets/	只有任务真的需要时，才进一步读取或运行

description

好的描述

description: 当用户要求审查 Markdown 技术教程的结构、标题层级、代码块说明和读者理解难度时使用。

这类描述同时包含了：

• 任务对象：Markdown 技术教程；
• 任务动作：审查结构、标题、代码块说明；
• 触发条件：用户要求审查文档；
• 适用边界：不是所有文档都触发。

 

怎么测试skills的稳定性

可以准备三类测试句：

测试句类型	目的	示例
明确触发	验证模型知道应该用这个 Skill	“请用代码审查技能审查这个 diff。”
隐含触发	验证描述是否覆盖真实表达	“帮我看看这个 PR 有没有安全和边界问题。”
不应触发	验证边界是否清楚	“解释一下这段代码在做什么。”

如果明确触发都不稳定，通常是路径、元数据或工具配置问题。 如果隐含触发不稳定，通常是 description 写得不够贴近真实用户表达。 如果不应触发时频繁触发，通常是 description 写得太宽。

区分：

Prompt 是临时指令。
Rules 是常驻规矩。
Memory 是历史状态。
Skill 是可复用做法。

Tool、MCP、Skill 经常放在一起讨论，但它们解决的问题不一样：

形式	解决什么问题	一句话理解
Tool	执行一个明确动作	“我能做什么动作”
MCP	用统一协议接入外部工具和资源	“外部能力怎么标准化接进来”
Skill	封装任务方法、流程、规则和资源	“遇到这类任务应该按什么方法做”

如何写一个高质量SKILL

description的写法

要点	示例
做什么	审查 Python / FastAPI 后端代码
什么时候用	当用户要求 code review、查找 bug 或安全风险时
处理什么输入	diff、PR、文件路径、代码片段
不要太泛	不要写成“帮助写代码”这种所有场景都可能匹配的描述

推荐模板：

description: 当用户要求【任务动作】，并且输入是【输入类型】，目标是【预期结果】时使用。不要用于【排除场景】。

什么时候写SKILLS

适合使用 Skill 的场景：

• 一套提示词会被多个 Agent 或多次任务复用；
• 某个任务有固定步骤和输出格式；
• 某项能力需要附带脚本、模板或参考资料；
• 希望把“能力说明”从主提示词里拆出来；
• 希望减少主 Agent 的 system prompt 长度；
• 团队有一套希望复用的标准流程；
• 某类任务需要按需加载大量上下文，而不是每次都塞进 Prompt。

判断口诀：

这个能力会重复用吗？
它有明确触发条件吗？
它有固定步骤或输出格式吗？
它需要附带模板、资料或脚本吗？
它不适合每次都放进主提示词吗？

常见问题排查：

问题现象	排查方向
Agent 完全不知道 Skill 存在	目录是否放对，工具是否支持该目录，是否需要重启或重新加载
Skill 目录存在但没有触发	description 是否明确写出触发场景
触发了错误的 Skill	多个 Skill 描述是否过于接近，职责是否重叠
触发后输出仍不稳定	SKILL.md 是否写清执行步骤、输出格式和失败处理
找不到资源或脚本	相对路径是否正确，是否在 SKILL.md 中明确引用
脚本运行失败	依赖是否安装，权限是否足够，脚本是否依赖不存在的环境变量
Skill 越写越长	是否应该拆成多个小 Skill，或把大段资料移入 references/
Agent 每次都加载 Skill	描述是否写得太宽泛，是否应该改成 Rules 或项目级说明

这里要记住：Skill 不是自动插件系统，它主要靠元数据、描述和任务匹配，让模型判断什么时候该用哪项能力。

最后要分清边界：

能力	主要解决什么问题
Prompt	当前任务的一次性指令
Rules / AGENTS.md	项目长期规则、团队偏好、常驻上下文
Memory	历史事实、用户偏好、长期状态
Tool	执行明确动作，如搜索、查库、写文件
MCP	标准化接入外部工具、资源和服务
Agent / Subagent	决策、规划、分工和执行
Skill	提供可复用的专业提示词、SOP、脚本和资源