Skill 技能

一、定义

Skill 是一种可复用的 Prompt 增强包，通过渐进式加载机制为 Agent 注入领域知识和工作流程。
Anthropic 将 Skill 规范作为开放标准发布，目前已被多个 Agent 产品采纳，包括 Claude Code、OpenAI Codex、GitHub Copilot、VS Code、Cursor、Gemini CLI、Kiro 等。

按照我的理解，Skill 就是将一个固定的 Prompt 提示词进行打包，省去每次编写，供模型调用。
比如，我经常使用 AI 工具将工作内容进行汇总并生成报告，报告的要求包括字数、日期、错别字检查、格式等，这些规则都是固定的。如果没有 Skill，每次都要写大致相同的 Prompt 提示词。有了 Skill 之后，我可以先让 AI 工具生成这些规则的 Skill，以后每次只调用这个 Skill 执行，简化每次编写相同 Prompt 提示词的工作。

二、Skill 与 Prompt 的区别

Prompt：临时指令，每次对话都要重写，易遗忘、占上下文。
Skill：长久指令包，可复用，不占对话空间。

三、Skill 目录

文件夹结构

/├── SKILL.md            # 必需：入口（含 YAML frontmatter）├── scripts/            # 可选：可执行脚本├── templates/          # 可选：代码/文档模板├── references/         # 可选：详细参考资料└── assets/             # 可选：静态资源

Skill 的核心是 SKILL.md，它包含了 Skill 的元数据（如名称、描述、输入输出格式、权限要求等）以及核心指令。Agent 会根据对话意图自动匹配并加载相关 Skill，然后按需读取 references/ 中的详细资料，调用 scripts/ 中的可执行代码，最后返回结构化结果。

SKILL.md

在 SKILL.md 中，你需要定义 Skill 的元数据和指令。

字段	是否必填	说明	约束
name	是	Skill 的唯一标识名	最多 64 个字符，仅允许小写字母、数字和连字符，不能以连字符开头或结尾，不能包含连续连字符，必须与所在文件夹名一致
description	是	描述这个 Skill 做什么、什么时候使用	最多 1024 个字符，不能为空，应该包含帮助 AI 识别相关任务的关键词
license	否	许可证信息	许可证名称或指向许可证文件的引用
compatibility	否	环境兼容性要求	最多 500 字符，说明需要的运行环境或依赖
metadata	否	自定义扩展元数据	键值对映射，可存储规范之外的额外属性
allowed-tools	否	预授权工具列表	空格分隔的字符串，实验性功能

正文部分就是 Skill 的核心指令。对正文格式没有硬性限制，只要能帮助 AI 有效执行任务即可。建议包含以下内容：分步骤的操作说明、输入输出示例、常见边界情况处理。建议正文控制在 500 行以内。如果内容较多，可以把详细的参考资料拆分到单独的文件中。

---name: my-skill-name              # kebab-case，与目录同名description: |  一句话讲清"做什么 + 何时使用"，写够触发关键词allowed-tools:                   # 工具白名单，收敛权限  - read_file  - run_terminalmetadata:  version: 0.1.0  tags: [vue, frontend]--- ---以下正文## 目标 (Purpose)xxxxx## 适用 / 不适用场景xxxxx## 输入 (Inputs)xxxxx## 执行流程 (Procedure)## 输出契约 (Output Contract)   ← 文件落点、格式、字段## 参考资料                      ← 链到 references/

四、如何编写

无需手动编写上述 SKILL 目录中的文件内容，我们可以让 AI 工具帮忙生成 SKILL。大部分工具都提供 SKILL 的创建功能。比如，Claude Code 提供了 create-skill Skill，我们可以使用它来创建 SKILL。

我们只需要在对话框中输入 Skill 的功能详细要求，例如：“请使用 create-skill 帮我创建 Skill，这个 Skill 需要帮我汇总我的工作内容，生成一个工作报告，字数 500 字”

五、如何安装

