跳到主要内容

技能系统

CountBot 的技能系统本质上是一套“可热加载的能力目录”。技能既可以是内置能力，也可以是工作空间里的自定义能力；既能只给模型看说明文档，也能携带脚本、模板、配置文件和参考资料，供 Agent 在运行时按需读取和调用。

这一章覆盖什么​

  • 技能在当前实现中的目录结构和加载方式
  • 技能如何注入系统提示词，何时按需读取
  • 技能管理 API 和配置管理 API
  • 当前内置技能清单
  • 自定义技能的组织方式和最佳实践

当前目录结构​

当前 CountBot 统一从工作空间加载技能：

workspace/
├── .skills_config.json
└── skills/
    ├── agent-browser/
    ├── agent-team-manager/
    ├── baidu-search/
    ├── cron-manager/
    ├── email/
    ├── image-analysis/
    ├── image-gen/
    ├── map/
    ├── news/
    ├── skill-creator/
    ├── terminal-session/
    ├── weather/
    └── web-design/

每个技能目录通常包含：

  • SKILL.md：技能说明与操作规范，必需
  • scripts/：辅助脚本，可选
  • assets/：模板、静态资源，可选
  • references/：外部工具参考资料，可选
  • templates/：命令模板或工作流模板，可选

技能是怎么生效的​

1. 启动或刷新时加载索引​

SkillsLoader 会扫描 workspace/skills/，读取每个技能的 SKILL.md 和 frontmatter，建立技能索引，同时结合 workspace/.skills_config.json 判断哪些技能已被禁用。

2. 系统提示词里只注入必要内容​

当前实现不是把所有技能全文都塞进系统提示词，而是分两类处理：

  • 自动加载技能：完整内容注入系统提示词
  • 普通技能：只放摘要，真正需要时再读取 SKILL.md

这能避免上下文过长，同时保留技能发现能力。

3. 运行时按需读取技能文件​

当模型决定使用某个普通技能时，会通过文件工具读取该技能目录下的说明文档、脚本或参考资料，再决定下一步怎么执行。

SKILL.md 建议结构​

当前实现允许 frontmatter 携带技能元数据。为了避免对外文档继续出现产品版本信息，建议至少保留这些字段：

---
name: my-skill
description: 这个技能解决什么问题
metadata:
  CountBot:
    always: false
    requires:
      bins: []
---

# 技能标题

## 适用场景
说明什么时候该使用这个技能。

## 操作步骤
写清楚模型应该读哪些文件、执行哪些脚本、怎样解释结果。

常用字段含义：

字段说明
name技能唯一名称
description技能简介，会出现在列表和摘要里
metadata.CountBot.always是否自动注入系统提示词
metadata.CountBot.requires.bins运行该技能依赖的命令行程序

技能管理 API​

技能管理接口位于 backend/api/skills.py。

基础管理​

方法路径说明
GET/api/skills获取技能列表
POST/api/skills创建工作空间技能
POST/api/skills/reload重载技能目录
GET/api/skills/{name}获取技能详情
PUT/api/skills/{name}更新工作空间技能
DELETE/api/skills/{name}删除工作空间技能
POST/api/skills/{name}/toggle启用或禁用技能

配置管理​

方法路径说明
GET/api/skills/{name}/config/schema获取技能配置 schema
GET/api/skills/{name}/config获取当前配置
PUT/api/skills/{name}/config保存配置
GET/api/skills/{name}/config/status获取配置状态
POST/api/skills/{name}/config/fix自动补齐或修复缺失字段
GET/api/skills/{name}/config/help获取该技能的配置帮助文档

返回数据里有哪些关键字段​

技能列表和详情接口会返回这些核心信息：

  • name
  • description
  • enabled
  • autoLoad
  • requirements
  • source

其中 source 当前可能是：

  • workspace
  • builtin
  • openclaw

启用、禁用与热重载​

启用状态保存在哪里​

当前启用状态保存在：

workspace/.skills_config.json

示例：

{
  "disabled_skills": ["news", "map"]
}

