Skills（Fased）

Fased 使用兼容 AgentSkills 的 Skills 文件夹来教智能体如何使用工具。每个 Skills 是一个包含带有 YAML frontmatter 和说明的 SKILL.md 的目录。Fased 加载内置 Skills 以及可选的本地覆盖，并在加载时根据环境、配置和二进制文件存在情况进行过滤。

当前 UI 流程

普通用户从 Agents > 选择 Agent > Skills 开始。这个标签页同时包含：

Skills library（内置、共享、工作区和插件 Skills）
插件目录搜索、审查、安装
+ Skill 创建技能
编辑 SKILL.md
typed config / env / API key 表单
dependency install 计划和验证
每 Agent 的 allow/deny 开关

全局 /skills 页面仍可作为深链或管理员视图存在，但主要操作应在选定 Agent 的 Skills 标签页完成。Skill 可以存在于 library 中，但没有被某个 Agent 允许；这两件事是分开的。状态含义：

Installed：Fased 找到了包含 SKILL.md 的 skill 文件夹。
Ready：skill 已存在，且所有二进制、环境变量、配置路径和 OS 要求都对 Gateway 进程可见。
Needs dependency：skill 文件存在，但所需可执行文件不在 Gateway 的 PATH 中。
Needs config：skill 依赖某个 config path 或账号设置。
Unsupported OS：skill 声明只支持其他操作系统。
Make editable copy：把只读内置/插件 skill 复制到选定 Agent 工作区以便编辑；这不是授权，也不安装依赖。

位置和优先级

Skills 从多个位置加载：

额外配置目录：skills.load.extraDirs（最低优先级）
内置 Skills：随安装包或 app bundle 发布
托管/共享 Skills：~/.fased/skills
个人 AgentSkills：~/.agents/skills
项目 AgentSkills：<workspace>/.agents/skills
Agent 工作区 Skills：<workspace>/skills

如果 Skills 名称冲突，优先级为： <workspace>/skills（最高）→ <workspace>/.agents/skills → ~/.agents/skills → ~/.fased/skills → 内置 Skills → extraDirs（最低）此外，你可以通过 ~/.fased/fased.json 中的 skills.load.extraDirs 配置额外的 Skills 文件夹（最低优先级）。

单智能体 vs 共享 Skills

在多智能体设置中，每个智能体有自己的工作区。这意味着：

单智能体 Skills 位于 <workspace>/skills 中，仅供该智能体使用。
共享 Skills 位于 ~/.fased/skills（托管/本地），对同一机器上的所有智能体可见。
如果你想要多个智能体使用一个通用的 Skills 包，也可以通过 skills.load.extraDirs（最低优先级）添加共享文件夹。

如果同一个 Skills 名称存在于多个位置，将应用通常的优先级规则：工作区优先，然后是托管/本地，最后是内置。

插件 + Skills

插件可以通过在 fased.plugin.json 中列出 skills 目录（相对于插件根目录的路径）来发布自己的 Skills。插件 Skills 在插件启用时加载，并参与正常的 Skills 优先级规则。你可以通过插件配置条目上的 metadata.fased.requires.config 对它们进行门控。参见插件了解发现/配置，以及工具了解这些 Skills 所教授的工具接口。

插件目录（安装 + 同步）

插件目录是 Fased 的公共 Skills 注册表。使用它来发现、安装、更新和备份 Skills。完整指南：插件目录。常见流程：

在 Agent > Skills 中搜索插件目录。
打开 review modal，检查 registry、archive scan、SKILL.md、权限、install plan、wallet/mining 风险。
选择安装目标：共享 library（~/.fased/skills）或选定 Agent 工作区。
安装后修复 readiness blocker：依赖、API key/env、config path 或 OS。
允许该 Agent 使用该 skill。
如果 skill 需要工具，打开 Agent > Tools 授权工具；如果能动用资金，打开 Wallets > Skill Grants 做窄授权。

CLI 仍可用于高级流程：

fased skills marketplace install <skill-slug>
fased skills marketplace update <skill-slug> --dry-run
fased skills marketplace update <skill-slug> --approve-permission-change
clawhub sync --all

Fased 会记录插件来源、archive scan、请求权限和更新审查。安装 skill 不会自动授予 Agent、工具、钱包、Mining 或任务权限。

安全注意事项

