Skill 编写

Skills 是教 Anyy 复用某个流程的最轻量方式。当能力可以用指令、示例、现有工具和 可选 helper 文件表达时，写 skill；只有在需要新的 runtime code、自定义 API 集成、 streaming 行为或新的审批边界时，才应该新增 tool。

本页说明如何编写 skill 文件。安装和运行时管理见 Skill 管理。

目录结构

Managed skill 是一个目录，目录 basename 必须匹配 SKILL.md 里的 name：

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

Anyy 识别四个支撑目录：

目录	用途
references/	额外文档、示例、API notes 和较长流程。
templates/	输出模板或可复用文本片段。
scripts/	assistant 可通过正常 tool policy 运行的 helper scripts。
assets/	图片、fixtures 或其他补充文件。

其他文件可以存在，但 skill_view 和 managed file writes 只暴露 SKILL.md 以及这四个目录 下的文件。

Front Matter

SKILL.md 必须以 YAML front matter 开头：

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

必填字段：

字段	规则
name	小写字母、数字和连字符；最长 64 个字符。
description	必填；最长 1024 个字符；不能包含类似 XML tag 的文本。

重要可选字段：

字段	存储方式
version	Skill version。
author、license	Skill metadata。
tags	Metadata tags。
platforms	与 Go runtime.GOOS 匹配的平台过滤，例如 linux 或 darwin。
metadata	嵌套在 metadata 下的通用 metadata。
anyy.metadata	复制到 skill metadata map 的 Anyy-specific metadata。
anyy.commands	该 skill 的显式 slash command descriptors。

不要把 Anyy-specific 字段放在嵌套的 metadata.anyy block 下。Anyy 从 顶层 anyy block 读取自己的 namespace。

编写指令

好用的 SKILL.md 应该让 assistant 清楚知道何时激活、怎么执行：

# Release Checklist

## When To Use

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

## Procedure

1. Inspect repository status and recent commits.
2. Run the documented verification commands.
3. Summarize release blockers before drafting the checklist.

## Pitfalls

- Do not invent release artifacts that are not present in the repository.
- Do not skip verification failures; include them as blockers.

## Verification

Confirm the checklist names the commands that were run and the exact result of
each command.

主文件应该聚焦常见路径。长 reference、示例和生成模板放到支撑文件里，然后在正文中说明何时用 skill_view(name, "references/file.md") 加载它们。

显式命令

每个可见 skill 在 TUI、CLI 和 API surfaces 上都会自动得到 synthetic /skill-name 命令。 如果需要不同命令名、channel-visible command、参数元数据，或自动加载支撑文件，则使用 anyy.commands：

anyy:
  commands:
    - name: /release-plan
      summary: Build a release plan from repository status.
      surfaces: [tui, cli, api, channel]
      load_files:
        - references/release-policy.md

规则：

• name 和 summary 必填。
• 省略 surfaces 时默认是 tui 和 cli。
• 与内置命令冲突的 command name 会被跳过。
• load_files 必须指向 skill 目录里的支撑文件。

支撑文件

在主指令中引用支撑文件：

For the full release policy, load `references/release-policy.md` with
`skill_view("release-checklist", "references/release-policy.md")`.

Anyy 会 normalize 支撑路径，并拒绝 path escape、absolute path 和使用反斜杠的路径。 Symlink 在列表中会被忽略，在 managed writes 中会被拒绝。

Agent-managed writes 的限制：

• patch 可以更新 SKILL.md 或支撑文件。
• write_file 和 remove_file 只能更新 references/、templates/、scripts/ 或 assets/。
• create 和 edit 的完整 SKILL.md 内容上限为 100,000 bytes。
• 支撑文件写入上限为 1 MiB。

Platform Filters

只有当 skill 真的依赖操作系统时才使用 platforms：

platforms: [darwin]

过滤值与 Go 的 runtime.GOOS 比较，而不是产品名称。macOS 使用 darwin，Linux 使用 linux，Windows 使用 windows。没有 platforms 的 skill 对所有平台可见。

编写检查清单

安装或提交 skill 前检查：

• SKILL.md 第一行是 ---，且 front matter 已关闭。
• 对 managed 或 system skills，name 与目录名一致。
• name 只使用小写字母、数字和连字符。
• description 用类似 "Use when..." 的触发条件描述开头。
• 正文说明何时使用、执行步骤、已知坑点和如何验证结果。
• 长 reference 放在 references/、templates/、scripts/ 或 assets/。
• Channel-visible commands 已显式声明需要的 surface。
• Skill 没有要求 assistant 绕过 approval、audit、provider、toolset 或 ChangePlan policy。

测试 Skill

安装本地 skill：

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

如果 gateway 正在运行，并且你需要立刻使用该 skill：

anyy skills install --now ./release-checklist

然后在 TUI 或其他该命令可见的 surface 里调用：

/release-checklist review the current repository state

如果 skill 不可见，检查：

• active --home 或 profile，
• skills.disabled 和 skills.disabled_by_surface，
• platforms，
• command surface declarations，
• 更早 root 中的重复名称 shadowing，
• skills RPC 中的 load warnings。