Cezar Skills 完全指南:用 Markdown 文件教会 AI Agent 你的团队编码规范
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"。
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,拉取最新版本; - 开关:来自默认供应商仓库的团队技能可以逐个启用/停用,本地和全局技能则始终启用。
团队技能仓库:一个 git 仓库,全项目共享
个人 Markdown 文件解决不了"全团队统一规范"的问题,cezar 的答案是 团队技能仓库(实现见 skills-remote.ts):
- 在项目下创建
.ai/cezar/config.json,写入skillsRepos字段即可:
{
"skillsRepos": [{ "repo": "acme/skills", "ref": "main" }]
}
- cezar 会在后台做一次 bare clone(只克隆、不检出),缓存到全局的
~/.cache/cez/skills/——一个仓库的克隆对所有项目复用,不占你的工作区; - 技能列表、正文都通过
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 即可:
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。