将第三方 Skills 视为不受信任的代码。启用前请阅读它们。
对于不受信任的输入和高风险工具，优先使用沙箱隔离运行。参见沙箱隔离。
skills.entries.*.env 和 skills.entries.*.apiKey 为该智能体轮次将秘密注入到宿主机进程中（而非沙箱）。将秘密保持在提示词和日志之外。
dependency install 是外部包信任边界。运行 npm/go/uv/brew/download 前，应查看包管理器、确切命令、pin/integrity 状态和 PATH 目标。命令退出 0 不代表 ready；Gateway 必须能看到所需二进制。
wallet/mining 权限永远不会因为安装 skill 自动授予。普通 wallet skill 只能使用显式允许的 Agent-role wallet；Mining 和 Vault 钱包不提供给通用 skills。
有关更广泛的威胁模型和检查清单，参见安全概览和Gateway 安全性。

格式（AgentSkills + Pi 兼容）

SKILL.md 必须至少包含：

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

注意事项：

我们遵循 AgentSkills 规范的布局/意图。
内嵌智能体使用的解析器仅支持单行 frontmatter 键。
metadata 应该是单行 JSON 对象。
在说明中使用 {baseDir} 来引用 Skills 文件夹路径。
可选的 frontmatter 键：
- homepage — 在 macOS Skills UI 中显示为”Website”的 URL（也支持通过 metadata.fased.homepage）。
- user-invocable — true|false（默认：true）。当为 true 时，Skills 作为用户斜杠命令暴露。
- disable-model-invocation — true|false（默认：false）。当为 true 时，Skills 从模型提示词中排除（仍可通过用户调用使用）。
- command-dispatch — tool（可选）。当设置为 tool 时，斜杠命令绕过模型直接调度到工具。
- command-tool — 当设置 command-dispatch: tool 时要调用的工具名称。
- command-arg-mode — raw（默认）。对于工具调度，将原始参数字符串转发到工具（无核心解析）。工具使用以下参数调用： { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }。

门控（加载时过滤）

