使用 Skills

Skills 是 Anyy 可以为某个任务加载的可复用流程：release checklist、项目 workflow、troubleshooting playbook、写作规范，或特定工具的操作 recipe。

完整参考见 Skills 系统。安装和生命周期管理见 Skill 管理。

什么时候使用 Skill

适合使用 skill 的工作是可重复的流程：

会反复运行的 checklist；
项目特定 release 或 deploy flow；
troubleshooting playbook；
写作或 review convention；
多步骤工具 recipe。

不要用 skill 保存一次性事实、secrets、临时 TODO 或原始研究链接。稳定事实放进 memory，临时进度留在 session，需要保存的材料放进 files/artifacts。

查找 Skills

列出当前 catalog：

anyy skills list

在 TUI 或其他暴露 gateway commands 的 runtime client 中：

/skills

Catalog 包含 active home、配置的 external roots、存在时的便携 ~/.agents/skills root，以及 Anyy system skills。如果某个 skill 缺失，先确认你正在使用预期 home：

anyy skills list --home ~/.anyy

使用前先查看 Skill

打开主指令：

anyy skills view release-checklist

当主文件指向 supporting file 时，打开该文件：

anyy skills view release-checklist references/workflow.md

在 session 中：

/skill release-checklist

Supporting paths 必须是相对路径、使用正斜杠、留在 skill directory 内，并指向 regular files。

使用 Skill

对 TUI、CLI 和 API surfaces 上的 visible skills，最简单的路径是 synthetic slash command：

/release-checklist review the current repository state

也可以自然语言请求：

Use the release-checklist skill to prepare this repository for a docs release.

Anyy 默认给模型一个 compact skill index。Assistant 只在相关时用 skill_view 加载完整 skill，然后在与其他 turn 相同的 tool、approval、audit 和 ChangePlan 规则下执行。

Messaging adapters 只暴露对该 channel surface 可用的 skill commands。一个 skill 存在于磁盘上，并不代表它自动成为消息平台命令。

安装本地 Skill

当你自己开发或 review skill 时，使用本地目录：

anyy skills install ./release-checklist
anyy skills view release-checklist

目录必须包含有效的 SKILL.md。对 managed skills，目录名必须匹配 name 字段。

如果 gateway 已经在运行，并且你希望新 skill 立刻可用：

anyy skills install --now ./release-checklist

不带 --now 时，文件会立即安装到磁盘，但运行中的 gateway 会继续使用当前 catalog，直到 reload 或 restart。

从 GitHub 安装

安装一个 skill directory：

anyy skills install github:owner/repo/path@main

只有当你明确想安装整个 collection 时，才安装 repository 中所有 candidate skills：

anyy skills install --all github:owner/repo
anyy skills install github:owner/repo/*

只有在你明确想替换同名 skill 时，才使用 --force：

anyy skills install --force github:owner/repo/path@main

Anyy 会通过 GitHub API 获取 committed files，在 managed manifest 中记录 ref 和 commit SHA，并在 commit 安装前扫描 staged content。Managed install 不会执行 third-party setup scripts。

安装单个 SKILL.md URL

公开 HTTPS SKILL.md 如果是 self-contained，可以这样安装：

anyy skills install --name release-checklist https://example.com/SKILL.md

当 skill 依赖 reference files、templates、scripts 或 assets 时，使用 directory 或 GitHub source。单文件 URL 不能携带这些文件。

添加共享 Skill Root

如果你在共享目录维护 skills，把它添加到 config.yaml：

skills:
  external_roots:
    - ~/.agents/skills
    - ${TEAM_SKILLS_ROOT}

然后 reload 正在运行的 gateway：

anyy skills reload

External roots 在 <home>/skills 后扫描，因此本地 managed skills 会覆盖同名 shared skills。

编写一个小 Skill

创建目录：

mkdir -p ~/.anyy/skills/release-checklist

写入 ~/.anyy/skills/release-checklist/SKILL.md：

---
name: release-checklist
description: Use when preparing a release checklist from repository state.
version: 1.0.0
tags: [release, checklist]
anyy:
  metadata:
    category: release
---
# Release Checklist

## When To Use

Use this skill when the user asks to prepare, verify, or review a release
checklist.

## Procedure

1. Inspect repository status.
2. Run the required verification commands.
3. Report blockers before drafting the checklist.

## Verification

Confirm the answer names the commands that were run and their results.

如果 gateway 正在运行，先 reload；否则启动一个新 session，让 catalog 从磁盘重新构建：

anyy skills reload

/release-checklist review this docs branch

如果内容更复杂，把详细说明放进 references/，并在主文件里说明 assistant 何时加载它们。

保持 Skills 健康

一个好的 skill 会说明：

何时使用；
按什么步骤做；
不要杜撰什么；
需要加载哪些支撑文件；
如何验证结果。

当 skill 过期时，优先 patch 现有 skill，而不是新增一个高度重复的 skill。如果你在 session 里让 Anyy 更新 managed skill，skill_manage 工具可以 patch 或 edit managed skill files，并在请求时 reload catalog。

Skills 不授予 tool access。如果 skill 要求 assistant 运行命令，但相关 toolset 未启用或 policy 要求 approval，正常 runtime 规则仍然生效。

故障排查

问题	检查
Skill 不在列表中	Active `--home` 或 profile、缺失 root、front matter 格式错误、`skills.disabled`、`platforms`、重复名称 shadowing。
Slash command 不出现	Command surface、内置命令冲突，或 skill 对该 surface 不可见。
已安装 skill 在运行中的 gateway 不生效	运行 `anyy skills reload`，重启 gateway，或安装/卸载时使用 `--now`。
Supporting file 打不开	路径必须是相对路径、使用正斜杠、留在 skill directory 内，并指向 regular file。
GitHub install 被阻止	检查 scan findings、文件数量/大小限制、symlinks、path escapes 或不支持的 repository layout。
单 URL install 失败	添加 `--name`，使用 HTTPS，并确认 `SKILL.md` 是 self-contained。

什么时候使用 Skill​

查找 Skills​

使用前先查看 Skill​

使用 Skill​

安装本地 Skill​

从 GitHub 安装​

安装单个 SKILL.md URL​

添加共享 Skill Root​

编写一个小 Skill​

保持 Skills 健康​

故障排查​