Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

技能

技能是可复用的指令和可选的工具定义，ZeroClaw 可以将其加载到智能体会话中。可将其用于可重复的工作流程，例如代码审查清单、部署操作手册、支持指南或特定领域的工具封装。

技能位于以下三个位置之一：

  • 每个代理的工作区技能位于 <install>/agents/<alias>/workspace/skills/<name>/。
  • <install>/shared/skills/<bundle>/<name>/ 下的共享技能包。代理在其配置中将该技能包列入 agents.<alias>.skill_bundles 时会加载这些内容。
  • <install>/data/skills/<name>/ 下的全局技能目录。CLI 可以将其作为回退位置安装，但代理不会自动加载全局技能。

在运行时，智能体应加载的技能请使用 bundles。bundle 在 [skill_bundles.<alias>] 下进行配置；当省略其 directory 时，ZeroClaw 会将其解析为 <install>/shared/skills/<alias>/。

<install>/shared/skills/<bundle>/<name>/

对于手动编写的本地技能，请使用 SKILL.md 或 SKILL.toml。当只需要指令加上简单的元数据时，请使用 SKILL.md。当技能需要结构化提示或工具定义时，请使用 SKILL.toml。ZeroClaw 也能识别用于注册表风格技能包的 manifest.toml，但 SKILL.md 和 SKILL.toml 是推荐的本地编写格式。

要将一组技能分发为带签名、带版本且可安装的软件包，请参阅技能包。请注意，这些技能包依赖插件系统，而预构建的发布二进制文件不包含该系统；对于标准二进制文件，本页面上的共享包是受支持的机制。

创建 Markdown 技能

创建一个 bundle，然后将一个仅包含说明的 skill 脚手架化到其中：

sh

zeroclaw skills bundle add ops
zeroclaw skills add release-check \
  --bundle ops \
  --description "Check release readiness before tagging" \
  --edit

skills add 命令会将 SKILL.md 写入已解析的 bundle 目录下，并在你的编辑器中打开它。请将生成的说明替换为你希望代理遵循的工作流：

# Release check

Review the release notes, changelog, version tags, and migration notes before confirming that a release is ready.

目录名将成为技能名称。当不存在 frontmatter description 时，ZeroClaw 会使用第一个非标题段落作为描述。

SKILL.md 还支持使用简单的 frontmatter 来定义元数据：

---
name: release-check
description: Check release readiness before tagging
version: 0.1.0
author: zeroclaw_user
tags: [release, docs]
---

# Release check

Review the release notes, changelog, version tags, and migration notes before confirming that a release is ready.

支持的 frontmatter 字段包括 name、description、author、version、tags、always 和 slash_options。

设置 always: true 后，即使智能体以紧凑技能提示模式运行（在该模式下，其他技能会进行摘要，其指令会按需通过 read_skill 加载），某个技能的完整指令仍会内联在系统提示中。默认值为 false。请将其留给必须始终对模型可见的策略或安全关键型技能，而不要用于上面的发布检查之类的常规工作流技能：

---
name: security-policy
description: Non-negotiable safety rules the agent must follow every turn.
version: 0.1.0
author: zeroclaw_user
tags: [policy]
always: true
---

# Security policy

Never exfiltrate secrets, never disable audit logging, and always ask for approval before touching production credentials.

创建 TOML 技能

技能也可以是结构化的 TOML 清单（SKILL.toml）。[skill] 表要求包含 name 和 description；省略 version 时其默认值为 0.1.0；author、tags、prompts 和 always 均为可选项（always 默认为 false；见上文）。工具条目可以使用 kind = "shell"、kind = "http" 或 kind = "script"。工具描述应保持聚焦且具体，以便模型知道何时使用它们。

HTTP 技能工具仅使用 http 和 https URL。参数在插入前会进行百分号编码，重定向和环境代理均已禁用，且解析后的目标必须通过 ZeroClaw 的公网出口策略。私有网络或元数据目标会被拒绝，大于一兆字节的响应正文会在可能扩展运行时内存之前被截断。

