Skill（技能）详解
Skill技能详解从概念到发布发布日期2026-08-07主题CodeBuddy / Codex / Claude 等 AI 编程助手中的 Skill 机制一、什么是 SkillSkill技能是 AI 编程助手的一种扩展能力系统本质上是给 AI 提供的一份“专业培训手册 工作流模板”。它把某个特定领域的最佳实践、操作流程、参考文档封装成一个可复用的模块让通用模型在处理该领域任务时表现得像专家。举个直白的类比一个通用 AI 助手好比一个什么都会一点的多面手Skill 则像给它发了一张专科医生执业证——遇到对应的病症时它就知道该按什么流程检查、关注哪些要点、输出什么格式的结果。与 Slash Command斜杠命令的区别Slash CommandSkill触发方式用户手动输入/xxxAI根据任务自动识别并调用也可手动触发使用场景固定、重复的操作需要按需加载的专业能力资源消耗每次输入都执行渐进式加载按需读取codebuddy中skill的位置其他AI编程工具也同理。二、Skill 的目录结构与文件格式存放位置Skill 必须放在约定的固定位置否则不会被识别.codebuddy/skills/xxx-skill/ # 项目级仓库根目录可团队共享 ~/.codebuddy/skills/xxx-skill/ # 用户级个人使用注意Skill不能随便放在项目根目录。根目录放的是AGENTS.md项目全局指令两者职责不同。目录内部结构一个 Skill 是独立目录至少包含SKILL.mdrelease-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 中的namedescription放入 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技能辅助初始化。 感谢阅读想了解更多 我的博客网站 | 记录思考分享干货 我的个人主页 | 关于我、开源项目
)
