Skills 系统

Skills 是 Anyy 可按需加载的可复用指令文档。它们是过程性记忆：适合保存“这个流程应该怎么做”；而持久化 memory 更适合保存稳定事实、偏好和环境信息。

Anyy 不把 skill 当作代码插件。一个 skill 是一个 SKILL.md 文件，加上可选的支撑文件，用来指导现有 agent、tools、approval 和 runtime policy。加载 skill 不会绕过工具治理、ChangePlan、审批策略、审计、provider 边界或已启用的 toolsets。

Skills 如何被发现

运行时，Anyy 会从多个 root 合成一个 skill catalog：

Root	来源	managed skill 操作是否写入
`<home>/skills`	profile-local 已安装和 agent-created skills	是
`skills.external_roots[]`	配置中的额外目录	否；作为 external root 扫描
`~/.agents/skills`	如果存在，会作为便携用户 skill root	否；作为 external root 扫描
`<home>/system/skills`	Anyy materialize 的系统 skills	否

没有 --home、ANYY_HOME 或 profile 选择时，active home 的内置 fallback 是 /root/.anyy。普通用户安装通常会通过 profile 或显式 --home 使用 ~/.anyy。

如果多个 root 里有同名 skill，先出现的 root 生效。因此 <home>/skills 里的 skill 会覆盖 external 或 system root 里的同名 skill。

缺失或格式错误的 root 不会让整个 catalog 加载失败。运行时会保留有效 skills，并通过 skills RPC 报告 load warnings。

使用 Skills

列出可用 skills：

anyy skills list

在 TUI 或暴露 gateway commands 的 runtime client 中使用：

/skills

查看某个 skill：

anyy skills view my-skill
anyy skills view my-skill references/workflow.md

模型轮次中，skills toolset 提供相同的读取路径：skills_list 和 skill_view。Anyy 会指示 assistant 只有在任务实质匹配某个 skill、并且完整指令会改变执行方式时，才调用 skill_view(name)。

动态 Slash Commands

每个可见 skill 都会得到一个按 skill 名生成的 synthetic slash command：

/my-skill explain this repository's release flow

Synthetic skill commands 暴露在 TUI、CLI 和 API surfaces。Messaging adapters 只会看到对应 channel surface 可用的命令。如果 skill 需要 channel 命令，需要在 anyy.commands 里显式声明，并包含 channel 或 weixin 等 surface。

用户调用 dynamic skill command 时，Anyy 会为当前 turn 加载该 skill 的完整 SKILL.md，并把命令后的文本作为用户任务发送。

渐进式披露

Skills 分层加载，避免模型在每一轮都携带所有 skill 正文：

层级	机制	加载内容
Catalog	Prompt index、`/skills`、`skills_list`	名称、描述、scope、commands、metadata 等 compact metadata。
主文件	`/skill`、`anyy skills view`、`skill_view(name)`	完整 `SKILL.md` 和支撑文件列表。
支撑文件	`skill_view(name, "references/file.md")`	Skill 目录下的一个文件。
Command load files	`anyy.commands[].load_files`	调用某个显式 skill command 时自动加载的支撑文件。

这样普通 session 保持轻量，同时 skill 仍然可以携带 reference material、scripts、 templates 或 assets。

SKILL.md 格式

每个 skill 都是一个目录，里面必须有 SKILL.md：

<home>/skills/
  release-checklist/
    SKILL.md
    references/
      workflow.md
    templates/
      release-notes.md
    scripts/
      collect-status.sh
    assets/
      diagram.png

Front matter 必须从 SKILL.md 顶部开始，用 --- 关闭，并包含 name 和 description：

---
name: release-checklist
description: Use when preparing an Anyy release checklist from repository state.
version: 1.0.0
author: Anyy Team
license: MIT
tags: [release, docs]
platforms: [linux, darwin]
anyy:
  metadata:
    category: release
  commands:
    - name: /release-checklist
      summary: Load release-checklist instructions.
      surfaces: [tui, cli, api]
      load_files:
        - references/workflow.md
