定制工作流入门

一句话：把 Codely 从通用助手，变成懂你们流程和规范的专属搭档。

配置目录（Windows / macOS / Linux）

级别	路径
用户级（全局）	`~/.codely-cli/` → Windows: `%USERPROFILE%\.codely-cli\`
项目级	项目根目录下的 `.codely-cli/`

项目级覆盖用户级 settings 中的同名字段；Skill 同名时项目级优先；MCP 两级合并。

四种定制 + FAQ

类型	配置文件	适合做什么
Skills	`skills/<name>/SKILL.md`	教 Agent 多步骤流程、团队规范、领域知识
Subagents	`agents/<name>.toml`	限定工具集/模型，做审查、搜索、跑测试等子任务
MCP Servers	`settings.json` → `mcpServers`	接入数据库、内部 API、Unity Bridge 等外部工具
Settings	`settings.json`	切换模型、认证、IDE 模式、功能开关
FAQ	内置知识库	Agent 检测到已知问题时主动给解决方案

MCP 重要限制：Codely 仅支持 HTTP(S) MCP。不支持 Cursor 常见的 stdio / npx 本地进程型配置。

快速决策：我该用哪个？

你想做什么？
│
├─ 教 Agent 一个新流程/知识？     →  Skill
│   ├─ 简单（< 500 行）          →  只写 SKILL.md
│   ├─ 复杂                      →  SKILL.md + references/
│   └─ 需要确定性执行            →  SKILL.md + scripts/
│
├─ 定义受限工具的子代理？         →  Subagent（agents/*.toml）
│
├─ 让 Agent 调用外部服务？        →  MCP（settings.json，HTTP only）
│
├─ 切换模型/认证/功能开关？       →  Settings
│
└─ 遇到报错或踩坑？              →  FAQ（或直接描述问题，Agent 会查）

变更后如何生效

改了什么	怎么生效
Skill 内容或新安装 Skill	执行 `/skills reload`
Subagent（`agents/*.toml`）	重启 Codely CLI 或者新开Cowork会话
Settings / MCP / 模型	重启 Codely CLI 新开Cowork会话

验证 Skill：/skills list
验证 MCP：重启后让 Agent 尝试调用该 MCP 提供的工具

5 分钟上手

1. 体验定制系统（无需手动激活）

直接提问即可，Agent 会自动加载本 skill：

> Skill 和 Subagent 有什么区别？
> 怎么给项目接一个 MCP 服务器？

不需要输入「激活 xxx skill」——那是 Agent 内部行为。

2. 创建第一个 Skill（推荐）

在对话里描述需求：

> 帮我创建一个 skill：用户要求 review 代码时，
> 检查 TODO、console.log、硬编码密钥，并输出审查报告

Agent 会用内置 skill-creator 生成目录、编写 SKILL.md、打包并询问安装范围。
安装后执行 /skills reload，再用 /skills list 确认。

手动创建：见 Skills 完整文档。

3. 创建第一个 Subagent

创建 %USERPROFILE%\.codely-cli\agents\quick-review.toml（或 ~/.codely-cli/agents/）：

name = "quick-review"
description = "快速只读代码审查。检查 TODO、调试残留、明显安全问题。"
model = "codely-flash"
temperature = 0.1

[tools]
allowed = ["read_file", "search_file_content", "glob"]

重启 Codely CLI 后使用：

> 用 quick-review 扫描 src/ 有没有 TODO

详细字段说明：Subagents 完整文档。

4. 接入第一个 MCP Server

编辑 ~/.codely-cli/settings.json（Windows 用 %USERPROFILE%\.codely-cli\settings.json）：

{
  "mcpServers": {
    "my-service": {
      "httpUrl": "https://mcp.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

重启 Codely CLI，再验证 MCP 工具是否出现在对话中。

仅 HTTP(S) URL，不支持 stdio
不要把 token 提交到 Git；团队共享配置时用占位符，每人本地填真实值

详细说明：MCP 完整文档。

5. 项目级模型切换

在项目根创建 .codely-cli/settings.json：

{ "model": "codely-core" }

重启 Codely CLI。仅覆盖 model 字段，其余继承用户级配置。

详细说明：Settings 完整文档。

典型用户用例

下面是从真实场景提炼的用法。每条包含：你想达成什么 → 该用哪种定制 → 你可以怎么说。

用例 1：个人——提交前自动检查

项目	内容
场景	每次 commit 前都要跑 lint、单测，但 Agent 经常漏步骤
定制	Skill（用户级或项目级）
你可以说	`帮我创建一个 skill：用户说「准备提交」或「commit 前检查」时，依次跑 npm run lint、npm test，全过才允许提交`
生效	安装后 `/skills reload`；之后说 `准备提交` 即可触发

用例 2：团队——共享编码规范

项目	内容
场景	团队有统一的命名、目录、PR 规范，希望每个成员 Agent 都遵守
定制	项目级 Skill（提交到 Git）
目录	`my-project/.codely-cli/skills/team-conventions/SKILL.md`
你可以说	`根据我们的 CONTRIBUTING.md 写一个 team-conventions skill，安装到项目级`
团队用法	同事 clone 后执行 `/skills reload`，无需每人单独配置

用例 3：全栈——让 Agent 查数据库

项目	内容
场景	开发时需要查 staging 数据库里的用户订单，不想手动开客户端
定制	MCP Server（HTTP）
配置	在 `settings.json` 的 `mcpServers` 里加数据库 MCP 的 `httpUrl`
你可以说	`查一下 staging 里 user_id=123 的最近 5 条订单`
注意	MCP 服务必须是 HTTP 端点；token 放用户级 settings，不要提交 Git

用例 4：Unity——编辑器内操作 + 项目分析

项目	内容
场景	在 Unity 项目里改场景、查 Prefab、分析脚本引用
定制	MCP（Unity Bridge）+ Settings（`unityInsight`）
配置示例	`settings.json` 中 `"unityInsight": { "enabled": true }`，并配置 Bridge MCP
你可以说	`检查 Player.prefab 上有没有 Missing Script` / `分析哪些脚本引用了 InventoryManager`
踩坑	Bridge 断连、Play Mode 限制等见 FAQ

用例 5：并行——后台跑测试，前台继续改代码

项目	内容
场景	完整测试要跑 10 分钟，不想干等
定制	Subagent（如 `test-runner`，允许 `run_shell_command`）
你可以说	`后台跑完整测试套件，同时帮我把 auth 模块的重构做完`
原理	Agent 用 `task` 工具后台启动 test-runner，前台继续其他工作；完成后收到通知

用例 6：多项目——大项目用强模型，小工具用快模型

项目	内容
场景	主仓库代码量大用 `codely-core`，脚本/文档仓库用 `codely-flash` 省钱提速
定制	项目级 Settings
配置	在各项目根 `.codely-cli/settings.json` 写 `{ "model": "codely-core" }` 或 `"codely-flash"`
生效	重启 Codely CLI；打开不同项目时自动用对应模型

用例 7：定时——工作日早上自动跑构建检查

项目	内容
场景	每个工作日上午 9 点自动检查 main 分支能否构建
定制	项目级 `scheduled_tasks.json`（或通过 `cron_create` 工具，`durable: true`）
配置示例	`.codely-cli/scheduled_tasks.json` 中 `"cron": "0 9 * * 1-5"`
你可以说	`创建一个 durable 定时任务：工作日 9 点检查 main 能否 npm run build`
注意	`durable: true` 才会写入文件，重启后仍有效

用例 8：安全审查——只读子代理 + 审查流程 Skill

项目	内容
场景	合并 PR 前做安全审查，不希望 Agent 顺手改代码
定制	Skill（审查清单）+ Subagent（只读工具）
Skill 说	检查 SQL 注入、XSS、硬编码密钥、权限校验缺失
Subagent 配	`tools.allowed = ["read_file", "search_file_content", "glob"]`
你可以说	`用 code-reviewer 按安全清单审查 src/api/ 目录`

用例 9：从同事/社区安装现成 Skill

项目	内容
场景	同事打包了一个 `deploy.skill`，你想直接用
定制	`codely skills install`
命令	`codely skills install ./deploy.skill --scope workspace`
你可以说	`帮我把 deploy.skill 安装到当前项目并 reload`
团队	`--scope workspace` 装到项目级，可随 Git 共享；`--scope user` 仅本机所有项目可用

用例 10：临时关掉某个 MCP，避免干扰

项目	内容
场景	某个 MCP 服务维护中，暂时不想让 Agent 调用它的工具
定制	Settings 里设 `"enabled": false`
配置示例	`"legacy-db": { "httpUrl": "...", "enabled": false }`
生效	重启 Codely CLI；无需删配置，维护完改回 `true` 即可

用例 11：Windows 开发——避免 PowerShell 编码坑

项目	内容
场景	让 Agent 写含 `{}` 的 Python/JSON 脚本，PowerShell 报错
定制	无需额外配置；Agent 应查 FAQ 并建议替代方案
你可以说	`用 write_file 写入这个 JSON，不要用 PowerShell 内联脚本`
参考	FAQ

用例 12：长任务——拆 Job 防止 Agent 忘上下文

项目	内容
场景	大规模重构，Agent 做到一半开始重复或丢上下文
定制	内置 `job_create` 工具 + 可选 Skill 定义拆分规则
你可以说	`把这个重构拆成 5 个 job，每步完成后验证再进入下一步`
配合	重要决策写入项目文档；复杂流程可写进 Skill 的 `references/`

组合速查

你的目标	推荐组合
统一团队规范	项目级 Skill
接外部系统	MCP + Settings
限制 Agent 权限	Subagent（`tools.allowed`）
复杂流程可重复	Skill + `scripts/`
审查不改代码	Subagent（只读）+ Skill（清单）
长任务不丢进度	Skill（步骤）+ `job_create`
不同项目不同能力	项目级 Settings（model / MCP）

安全与团队协作

settings.json 中的 API Key / Token 不要提交到 Git
适合提交到 Git 的：项目级 Skill、不含密钥的 MCP URL 模板、模型选择
项目级 Skill 放入 .codely-cli/skills/，团队成员 clone 后执行 /skills reload

新手常见问题

现象	先检查
Skill 安装了但列表里没有	是否执行了 `/skills reload`；路径是否为 `skills/<name>/SKILL.md`
Subagent 调不到	是否重启 CLI；`name` 是否与 `task` 的 `subagent_name` 一致
MCP 工具不出现	是否重启 CLI；`httpUrl` 是否可访问；是否误用了 stdio 配置
改了 settings 没生效	项目级路径是否为 `<项目根>/.codely-cli/settings.json`；是否重启
Windows 命令/编码报错	见 FAQ

更多问题（含 Unity 专项）：FAQ 完整文档

详细文档索引

文档	内容
Skills	Skill 结构、frontmatter、安装、最佳实践
Subagents	TOML 字段、内置子代理、`task` 参数
MCP Guide	MCP 配置 schema、HTTP 限制、示例
Settings	全局/项目 settings、模型、定时任务
FAQ	已知问题与解决方案（含通用配置问题）

文件结构一览

~/.codely-cli/                    # 用户级（Windows: %USERPROFILE%\.codely-cli\）
├── settings.json
├── model-config.json
├── agents/*.toml
└── skills/
    └── codely-customizations/
        ├── SKILL.md
        └── references/           # 本目录

<project>/.codely-cli/            # 项目级
├── settings.json
├── scheduled_tasks.json
└── skills/<name>/SKILL.md

配置目录（Windows / macOS / Linux）​

四种定制 + FAQ​

快速决策：我该用哪个？​

变更后如何生效​

5 分钟上手​

1. 体验定制系统（无需手动激活）​

2. 创建第一个 Skill（推荐）​

3. 创建第一个 Subagent​

4. 接入第一个 MCP Server​

5. 项目级模型切换​

典型用户用例​

用例 1：个人——提交前自动检查​

用例 2：团队——共享编码规范​

用例 3：全栈——让 Agent 查数据库​

用例 4：Unity——编辑器内操作 + 项目分析​

用例 5：并行——后台跑测试，前台继续改代码​

用例 6：多项目——大项目用强模型，小工具用快模型​

用例 7：定时——工作日早上自动跑构建检查​

用例 8：安全审查——只读子代理 + 审查流程 Skill​

用例 9：从同事/社区安装现成 Skill​

用例 10：临时关掉某个 MCP，避免干扰​

用例 11：Windows 开发——避免 PowerShell 编码坑​

用例 12：长任务——拆 Job 防止 Agent 忘上下文​

组合速查​

安全与团队协作​

新手常见问题​

详细文档索引​

文件结构一览​