二、什么是 Skills
Skills 类似于为 AI 助手提供的“专业培训”。通过 Skill，你可以：
·封装专业知识：将特定领域的最佳实践和操作流程封装成可复用的技能
·提供工作流模板：定义标准化的任务处理流程，提高工作效率
·扩展 AI 能力：让 AI 助手能够处理更专业、更复杂的任务
·团队协作共享：项目级 Skills 可以在团队成员间共享专业知识
三、Skills vs Slash Commands
| 特性 | Skills | Slash Commands |
| 触发方式 | AI 模型自动识别并调用 | 用户手动输入命令 |
| 使用场景 | 专业领域任务处理 | 快捷操作和工作流 |
| 权限控制 | 支持工具白名单限制 | 无特殊权限控制 |
| 工作目录 | 支持自定义基础目录 | 使用当前工作目录 |
| 可见性 | 对用户透明，AI 自动决策 | 用户主动发起 |
简单来说：
·Slash Commands 是用户主动调用的快捷方式
·Skills 是 AI 根据任务需求自动选择的专业能力
五、目录结构
Skills 通过在特定目录中创建 SKILL.md 文件来定义：
1. 项目级 Skills：.codebuddy/skills/（项目根目录下）
2. 用户级 Skills：~/.codebuddy/skills/（用户主目录下）
每个 Skill 一个独立的目录，包含 SKILL.md 文件：
.codebuddy/skills/├── pdf/ │ └── SKILL.md├── data-analysis/│ └── SKILL.md└── code-review/ └── SKILL.md
六、SKILL.md 格式
Skill 文件使用 Markdown 格式，支持 YAML Frontmatter 定义元数据：
—name: pdfdescription: PDF 文档处理专家allowed-tools: Read, Write, Bash, WebFetch—你是一个 PDF 文档处理专家，擅长：- 解析和提取 PDF 内容- 转换 PDF 为其他格式- 生成 PDF 报告当用户需要处理 PDF 相关任务时，请使用以下工作流：1. 首先检查 PDF 文件是否存在2. 使用适当的工具提取内容3. 根据需求进行处理4. 生成结果报告可用工具：- pdftotext：提取文本内容- pdfinfo：获取 PDF 信息
七、Frontmatter 字段
| 字段 | 是否必填 | 说明 | 示例 |
| name | 否 | Skill 名称，未指定时使用目录名 | |
| description | 否 | Skill 描述，帮助 AI 理解何时使用 | PDF 文档处理专家 （project) |
| allowed-tools | 否 | 允许使用的工具白名单，逗号分隔 | Read, Write, Bash |
| disable-model-invocation | 否 | 设置为 true 时，Skill 不会出现在 Skill 工具中，只能通过 /skill-name 手动触发 | true |
| user-invocable | 否 | 设置为 false 时，Skill 从 / 菜单中隐藏，仅供 AI 内部调用或其他 Skill 引用，默认 true | false |
| context | 否 | 设置为 fork 时，Skill 在独立的 subagent 上下文中执行 | fork |
| agent | 否 | 指定 subagent 类型，仅在 context: fork 时有效 | Explore |
| model | 否 | 指定 Skill 执行时使用的模型（仅 context: fork 时生效，未配置时回退到 agent 默认模型） | claude-sonnet-4 |
| hooks | 否 | 在 SKILL.md 中声明 Skill 专属的 Hooks，仅 context: fork 时生效，详见 在 Skill 中配置 Hooks | 见下文 |
八、变量占位符
SKILL.md 内容支持以下占位符，加载或执行时自动替换。同样的占位符也适用于自定义斜杠命令和 subagent 定义。
| 占位符 | 替换为 | 适用来源 |
| ${CODEBUDDY_PLUGIN_ROOT} | 插件安装根目录 | 仅插件来源的 skill |
| ${CODEBUDDY_SKILL_DIR} | 当前 SKILL.md 所在目录的绝对路径 | 所有来源 |
| ${CODEBUDDY_SESSION_ID} | 当前会话 ID（运行时注入） | 所有来源 |
| ${MY_ENV_VAR} 等大写环境变量 | process.env.MY_ENV_VAR 的值 | 所有来源 |
| ${MY_ENV_VAR:-默认值} | 环境变量，缺失时使用默认值 | 所有来源 |
为与 Claude Code 保持兼容，${CLAUDE_PLUGIN_ROOT}、${CLAUDE_SKILL_DIR}、${CLAUDE_SESSION_ID} 也被识别为等价的别名。
未设置的环境变量占位符会原样保留，不会被替换为空字符串；用户或项目来源的 skill 中 ${CODEBUDDY_PLUGIN_ROOT} 会保留字面量（该变量仅适用于插件来源）。
示例：
—description: 带占位符的 skill 示例—读取脚本 @${CODEBUDDY_SKILL_DIR}/scripts/analyze.py 并使用密钥 ${MY_API_TOKEN:-dev-fallback} 执行。当前会话标识：${CODEBUDDY_SESSION_ID}
九、执行 Shell 命令
与斜杠命令一样，Skills 也支持在 SKILL.md 中使用 !command“ 语法内联执行 Shell 命令。当 Skill 被触发时（无论是 AI 自动调用还是用户通过 /skill-name 手动触发），这些命令会被执行，输出结果会替换到 Skill 内容中，供 AI 后续分析。
示例：
—description: 项目状态分析—### 当前工作目录!`echo "CWD=$(pwd)"`### Git 状态!`git status –short`### 最近提交!`git log –oneline -5`请基于以上信息分析项目当前状态。
十、支持的特性
·$ARGUMENTS 参数替换：在 Shell 命令执行前，$ARGUMENTS 会被替换为用户传入的参数
·@file 文件引用：Shell 命令执行后，@file 引用会按大小和 token 上限处理；小文件直接注入，较长内容会截断并附继续读取提示，超大文件保留原始引用
·错误隔离：单个命令执行失败不会影响其他命令，失败的命令会被替换为空字符串
处理管道：$ARGUMENTS 替换 → !command“ 执行 → @file 引用处理，与斜杠命令的处理顺序一致。
十一、Context Fork
context: fork 使 Skill 在隔离的子代理上下文中运行，不访问对话历史。
—name: deep-researchdescription: 深入研究某个主题context: forkagent: Explore—研究 $ARGUMENTS：1. 使用 Glob 和 Grep 查找相关文件2. 读取并分析代码3. 总结发现并附加具体文件引用
十二、可用 Agent 类型
| 类型 | 说明 |
| general-purpose | 通用（默认） |
| Explore | 只读工具，优化代码库探索 |
| Plan | 规划和分析 |
| 自定义 | .codebuddy/agents/ 中定义的 agent |
十三、隐藏 Skill（user-invocable）
user-invocable: false 使 Skill 从 / 菜单中隐藏，适用于：
·背景知识类 Skill（如项目规范、编码标准）
·仅供其他 Skill 或 AI 内部引用的辅助 Skill
—name: project-guidelinesdescription: 项目编码规范和最佳实践user-invocable: false—# 项目编码规范本项目遵循以下编码标准：- 使用 TypeScript 严格模式- 函数命名使用 camelCase- 组件命名使用 PascalCase…
这类 Skill 会被加载到 AI 的上下文中，但用户无法通过 / 菜单直接调用。
十四、执行流程
1. 创建新的隔离上下文
2. 子代理接收 Skill 内容作为提示
3. agent 字段决定执行环境
4. 结果返回主对话
注意：context: fork 只适用于包含明确任务的 Skill。仅有指导方针没有具体任务时，不会产生有意义的输出。
十五、在 Skill 中配置 Hooks
版本要求：Skill frontmatter hooks 字段需要 CodeBuddy Code 支持 Frontmatter Hooks 的版本（Beta）。
除了在 ~/.codebuddy/settings.json 中全局配置 Hooks，Skill 还可以直接在 SKILL.md 的 frontmatter 里声明 hooks 字段，把 Hook 与 Skill 自身打包在一起。这对于 fork 类 Skill 尤其有用——可以在 fork subagent 内部加守卫、日志、回调，且不污染主会话。
十六、适用范围
·仅 context: fork 生效：注入路径（默认 inline 模式）的 Skill 没有清晰的生命周期边界，frontmatter hooks 会被解析但不会注册到运行时。
·生命周期与 fork subagent 绑定：fork subagent 启动时注册 hooks，结束时自动清理，不影响主会话和其他 Skill。
·Stop 自动转 SubagentStop：在 frontmatter 中写 Stop event 会被自动重写为 SubagentStop，对齐 subagent 完成的真实事件。
十七、字段格式
hooks 字段的结构和 settings.json 中的 hooks 完全一致——按事件名分组、每条配置可带 matcher 和 hooks[] 数组：
—name: secure-reviewerdescription: 代码审查 Skill，在执行前检查文件白名单context: forkagent: Explorehooks: PreToolUse: – matcher: "Read|Glob|Grep" hooks: – type: command command: ${CODEBUDDY_SKILL_DIR}/scripts/check-paths.sh timeout: 10 PostToolUse: – matcher: "Bash" hooks: – type: prompt prompt: "检查 Bash 输出是否包含敏感信息，发现则在 reason 字段说明。" Stop: # 自动重写为 SubagentStop – hooks: – type: command command: echo "review skill finished" >> ${CODEBUDDY_PROJECT_DIR}/.cbc-review.log—请审查 $ARGUMENTS 中提到的文件…
支持的 hook type：
·command：执行 Shell 命令（含 shell: bash | powershell、timeout、if、once、async 等可选字段）
·prompt：交给小模型（默认 Haiku 级）做语义判定
·agent：起一个 subagent 做更复杂的判定，可以指定 agentType / model
·http：把事件 payload 通过 POST/PUT/PATCH 发到指定 URL
完整字段语义请参考 Hook 参考指南。
十八、安全闸门：admin-trusted
出于安全考虑，来自非内置来源的 Skill frontmatter hooks 默认不会被注册。当前所有通过 .codebuddy/skills/、项目本地、插件市场加载的 Skill 都属于“非可信来源”——它们可以静默触发 Shell 命令，因此需要用户显式同意。
启用方式：在 ~/.codebuddy/settings.json 中设置
{ "allowUntrustedFrontmatterHooks": true}
启用后所有来源的 Skill / Agent frontmatter hooks 才会被注册；否则 CLI 会输出类似下面的 warning 并跳过该 Skill 的 hooks：
[AgentTask] Frontmatter hooks from skill 'secure-reviewer' skipped(source not admin-trusted; enable `allowUntrustedFrontmatterHooks` in settings to allow)
内置 product-bundled 的 Skill 不受此闸门约束，自动放行。Plugin 通过 hooks/hooks.json 配置的 hooks 走另一条路径，不受该闸门控制。
十九、与全局 hooks 的合并
Skill frontmatter hooks 和 settings.json 中的全局 hooks 是叠加合并关系——同一事件下两边的所有匹配 hooks 都会被并行触发，不存在覆盖。区别在于：
| 来源 | 作用域 | 是否受 admin-trusted 闸门约束 |
| settings.json (全局/项目/local) | 整个会话 | 否 |
| Plugin hooks/hooks.json | 整个会话（插件启用时） | 否 |
| Agent .md frontmatter | 该 subagent 生命周期 | 是 |
| Skill SKILL.md frontmatter（仅 fork） | 该 fork subagent 生命周期 | 是 |
20、调试
·启动时设置 CODEBUDDY_DEBUG=1，可以在日志看到 [ScopedHookRegistry] registered N hook config(s) for scope … 等注册行。
·frontmatter 里非法的 hook 定义会被静默丢弃，但会在日志输出 [parseFrontmatterHooks] skill 'xxx': event 'YYY' invalid: …，仔细看日志即可定位。
22、示例 1：PDF 处理 Skill
文件：.codebuddy/skills/pdf/SKILL.md
—name: pdfdescription: PDF 文档处理和转换专家allowed-tools: Read, Write, Bash, WebFetch—# PDF 处理专家你是一个专业的 PDF 文档处理专家。## 核心能力- 提取 PDF 文本内容- 转换 PDF 为 Markdown、HTML 等格式- 合并和拆分 PDF 文件- 提取 PDF 元数据和书签## 工作流程1. 检查 PDF 文件是否存在并可访问2. 使用 pdftotext 或 pdfinfo 获取基本信息3. 根据任务类型选择合适的处理工具4. 验证输出结果的完整性## 可用工具- pdftotext：提取纯文本- pdfinfo：获取文档信息- pdftk：合并拆分操作
使用：当用户询问“帮我提取这个 PDF 的内容”时，AI 会自动识别需要 PDF 处理能力并调用该 Skill。
23、示例 2：数据分析 Skill
文件：~/.codebuddy/skills/data-analysis/SKILL.md
—name: data-analysisdescription: 数据分析和可视化专家allowed-tools: Read, Write, Bash, WebFetch, NotebookEdit—# 数据分析专家你是一个专业的数据分析师，擅长使用 Python 和相关工具进行数据分析。## 核心能力- 数据清洗和预处理- 统计分析和建模- 数据可视化- 生成分析报告## 分析流程1. 理解数据结构和质量2. 清洗和预处理数据3. 执行统计分析4. 创建可视化图表5. 生成分析结论## 工具库- pandas：数据处理- numpy：数值计算- matplotlib/seaborn：可视化- scikit-learn：机器学习## 最佳实践- 始终先探索数据质量- 使用 Jupyter Notebook 进行交互式分析- 保存中间结果避免重复计算
24、示例 3：代码审查 Skill
文件：.codebuddy/skills/code-review/SKILL.md
—name: code-reviewdescription: 代码审查和质量检查专家allowed-tools: Read, Grep, Bash, Edit—# 代码审查专家你是一个经验丰富的代码审查者，遵循业界最佳实践。## 审查重点1. **代码质量** – 命名规范 – 代码复杂度 – 重复代码2. **安全性** – SQL 注入风险 – XSS 漏洞 – 认证授权问题3. **性能** – 算法效率 – 资源使用 – 缓存策略4. **可维护性** – 代码注释 – 模块化设计 – 测试覆盖## 审查流程1. 理解代码变更的目的2. 检查代码风格和规范3. 分析潜在的 Bug 和性能问题4. 验证安全性5. 提供建设性的改进建议## 输出格式- 优点：列出做得好的地方- 问题：指出需要改进的地方- 建议：提供具体的改进方案
25、AI 如何选择 Skills
AI 根据以下因素决定是否调用 Skill：
1. 任务匹配度：任务描述与 Skill description 的相关性
2. 工具需求：任务所需工具是否在 allowed-tools 范围内
3. 上下文相关性：当前对话上下文是否适合使用该 Skill
4. Skill 来源：项目级 Skills 优先于用户级 Skills
26、从设置覆盖 Skill 可见性（skillOverrides）
skillOverrides 设置让你在不修改 SKILL.md 的情况下，从 settings 控制单个 Skill 的可见性，适用于你不方便改动的 Skill（例如提交进共享仓库的项目 Skill）。
配置位于 settings 的 skillOverrides，按 Skill 名索引，每个值为四态之一：
| 值 | 对模型可见 | 在 / 菜单 | 说明 |
| on | 名称 + 描述 | 是 | 不覆盖，回退 SKILL.md frontmatter 现状 |
| name-only | 仅名称 | 是 | 折叠描述，省 context 预算 |
| user-invocable-only | 隐藏 | 是 | 对模型隐藏（不进清单），用户与模型按名调用仍放行 |
| off | 隐藏 | 隐藏 | 对模型与菜单都隐藏，按名调用返回禁用提示 |
/skills 菜单把 user-invocable-only 状态标注为 user-only；这只是显示用短标签，写进配置文件的仍是规范值 user-invocable-only。
未列出的 Skill 视为 on。示例：
{ "skillOverrides": { "legacy-context": "name-only", "deploy": "off" }}
设为 off 后，/skill-name 及模型按名调用都会被拦截并提示：
Skill "<name>" is disabled via skillOverrides. Re-enable it in /skills or remove the override from your settings to run it.
要点：
·plugin Skill 不受 skillOverrides 影响，改用 /plugin 管理；在 /skills 里显示为锁定（locked by plugin），不可编辑。
·/skills 菜单可视化编辑：↑/↓ 选择，enter / space / ←/→ 循环切换状态，按 Esc 时统一写入 .codebuddy/settings.local.json 并提示本次改动数量（Updated N skill override / No changes）；未按 Esc 直接离开则不落盘。
·生效优先级：PROJECT_LOCAL（.codebuddy/settings.local.json）> PROJECT（.codebuddy/settings.json）> USER（~/.codebuddy/settings.json），高优先级按 Skill 名覆盖低优先级。工作区根即 home 时，PROJECT 与 USER 为同一文件。
·非法值自动回退：合并前会先过滤掉不属于四态的非法值，因此高优先级文件里的非法值不会遮蔽低优先级文件里的合法值（回退到上一个有效文件）；全部非法时该 Skill 视为 on。
28、allowed-tools 白名单
通过 allowed-tools 字段限制 Skill 可以使用的工具：
allowed-tools: Read, Write, Bash(git:*), Grep
支持的工具模式匹配：
·Bash(git:*) – 只允许 git 相关命令
·Edit(src/**/*.ts) – 只允许编辑特定路径文件
29、工作目录限制
每个 Skill 都有自己的 baseDirectory（SKILL.md 所在目录），可以在 Skill 指令中引用：
当处理文件时，优先在 {baseDirectory} 目录下查找相关资源。
31、1. 清晰的 Skill 描述
# ✖ 不好description：处理文件# ✔ 好description: PDF 文档解析和转换专家，支持文本提取和格式转换 （project)
32、2. 详细的指令内容
提供详细的：
·核心能力说明
·标准工作流程
·可用工具列表
·常见场景处理方法
·输出格式要求
33、3. 合理的工具权限
只授予必需的工具权限：
# ✖ 权限过大allowed-tools: Bash# ✔ 精确控制allowed-tools: Read, Write, Bash(git:status,git:diff), Grep
34、4. 组织 Skill 目录
按功能领域组织 Skills：
.codebuddy/skills/├── document/│ ├── pdf/SKILL.md│ └── markdown/SKILL.md├── data/│ ├── analysis/SKILL.md│ └── visualization/SKILL.md└── code/ ├── review/SKILL.md └── refactor/SKILL.md
36、查看已加载的 Skills
使用 /skills 命令查看当前已加载的所有 Skills：
/skills
Skills 面板会显示：
·User skills：用户级 Skills（~/.codebuddy/skills/）
·Project skills：项目级 Skills（.codebuddy/skills/）
·Plugin skills：插件提供的 Skills
每个 Skill 会显示名称和预估的 token 数量。
37、常见问题
Q: Skill 没有被触发？
·检查 description 是否清晰描述了 Skill 的功能
·确认任务描述与 Skill 能力匹配
·验证 allowed-tools 是否包含所需工具
Q: Skill 权限不足？
·检查 allowed-tools 配置
·确认工具名称拼写正确
·使用模式匹配精确控制权限
Q：项目级和用户级 Skill 冲突？
·项目级 Skills 优先级更高
·使用不同的 name 避免冲突
39、Skills + Memory
Skills 可以访问 Memory 系统存储的信息：
在执行数据分析时，参考 Memory 中保存的数据模式和业务规则。
40、Skills + Slash Commands
Slash Commands 可以引用 Skills：
<!– .codebuddy/commands/analyze-data.md –>请使用 data-analysis skill 分析文件：$1
41、Skills + MCP
Skills 可以调用 MCP 提供的外部工具（如果在 allowed-tools 中）。
42、下一步
·斜杠命令 – 了解用户主动命令
·设置配置 – 配置工具权限
·MCP 集成 – 扩展外部工具能力