---
# Release Checklist

## When To Use

Use this skill when...

## Procedure

1. Inspect repository status.
2. Build the checklist.

## Verification

Confirm...

必需校验规则：

字段	规则
`name`	只能使用小写字母、数字和连字符；最长 64 个字符。
`description`	必填；最长 1024 个字符；不能包含类似 XML tag 的文本。
目录名	对 managed 和 system skills，目录名必须等于 `name`。
保留名称	Skill name 不能包含 validator 拒绝的 provider-reserved words。

可选字段包括 version、author、license、tags、platforms、顶层 metadata，以及 Anyy 专用的 anyy.metadata 和 anyy.commands。

platforms 会按 Go runtime platform 过滤 skill。Linux 使用 linux，macOS 使用 darwin，也可以使用其他精确的 runtime.GOOS 值。不设置时，skill 对所有平台可见。

显式 Skill Commands

anyy.commands 用来为 skill 声明显式命令：

字段	必填	含义
`name`	是	Slash command 名称，通常以 `/` 开头。
`summary`	是	在 command catalog 中展示的说明。
`surfaces`	否	命令出现在哪些 surfaces。省略时默认 TUI 和 CLI。
`args_schema`	否	面向 command clients 的 JSON-schema-like 参数元数据。
`load_files`	否	该命令触发 skill 时一并加载的支撑文件。

可用 surface 名称包括 tui、cli、api、channel、weixin 和 cron。与内置命令冲突的 skill command 会被跳过。

支撑文件

Skill viewer 和 manager 识别以下支撑目录：

目录	用途
`references/`	assistant 可按需加载的额外文档和示例。
`templates/`	输出模板或可复用片段。
`scripts/`	如果 policy 允许，assistant 可通过普通工具运行的 helper scripts。
`assets/`	图片、fixtures 或其他补充文件。

支撑路径必须是相对路径，使用正斜杠，并且不能逃逸 skill 目录。Symlink 和非 regular file 会被忽略或拒绝。

配置

Skills runtime 配置位于 config.yaml 的 skills 下：

skills:
  external_roots:
    - ~/.agents/skills
    - ${TEAM_SKILLS_ROOT}
  disabled:
    - skill_user_abc123
  disabled_by_surface:
    tui:
      - experimental-skill
    api:
      - /internal-command

字段	含义
`external_roots`	在 `<home>/skills` 之后、system skills 之前扫描的额外目录。支持 `~`、`$VAR` 和 `${VAR}` 展开。缺失环境变量会让该 root 被跳过。
`disabled`	全局隐藏列表。条目可以是 skill ID、skill name 或 skill command name。
`disabled_by_surface`	按 surface 隐藏，条目形式同 `disabled`。

Gateway 也可以通过 skills.toggle RPC 按精确 skill ID toggle 非 system skill。它会写入 skills.disabled，并为 active scope 重新加载 catalog。

安全模型

Skill 读取属于低风险 runtime read。Skill mutation 属于高风险配置变更，并按 skill change 审计。

Managed installs 和 agent writes 有这些边界：

HTTPS skill URL 必须使用 https，不能包含凭据，且不能指向 private 或 internal network hosts。
单个远程 SKILL.md URL 需要 --name，并且必须 self-contained。
GitHub install 通过 GitHub API 获取 committed files，拒绝 symlink 和不支持的 tree entry，限制文件数量和大小，扫描 staged directory，并在 <home>/skills/.manifest.json 记录来源。
Dangerous scan finding 会阻止安装。Caution finding 需要 --force。
Managed edits 拒绝 symlinked skills，只能写 SKILL.md 或 references/、templates/、 scripts/、assets/ 下的文件。

Skills 可以告诉 assistant 应该怎么做，但不会授予新的 tool access。真正能运行什么，仍由 active toolsets、tool governance、approval policies 和 provider/runtime 边界决定。

Skills 如何被发现​

使用 Skills​

动态 Slash Commands​

渐进式披露​

SKILL.md 格式​

显式 Skill Commands​

支撑文件​

配置​

安全模型​