注意这里的真实字段名是 disabled_skills。

什么时候需要重载​

这些场景建议调用 POST /api/skills/reload：

  • 手动往 workspace/skills/ 新增了技能目录
  • 修改了 SKILL.md
  • 新增了脚本、模板或参考资料
  • 批量导入技能后希望立即刷新列表

哪些技能能被编辑​

当前写操作只允许针对 workspace 来源的技能：

  • 可以创建
  • 可以更新
  • 可以删除

非工作空间技能不会被这些接口直接改写。

技能配置状态​

配置状态接口当前会返回这些状态值：

  • no_schema
  • not_configured
  • invalid_format
  • missing_fields
  • valid

它们分别对应：

  • 没有可视化 schema
  • 还没有配置文件
  • 配置文件格式错误
  • 缺少必填字段或字段校验不通过
  • 配置可正常使用

当前内置技能​

以下技能已经在当前工作空间中存在。

技能作用常见依赖或配置
agent-browser浏览器自动化、表单操作、抓取与截图需要本地安装 agent-browser CLI
agent-team-manager管理团队、成员和团队模型配置无额外配置
baidu-search百度搜索与检索增强scripts/config.json
cron-manager创建、更新、批量管理定时任务与任务会话无额外配置
emailQQ / 163 邮箱收发、附件处理scripts/config.json
find-skills基于腾讯 SkillHub 搜索、安装和管理技能无额外配置
image-analysisOCR、视觉理解、图片分析scripts/config.json
image-gen文生图与图片生成scripts/config.json
map地图、路线与 POI 检索scripts/config.json
news新闻与资讯聚合无额外配置
skill-creator生成、打包、评估和改进技能无额外配置
terminal-session终端会话辅助能力无额外配置
weather天气查询无额外配置
web-design页面生成与 Cloudflare Pages 部署scripts/config.json

两个值得单独认识的技能​

agent-team-manager​

这个技能不是执行团队，而是“配置团队”：

  • 列出团队
  • 查看团队详情
  • 从模板创建团队
  • 增删改成员
  • 设置团队专属模型

详细见 Agent Team Manager。

cron-manager​

这个技能现在已经不只是基础 CRUD，而是完整的任务管理入口：

  • create / update / delete
  • enable / disable
  • run
  • validate
  • batch-create
  • batch-delete
  • messages
  • clean
  • reset

而且会自动读取当前聊天环境中的：

  • COUNTBOT_CHANNEL
  • COUNTBOT_CHAT_ID
  • COUNTBOT_ACCOUNT_ID

详细见 定时任务。

自定义技能怎么组织​

最小可用技能​

workspace/skills/my-skill/
└── SKILL.md

带脚本的技能​

workspace/skills/my-skill/
├── SKILL.md
└── scripts/
    └── main.py

带配置的技能​

workspace/skills/my-skill/
├── SKILL.md
└── scripts/
    ├── config.json
    └── config.json.example

自定义技能编写建议​

  • 描述要具体，让模型知道什么时候该启用这个技能
  • 步骤要写成“可执行说明”，不要只写概念
  • 复杂技能优先把命令封装进 scripts/
  • 需要用户填写的参数尽量提供 config.json.example
  • 如果适合做可视化配置，补充 schema 和帮助文档
  • 高频技能才考虑自动注入，避免系统提示词膨胀

常见排查​

技能目录已经创建，但页面看不到​

优先检查：

  • 目录名是否合法
  • 是否存在 SKILL.md
  • frontmatter 是否可解析
  • 是否需要调用 /api/skills/reload

技能列表里有，但模型不使用​

优先检查：

  • description 是否写清触发场景
  • 是否被禁用
  • 是否需要让模型按需读取脚本或参考资料
  • 是否误以为“有技能”就一定自动调用

配置页面显示不完整​

优先检查：

  • 是否存在 schema
  • 配置文件是否为合法 JSON
  • config/status 返回的状态是什么
  • config/help 是否有针对性的帮助内容

相关文档​