CodeBuddy Code Skills （技能系统）

Skills 是 CodeBuddy Code 的扩展能力系统，允许您创建专业的领域知识和工作流模板，让 AI 助手能够更专业地处理特定类型的任务。

什么是 Skills

Skills 类似于为 AI 助手提供的"专业培训"。通过 Skill，您可以：

封装专业知识：将特定领域的最佳实践和操作流程封装成可复用的技能
提供工作流模板：定义标准化的任务处理流程，提高工作效率
扩展 AI 能力：让 AI 助手能够处理更专业、更复杂的任务
团队协作共享：项目级 Skills 可以在团队成员间共享专业知识

Skills vs Slash Commands

特性	Skills	Slash Commands
触发方式	AI 模型自动识别并调用	用户手动输入命令
使用场景	专业领域任务处理	快捷操作和工作流
权限控制	支持工具白名单限制	无特殊权限控制
工作目录	支持自定义基础目录	使用当前工作目录
可见性	对用户透明，AI 自动决策	用户主动发起

简单来说：

Slash Commands 是用户主动调用的快捷方式
Skills 是 AI 根据任务需求自动选择的专业能力

创建 Skills

目录结构

Skills 通过在特定目录中创建 SKILL.md 文件来定义：

项目级 Skills：.codebuddy/skills/（项目根目录下）
用户级 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 定义元数据：

markdown

---
name: pdf
description: PDF 文档处理专家
allowed-tools: Read, Write, Bash, WebFetch
---

你是一个 PDF 文档处理专家，擅长：
- 解析和提取 PDF 内容
- 转换 PDF 为其他格式
- 生成 PDF 报告

当用户需要处理 PDF 相关任务时，请使用以下工作流：
1. 首先检查 PDF 文件是否存在
2. 使用适当的工具提取内容
3. 根据需求进行处理
4. 生成结果报告

可用工具：
- pdftotext：提取文本内容
- pdfinfo：获取 PDF 信息

Frontmatter 字段

字段	必填	说明	示例
`name`	否	Skill 名称，未指定时使用目录名	`pdf`
`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`

执行 Shell 命令

与斜杠命令一样，Skills 也支持在 SKILL.md 中使用 !command`` 语法内联执行 Shell 命令。当 Skill 被触发时（无论是 AI 自动调用还是用户通过 /skill-name 手动触发），这些命令会被执行，输出结果会替换到 Skill 内容中，供 AI 后续分析。

示例：

markdown

---
description: 项目状态分析
---

### 当前工作目录

!`echo "CWD=$(pwd)"`

### Git 状态

!`git status --short`

### 最近提交

!`git log --oneline -5`

请基于以上信息分析项目当前状态。

支持的特性

$ARGUMENTS 参数替换：在 Shell 命令执行前，$ARGUMENTS 会被替换为用户传入的参数
@file 文件引用：Shell 命令执行后，@file 引用会被处理并注入文件内容
错误隔离：单个命令执行失败不会影响其他命令，失败的命令会被替换为空字符串

💡 处理管道：$ARGUMENTS 替换 → !command`` 执行 → @file 引用处理，与斜杠命令的处理顺序一致。

Context Fork

context: fork 使 Skill 在隔离的子代理上下文中运行，不访问对话历史。

yaml

---
name: deep-research
description: 深入研究某个主题
context: fork
agent: 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

yaml

---
name: project-guidelines
description: 项目编码规范和最佳实践
user-invocable: false
---

# 项目编码规范

本项目遵循以下编码标准：
- 使用 TypeScript 严格模式
- 函数命名使用 camelCase
- 组件命名使用 PascalCase
...

这类 Skill 会被加载到 AI 的上下文中，但用户无法通过 / 菜单直接调用。

执行流程

创建新的隔离上下文
子代理接收 Skill 内容作为提示
agent 字段决定执行环境
结果返回主对话

注意：context: fork 只适用于包含明确任务的 Skill。仅有指导方针没有具体任务时，不会产生有意义的输出。

使用示例

示例 1：PDF 处理 Skill

文件：.codebuddy/skills/pdf/SKILL.md

markdown

---
name: pdf
description: 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。

示例 2：数据分析 Skill

文件：~/.codebuddy/skills/data-analysis/SKILL.md

markdown

---
name: data-analysis
description：数据分析和可视化专家
allowed-tools: Read, Write, Bash, WebFetch, NotebookEdit
---

# 数据分析专家

你是一个专业的数据分析师，擅长使用 Python 和相关工具进行数据分析。

## 核心能力
- 数据清洗和预处理
- 统计分析和建模
- 数据可视化
- 生成分析报告

## 分析流程
1. 理解数据结构和质量
2. 清洗和预处理数据
3. 执行统计分析
4. 创建可视化图表
5. 生成分析结论

## 工具库
- pandas：数据处理
- numpy：数值计算
- matplotlib/seaborn：可视化
- scikit-learn：机器学习

## 最佳实践
- 始终先探索数据质量
- 使用 Jupyter Notebook 进行交互式分析
- 保存中间结果避免重复计算

示例 3：代码审查 Skill

文件：.codebuddy/skills/code-review/SKILL.md

markdown

---
name: code-review
description：代码审查和质量检查专家
allowed-tools: Read, Grep, Bash, Edit
---

# 代码审查专家

你是一个经验丰富的代码审查者，遵循业界最佳实践。

## 审查重点
1. **代码质量**
   - 命名规范
   - 代码复杂度
   - 重复代码