SKILL 本身就是一个文件夹，无需安装。我们只需要将 SKILL 文件夹放到 AI 工具的目录下，如：C:\Users\Administrator\.claude\skills 目录下即可。这是一个用户级的 SKILL，可在该用户下的所有项目中使用。

特别注意：SKILL 往往会区分项目级和用户级。项目级 SKILL 只能在当前项目中使用，用户级 SKILL 可以在所有项目中使用。
项目级与用户级只是存放的目录不同。找对文件夹，就可以使用了。

不同 AI 工具对 Skill 的存放路径有所不同：

工具	用户级路径	项目级路径
Claude Code	~/.claude/skills/	<项目根目录>/.claude/skills/
Trae	~/.trae/skills/	<项目根目录>/.trae/skills/
VS Code (Kiro)	~/.kiro/skills/	<项目根目录>/.kiro/skills/
Cursor	~/.cursor/skills/	<项目根目录>/.cursor/skills/

Windows 路径示例：

• 用户级：C:\Users\<用户名>\.claude\skills\
• 项目级：D:\MyProject\.claude\skills\

六、如何被加载

三层渐进式加载机制是 Skills 规范最精妙的设计，借鉴了 UI/UX 领域的渐进式信息披露策略：

层级	加载内容	加载时机	Token 成本
L1 目录层	name + description	会话启动时	每个 Skill ~50-100 tokens
L2 指令层	完整 SKILL.md body	Skill 被激活时	建议 <5000 tokens
L3 资源层	scripts/、references/、assets/ 中的文件	指令引用时按需	视文件大小

七、如何触发执行

3 种方式：

1. 用户使用命令触发

   ：比如在对话框输入”/skill-name 按照要求执行，给我生成工作报告”。其中”/skill-name”就是命令。

2. 用户提示词触发

   ：比如在对话框输入”使用 skill-name 的 Skill，按照要求执行，给我生成工作报告”。其中”使用 skill-name 的 Skill”就是提示词。

3. 自主触发

   ：比如在对话框输入”按照要求执行，给我生成工作报告”。模型会根据对话内容，自动判断是否需要调用 Skill。这个过程因为是由模型自己判断的，所以可能会触发，也可能不会触发。触发的核心是匹配 SKILL.md 文件中的 name + description 字段。

八、执行流程

用户请求 →
Agent 解析意图 →
扫描 Skill 的 name + description →
命中后加载 SKILL.md →
按需读取 references、scripts、templates、allowed-tools →
返回结构化结果

十、调试与排错

验证 Skill 是否加载

1. 重启 AI 工具（部分工具需要重启才能识别新 Skill）
2. 在对话中输入 /skills 或询问 “列出可用的 Skills”
3. 检查 Skill 目录名称是否与 name 字段一致

常见错误

错误现象	可能原因	解决方法
Skill 无法触发	name 或 description 不匹配	检查关键词是否包含在描述中
YAML 解析失败	格式错误或特殊字符	使用 YAML 验证工具检查
脚本无法执行	权限不足或路径错误	检查文件权限和相对路径
模板变量未替换	变量名拼写错误	核对模板中的占位符名称

十一、版本管理

版本号规范（SemVer）

• MAJOR.MINOR.PATCH

  （如 1.2.3）

• MAJOR：不兼容的 API 变更

• MINOR：向下兼容的功能新增

• PATCH：向下兼容的问题修复

更新 Skill 的最佳实践

1. 修改前先备份旧版本
2. 更新 metadata.version 字段
3. 在 references/ 中添加 CHANGELOG.md 记录变更
4. 测试验证后再正式使用

十二、安全性注意事项

allowed-tools 权限控制

• 只声明实际需要的工具
• 避免使用通配符（如 *）授权所有工具
• 敏感操作（如删除文件）需要谨慎授权

敏感信息处理

• 不要在 Skill 中硬编码 API Key、密码等敏感信息
• 使用环境变量或用户输入获取敏感信息
• 示例：

## 输入- apiKey: API 密钥（通过环境变量 MY_API_KEY 读取）

脚本安全

• 审查 scripts/ 目录下的所有脚本
• 避免执行来自不可信来源的代码
• 对用户输入进行验证和过滤