cap_skill — Skill 管理工具

源码：cap_skill_mgr.c · 头文件：cap_skill_mgr.h

定位

cap_skill 是将 core 运行时功能暴露为工具的代表实现。它不实现任何自己独立的业务逻辑，而是将 claw_skill 模块（见 claw_skill）的能力——注册/注销 Skill、激活 Skill——封装成 LLM 可调用的工具，同时向 Console 暴露为 cap call 命令。

这种「薄包装（thin wrapper）」模式在 ESP-Claw 中很常见：底层功能由 claw_* 模块实现，cap_* 组件负责将其转化为工具接口和调用路由。

暴露的工具

cap_skill 注册了四个 Callable：

工具 ID	描述
`list_skill`	列出 Skills 根目录下所有 Markdown 中发现的 Skill
`register_skill`	创建一个运行时管理的 `skills/<skill_id>/SKILL.md` 并重载注册表
`unregister_skill`	删除一个运行时管理的 Skill Markdown 并重载注册表
`activate_skill`	激活 Skill 并以工具返回值的形式返回完整 Skill 文档，同步开放对应 `metadata.cap_groups`

除 list_skill 外，其余工具均标记为 CLAW_CAP_FLAG_CALLABLE_BY_LLM，即 LLM 可直接调用。

核心实现分析

`activate_skill`：工具返回即上下文注入

activate_skill 是最核心的工具。它的执行链路展示了 Capability 如何操作 core 运行时状态，同时利用工具返回值实现缓存友好的上下文注入：

activate_skill 执行后会：

读取 Skill 的 SKILL.md 文档全文
调用 claw_skill_activate_for_session 写入激活状态
调用 cap_skill_sync_session_visible_groups 更新工具可见白名单
将 Skill 文档以 <skill_content name="skill_id">...</skill_content> 格式作为工具调用返回值返回给 LLM

LLM 在同一轮对话中即可获得完整 Skill 文档，并在下一轮看到新开放的工具。当需要多个 Skill 时，LLM 可在单次响应中并行调用多个 activate_skill，批量获取多份文档。

`register_skill`：文件系统完整性检查

注册一个新 Skill 时，cap_skill 执行严格的合法性检查：

// 1. 路径安全：禁止 "/" 开头、".." 跳目录、反斜杠
if (!cap_skill_path_is_valid(file_item->valuestring)) { ... }

// 2. file 必须匹配 <skill_id>/SKILL.md，且位于 /fatfs/skills/ 下
if (!cap_skill_path_is_valid(skill_id, file)) { ... return ESP_ERR_INVALID_ARG; }

// 3. 不允许重复 skill_id
if (cap_skill_catalog_contains_id(skills, skill_id)) { ... return ESP_ERR_INVALID_ARG; }

创建或删除 SKILL.md 后立即调用 claw_skill_reload_registry() 使变更生效；若重载失败，自动回滚到修改前的内容，保持目录一致性。

Session 隔离

activate_skill 从 ctx->session_id 获取当前会话 ID，激活状态按 session 独立存储。这意味着：

Telegram 会话和飞书会话可以激活不同的 Skill 集合
重启后，持久化在文件系统的激活状态会自动恢复

输出格式

activate_skill 成功时，返回 Skill 文档原文包装在 XML 标签中：

<skill_content name="cap_lua">
... SKILL.md 正文 ...
</skill_content>

失败时返回结构化 JSON：

{
  "ok": false,
  "error": "failed to read skill document",
  "skill_id": "nonexistent"
}

其余工具（register_skill、unregister_skill）也返回结构化 JSON 表示操作结果。

Skills 文档位置

cap_skill 本身没有对应的 Skills 文档（因为 Skill 管理工具总是对 LLM 可见，不需要通过 Skill 激活）。cap_skill Group 通常在应用启动时直接加入 claw_cap_set_llm_visible_groups 白名单。

与 `claw_skill` 的分工

层	模块	职责
框架层	`claw_skill`	Skills 目录解析、session 激活状态持久化、文档读取、Skills 目录列表 provider
工具层	`cap_skill`	将上述功能暴露为 LLM 工具，供 Console / Agent 调用；激活时通过工具返回值注入文档

cap_skill 是一个纯粹的「适配器」：它不持有任何状态，所有操作都委托给 claw_skill，自己只负责参数解析、错误格式化和返回值构造。