跳到主要内容

定制工作流入门

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

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

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

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

四种定制 + FAQ​

类型配置文件适合做什么
Skillsskills/<name>/SKILL.md教 Agent 多步骤流程、团队规范、领域知识
Subagentsagents/<name>.toml限定工具集/模型，做审查、搜索、跑测试等子任务
MCP Serverssettings.json → mcpServers接入数据库、内部 API、Unity Bridge 等外部工具
Settingssettings.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 完整文档

详细文档索引​

文档内容
SkillsSkill 结构、frontmatter、安装、最佳实践
SubagentsTOML 字段、内置子代理、task 参数
MCP GuideMCP 配置 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