Skill（技能）详解：从概念到发布
发布日期：2026-08-07
主题：CodeBuddy / Codex / Claude 等 AI 编程助手中的 Skill 机制
一、什么是 Skill
Skill（技能）是 AI 编程助手的一种"扩展能力系统"，本质上是给 AI 提供的一份“专业培训手册 + 工作流模板”。
它把某个特定领域的最佳实践、操作流程、参考文档封装成一个可复用的模块，让通用模型在处理该领域任务时表现得像专家。
举个直白的类比：
一个通用 AI 助手好比一个"什么都会一点的多面手"；
Skill 则像给它发了一张"专科医生执业证"——遇到对应的病症时，它就知道该按什么流程检查、关注哪些要点、输出什么格式的结果。
与 Slash Command（斜杠命令）的区别
| Slash Command | Skill | |
|---|---|---|
| 触发方式 | 用户手动输入/xxx | AI根据任务自动识别并调用（也可手动触发） |
| 使用场景 | 固定、重复的操作 | 需要按需加载的专业能力 |
| 资源消耗 | 每次输入都执行 | 渐进式加载，按需读取 |
codebuddy中skill的位置，其他AI编程工具也同理。
二、Skill 的目录结构与文件格式
存放位置
Skill 必须放在约定的固定位置，否则不会被识别：
.codebuddy/skills/xxx-skill/ # 项目级（仓库根目录，可团队共享） ~/.codebuddy/skills/xxx-skill/ # 用户级（个人使用）注意：Skill不能随便放在项目根目录。根目录放的是
AGENTS.md（项目全局指令），两者职责不同。
目录内部结构
一个 Skill 是独立目录，至少包含SKILL.md：
release-docs/ ├── SKILL.md # 必填，核心文件 ├── references/ # 参考资料/检查清单（可选） ├── scripts/ # 可执行脚本（可选） ├── examples/ # 示例输出（可选） └── assets/ # 模板/静态资源（可选）如图：
SKILL.md 文件格式
SKILL.md由YAML Frontmatter（元数据）+Markdown 指令（正文）两部分组成。
Frontmatter 常用字段：
| 字段 | 必填 | 说明 |
|---|---|---|
name | 否 | 技能名称，默认取目录名 |
description | 否 | 最重要，帮助 AI 判断何时使用，要写清晰具体 |
allowed-tools | 否 | 工具白名单，支持模式匹配，如Bash(git:*) |
disable-model-invocation | 否 | true时仅可手动/skill-name触发 |
user-invocable | 否 | false时从/菜单隐藏 |
context | 否 | fork时在独立 subagent 上下文执行 |
agent/model/hooks | 否 | 配合context: fork使用 |
最小可用的 SKILL.md 示例：
--- name: pdf description: PDF 文档解析和转换专家，可将 PDF 提取为 Markdown/HTML 等格式 allowed-tools: Read, Write, Bash, WebFetch --- # PDF 处理专家 你是一个专业的 PDF 文档处理专家。 ## 核心能力 - 提取 PDF 文本内容 - 转换 PDF 为 Markdown、HTML 等格式 ## 工作流程 1. 读取文档 2. 提取内容 3. 输出转换结果三、Skill 的调用过程
Skill 采用的是渐进式信息披露（Progressive Disclosure）机制，核心目的是节约上下文窗口（token）。整个调用分为三个阶段：
第 1 步：启动注册（只读元数据）
CodeBuddy 启动时扫描技能目录，对每个 Skill只读取 Frontmatter 中的name+description，放入 AI 的"已知技能清单"。此时不读取正文，消耗极小的上下文。
第 2 步：按需加载（匹配触发）
当你在对话中提出任务时，AI 将你的需求与每个 Skill 的description进行匹配：
- 匹配 → 读取完整的
SKILL.md正文，获得审查流程、维度、报告格式等指令 - 不匹配 → 不加载，节省上下文
触发方式有两种：
- 自动触发：AI 根据
description判断任务相关，主动调用 - 手动触发：用户显式输入
/skill-name或指名调用
第 3 步：运行时引用（按需读取参考资料）
执行任务时，AI 按SKILL.md的指引按需打开references/等目录里对应的文件。比如审查前端代码就读frontend-checklist.md。这些清单"用到才读"，不会在每次对话都加载。
调用过程总览（流程图）
下图完整展示了一次 Skill 调用的流程：
┌─────────────────┐ │ 用户提出任务 │ └────────┬────────┘ │ ▼ ┌─────────────────────────────────────┐ │ 【阶段一：启动注册】 │ │ CodeBuddy 扫描技能目录 │ │ 只读取各 Skill 的 name + description│ └────────┬────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ 【阶段二：按需加载】 │ │ AI 匹配任务与 description │ └────────┬─────────────┬──────────────┘ │ 匹配 │ 不匹配 ▼ ▼ ┌──────────────────┐ ┌──────────────────────┐ │ 读取完整 SKILL.md │ │ 不加载该 Skill │ │ 正文（流程/维度/ │ │ （节省上下文） │ │ 报告格式等） │ └──────────────────────┘ └────────┬─────────┘ │ ▼ ┌─────────────────────────────────────┐ │ 【阶段三：运行时引用】 │ │ 按类型按需读取 references/ 清单 │ │ （如前端→frontend-checklist.md） │ └────────┬────────────────────────────┘ │ ▼ ┌──────────────────┐ │ AI 执行审查/任务 │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 输出结构化结果 │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 结束 │ └──────────────────┘图中三个方框分别对应上文三个阶段：阶段一 启动注册 → 阶段二 按需加载 → 阶段三 运行时引用。可以看到
references/只有在最后阶段、且匹配到对应类型时才被读取。
谁在"读取"？
需要澄清一个关键点：不是某个固定程序在读取清单，而是 AI 模型（LLM）本身。
references/里的清单、SKILL.md里的指令，本质都是喂给模型的文本。模型利用推理能力逐项核对、判断、生成报告。因此：
你补充清单 = 给 AI 更多审查依据；
清单只是"提词器"，最终判断靠模型的智能。
四、Skill 的发布与共享
发布方式取决于你想共享的范围：
1. 团队内共享（最简单）
把.codebuddy/skills/目录随代码仓库提交，团队成员 clone 后技能自动生效。
2. 个人分发
把 Skill 目录放到用户的~/.codebuddy/skills/，或写个安装脚本。
3. 插件市场分发（最正式）
将 Skill 打包成插件发布到插件市场，可被更广范围的用户安装，且不受skillOverrides设置影响。
可见性管理（skillOverrides）
可在 settings 中配置控制 Skill 可见性，无需修改 SKILL.md：
| 值 | 对模型可见 | 在/菜单 |
|---|---|---|
on | 名称 + 描述 | 是 |
name-only | 仅名称 | 是 |
user-invocable-only | 隐藏 | 是 |
off | 隐藏 | 隐藏 |
五、最佳实践
写 SKILL.md 的建议
description要具体：❌处理文件→ ✅PDF 文档解析和转换专家...- 提供详细的核心能力、工作流程、工具列表
- 只授予必需的工具权限，最小化安全风险（如
Bash(git:*)精确控制） - 复杂任务可补充分级标准、边界约束、示例报告（参考下面实践案例）
安全注意事项
⚠️admin-trusted 安全闸门：来自非内置来源的 Skill 的 frontmatterhooks默认不会注册。需在~/.codebuddy/settings.json中设置"allowUntrustedFrontmatterHooks": true才能启用——这是为了防范恶意 Skill。
六、实践案例：xinjie-review 技能
今天我用本仓库真实创建了一个全栈审查技能xinjie-review，可作为参考模板。
NPM仓库地址：https://www.npmjs.com/package/xinjie-review
发布文章：Skill 从零编写到发布上线
目录结构
.codebuddy/skills/xinjie-review/ ├── SKILL.md # 核心定义 ├── README.md # 使用说明 ├── references/ # 分类检查清单 │ ├── frontend-checklist.md │ ├── backend-checklist.md │ ├── style-checklist.md │ ├── document-checklist.md │ ├── flowchart-checklist.md │ └── dependency-security-checklist.md ├── examples/ │ └── sample-review.md # 示例报告 └── scripts/ └── gen-report.sh # 报告生成脚本设计要点（值得借鉴）
- 多类型覆盖：SKILL.md 定义了"自动识别类型"表，支持前端/后端/样式/文档/流程图等混合审查
- 统一分级标准：为 🔴阻断 / 🟠严重 / 🟡建议 / 🔵风格 定义了明确的判定标准表和优先级规则，保证不同模型判定一致
- 边界约束：明确"只审查不擅自修改，除非用户明确要求"，防止审查过程中意外改动代码
- PR/MR 审查流程：基于
git diff的输出流程，支持 Approve / Request changes 结论 - 示例参照：提供
examples/sample-review.md，让 AI 首次输出格式不走样
实测效果
用该技能审查了一段 Vue 登录组件，准确识别出：
- 🔴 阻断级：
v-html渲染接口数据（XSS 风险） - 🟠 严重级：
await无 try/catch 导致 loading 卡死、调试日志泄露 - 🟡 建议级：魔法数字、高频轮询无缓存
- 同时肯定了定时器正确清理等亮点
输出为带文件 + 行号 + 问题 + 影响 + 修复建议的结构化分级报告。
七、总结
Skill 是 AI 编程助手中"把专家经验封装为可复用模块"的机制，核心价值在于：
- 让通用模型在特定领域表现更专业
- 通过渐进式披露节约上下文
- 实现团队/社区的技能复用与共享
如果你要创建一个 Skill，记住三步：建目录 → 写SKILL.md→ 放到约定位置。官方也提供了skill-creator技能辅助初始化。
🚀 感谢阅读！想了解更多？
📖 我的博客网站 | 记录思考，分享干货
🏡 我的个人主页 | 关于我、开源项目