技能系统
AggRoot 的技能系统提供可复用的任务模板，让你通过简短的命令执行常见操作。本章介绍内置技能、自定义技能和技能市场。
内置技能
AggRoot 开箱即提供以下内置技能：
| 技能名 | 描述 | 使用场景 |
|---|---|---|
explain |
解释代码或概念 | 需要详细理解某段代码的工作原理 |
refactor |
重构代码以改善质量 | 改善代码结构、可读性或性能 |
test |
为代码编写测试 | 为现有代码生成单元测试 |
document |
生成文档 | 为函数、类或模块生成文档注释 |
debug |
调试问题和错误 | 排查 Bug、分析错误信息 |
analyze |
分析代码库结构 | 理解架构、依赖关系和模式 |
security-check |
安全检查 | 审查代码中的安全漏洞 |
commit |
生成提交信息 | 创建符合规范的 Git 提交 |
使用技能
斜杠命令
在输入框中使用 /技能名 调用技能：
Agent> /explain this function
Agent> /refactor src/utils/helpers.ts
Agent> /test src/domain/agent/aggregate.ts
Agent> /document src/config.ts --format tsdoc
Agent> /debug TypeError: Cannot read properties of undefined
Agent> /analyze architecture --depth deep
Agent> /security-check src/ --focus injection
Agent> /commit
通过 Skill 工具调用
AggRoot 的模型也可以通过 Skill 工具在对话中调用技能：
请使用 test 技能为 aggregate.ts 编写测试
列出可用技能
使用 ListSkills 工具或输入 /skills 查看当前所有可用技能：
Agent> 列出所有可用的技能
技能参数
每个技能可以接受不同的参数：
explain
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
topic |
string | 是 | 要解释的代码或概念 |
level |
string | 否 | 解释级别：beginner / intermediate / advanced（默认 intermediate） |
/explain React hooks --level beginner
refactor
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file |
string | 是 | 要重构的文件路径 |
focus |
string | 否 | 关注方向：readability / performance / maintainability / all |
/refactor src/utils/helpers.ts --focus performance
test
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file |
string | 是 | 要编写测试的文件路径 |
framework |
string | 否 | 测试框架：vitest / jest / mocha（默认 vitest） |
/test src/domain/agent/aggregate.ts --framework vitest
document
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file |
string | 是 | 要文档化的文件路径 |
format |
string | 否 | 格式：jsdoc / tsdoc / markdown（默认 tsdoc） |
debug
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
error |
string | 是 | 错误信息或描述 |
context |
string | 否 | 额外的上下文信息 |
analyze
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
scope |
string | 是 | 分析范围：architecture / dependencies / patterns / all |
depth |
string | 否 | 分析深度：quick / standard / deep |
security-check
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file |
string | 否 | 要检查的文件或目录 |
focus |
string | 否 | 关注方向：injection / auth / crypto / all |
commit
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
message |
string | 否 | 可选的提交信息提示 |
自定义技能
你可以在项目中创建自定义技能模板。
技能文件格式
在 .aggroot/skills/ 目录下创建 Markdown 文件，包含 YAML frontmatter：
---
name: my-custom-skill
description: 自定义技能的描述
whenToUse: 当你需要执行某某操作时使用此技能
arguments:
- name: target
description: 目标文件或目录
required: true
- name: mode
description: 执行模式: quick / full
default: quick
allowedTools:
- read_file
- replace
- glob
context: inline
userInvocable: true
---
## 任务指令
请对 {{target}} 执行以下操作：
1. 读取文件内容
2. 分析代码结构
3. 按 {{mode}} 模式输出结果
### 输出格式
- 概述
- 发现的问题
- 建议的改进
Frontmatter 字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | 技能名称（用于调用） |
description |
string | 技能描述 |
whenToUse |
string | 何时使用此技能 |
arguments |
array | 技能参数定义 |
allowedTools |
array | 允许使用的工具列表 |
model |
string | 使用的模型（可选） |
context |
string | 执行上下文：inline（当前会话）/ fork（独立子代理） |
agent |
string | 指定使用的代理（可选） |
userInvocable |
boolean | 用户是否可以直接调用 |
参数定义
arguments:
- name: file # 参数名
description: 目标文件 # 参数描述
required: true # 是否必填
default: null # 默认值
type: string # 类型：string / number / boolean / array / object
enum: # 可选值列表
- quick
- full
技能加载路径
AggRoot 从以下路径加载技能，按优先级排列：
| 优先级 | 路径 | 说明 |
|---|---|---|
| 1 | .aggroot/skills/*.md |
项目级自定义技能 |
| 2 | ~/.aggroot/skills/*.md |
全局自定义技能 |
| 3 | 内置技能 | AggRoot 自带技能 |
| 4 | Skillhub 技能 | 从技能市场安装的技能 |
| 5 | MCP 提示词 | MCP 服务器提供的提示词技能 |
同名技能按优先级覆盖，项目级 > 全局级 > 内置。
执行上下文
技能可以指定不同的执行上下文：
inline（内联）
在当前会话中直接执行。技能的提示词会注入到当前对话中，模型直接响应。
- 优点：快速，无需额外启动
- 缺点：会占用当前会话的上下文
- 适用：简单的、单步的任务
fork（分支）
在独立的子代理会话中执行。技能的提示词和工具在子代理中运行，结果返回给主会话。
- 优点：不污染主会话上下文，可以使用不同的模型
- 缺点：启动开销略大
- 适用：复杂的、多步的任务
Skillhub 技能市场
AggRoot 集成了 Skillhub（AI 技能市场），可以搜索和安装社区技能。Skillhub CLI 通过 npx skillhub 调用，无需全局安装。
搜索技能
/skillhub-search 代码审查
支持的搜索选项：
-p <platform>：按平台过滤（claude, codex, copilot, cursor, windsurf）-s <sort>：排序方式（recommended, aiScore, downloads, stars, rating, recent）-l <number>：结果数量
安装技能
npx skillhub install <skill-id>
技能 ID 格式为 owner/repo/skill-name（如 openclaw/skills/commit）。
支持的安装选项：
-p <platform>：指定目标平台--project：安装到当前项目（而非全局）
列出已安装技能
npx skillhub list # 全局技能
npx skillhub list --all # 全部（含项目级）
npx skillhub list --project # 仅项目级
更新技能
npx skillhub update # 更新所有技能
npx skillhub update <name> # 更新指定技能
卸载技能
npx skillhub uninstall <skill-name>
查看帮助
npx skillhub --help
npx skillhub <command> --help
可用 Skillhub 技能
| 技能名 | 描述 |
|---|---|
skillhub-search |
搜索技能 |
skillhub-install |
安装技能 |
skillhub-list |
列出已安装技能 |
skillhub-update |
更新技能 |
skillhub-uninstall |
卸载技能 |
skillhub-help |
查看帮助 |
常见问题
技能未生效
- 确认技能文件在正确的目录（
.aggroot/skills/或~/.aggroot/skills/） - 检查 YAML frontmatter 格式是否正确
- 使用
ListSkills工具查看技能是否注册成功
自定义技能覆盖内置技能
如果你创建了与内置技能同名的自定义技能，自定义技能优先。这可以用来定制内置技能的行为。
技能执行出错
检查 allowedTools 列表是否包含技能所需的所有工具。如果技能需要 Shell 命令但未在 allowedTools 中声明 run_shell_command，执行时会报错。