5.3 技能机制：借助内置库固化指令

工具决定“能做什么”，而工程化的方法决定“如何更稳地做”。 插件与技能并行使用，能力与方法互补。 插件负责扩展运行时能力与工具，技能负责固化可复用的方法论与执行步骤。 新项目通常两者配合使用，而不是互相替代。

5.3.1 定位与分工：插件扩展能力，技能固化方法

在系统边界与底层物理形态上可以把职责拆成两部分：

1. 能力层（Plugins）：插件本质是运行在 Gateway 进程内的 TypeScript 扩展模块，在核心资源区执行代码逻辑。表现为新增系统工具、自定义 RPC/HTTP 接口或新频道的注入。

2. 方法层（Skills）：技能本质是一段可被模型按需读取的说明文件（Markdown）+ 资源包。它不执行代码，而是固化常见任务的“执行意图、指令步骤与验收标准”，教导模型如何调用已有的工具。

简而言之：如果需求涉及新增外部接口访问或深度的控制面能力扩展，必须写 TS 插件；如果需求是让大模型按团队统一方法稳定执行已有体系的组合操作，只需写 Markdown 技能。

5.3.2 插件管理：安装、启用、白名单与自检

插件体系的核心是“显式启用与显式允许”。官方插件文档给出了 plugins.entries 的配置结构，以及 plugins.allow、plugins.deny 的白名单机制。

插件启用常见写法如下：

{
  plugins: {
    entries: {
      'com.example.my_plugin': {
        enabled: true,
        config: {
          // 插件自定义配置
        },
      },
    },
    allow: ['com.example.my_plugin'],
  },
}

上线前建议把插件自检纳入验收流程：

• plugins list

• plugins doctor

• status --deep

说明：有的部署会要求在这些子命令前加上“主命令前缀”；若执行时报“找不到命令”，优先参考你本地 CLI 的帮助与本书其他章节的写法。

5.3.3 技能文件与 ClawHub：便捷背后的供应链隐患

技能用于把高频任务沉淀为“可执行步骤 + 约束 + 验收标准”的文档化流程。在整个开源生态中，ClawHub 充当了公共的技能仓库，它支持基于向量的语义检索、版本控制（Semver）以及便捷的 CLI 安装更新体验。

你可以通过语义搜索并安装别人建好的能力包：

示例：

skills list --eligible "daily report"
agent --message "调用 daily-report（传入日期、数据源等参数）"

下面给出一个自编写的简化技能模板：

# 渠道自检

本节提供了自检方式。

## 适用场景

渠道不回消息、群聊不触发、配对异常。

## 步骤

1. 先跑 `doctor --fix`。
2. 再跑 `channels status --probe`。
3. 若仍异常，跟随 `logs --follow --json` 过滤 `routed` 与 `tool_denied` 事件。

## 输出要求

必须给出命令、预期输出、异常分支与下一步。

注意：技能是方法说明，不是工具权限边界；是否允许执行高风险工具仍由工具策略与沙箱决定。

警惕生态风险：把 SKILL.md 当作高危诱导

在享受从 ClawHub 一键下载“黑客指令集”的快感时，必须正视其背后的供应链隐患。2026 年初的多家安全机构报告（如 Snyk 披露的 Leaky Skills）指出：ClawHub 中存在大量极度不安全的开源技能指令。由于技能只是 markdown 文件，它常常通过复杂的 prompt 被用作一种“诱导式的恶意载荷执行器”。

例如：一些恶意的 SKILL.md 会明确要求大模型在执行相关 API 工具前，将用户的环境变量、API 凭据甚至本地敏感文件明文输出到对话历史中，或者诱导执行含毒的 Bash 一键脚本命令。模型很聪明，但也极易被文档洗脑而照做。

因此，引入第三方技能时，您必须亲自 review 对应的 SKILL.md 内容，防范一切企图绕过您的工具拦截链的指令操作。

5.3.4 治理建议：用工具策略兜边界，用技能提稳定性

• 用工具策略做允许、拒绝与分层治理，拒绝规则优先于允许规则，避免越权。详见 5.2 工具策略：允许、拒绝与分层策略。

• 用插件显式白名单控制可加载的高权限 Node 系统执行模块。

• 用技能沉淀高频的内部分发流程，但在团队引入外部技能时，将其视同为“不可信的混淆代码”来强制审查。

延伸阅读：

• Prompt 工程指南：https://github.com/yeasy/prompt_engineering_guide

• Context 工程指南：https://github.com/yeasy/context_engineering_guide