Cezar Skills 完全指南:用 Markdown 文件教会 AI Agent 你的团队编码规范

原创2026-10-26 20:34:431,619 阅读

Cezar Skills 完全指南:用 Markdown 文件教会 AI Agent 你的团队编码规范

cezar 是一个开源的 AI 编码代理编排器,而它的 Skills(技能) 功能是最值得上手的一点:你只需写一个普通的 Markdown 文件,就能把团队的编码规范、代码评审标准、提交习惯"教给" Claude Code、Codex、OpenCode 等 AI Agent。本文面向新手,讲清楚 Skills 是什么、放在哪里、怎么写、怎么在任务和工作流中使用,以及如何让团队共享同一套规范。

什么是 Skill:一份 AI 能直接执行的 Markdown 剧本

在 cezar 里有三个核心概念:Task(任务)、Skill(技能)、Chain(工作流)。其中 Skill 就是一段 Markdown 文本——cezar 官方称之为 "Markdown playbooks"(剧本)。

它的工作方式非常直白:

  • 你在任务的某个步骤里引用一个 Skill;
  • cezar 会把该 Markdown 的正文内容作为额外的系统提示词注入 Agent 会话;
  • 于是 Agent 在推理和写代码时,就"记得"你的规范——命名规则、测试要求、错误处理方式等。

一句话概括:你不改代码,只改提示词,就能稳定地塑造 AI 的写法。这也是 cezar 强调的 "you shape how the agent reasons without touching code"。

cezar Workflow 编排界面:把 Skills 技能拖进任务链中保存为 YAML

Skills 放在哪里:5 个发现目录与优先级

cezar 启动任务前会自动扫描多个目录,合并出一份完整技能目录。发现顺序由 skills.ts 中的 SKILL_DIRS 定义,按以下优先级从高到低(同名时靠前的目录胜出):

优先级 目录 来源标签 说明
1 .ai/cezar/skills/ cezar 专属于 cezar 的本地技能
2 .ai/skills/ ai 与其他 Agent 工具共享的通用位置
3 .agents/skills/、.claude/skills/、.codex/skills/、.cursor/skills/、.opencode/skills/ agents npx skills 安装目录及各 Agent 的镜像目录
4 ~/.agents/skills/、~/.claude/skills/ global 用户级全局技能,所有项目可用
5 团队 Skills 仓库(git 远程仓库) team 详见下文"团队技能仓库"
6 内置技能 builtin cezar 自带的 create-cezar-automation 等