斜杠命令选项和本地化

标记为 slash 的技能会以聊天频道斜杠命令的形式展示（例如 Discord /search）。它可以声明带类型的 [[skill.slash_options]]；未声明任何选项的技能会回退为一个必填的自由文本输入。命令描述和每个选项描述都可接受一个可选的 description_localizations 映射，以区域设置代码为键。未知或不受支持的区域设置代码会被丢弃并给出警告，而不是导致注册失败，因此拼写错误不会卡住命令注册。

[skill]
name = "search"
description = "搜索网络"
tags = ["slash"]
# 本地化的命令描述，以语言区域代码为键。
description_localizations = { fr = "Rechercher sur le web", ja = "ウェブを検索" }

[[skill.slash_options]]
name = "query"
description = "搜索查询"
type = "string"
required = true
# 本地化的选项描述，格式相同。
description_localizations = { fr = "La requête de recherche" }

管理已安装的技能

列出完整清单：

sh

zeroclaw skills list

列出一个代理在运行时准确加载的内容：

sh

zeroclaw skills list --agent default

直接列出一个 bundle：

sh

zeroclaw skills list --bundle ops

审查已安装的技能或本地技能目录：

sh

zeroclaw skills audit release-check
zeroclaw skills audit ./release-check

从本地目录、Git URL 或注册表名称安装技能：

sh

zeroclaw skills install ./release-check --bundle ops
zeroclaw skills install https://example.com/zeroclaw-release-check.git --bundle ops
zeroclaw skills install release-check --agent default

从 Git 目录仓库按名称安装一个技能（其技能位于 skills/<name>/ 下）：

sh

zeroclaw skills install https://github.com/vercel-labs/skills --skill find-skills

安装目标优先级是：

  1. 显式 --bundle <alias>。
  2. 目标代理的唯一分配 bundle。--agent <alias> 用于选择目标代理；省略时，ZeroClaw 使用当前活动的运行时代理。
  3. <install>/data/skills/ 下的全局目录。

如果目标 agent 有多个 bundle，请传入 --bundle，这样目标就不会产生歧义。如果 ZeroClaw 回退到全局目录，skill 会被安装并列出，但不会有 agent 自动加载它。将其附加到某个 bundle 中，以便在运行时可用。

移除已安装的技能：

sh

zeroclaw skills remove release-check --bundle ops
zeroclaw skills remove release-check --agent default

从 bundle 中移除会归档技能目录，以便可以恢复。 从全局目录中移除会在现有路径包含检查通过后删除全局副本。

运行 TEST.sh 对某个技能进行验证，或省略名称以测试所有已安装的技能：

sh

zeroclaw skills test release-check
zeroclaw skills test --verbose

zeroclaw skills test 会在 TEST.sh 文件存在时运行该技能的 TEST.sh 文件。在运行你尚未信任的技能源中的测试之前，请先检查 TEST.sh。

如果 zeroclaw skills list 显示了某个技能，但代理未使用它，请检查运行时视图：

sh

zeroclaw skills list --agent default

当该技能仅出现在全局组中时，将其安装到一个 bundle 中，并确保该 agent 在 agents.<alias>.skill_bundles 中列出该 bundle。

有关将内置工具转变为可复用操作器工作流的完整示例，请参见 using relationship memory from skills。

提示触发的功能建议

ZeroClaw 可以在提交的提示词明确指向了缓存的注册表元数据中存在但尚未安装的内容时，选择性地建议一项可安装的技能能力。服务器端的处理流程在提交之后、正常的 LLM 回合之前运行。它仅返回一项建议；它不会安装该技能、启用它、写入记忆，也不会将技能主体视为全局指令。

通过 skills 配置启用它（gateway、zerocode 或 zeroclaw config set）。建议匹配器使用已安装的技能名称以及缓存的注册表元数据，例如名称、别名和 frontmatter。它有意避免匹配未经批准的技能正文。在插件注册表的搜索/安装界面可用之前，插件/包级别的发现仍属于后续工作范围。用户仍在输入时进行精确的编写时建议需要 ACP、gateway 或客户端 UI 支持，不在这一仅限服务器的路径范围内。

