Skills 扩展

Skill 是用户自定义的、可复用的命令,它本质上是一段带 frontmatter 的 markdown 指令,告诉 AI"在这种任务下应该怎么做"。写好 skill 之后,它会像内置斜杠命令一样出现在菜单里,或者被 use_skill 工具按需调用。

Skill 能做什么

• 把常见工作流固化下来:发布 release、写 changelog、跑回归测试、生成周报…
• 封装需要一步一步引导的复杂任务:代码重构流程、bug 根因分析、性能调优
• 让模型在特定话题下遵循你定义的步骤和校验规则

Skill 文件结构

一个 skill 通常是一个目录,里面至少包含一个 SKILL.md:

my-skills/
├── release/
│   └── SKILL.md
├── write-changelog/
│   └── SKILL.md
└── debug-flaky-test/
    ├── SKILL.md
    └── references/
        └── pattern-library.md

SKILL.md 的典型格式:

---
name: release
description: 发布一个新的 release tag,更新 changelog,并打包
---

## 何时使用

当用户说"发布新版本"、"出一个 release"、"打 tag" 时使用。

## 步骤

1. 通过 `git log` 确认上次发布以来的改动
2. 让用户确认 semver 版本号(patch / minor / major)
3. 更新 `CHANGELOG.md` 中新增条目
4. 运行 `pnpm build` 并确保构建通过
5. 创建 git tag `v<version>` 并写上发布说明
6. 运行 `pnpm publish`(或者对应的发布命令)

## 规则

- 版本号必须符合 semver
- 不允许绕过测试,任何失败都必须先修复
- 发布失败时,回滚所有本地 tag 和 changelog 改动

工具预授权：allowed-tools

allowed-tools 声明调用此 skill 的当前回合可以免去常规审批的工具。它不是排他白名单：未列出的工具仍可调用，继续按现有权限与审批规则处理。

推荐使用 allowed-tools；兼容下划线别名 allowed_tools，校验规则相同。重复声明该字段（包括两种写法混用）会拒绝加载。

---
name: setup
description: 安装 vibekeys-plugin 的 hidapi 依赖
allowed-tools:
  - Bash(pip3 *)
  - Bash(pip *)
  - Bash(python3 -c *)
---

支持 YAML 缩进列表、行内列表（allowed-tools: [Bash, read_file]），也支持空格或逗号分隔的单行字符串（allowed-tools: Bash(pip3 *) read_file）。括号内的空格保留。工具名和模式复用静态 permissions 规则的匹配语法，Bash 与 bash、Read 与 read_file 对应。语法不完整的声明拒绝加载，不会退化成宽泛授权。

通过斜杠命令、$ 菜单、/skills 或模型的 use_skill 成功调用后，授权仅作用于调用它的 agent；下一条用户消息（包括运行中的追加消息）、回合结束或取消、会话切换和运行时重建都不会继承旧授权。恢复历史会话也不会重新授予权限。

全局或项目级 deny 仍优先；敏感路径、凭据、plan mode 等安全边界不被绕过。AtomCode 还保留对破坏性 shell 命令的常规审批：skill 的声明不让这类命令免审批。这是在 Claude Code 预授权语义上保留的产品安全限制；用户自己配置的静态 allow 规则仍按原有语义处理。

Bash 预授权不是沙箱。 Shell 命令本身仍可能读写文件或联网；不要把 allowed-tools: Bash 解读为“只能安装依赖”。插件 hook 和 skill 模板中的预执行 shell 片段属于独立执行入口，不受此模型工具调用预授权控制。

Skill 目录

AtomCode 会从若干约定位置加载 skills:

• 全局:~/.atomcode/skills/
• 项目级:当前工作目录及其上级的 .atomcode/skills/(如有)

项目级会覆盖同名全局 skill,方便你在不同项目用同一个名字定义不同流程。

调用方式

通过斜杠命令

所有加载成功的 skill 会自动出现在斜杠命令补全菜单里:

> /release
> /write-changelog
> /debug-flaky-test

通过 $ 菜单

在输入框行首打一个 $,会弹出一个 skills 菜单(和 /skills 列出的是同一批可调用技能);继续输入可过滤,Tab 补全高亮项的名字,提交 $<name> [参数] 即调用该 skill。它和斜杠命令是两套并行入口:/ 走斜杠命令补全,$ 专门用来挑 skill,后面还能直接带参数,例如 $brainstorming 帮我想登录方案。

v5.0.3 的 /skills 支持用多个名称或片段一次选择多个 Skill，并会回显实际加载结果。新安装的 Skill 也会自动刷新，通常不需要重启 AtomCode。

模型自动触发

模型可以主动调用 use_skill 工具,把一个与任务相关的 skill 作为子流程运行。比如你说"帮我发布新版本",即便不显式打 /release,模型也可能自动选择调用这个 skill。

写好一个 skill 的几条经验

• description 要具体 —— 它决定了菜单里的描述文本,也是模型判断"要不要用这个 skill"的主要依据。
• 步骤要有序 —— 模型会按顺序读,把强依赖步骤放在前面。
• 明确分支 —— "如果 build 失败则…;否则…",比让模型自己猜要可靠得多。
• 列出红线 —— 绝对不能做的事情放在独立的"规则"小节,提高顺从度。
• 必要时用子文档 —— 把很长的参考资料放到 references/*.md,只在 SKILL.md 里留一句"必要时参见…"。

与项目指令的分工

下一步

• 基本使用 —— 回到日常使用场景
• 常见问题 —— 为什么我的 skill 没出现在菜单里?