Fased 使用 metadata（单行 JSON）在加载时过滤 Skills：

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
  {
    "fased":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

metadata.fased 下的字段：

always: true — 始终包含该 Skills（跳过其他门控）。
emoji — macOS Skills UI 使用的可选表情符号。
homepage — 在 macOS Skills UI 中显示为”Website”的可选 URL。
os — 可选的平台列表（darwin、linux、win32）。如果设置，该 Skills 仅在这些操作系统上有资格。
requires.bins — 列表；每个都必须存在于 PATH 中。
requires.anyBins — 列表；至少一个必须存在于 PATH 中。
requires.env — 列表；环境变量必须存在或在配置中提供。
requires.config — fased.json 路径列表，必须为真值。
primaryEnv — 与 skills.entries.<name>.apiKey 关联的环境变量名称。
install — macOS Skills UI 使用的可选安装器规格数组（brew/node/go/uv/download）。

沙箱隔离注意事项：

requires.bins 在 Skills 加载时在宿主机上检查。
如果智能体处于沙箱隔离状态，二进制文件也必须存在于容器内部。通过 agents.defaults.sandbox.docker.setupCommand（或自定义镜像）安装它。setupCommand 在容器创建后运行一次。包安装还需要网络出口、可写的根文件系统和沙箱中的 root 用户。示例：summarize Skills（skills/summarize/SKILL.md）需要 summarize CLI 在沙箱容器中才能运行。

安装器示例：

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "fased":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

注意事项：

如果列出了多个安装器，Gateway 网关会选择单个首选选项（可用时选择 brew，否则选择 node）。
如果所有安装器都是 download，Fased 会列出每个条目，以便你查看可用的构件。
安装器规格可以包含 os: ["darwin"|"linux"|"win32"] 按平台过滤选项。
Node 安装遵循 fased.json 中的 skills.install.nodeManager（默认：npm；选项：npm/pnpm/yarn/bun）。这仅影响 Skills 安装；Gateway 网关运行时应仍为 Node（不推荐 Bun 用于 WhatsApp/Telegram）。
Go 安装：如果缺少 go 且 brew 可用，Gateway 网关会首先通过 Homebrew 安装 Go，并在可能时将 GOBIN 设置为 Homebrew 的 bin。
Download 安装：url（必填）、archive（tar.gz | tar.bz2 | zip）、extract（默认：检测到归档时自动）、stripComponents、targetDir（默认：~/.fased/tools/<skillKey>）。

如果没有 metadata.fased，该 Skills 始终有资格（除非在配置中禁用或被 skills.allowBundled 阻止用于内置 Skills）。

配置覆盖（`~/.fased/fased.json`）

内置/托管 Skills 可以被切换并提供环境变量值：

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

注意：如果 Skills 名称包含连字符，请用引号括起键名（JSON5 允许带引号的键名）。配置键默认匹配 Skills 名称。如果 Skills 定义了 metadata.fased.skillKey，请在 skills.entries 下使用该键。规则：

enabled: false 禁用该 Skills，即使它是内置/已安装的。
env：仅在变量在进程中尚未设置时注入。
apiKey：为声明 metadata.fased.primaryEnv 的 Skills 提供的便捷字段。
config：用于自定义单 Skills 字段的可选容器；自定义键必须放在这里。
allowBundled：可选的仅用于内置 Skills 的白名单。如果设置，只有列表中的内置 Skills 才有资格（托管/工作区 Skills 不受影响）。

环境变量注入（每次智能体运行）

当智能体运行开始时，Fased：

读取 Skills 元数据。
将任何 skills.entries.<key>.env 或 skills.entries.<key>.apiKey 应用到 process.env。
使用有资格的 Skills 构建系统提示词。
在运行结束后恢复原始环境。

这是限定于智能体运行范围内的，不是全局 shell 环境。

会话快照（性能）

Fased 在会话开始时对有资格的 Skills 进行快照，并在同一会话的后续轮次中重用该列表。对 Skills 或配置的更改在下一个新会话中生效。当 Skills 监视器启用或出现新的有资格的远程节点时，Skills 也可以在会话中刷新（见下文）。将此视为热重载：刷新后的列表会在下一个智能体轮次被获取。

远程 macOS 节点（Linux Gateway 网关）

如果 Gateway 网关运行在 Linux 上但连接了一个允许 system.run 的 macOS 节点（Exec 批准安全设置未设为 deny），当所需的二进制文件存在于该节点上时，Fased 可以将仅限 macOS 的 Skills 视为有资格。智能体应通过 nodes 工具（通常是 nodes.run）执行这些 Skills。这依赖于节点报告其命令支持以及通过 system.run 进行的二进制文件探测。如果 macOS 节点稍后离线，Skills 仍然可见；调用可能会失败，直到节点重新连接。

Skills 监视器（自动刷新）

默认情况下，Fased 监视 Skills 文件夹，并在 SKILL.md 文件更改时更新 Skills 快照。在 skills.load 下配置：

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

Token 影响（Skills 列表）

当 Skills 有资格时，Fased 将可用 Skills 的紧凑 XML 列表注入到系统提示词中（通过 pi-coding-agent 中的 formatSkillsForPrompt）。成本是确定性的：

基础开销（仅当 ≥1 个 Skills 时）： 195 字符。
每个 Skills： 97 字符 + XML 转义的 <name>、<description> 和 <location> 值的长度。

公式（字符）：

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

注意事项：

XML 转义将 & < > " ' 扩展为实体（&、< 等），增加长度。
Token 数量因模型分词器而异。粗略的 OpenAI 风格估计是 ~4 字符/token，所以每个 Skills 97 字符 ≈ 24 token 加上你的实际字段长度。

托管 Skills 生命周期

Fased 作为安装的一部分（repo 安装或 FasedAgent.app）发布一组基线 Skills 作为内置 Skills。~/.fased/skills 用于本地覆盖（例如，在不更改内置副本的情况下固定/修补 Skills）。工作区 Skills 由用户拥有，在名称冲突时覆盖两者。

配置参考

参见 Skills 配置了解完整的配置 schema。

寻找更多 Skills？

打开 Agent > Skills 并使用插件目录搜索。

​Skills（Fased）

​当前 UI 流程

​位置和优先级

​单智能体 vs 共享 Skills

​插件 + Skills

​插件目录（安装 + 同步）

​安全注意事项

​格式（AgentSkills + Pi 兼容）

​门控（加载时过滤）

​配置覆盖（~/.fased/fased.json）

​环境变量注入（每次智能体运行）

​会话快照（性能）

​远程 macOS 节点（Linux Gateway 网关）

​Skills 监视器（自动刷新）

​Token 影响（Skills 列表）

​托管 Skills 生命周期

​配置参考

​寻找更多 Skills？

Skills（Fased）

当前 UI 流程

位置和优先级

单智能体 vs 共享 Skills

插件 + Skills

插件目录（安装 + 同步）

安全注意事项

格式（AgentSkills + Pi 兼容）

门控（加载时过滤）

配置覆盖（`~/.fased/fased.json`）

环境变量注入（每次智能体运行）

会话快照（性能）

远程 macOS 节点（Linux Gateway 网关）

Skills 监视器（自动刷新）

Token 影响（Skills 列表）

托管 Skills 生命周期

配置参考

寻找更多 Skills？