脚本安全

ZeroClaw 会在加载或安装技能前对其进行审计。默认情况下，类似脚本的文件（如 .sh、.bash、.ps1 以及带有 shell shebang 的文件）会被阻止。

如果您有意使用包含脚本的技能，请启用 skills.allow_scripts。除非您信任该技能来源并已审查脚本的行为，否则请保持此项禁用。

有关 Python 特定的执行模式、解释器策略以及原生与 Docker 的权衡，请参阅运行 Python 技能。

正在加载社区技能

社区开放技能（open-skills）的加载需通过 skills 配置显式启用。启用后，ZeroClaw 会从配置的 open_skills_dir 加载技能；若未设置该目录，则从 $HOME/open-skills 加载。如果该目录不存在，ZeroClaw 可能会克隆社区开放技能仓库；如果该目录存在且是一个 git 检出（checkout），ZeroClaw 可能会拉取更新。请仅对你信任的社区来源启用此功能，或将 open_skills_dir 指向一份经过审查的本地副本。

高级配置

默认的提示注入模式是 full，会在系统提示中包含完整的技能说明。全局设置 prompt_injection_mode = "compact"，或在运行时配置文件中设置该选项，以便将普通技能元数据保留在上下文中，并通过 read_skill 按需加载说明。标记为 always: true 的技能在紧凑模式下仍会保留其完整说明。紧凑模式可减少提示大小；但它不是不受信任技能来源的隔离边界。

自主技能创建

在成功完成多步骤任务（至少两次工具调用）后，ZeroClaw 可以将执行过程保存为可复用的技能。这默认关闭，并且需要主动启用：

[skills.skill_creation]
enabled = true              # off by default
max_skills = 500            # LRU cap: oldest auto-generated skill is evicted past this
similarity_threshold = 0.85 # embedding-dedup cutoff; near-duplicate tasks are skipped

默认情况下，每个创建的 skill 都是一个直接从工具调用轨迹生成的确定性 SKILL.toml；不涉及模型调用。

Reflection (SKILL.md 合成)

启用反思后，ZeroClaw 会改为请求代理已配置的模型提供方，从执行的一个有界片段（任务、工具调用轨迹和最终答案）中合成一个规范的 SKILL.md。每个输入都会独立截断到配置的字符预算，因此即使执行规模很大，也绝不会生成无限制的反思请求：

[skills.skill_creation]
enabled = true
reflection_enabled = true   # opt-in; requires enabled = true
max_task_chars = 1000           # task description budget
max_tool_trace_chars = 4000     # tool-call trace budget
max_final_answer_chars = 2000   # final assistant answer budget

如果反射调用失败（提供方错误、输出格式错误，或正文为空），ZeroClaw 会回退到确定性的 SKILL.toml 路径，因此启用反射绝不会导致 skill 无法创建。反射生成的 skills 会标记为 zeroclaw-auto 作者，并与 SKILL.toml skills 一样参与去重和 LRU 驱逐。

因为 reflection 会将转发后的内容发送给模型提供方，所以任务、工具调用轨迹和最终答案都会在提示词组装并发送之前，使用与 ZeroClaw 对频道响应应用的相同外发内容护栏，对凭据形态的值（API 密钥、令牌、AWS 凭据、PEM 私钥、JWT、数据库连接 URL，以及高熵密钥）进行扫描并删除。删除会在请求前于进程内运行，因此出现在工具参数或最终答案中的密钥会被替换为 [REDACTED_…] 标记，而不会传达到提供方。

反思 vs. 技能改进。 反思（[skills.skill_creation] reflection_enabled）会从已完成的执行轨迹中_创建一个新技能_。[skills.skill_improvement] 后台复审 fork 是一个独立功能，它会在已有技能被使用后_修补现有技能_。它们可以独立启用。

另见