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 改动

Skill 目录

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

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

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

调用方式

通过斜杠命令

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

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

模型自动触发

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

写好一个 skill 的几条经验

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

与项目指令的分工

下一步

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