本文由 莫潇羽@无忆研习社（www.wuyi.wiki）撰写，转载请注明出处。
快速摘要
如果你只有两分钟，看这里：
CodeBuddy 是腾讯推出的 AI 编程工具矩阵，涵盖 IDE 插件、独立 IDE 和 CLI 命令行三种形态，可以理解为腾讯版的 AI 编程全家桶。 其中 CodeBuddy Code（CLI 版）于 2025 年 9 月正式发布，在命令行里实现自然语言驱动的全流程开发，支持多模型切换（包括混元、DeepSeek 等国内模型）。
在 CLI 工具背后，还有一套叫做 Agent Skills（技能包） 的新型工程范式。它不是 Prompt，不是 MCP，而是介于两者之间的"标准化 SOP 工具包"：把提示词、脚本、知识库三合一，通过渐进式三层加载机制（L1 元数据→L2 核心指令→L3 资源文件）大幅降低 Token 消耗、提升复杂任务的执行质量。
本文核心内容：
- CodeBuddy 三种形态对比及安装上手
- CLI 核心命令逐一拆解（-p 无头模式、-r 会话恢复、/model 模型切换、yolo 权限模式……）
- Memory 记忆与规则（Rules）配置方法
- Agent Skills 底层原理与三层加载机制详解
- 从零搭建一个企业级技能包（以会议纪要自动同步为例）
- Skills 在 CodeBuddy / Trae / 扣子中的跨平台使用
- MCP 服务配置与自定义开发
想看完整拆解，往下翻。
一、CodeBuddy 到底是什么，跟其他 AI 编程工具有何不同
市面上 AI 编程工具越来越多，开发者容易被各种新名词搞乱。我自己折腾了一段时间，把 CodeBuddy 放在整个 AI 编程工具的大背景里看，它最大的特点是三形态合一：
- CodeBuddy 插件：装在 VS Code 或 JetBrains 里的补全助手，主打日常编码提速，Craft 模式可生成多文件项目，是国内首批支持 MCP 的代码助手之一。
- CodeBuddy IDE：独立的桌面 IDE，集成了从产品设计到部署的全流程，强调"无需一行代码，自然语言对话即可开发应用"，国际版整合了多个主流大模型，国内版支持腾讯混元、DeepSeek 等。
- CodeBuddy Code（CLI）：2025 年 9 月发布的命令行工具，面向习惯终端作业的专业开发者，逻辑跟 Claude Code 非常接近，但对国内开发环境更友好，支持国内模型，安装不需要额外操作。
三者共用额度，可以按场景自由切换。
┌─────────────────────────────────────────────────────────┐
│ CodeBuddy 三形态对比 │
├───────────────┬─────────────┬────────────┬──────────────┤
│ │ 插件形态 │ IDE 形态 │ CLI 形态 │
├───────────────┼─────────────┼────────────┼──────────────┤
│ 适用人群 │ 专业开发者 │ 非技术背景 │ 专业/高级开发│
│ 安装方式 │ 插件市场 │ 独立安装包 │ npm 一行命令 │
│ 核心场景 │ 补全/Craft │ 自然语言建 │ 终端+管道+CI │
│ 模型支持 │ 混元/DS等 │ 国内外均有 │ 国内外均有 │
│ MCP 支持 │ ✅ │ ✅ │ ✅ │
└───────────────┴─────────────┴────────────┴──────────────┘根据腾讯公开的数据，腾讯内部已有超过 90% 的工程师在用 CodeBuddy，编码时间平均缩短 40% 以上，AI 生成代码占比超过一半。这个数据不管怎么看，说明它在真实的大规模工程场景里经过了验证。
值得一提的是，这套工具在能力设计上对齐了当前主流 AI 编程工具的通用范式，比如自定义 Agents、Skills 技能包、MCP 集成等——这些都是眼下 AI 编程工具的标配方向，不是某一家独有的。这意味着学会了 CodeBuddy 的核心用法，迁移到其他工具的成本很低；同样，如果你之前用过其他 AI CLI 工具，上手 CodeBuddy 也不会有太大障碍。
对于个人开发者来说，CLI 形态是学习成本最低、上限最高的入口。接下来我会重点拆解这块。
二、安装与快速上手
2.1 前置依赖：Node.js
CodeBuddy Code 基于 npm 分发，所以第一步是装 Node.js。去官网下 LTS 版本，Windows 记得勾选"Add to PATH"，装完验证一下：
node -v
npm -v两个命令都有输出，说明环境 OK。
2.2 安装 CodeBuddy Code
npm install -g @tencent-ai/codebuddy-code国内网络下 npm 有时候慢，可以先切到腾讯源加速：
npm config set registry https://mirrors.cloud.tencent.com/npm/装完之后执行下面的命令验证：
codebuddy --version
# 或者简写
cbc --version看到版本号就说明安装成功了。CodeBuddy Code 有个简写叫 cbc，跟 codebuddy 效果完全一样，打起来省事。
2.3 登录授权
首次运行 codebuddy 会弹出浏览器做登录授权，支持腾讯云账号登录。国际版可以用 Google/GitHub 账号。登录成功后终端会显示一个类似下面的交互界面：
╔══════════════════════════════════════╗
║ CodeBuddy Code CLI ║
║ AI-powered terminal development ║
╚══════════════════════════════════════╝
> 进到这个界面，就可以开始用了。最直接的用法就是自然语言提需求，比如"帮我分析一下当前目录的项目结构"，它会自动扫描文件、分析后给出回答。
三、CLI 核心命令全拆解
这是 CodeBuddy Code 的精华所在。我把用得到的命令按场景归类，逐一讲清楚。
3.1 两种交互模式
交互模式（默认）：直接运行 codebuddy，进入类似聊天的对话界面，支持多轮问答，AI 会记住上下文。
无头模式（-p 参数）：适合单次任务或与 Shell 脚本配合，结果直接输出到终端，不需要人参与交互。
# 无头模式：让 AI 分析当前目录
codebuddy -p "请分析当前项目结构，列出主要模块" --dangerously-skip-permissions
# 结合管道：抓取 git 日志交给 AI 分析
git log --oneline -20 | codebuddy -p "分析这些提交，找出可能引入 bug 的变更" --dangerously-skip-permissions--dangerously-skip-permissions 这个参数后面会专门解释，现在只需要知道：加上它，AI 可以自动执行命令，不需要每次手动确认。
这两种模式的区别，简单说就是：交互模式适合探索性工作（"我还不确定要做什么，边聊边想"），无头模式适合明确任务（"我知道要干嘛，给我结果就行"）。
3.2 会话管理：-r 和 -c
# 恢复上次会话
codebuddy -r
# 列出历史会话，选择恢复
cbc -r这个功能特别实用。比如你同时在跑两个项目，一个写前端一个写后端，分别开了两个 codebuddy 会话。第二天回来想继续某个任务，用 -r 能看到会话列表，选一个恢复，上下文全在。
# 连接到 IDE（自动检测当前 IDE 并关联）
codebuddy --ide这个命令会让 CLI 和 CodeBuddy IDE 建立连接，方便在终端和图形界面之间切换。
3.3 模型切换：/model
在交互模式下，输入 /model 可以看到可用模型列表并切换：
/model会显示类似这样的列表（国内版）：
|
模型名称 |
速度倍率 |
适用场景 |
|
腾讯混元（默认） |
1x |
日常开发、代码补全 |
|
DeepSeek-V3 |
0.8x |
长代码生成、复杂逻辑 |
|
DeepSeek-V3.1 |
1.2x |
需要更快响应时 |
速度倍率越高，Token 消耗越大，但出结果越快。我的习惯是平时用默认模型，处理复杂架构设计时切到能力更强的版本。
也可以在启动时直接指定模型：
codebuddy --model deepseek-v3 -p "帮我设计一个微服务架构"
# 设置回退模型：主模型超载时自动降级
codebuddy --model deepseek-v3 --fallback-model hunyuan -p "复杂任务"3.4 权限控制：从标准模式到 yolo 模式
这是很多人踩坑的地方，要单独说清楚。
默认权限模式：每当 AI 要执行一个"有副作用"的操作（创建文件、运行命令、删除内容……），都会弹出确认提示，需要用户选 yes/no。安全，但效率低。
yolo 模式（--dangerously-skip-permissions）：跳过所有权限验证，AI 想执行什么就执行什么，无需确认。效率极高，但风险也大——AI 搞错了你也不会被提醒，有可能误删文件。
# 启用 yolo 模式
codebuddy -p "帮我重构这个文件" --dangerously-skip-permissions
# 或者在交互模式下通过 Shift+Tab 循环切换权限模式我自己的做法是：在沙盒环境（Docker 容器、虚拟机）里用 yolo 模式跑复杂任务，本地生产代码库一律用标准模式。这样既不损失效率，也不会付出代价。
还有一种细粒度控制，通过 --allowedTools 参数指定允许执行哪些工具类型：
# 只允许读取和编辑，不允许执行命令
codebuddy --allowedTools "Read Edit" -p "分析代码质量"3.5 输出格式控制
# JSON 格式输出，方便程序处理
codebuddy -p "分析这个函数的性能" --output-format json | jq '.response'
# 流式输出（打字机效果），适合生成长内容
codebuddy -p "帮我写一个完整的技术方案文档" --output-format stream-json3.6 调试与诊断
# 开启 debug 模式，查看详细日志
codebuddy --debug -p "测试某个功能"
# 详细输出模式
codebuddy --verbose -p "需要更多信息的任务"3.7 常用快捷键汇总
在交互模式里，下面这些快捷键会经常用到：
↑ / ↓ 查看历史命令
Tab 自动补全命令
Ctrl+C 退出当前会话
Shift+Tab 循环切换权限模式（标准 → 自动接受 → 计划 → yolo）
/clear 清空当前对话上下文
/cost 查看当前会话 Token 消耗
/memory 管理记忆文件（后面详讲）
\help 列出所有斜杠命令3.8 结合 Linux 命令的高效玩法
CLI 模式最有价值的地方，是能把 AI 能力和已有的 Shell 命令无缝接管。这是图形化 IDE 做不到的。
场景一：分析线上错误日志
以前分析日志，要人工 tail -f 盯着看，效率很低。现在可以这样：
# 抓取最近 100 行错误日志，交给 AI 分析
tail -n 100 /var/log/app/error.log | codebuddy -p "分析这些错误日志，找出最频繁的错误类型，给出可能的根因" --dangerously-skip-permissionsAI 会帮你扫描日志、归类错误、推断可能的原因，通常几秒钟能给出一个结构化的分析报告，比人工翻日志快得多。
场景二：分析 Git 提交历史
# 分析过去两周的提交，找出可能引入性能问题的变更
git log --since="2 weeks ago" --oneline --stat | codebuddy -p "分析这些 git 提交，哪些变更可能引入了性能问题？重点关注数据库查询相关的改动" --dangerously-skip-permissions场景三：批量处理脚本
如果你要批量生成多份文档，或者对一批文件做相同的处理，可以写一个 Shell 循环，在循环里调用 codebuddy：
# 批量为目录下的每个 Python 文件生成单元测试
for file in src/*.py; do
codebuddy -p "为以下文件生成单元测试，遵循 pytest 规范：$(cat $file)" \
--output-format json \
--dangerously-skip-permissions > "tests/test_$(basename $file .py).py"
done这三个场景用起来，CodeBuddy CLI 就从"聊天工具"变成了真正的"开发自动化引擎"。
CodeBuddy Code 的配置有三个层级，从低到高优先级依次是：用户级 < 项目级 < 本地个人级。
~/.codebuddy/settings.json ← 用户级（所有项目通用）
└── 当前项目/.codebuddy/
├── settings.json ← 项目级（提交到 Git，团队共享）
└── settings.local.json ← 本地个人级（加入 .gitignore）用户级配置：当前电脑上所有项目都会读取，适合写一些个人偏好，比如默认模型、常用的 API Key。
项目级配置：提交到代码仓库，团队里所有人共享一套规范，适合团队统一的权限策略、默认模型、MCP 配置。
本地个人级：加到 .gitignore，只对自己生效，不影响别人，适合一些个人习惯设置。
一个典型的项目级配置文件长这样：
{
"model": "deepseek-v3",
"permissions": {
"allow": ["Read", "Edit", "Bash(git:*)"],
"deny": ["Bash(rm:*)"]
},
"env": {
"NODE_ENV": "development"
}
}这里的权限规则语法支持到命令级别——比如允许所有 git 命令，但明确禁止 rm 删除操作。团队协作时，建议把这套权限策略写进项目级配置，防止 AI 在执行任务时误操作生产数据。
五、Memory 记忆功能：让 AI 记住你的项目
每次新开一个 codebuddy 对话，AI 默认对你的项目一无所知。Memory 功能就是用来解决这个问题的——把项目规范、技术栈、约定俗成的东西写进一个 Markdown 文件，让 AI 每次都能"预加载"这些背景知识。
5.1 创建记忆文件
在交互模式下输入：
/memory会出现两个选项：项目级记忆 or 用户级记忆。
- 项目级：放在
.codebuddy/CODEBUDDY.md，只对当前项目生效，可以提交到 Git。 - 用户级：放在
~/.codebuddy/CODEBUDDY.md，对这台机器上所有项目生效。
选项目级更常见，点确认后工具会帮你自动打开这个文件。
5.2 写什么进去
这个文件就是你的"项目说明书"，内容随便写，AI 每次启动都会读取。一个写得好的项目记忆文件大概是这个结构：
# 项目背景
本项目是一个面向中小企业的 CRM 系统，前端用 Vue 3 + TypeScript，后端用 Java Spring Boot。
# 技术规范
- Python 脚本统一用 3.10+，不用 f-string 以外的格式化方式
- 前端组件命名用 PascalCase，文件名用 kebab-case
- 提交信息格式：feat/fix/docs/chore: 简短描述
# 测试覆盖率要求
单元测试覆盖率 > 80%，核心业务逻辑 > 95%
# 默认模型
团队统一使用 deepseek-v3，复杂架构分析用 deepseek-v3.1莫潇羽@无忆研习社 有个小技巧：把常见的"踩坑点"也写进去，比如"本项目的 config.js 里 API_BASE_URL 不要直接用 localhost，要用 process.env 变量"。这样 AI 生成代码时会自动规避这些问题。
5.3 自定义斜杠命令
除了记忆文件，你还可以在 .codebuddy/commands/ 目录下创建自定义命令。每个命令是一个 Markdown 文件：
---
description: 自动提交代码并推送到远端
---
# 自动提交
1. 执行 `git add -A`
2. 根据变更内容自动生成符合规范的 commit message
3. 执行 `git commit -m "<生成的message>"`
4. 执行 `git push origin HEAD`保存为 .codebuddy/commands/auto-commit.md 之后，在对话里输入 /auto-commit，AI 就会按这个流程帮你执行。省去反复敲相同操作的麻烦。
六、Agents 子代理：给 AI 分配专属角色
随着任务越来越复杂，单一的对话模式已经不够用了。CodeBuddy Code 支持创建"子代理（Agents）"——把特定的角色、流程、工具组合封装成一个可复用的智能体。
6.1 创建一个 Agent
在交互模式下：
/agents选择"创建新 Agent"，输入描述，工具会自动生成一个 Agent 配置文件，放在 .codebuddy/agents/ 目录下。
一个典型的代码审查 Agent 配置文件大概长这样：
# .codebuddy/agents/code-reviewer.md
---
name: code-reviewer
description: 专注代码质量审查，检查安全漏洞、性能问题和最佳实践
model: deepseek-v3.1
tools:
- Read
- Grep
- Glob
---
# 代码审查专家
你是一名资深代码审查专家，负责对提交的代码变更进行系统性审查。
## 审查维度
1. 安全性：XSS、SQL 注入、敏感信息泄露等
2. 性能：N+1 查询、内存泄漏、不必要的重复计算
3. 可维护性：命名规范、函数复杂度、注释质量
4. 测试覆盖：关键路径是否有单测
## 输出格式
按优先级（P0/P1/P2）列出问题，每条问题给出：
- 问题描述
- 所在文件及行号
- 修改建议创建完之后，在对话里可以直接召唤这个 Agent：
请用 code-reviewer 审查一下我刚提交的这次 PR 变更AI 会自动找到并激活这个 Agent，按它定义的流程和工具执行审查。
Agents 和普通对话的区别：普通对话是通用的，Agents 是专业化的。把重复、高频、有固定流程的任务封装成 Agent，既能保证执行质量，也省去每次重新解释需求的成本。
还有一点值得提：Agents 的工具列表要谨慎配置。如果你的 Agent 只需要读取文件和执行搜索，就只给它 Read 和 Grep 权限，不要给 Bash 这样的宽泛权限。权限越精准，执行越可控，出问题的概率越低。这和最小权限原则在传统系统设计里的地位是一样的——安全永远比便利更重要。
七、为什么需要 Agent Skills？单靠提示词有什么问题
说完 CLI 和 Agents，到了这篇文章最核心的部分——Agent Skills（技能包）。
我自己也踩过这个坑：花了很多时间写了一个几百行的系统提示词，测试时 AI 表现挺好，但一旦进入真实的复杂业务流程，问题就冒出来了。解决了第一个问题，第二个问题又出现。把提示词改得更详细，它又开始忽略其他细节……
这不是偶发现象，背后有结构性原因：
第一，上下文越长，注意力越散。 大模型底层的 Transformer 注意力机制在长文本场景下会出现衰减，排在上下文中间的内容往往被忽略，这就是常说的"Lost in the Middle"问题。你写了 500 行提示词，AI 真正"认真读"的可能只有开头和结尾。
第二，提示词一旦复杂，步骤容易混乱。 一个大任务如果没有合理拆分，AI 执行时很容易把顺序搞错，或者漏掉某些步骤。就像你交代一个人同时做十件事，结果他做了六件忘了四件。
第三，工具定义占 Token，还容易被误调用。 如果你在系统提示词里堆了很多工具定义，AI 在判断用哪个工具时容易出错，而且这些定义本身就要消耗大量 Token。
Agent Skills 就是针对这三个问题设计的解决方案。不过在说它是什么之前，我想先多聊两句"为什么单靠堆提示词行不通"——这个问题比很多人想得要深。
提示词的本质困境是线性与并发之间的矛盾。我们写提示词，是在把复杂的、网状的业务逻辑，硬压成一段线性文本。文本里每一条规则都要跟其他规则争夺模型的注意力。规则越多，相互干扰越严重。你加了第 20 条规则去约束 AI 的输出格式，它可能就开始忘记第 5 条规则里你定义的数据结构。这不是模型"变傻了"，是注意力资源被稀释了。
做过 AI Agent 开发的人可能都有这个体验：某个提示词在简单场景下表现很好，一旦任务链条拉长、工具调用次数变多，结果就开始漂移。今天输出是 JSON，明天可能变成 Markdown；今天会主动问澄清性问题，明天可能就直接猜了。这种不稳定性，在生产环境里会让人非常头疼。
再加上一个现实问题：知识文档的体量往往超过上下文窗口的承载能力。一个企业的内部文档体系，技术规范、产品手册、财务制度、合规要求……加在一起轻松上百份文件、几十兆内容。不可能每次对话都把这些全塞进去，但如果不塞，AI 在生成内容时又缺少必要的背景知识，容易出错。
这就是为什么需要一套"按需、分级、可组合"的知识调度机制，而不是一个越写越长的大提示词。
7.1 Skills 不等于提示词，也不等于 MCP
这两个区别值得说清楚，我见过很多人把它们混淆。
Skills vs 提示词（Prompt）：提示词是线性文本，一次性全部载入上下文；Skills 是结构化的技能包，按需分级加载，用多少加载多少。提示词没有文件系统结构，Skills 有标准的目录规范和引用机制。
Skills vs MCP：MCP（模型上下文协议）解决的是"AI 如何连接外部工具和数据源"的问题，可以类比为"AI 时代的 USB-C 接口"——只要实现了 MCP 协议，各种外部服务都能接入。而 Skills 解决的是"AI 如何按标准流程执行复杂任务"的问题，更像是"菜谱"——告诉 AI 做这件事的完整步骤、注意事项、需要参考的资料。
一句话记忆：MCP 给 AI 装了"手"（能碰到外部世界），Skills 给 AI 装了"技能书"（知道怎么做某件事）。 两者配合使用才是完整的方案。
八、Skills 核心原理：三层渐进式加载机制
这是 Skills 设计里最精妙、也最关键的部分。
传统方式（比如直接把所有资料塞进提示词）的问题是：你有 50 个知识文档，每次对话都要把这 50 个文档全部加载进上下文，不管这次任务用不用得到。上下文窗口撑爆了，Token 成本也炸了。
Skills 的解法叫渐进式加载（Progressive Disclosure），按三个层级逐步展开：
L1 元数据层（始终加载）
↓ AI 判断当前任务匹配
L2 核心指令层（按需加载）
↓ 执行过程中需要额外资源
L3 资源文件层（深度按需）L1：元数据（永远只加载这一部分）
L1 只包含技能的名称和描述，大概几十到一百个 Token，每次对话都会载入。AI 用它来做"意图匹配"——判断当前任务跟这个 Skill 是否相关。
---
name: meeting-minutes
description: 会议纪要生成与文档同步助手。用于对会议内容进行智能提炼，生成标准格式的会议纪要，并可选同步到公司内网服务器。
---就这么几行，这是 L1 的全部内容。
L2：核心指令（匹配后才加载）
只有 AI 判断"当前任务跟这个 Skill 相关"之后，才会加载 SKILL.md 的正文部分，获取详细的执行指南。这部分通常在 5000 Token 以内。
L3：资源文件（执行时按需调用）
到了真正执行任务，需要调用知识库或者运行脚本时，才触发 L3 加载。比如会议里提到了"预算审批"，AI 才去加载财务手册；会议纪要需要上传服务器，才去执行上传脚本。
这个机制在实际工程中意味着什么？ 假设你的项目里有 30 个 Skills，每个 Skills 的 references 目录里平均有 500KB 的知识文档。传统做法把这些全塞进提示词，上下文直接爆炸。用 Skills 的渐进式加载，每次对话通常只激活 1-2 个 Skill，L3 资源也是按触发条件精准加载，实际消耗的 Token 可能只有传统方式的 5%-10%。
┌─────────────────────────────────────────────────────┐
│ 三层加载机制 Token 消耗对比 │
├────────────┬───────────┬────────────────────────────┤
│ 加载层级 │ Token 量 │ 触发条件 │
├────────────┼───────────┼────────────────────────────┤
│ L1 元数据 │ ~100 个 │ 始终加载 │
│ L2 核心指令│ <5000 个 │ AI 判断任务相关时 │
│ L3 资源文件│ 按需变化 │ 执行中需要特定资料/脚本时 │
└────────────┴───────────┴────────────────────────────┘九、Skills 文件结构与编写规范
知道了原理，下面说怎么写。
9.1 目录结构
一个标准的 Skill 目录长这样：
.codebuddy/skills/
└── meeting-minutes/ ← 技能包名称（英文）
├── SKILL.md ← 必须，核心说明文件
├── scripts/ ← 可选，可执行脚本
│ └── upload.py ← 上传脚本示例
├── references/ ← 可选，知识库文档
│ └── finance-manual.md
└── assets/ ← 可选，模板/静态资源
└── minutes-template.mdSKILL.md 是唯一必须的文件，其他三个目录按需创建。
9.2 SKILL.md 格式详解
SKILL.md 文件的开头必须有 YAML frontmatter（用两个 --- 包裹），这就是 L1 元数据：
---
name: meeting-minutes
description: 会议纪要生成与文档同步助手。用于对会议内容进行智能提炼，生成标准格式的会议纪要，并可选同步到公司内网。适用场景：技术周会、项目复盘、客户沟通会等。
---description 写得越清晰，AI 的意图匹配越准确。建议用一两句话描述"这个技能做什么事"以及"适用什么场景"。
frontmatter 后面就是 L2 的核心指令，格式自由，普通 Markdown 即可：
# 会议纪要助手
## 角色定位
你是一名专业的会议纪要整理专员，擅长从非结构化的会议对话中提炼关键信息。
## 总结规则
对会议内容按以下维度进行提炼，每个维度用 2-3 句话概括：
1. 参会人员：列出所有发言人
2. 议题清单：本次会议讨论了哪些主题
3. 决策事项：形成了哪些明确决定
4. 行动项：谁负责什么事情，截止时间是什么
> 当会议内容涉及预算、采购、资金成本等财务相关关键词时，
> 自动触发参考 references/finance-manual.md，并在纪要末尾
> 添加"财务提醒"章节。
## 上传规则
当用户提到"上传"、"同步"、"推送到服务器"时，
调用 scripts/upload.py 脚本，将纪要内容同步到公司内网。
## 输出格式示例
输入（会议对话片段）：
> 张三：用户模块已完成，今天提测。
> 李四：接口文档周五前给出来。
期望输出：会议纪要
=======
参会人员：张三、李四
议题：模块进展同步
决策：接口文档周五交付
行动项：李四 - 接口文档，deadline 周五
9.3 references 目录
references 里放的是知识库文档，纯文本格式最佳（Markdown、txt 均可）。写 SKILL.md 时用条件语句描述"什么时候读这个文档"，就能实现 L3 的精准触发。
比如 references/finance-manual.md 里放公司的财务报销制度，只有当会议内容提到财务相关词汇时，AI 才会去读取这份文件——而不是每次都把整份文件塞进上下文。
9.4 scripts 目录
scripts 里放的是可执行脚本，支持 Python、Bash 等。需要调用外部服务、上传文件、查询数据库时，就把对应逻辑写成脚本放这里，然后在 SKILL.md 里描述触发条件。
一个模拟上传的 Python 脚本大概长这样：
#!/usr/bin/env python3
# scripts/upload.py
import sys
import json
import time
import hashlib
def upload_minutes(content: str) -> dict:
"""将会议纪要上传到公司内网（示例，实际替换为真实 API）"""
# 数据校验
if not content or len(content) < 10:
raise ValueError("会议纪要内容不能为空")
# 生成文档 ID
doc_id = hashlib.md5(content.encode()).hexdigest()[:8].upper()
timestamp = int(time.time())
# TODO: 替换为实际的内网 API 调用
# response = requests.post("http://intranet.company.com/api/docs", ...)
# 模拟返回结果
return {
"status": "success",
"doc_id": f"MTG-{doc_id}",
"url": f"http://intranet.company.com/docs/MTG-{doc_id}",
"created_at": timestamp
}
if __name__ == "__main__":
content = sys.argv[1] if len(sys.argv) > 1 else ""
result = upload_minutes(content)
print(json.dumps(result, ensure_ascii=False, indent=2))
print(f"\n✅ 上传成功 | 文档 ID: {result['doc_id']}")
print(f" 访问地址: {result['url']}")十、从零实战：搭建企业级会议纪要 Skills
说了这么多理论，现在来走一遍完整的搭建流程。以"会议纪要自动生成与同步"为例，这个场景是我自己觉得最有代表性的——它同时涉及 L1/L2/L3 三层加载，还包含知识库引用和脚本调用两种机制。
10.1 第一步：建目录
在项目根目录下：
mkdir -p .codebuddy/skills/meeting-minutes/scripts
mkdir -p .codebuddy/skills/meeting-minutes/references10.2 第二步：写 SKILL.md
参考上面的格式规范，把 L1 元数据和 L2 核心指令写好。关键点：
- description 要精准，帮助 AI 做意图匹配
- 条件触发语句要明确（"当……时，参考……"）
- 提供清晰的输入输出示例
10.3 第三步：放知识库文档
把公司财务手册（或者任何相关的参考文档）放进 references/ 目录，命名有意义，在 SKILL.md 里精确引用：
> 当对话涉及以下关键词时触发本文档：预算、采购、报销、资金成本、审批
> 参考文件：references/finance-manual.md（公司财务手册 v2.3）10.4 第四步：写上传脚本
把上面示例的 upload.py 放到 scripts/ 目录下，实际使用时替换成真实的内网 API 地址。
10.5 第五步：测试三个场景
场景一：基础会议总结（只触发 L1+L2）
使用会议纪要助手总结以下内容：
张三：用户模块已完成，明天提测。
李四：接口文档我来写，周五前给。
王五：测试环境的问题找运维小陈。正常输出参会人员、议题、决策、行动项，不会触发财务手册。
场景二：涉及财务的会议（触发 L1+L2+L3知识库）
使用会议纪要助手总结以下内容：
张三：Q3 营销活动预算申请 8 万元以内。
李四：采购物料需要提前走审批流程。
王五：按公司财务规定来，没问题。这次 AI 会发现"预算""采购""审批"这些关键词，主动读取 references/finance-manual.md，在纪要末尾生成"财务提醒"章节，引用手册里对应条款。
场景三：纪要生成后同步服务器（触发 L1+L2+L3脚本）
使用会议纪要助手总结以下会议内容，完成后上传到公司服务器：
<会议内容同上>AI 识别到"上传"关键词，完成总结后自动调用 scripts/upload.py，返回文档 ID 和访问链接。
这三个场景，分别验证了 Skills 的三层加载机制——对于没用到的资源，一个字都不会加载到上下文里。
10.6 实战中的调试技巧
搭建 Skills 的过程不会一帆风顺，这里分享几个我自己踩坑后总结出来的调试方法。
技巧一：从 L1 开始验证。搭好目录和 SKILL.md 之后，先不用测试复杂场景，直接问 AI："你现在有哪些技能？"看它能不能正确识别出你的 Skill，以及描述对不对。如果这一步都不对，后续加载肯定也不对，先排查 SKILL.md 的 frontmatter 格式是否有误。
技巧二：用关键词显式触发。L2 和 L3 的加载依赖意图识别，初期测试时可以在提问里加上明确的关键词，比如"请使用 meeting-minutes 技能帮我……"，这样绕过意图判断，强制触发指定 Skill，更容易定位问题出在哪个层。
技巧三：观察 AI 是否读取了参考文档。L3 加载是否触发，可以从 AI 的回答里侧面判断——它在回答里有没有引用 references 里特定文档的内容？如果你的财务手册里写了"14个工作日走OA流程"，而 AI 的回答里提到了这个数字，说明 L3 触发成功了；如果没有，再检查 SKILL.md 里的触发条件描述是否足够精准。
技巧四：脚本先单独测试。scripts 里的脚本在被 AI 调用之前，先在命令行里手动执行一次，确认它能正常运行、输入输出格式正确。很多时候 AI 调脚本报错，根本原因是脚本本身有 bug，跟 AI 无关。
# 手动测试上传脚本
python3 .codebuddy/skills/meeting-minutes/scripts/upload.py "这里是会议纪要测试内容"技巧五：善用 /cost 命令追踪消耗。每次跑完一个 Skills 场景，用 /cost 看看这次对话的 Token 消耗，跟预期比对。如果消耗明显偏高，检查有没有不必要的 L3 触发，或者某个 references 文件太大需要精简。
十一、在不同工具中使用 Skills
Skills 最大的优势之一是跨平台可移植。你写好一个 Skill，可以在 CodeBuddy、Trae、Claude Code 等支持 Agent Skills 标准的工具里直接使用，效果基本一致。
11.1 在 CodeBuddy IDE 中使用
打开 CodeBuddy IDE 右上角的"设置"→"技能"，可以看到两个标签：用户技能（所有项目共用）和项目技能（仅当前项目）。
方法一：直接把技能目录放到 .codebuddy/skills/ 下，IDE 会自动扫描并加载。
方法二：点击"导入技能"，选择已有的技能包目录导入。
导入成功后，在对话框里直接描述需求，IDE 会自动匹配并激活对应的 Skill。也可以用 @技能名称 的方式显式召唤。
CodeBuddy 官方还提供了技能市场，里面有官方整理的常用技能，涵盖 AI 开发工具、效率提升、数据分析、内容创作等类别，可以直接下载安装：
在技能设置页面 → 浏览技能市场 → 点击"安装"