2. **安全性**
   - SQL 注入风险
   - XSS 漏洞
   - 认证授权问题

3. **性能**
   - 算法效率
   - 资源使用
   - 缓存策略

4. **可维护性**
   - 代码注释
   - 模块化设计
   - 测试覆盖

## 审查流程
1. 理解代码变更的目的
2. 检查代码风格和规范
3. 分析潜在的 Bug 和性能问题
4. 验证安全性
5. 提供建设性的改进建议

## 输出格式
- ✅ 优点：列出做得好的地方
- ⚠️ 问题：指出需要改进的地方
- 💡 建议：提供具体的改进方案

AI 如何选择 Skills

AI 根据以下因素决定是否调用 Skill：

任务匹配度：任务描述与 Skill description 的相关性
工具需求：任务所需工具是否在 allowed-tools 范围内
上下文相关性：当前对话上下文是否适合使用该 Skill
Skill 来源：项目级 Skills 优先于用户级 Skills

权限控制

allowed-tools 白名单

通过 allowed-tools 字段限制 Skill 可以使用的工具：

yaml

allowed-tools: Read, Write, Bash(git:*), Grep

支持的工具模式匹配：

Bash(git:*) - 只允许 git 相关命令
Edit(src/**/*.ts) - 只允许编辑特定路径文件

工作目录限制

每个 Skill 都有自己的 baseDirectory（SKILL.md 所在目录），可以在 Skill 指令中引用：

markdown

当处理文件时，优先在 {baseDirectory} 目录下查找相关资源。

最佳实践

1. 清晰的 Skill 描述

yaml

# ❌ 不好
description：处理文件

# ✅ 好
description: PDF 文档解析和转换专家，支持文本提取和格式转换 （project)

2. 详细的指令内容

提供详细的：

核心能力说明
标准工作流程
可用工具列表
常见场景处理方法
输出格式要求

3. 合理的工具权限

只授予必需的工具权限：

yaml

# ❌ 权限过大
allowed-tools: Bash

# ✅ 精确控制
allowed-tools: Read, Write, Bash(git:status,git:diff), Grep

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

调试 Skills

查看已加载的 Skills

使用 /skills 命令查看当前已加载的所有 Skills：

/skills

Skills 面板会显示：

User skills：用户级 Skills（~/.codebuddy/skills/）
Project skills：项目级 Skills（.codebuddy/skills/）
Plugin skills：插件提供的 Skills

每个 Skill 会显示名称和预估的 token 数量。

常见问题

Q: Skill 没有被触发？

检查 description 是否清晰描述了 Skill 的功能
确认任务描述与 Skill 能力匹配
验证 allowed-tools 是否包含所需工具

Q: Skill 权限不足？

检查 allowed-tools 配置
确认工具名称拼写正确
使用模式匹配精确控制权限

Q：项目级和用户级 Skill 冲突？

项目级 Skills 优先级更高
使用不同的 name 避免冲突

与其他功能的配合

Skills + Memory

Skills 可以访问 Memory 系统存储的信息：

markdown

在执行数据分析时，参考 Memory 中保存的数据模式和业务规则。

Skills + Slash Commands

Slash Commands 可以引用 Skills：

markdown

<!-- .codebuddy/commands/analyze-data.md -->
请使用 data-analysis skill 分析文件：$1

Skills + MCP

Skills 可以调用 MCP 提供的外部工具（如果在 allowed-tools 中）。

下一步

斜杠命令 - 了解用户主动命令
设置配置 - 配置工具权限
MCP 集成 - 扩展外部工具能力

Skills - 让 AI 成为领域专家

CodeBuddy Code Skills （技能系统） ​

什么是 Skills ​

Skills vs Slash Commands ​

创建 Skills ​

目录结构 ​

SKILL.md 格式 ​

Frontmatter 字段 ​

执行 Shell 命令 ​

支持的特性 ​

Context Fork ​

可用 Agent 类型 ​

隐藏 Skill（user-invocable） ​

执行流程 ​

使用示例 ​

示例 1：PDF 处理 Skill ​

示例 2：数据分析 Skill ​

示例 3：代码审查 Skill ​

AI 如何选择 Skills ​

权限控制 ​

allowed-tools 白名单 ​

工作目录限制 ​

最佳实践 ​

1. 清晰的 Skill 描述 ​

2. 详细的指令内容 ​

3. 合理的工具权限 ​

4. 组织 Skill 目录 ​

调试 Skills ​

查看已加载的 Skills ​

常见问题 ​

与其他功能的配合 ​

Skills + Memory ​

Skills + Slash Commands ​

Skills + MCP ​

下一步 ​

CodeBuddy Code Skills （技能系统）

什么是 Skills

Skills vs Slash Commands

创建 Skills

目录结构

SKILL.md 格式

Frontmatter 字段

执行 Shell 命令

支持的特性

Context Fork

可用 Agent 类型

隐藏 Skill（user-invocable）

执行流程

使用示例

示例 1：PDF 处理 Skill

示例 2：数据分析 Skill

示例 3：代码审查 Skill

AI 如何选择 Skills

权限控制

allowed-tools 白名单

工作目录限制

最佳实践

1. 清晰的 Skill 描述

2. 详细的指令内容

3. 合理的工具权限

4. 组织 Skill 目录

调试 Skills

查看已加载的 Skills

常见问题

与其他功能的配合

Skills + Memory

Skills + Slash Commands

Skills + MCP

下一步