几个对新手友好的设计:

  • 零配置可用:一个目录都不存在也完全没问题,任务步骤会自动退化为纯提示词模式。
  • 本地优先:仓库里的技能永远能"盖住"同名团队技能,"用户的仓库才是事实来源"。
  • 目录即技能:只要某个文件夹里包含 SKILL.md,整个文件夹就是一个技能(以文件夹命名),其中的 references/*.md 等文件属于该技能的参考资料,不会被当成独立技能。

写你的第一个 Skill 文件

一个 Skill 就是一个 .md 文件,可选地带一段 YAML frontmatter 元信息。最小示例:

---
name: project-conventions
description: 本项目编码规范:类型优先、禁止 any、必须补测试
---

# 编码规范

- 使用 TypeScript 严格模式,禁止 any。
- 每个新增函数必须有单元测试。
- 提交信息遵循 Conventional Commits 格式。
  • name:技能名称,缺省时取文件名(SKILL.md 则取文件夹名)。
  • description:一句话说明用途,会显示在 Skills 目录页和任务选择器里,建议写好——Agent 和人都是先看描述决定用不用。
  • interactive: true:可选标记,表示该技能适合"边问边做"的交互式场景。

frontmatter 的解析逻辑在 parseFrontmatter 中实现,支持 key: value、内联数组和块状数组,格式宽松、容错友好。

写好 description 是关键:它决定了技能在目录页和任务下拉框里的"可读性",也帮助 Agent 判断何时该套用这份规范。

Skills 目录页:预览、搜索与开关一站搞定

打开驾驶舱左侧边栏的 Skills 页面(路由 /skills,实现见 skills.tsx),你会看到:

  • 完整技能列表,按来源分组:PROJECT(项目内)、GLOBAL(全局)、团队仓库名;
  • 搜索框,按名称和描述实时过滤;
  • 来源标签,一眼看出技能来自本地、全局还是远程团队仓库;
  • 预览面板:点击任意技能,右侧渲染完整的 Markdown 正文、frontmatter 源码,以及"被哪几个工作流引用"(Used by N workflows);
  • Refresh 按钮:对团队技能仓库执行一次 git fetch,拉取最新版本;
  • 开关:来自默认供应商仓库的团队技能可以逐个启用/停用,本地和全局技能则始终启用。

cezar Skills 技能目录页:Markdown 剧本预览、来源标签与工作流引用

团队技能仓库:一个 git 仓库,全项目共享

个人 Markdown 文件解决不了"全团队统一规范"的问题,cezar 的答案是 团队技能仓库(实现见 skills-remote.ts):

  1. 在项目下创建 .ai/cezar/config.json,写入 skillsRepos 字段即可:
{
  "skillsRepos": [{ "repo": "acme/skills", "ref": "main" }]
}
  1. cezar 会在后台做一次 bare clone(只克隆、不检出),缓存到全局的 ~/.cache/cez/skills/——一个仓库的克隆对所有项目复用,不占你的工作区;
  2. 技能列表、正文都通过 git ls-tree / git show 直接从缓存读取,离线时自动降级:团队技能暂时消失,本地技能照常工作,从不阻塞启动。

几个实用细节:

  • 组织级仓库:公司级共享仓库在 Settings → Global → Skills 中配置,存储于 ~/.cezar/config.json 的 orgSkillsRepos,对每个项目生效;组织仓库只认 skills/ 文件夹下的 Markdown,避免把仓库里的文档误当成技能。
  • 版本锁定:ref 可以钉住一个完整的 commit SHA,防止分支被强推后规范悄悄漂移。
  • 默认仓库:不配置任何东西时,cezar 默认加载 open-mercato/skills(PR 创建、代码评审、CI 修复、规范编写等通用技能),且支持按技能逐个停用。
  • 安全加固:远程地址只接受 owner/name、https/ssh/git URL 和本地路径,并禁用 ext::/fd:: 等 git 传输助手,杜绝配置被恶意注入的风险。

在任务与工作流中使用 Skills

写好的技能有三种最常用的用法:

1. 新建任务时直接选择。 在任务输入框下方点开技能选择器,选中一个 Skill 即可:

cezar 新建任务时从下拉框选择 Skill 技能并开启 Autonomous 模式

2. 写进工作流 YAML。 在 .ai/cezar/workflows/ 的步骤里加一行 skill:,Agent 步骤执行时就会套用该规范,onFail 还能让检查失败后带着错误信息自动重试(格式说明见 docs/reference.md):

steps:
  - id: implement
    prompt: "{{task}}"
    skill: project-conventions   # 套用你的 Markdown 技能
    runner: codex
  - id: verify
    command: "npm test"
    onFail: { retry: implement, max: 2 }

也可以完全不用写 YAML:在 Workflows 页把技能像搭积木一样拖进节点链,自动保存为 YAML。

3. 设为默认技能。 在配置里指定 defaultSkill,每次新建任务都会预选该规范;再配合 Autonomous 开关,Agent 会一路执行到底不再停下来问你——"选个剧本,打开自动驾驶,走人"。

值得一提的是,每个任务都运行在独立的 git worktree 里,cezar 会自动把选中的技能(以及正文中引用到的其他技能)安装进任务的 .claude/skills/ 和 .agents/skills/(逻辑见 skills-provision.ts),让 Agent 在自己的技能搜索路径里也能找到它们,且不会污染你的仓库。

自动检查与更新

通过 npx skills 安装并登记在 lock 文件里的 Open Mercato 技能,cezar 会在后台定时检查更新并自动应用,过程有锁保护、限时有缓存、失败静默降级,永远不会卡住启动。关闭方式有两个:

  • Settings → Global → Skills 中取消 "Update Open Mercato skills automatically";
  • 环境变量 CEZ_SKILLS_AUTO_UPDATE=0。

手动更新则很简单:Skills 页面点 Refresh 拉取团队仓库,或在页面上直接应用上游技能更新。

常见问题速答

  • 技能没出现在列表里? 检查文件是否在上述 5 类目录之一,且目录名含 SKILL.md 时技能名取文件夹名;远程技能则需要网络或本地缓存。
  • 同名技能哪个生效? 按优先级"本地盖远程":项目内 > 全局 > 团队仓库 > 内置。
  • 团队仓库离线了? 自动降级,本地技能不受影响;恢复网络后 Refresh 即可。
  • 技能正文能写什么? 任意 Markdown:清单、正反例代码片段、评审标准、流程说明——它最终就是 Agent 的系统提示词。

总结

cezar 的 Skills 把"教 AI 按团队规范干活"这件事降到了最低门槛:一个 Markdown 文件,一个目录约定,一份 git 共享仓库。新手可以从 .ai/skills/ 下放一个写满团队规范的文件开始,逐步走向组织级仓库 + 工作流 + 自动驾驶的完整流程。相关核心模块可参考 skills.ts(发现与解析)、skills-remote.ts(团队仓库)、skills-provision.ts(任务内安装)与 skills-update.ts(自动更新),完整配置项见 docs/reference.md。

登录后查看全文
cezar