扩展 CSC
了解何时使用 AGENTS.md、Skills、Subagents、Hooks、MCP 和Plugins。
CSC 将一个能推理代码的模型与用于文件操作、搜索、执行和网络访问的内置工具结合在一起。内置工具覆盖了大多数编码任务。本指南介绍扩展层：你添加的功能，用于自定义 CSC 的知识、连接外部服务以及自动化工作流。
注意： 关于核心代理循环的工作原理，请参阅 CSC 的工作原理。
CSC 新手？ 从 AGENTS.md 开始了解项目约定，然后在出现特定触发条件时逐步添加其他扩展。
概览
扩展插入代理循环的不同部分：
- AGENTS.md 添加 CSC 每次会话都能看到的持久上下文
- Skills 添加可复用的知识和可调用的工作流
- MCP 将 CSC 连接到外部服务和工具
- Subagents 在隔离上下文中运行自己的循环，返回摘要
- Agent teams 协调多个具有共享任务和点对点消息传递的独立会话
- Hooks 作为确定性脚本完全在循环之外运行
- Plugins 和 市场 打包和分发这些功能
Skills是最灵活的扩展。Skills是一个包含知识、工作流或指令的 Markdown 文件。你可以使用 /deploy 这样的命令调用Skills，或者 CSC 可以在相关时自动加载它们。Skills可以在你当前的对话中运行，也可以通过Subagents在隔离上下文中运行。
根据目标匹配功能
功能范围从 CSC 每次会话都能看到的始终在线上下文，到你或 CSC 可以按需调用的能力，再到在特定事件上运行的背景自动化。下表展示了可用的功能以及何时使用它们。
| 功能 | 作用 | 何时使用 | 示例 |
|---|---|---|---|
| AGENTS.md | 每次对话加载的持久上下文 | 项目约定、"始终执行 X" 规则 | "使用 pnpm，不要用 npm。提交前运行测试。" |
| Skills | CSC 可以使用的指令、知识和工作流 | 可复用内容、参考文档、可重复任务 | /deploy 运行你的部署清单；包含端点模式的 API 文档Skills |
| Subagents | 返回摘要结果的隔离执行上下文 | 上下文隔离、并行任务、专业工作者 | 读取大量文件但仅返回关键发现的研究任务 |
| Agent teams | 协调多个独立的 CSC 会话 | 并行研究、新功能开发、用竞争假设调试 | 启动审查者同时检查安全性、性能和测试 |
| MCP | 连接到外部服务 | 外部数据或操作 | 查询数据库、发送 Slack 消息、控制浏览器 |
| Hooks | 在事件上运行的确定性脚本 | 可预测的自动化，不涉及 LLM | 每次文件编辑后运行 ESLint |
Plugins是打包层。Plugins将Skills、Hooks、Subagents和 MCP 服务器捆绑到一个可安装的单元中。PluginsSkills有命名空间（如 /my-plugin:review），因此多个Plugins可以共存。当你想在多个仓库中复用相同的设置或通过市场分发给他人时，请使用Plugins。
逐步构建你的设置
你不需要一开始就配置所有内容。每个功能都有一个可识别的触发条件，大多数团队大致按以下顺序添加它们：
| 触发条件 | 添加 |
|---|---|
| CSC 两次弄错某个约定或命令 | 将其添加到 AGENTS.md |
| 你一直输入相同的提示来启动任务 | 将其保存为用户可调用的Skills |
| 你第三次将相同的操作手册或多步骤流程粘贴到聊天中 | 将其捕获为Skills |
| 你一直从 CSC 看不到的浏览器标签页复制数据 | 将该系统连接为 MCP 服务器 |
| 一个辅助任务用你不再引用的输出淹没了你的对话 | 通过Subagents路由它 |
| 你希望某件事每次无需询问就自动发生 | 编写一个Hooks |
| 第二个仓库需要相同的设置 | 将其打包为Plugins |
相同的触发条件也告诉你何时更新已有的内容。反复出现的错误或反复出现的审查意见是 AGENTS.md 的编辑，而不是聊天中的一次性纠正。你一直手动调整的工作流是需要再次修订的Skills。
比较相似功能
有些功能看起来可能相似。以下是如何区分它们。
Skills vs Subagents
Skills和Subagents解决不同的问题：
- Skills是可以加载到任何上下文中的可复用内容
- Subagents是与主对话分开运行的隔离工作者
| 方面 | Skills | Subagents |
|---|---|---|
| 是什么 | 可复用的指令、知识或工作流 | 拥有自己上下文的隔离工作者 |
| 核心优势 | 跨上下文共享内容 | 上下文隔离。工作分开进行，仅返回摘要 |
| 最适合 | 参考材料、可调用的工作流 | 读取大量文件的任务、并行工作、专业工作者 |
Skills可以是参考型或操作型。 参考型Skills提供 CSC 在整个会话中使用的知识（如你的 API 风格指南）。操作型Skills告诉 CSC 执行特定操作（如运行部署工作流的 /deploy）。
使用Subagents当你需要上下文隔离或上下文窗口即将满时。Subagents可能读取数十个文件或运行大量搜索，但你的主对话只接收摘要。由于Subagents的工作不消耗你的主上下文，当你不需要中间工作保持可见时，这也很有用。自定义Subagents可以有自己的指令，并且可以预加载Skills。
它们可以组合使用。 Subagents可以预加载特定Skills（skills: 字段）。Skills可以使用 context: fork 在隔离上下文中运行。详情请参阅Skills。
AGENTS.md vs Skills
两者都存储指令，但它们的加载方式不同，用途也不同。
| 方面 | AGENTS.md | Skills |
|---|---|---|
| 加载方式 | 每次会话自动加载 | 按需加载 |
| 可以包含文件 | 可以，使用 @path 导入 | 可以，使用 @path 导入 |
| 可以触发工作流 | 不可以 | 可以，使用 /<name> |
| 最适合 | "始终执行 X" 规则 | 参考材料、可调用的工作流 |
放入 AGENTS.md如果 CSC 应该始终知道它：编码约定、构建命令、项目结构、"永远不要做 X" 规则。
放入Skills如果它是 CSC 有时需要的参考材料（API 文档、风格指南）或你用 /<name> 触发的工作流（部署、审查、发布）。
经验法则： 保持 AGENTS.md 在 200 行以内。如果它在增长，将参考内容移到Skills或拆分为 .costrict/rules/ 文件。
AGENTS.md vs 规则 vs Skills
三者都存储指令，但它们的加载方式不同：
| 方面 | AGENTS.md | .costrict/rules/ | Skills |
|---|---|---|---|
| 加载方式 | 每次会话 | 每次会话，或在打开匹配文件时 | 按需，在调用或相关时 |
| 范围 | 整个项目 | 可以限定到文件路径 | 特定任务 |
| 最适合 | 核心约定和构建命令 | 特定语言或特定目录的指南 | 参考材料、可重复的工作流 |
使用 AGENTS.md用于每次会话都需要的指令：构建命令、测试约定、项目架构。
使用规则保持 AGENTS.md 的专注。带有 paths frontmatter 的规则仅在 CSC 处理匹配文件时加载，节省上下文。
使用Skills用于 CSC 仅偶尔需要的内容，如 API 文档或你用 /<name> 触发的部署清单。
Subagents vs Agent teams
两者都并行化工作，但架构不同：
- Subagents在你的会话内运行，并将结果报告回主上下文
- Agent teams是相互通信的独立 CSC 会话
| 方面 | Subagents | Agent teams |
|---|---|---|
| 上下文 | 拥有上下文窗口；结果返回给调用者 | 拥有上下文窗口；完全独立 |
| 通信 | 仅将结果报告回主代理 | 团队成员之间直接消息传递 |
| 协调 | 主代理管理所有工作 | 共享任务列表与自我协调 |
| 最适合 | 只关心结果的聚焦任务 | 需要讨论和协作的复杂工作 |
| Token 成本 | 较低：结果摘要返回主上下文 | 较高：每个团队成员是独立的 CSC 实例 |
使用Subagents当你需要快速、聚焦的工作者时：研究问题、验证声明、审查文件。Subagents完成工作并返回摘要。你的主对话保持整洁。
使用Agent teams当团队成员需要共享发现、相互质疑并独立协调时。Agent teams最适合具有竞争假设的研究、并行代码审查以及每个团队成员负责独立部分的新功能开发。
过渡点： 如果你正在运行并行Subagents但达到了上下文限制，或者你的Subagents需要相互通信，Agent teams是自然的下一步。
注意： Agent teams是实验性功能，默认禁用。请参阅Agent teams了解设置和当前限制。
MCP vs Skills
MCP 将 CSC 连接到外部服务。Skills扩展 CSC 的知识，包括如何有效地使用这些服务。
| 方面 | MCP | Skills |
|---|---|---|
| 是什么 | 连接外部服务的协议 | 知识、工作流和参考材料 |
| 提供 | 工具和数据访问 | 知识、工作流、参考材料 |
| 示例 | Slack 集成、数据库查询、浏览器控制 | 代码审查清单、部署工作流、API 风格指南 |
它们解决不同的问题，并且可以很好地配合使用：
MCP 赋予 CSC 与外部系统交互的能力。没有 MCP，CSC 无法查询你的数据库或发送 Slack 消息。
Skills 赋予 CSC 如何有效使用这些工具的知识，以及你可以用 /<name> 触发的工作流。Skills可能包括你团队的数据库架构和查询模式，或带有团队消息格式规则的 /post-to-slack 工作流。
示例：MCP 服务器将 CSC 连接到你的数据库。Skills教会 CSC 你的数据模型、常见查询模式以及不同任务使用哪些表。
了解功能如何分层
功能可以在多个层级定义：用户级、项目级、通过Plugins或通过托管策略。你还可以在子目录中嵌套 AGENTS.md 文件，或将Skills放在 monorepo 的特定包中。当同一功能存在于多个层级时，它们的分层方式如下：
- AGENTS.md 文件是累加的：所有层级同时向 CSC 的上下文贡献内容。来自工作目录及上级目录的文件在启动时加载；子目录在你处理它们时加载。当指令冲突时，CSC 使用判断来协调它们，更具体的指令通常优先。请参阅 AGENTS.md 文件如何加载。
- Skills和Subagents按名称覆盖：当同一名称存在于多个层级时，一个定义根据优先级胜出（Skills：托管 > 用户 > 项目；Subagents：托管 > CLI 标志 > 项目 > 用户 > Plugins）。PluginsSkills有命名空间以避免冲突。请参阅Skills发现和Subagents范围。
- MCP 服务器按名称覆盖：本地 > 项目 > 用户。请参阅 MCP 范围。
- Hooks合并：所有注册的Hooks无论来源都会在匹配事件时触发。请参阅Hooks。
组合功能
每个扩展解决不同的问题：AGENTS.md 处理始终在线的上下文，Skills处理按需知识和工作流，MCP 处理外部连接，Subagents处理隔离，Hooks处理自动化。实际的设置根据你的工作流组合它们。
例如，你可能使用 AGENTS.md 来管理项目约定，使用Skills来管理部署工作流，使用 MCP 连接数据库，使用Hooks在每次编辑后运行 lint。每个功能处理它最擅长的事情。
| 模式 | 工作方式 | 示例 |
|---|---|---|
| Skills + MCP | MCP 提供连接；Skills教会 CSC 如何有效使用它 | MCP 连接数据库，Skills记录架构和查询模式 |
| Skills + Subagents | Skills生成Subagents进行并行工作 | /audit Skills启动在隔离上下文中工作的安全、性能和样式Subagents |
| AGENTS.md + Skills | AGENTS.md 保持始终在线的规则；Skills保持按需加载的参考材料 | AGENTS.md 说"遵循我们的 API 约定"，Skills包含完整的 API 风格指南 |
| Hooks + MCP | Hooks通过 MCP 触发外部操作 | 编辑后Hooks在 CSC 修改关键文件时发送 Slack 通知 |
了解上下文成本
你添加的每个功能都会消耗 CSC 的一些上下文。太多可能会填满你的上下文窗口，但也可能增加噪音使 CSC 效率降低；Skills可能无法正确触发，或者 CSC 可能忘记你的约定。了解这些权衡有助于你构建有效的设置。有关这些功能在运行会话中如何组合的交互视图，请参阅探索上下文窗口。
按功能的上下文成本
每个功能有不同的加载策略和上下文成本：
| 功能 | 加载时机 | 加载内容 | 上下文成本 |
|---|---|---|---|
| AGENTS.md | 会话启动 | 完整内容 | 每次请求 |
| Skills | 会话启动 + 使用时 | 启动时描述，使用时完整内容 | 低（每次请求仅描述）* |
| MCP 服务器 | 会话启动 | 工具名称；完整 schema 按需加载 | 低，直到使用工具 |
| Subagents | 生成时 | 带有指定Skills的新鲜上下文 | 与主会话隔离 |
| Hooks | 触发时 | 无（外部运行） | 零，除非Hooks返回额外上下文 |
*默认情况下，Skills描述在会话启动时加载，以便 CSC 可以决定何时使用它们。在Skills的 frontmatter 中设置 disable-model-invocation: true 可以在你手动调用之前将其对 CSC 完全隐藏。这将你仅自行触发的Skills的上下文成本降低为零。
了解功能如何加载
每个功能在会话的不同时间点加载。以下解释了每个功能的加载时间和进入上下文的内容。
AGENTS.md
何时： 会话启动
加载内容： 所有 AGENTS.md 文件（托管、用户和项目级别）的完整内容。
继承： CSC 从你的工作目录向上读取到根目录的 AGENTS.md 文件，并在访问子目录时发现嵌套的文件。详情请参阅 AGENTS.md 文件如何加载。
💡 提示： 保持 AGENTS.md 在 200 行以内。将参考材料移到按需加载的Skills中。
Skills
Skills是 CSC 工具包中的额外能力。它们可以是参考材料（如 API 风格指南）或你用 /<name> 触发的可调用工作流（如 /deploy）。CSC 包含开箱即用的捆绑Skills，如 /simplify、/batch 和 /debug。你也可以创建自己的Skills。CSC 在适当时使用Skills，或者你可以直接调用一个Skills。
何时： 取决于Skills的配置。默认情况下，描述在会话启动时加载，完整内容在使用时加载。对于仅用户Skills（disable-model-invocation: true），在你调用之前不会加载任何内容。
加载内容： 对于模型可调用的Skills，CSC 在每次请求中看到名称和描述。当你用 /<name> 调用Skills或 CSC 自动加载它时，完整内容加载到你的对话中。
CSC 如何选择Skills： CSC 将你的任务与Skills描述匹配，以决定哪些是相关的。如果描述模糊或重叠，CSC 可能加载错误的Skills或遗漏有帮助的Skills。要告诉 CSC 使用特定Skills，用 /<name> 调用它。设置了 disable-model-invocation: true 的Skills在你调用之前对 CSC 是不可见的。
上下文成本： 低，直到使用。仅用户Skills在调用前成本为零。
在Subagents中： Skills在Subagents中的工作方式不同。不是按需加载，传递给Subagents的Skills在启动时完全预加载到其上下文中。Subagents不从主会话继承Skills；你必须显式指定它们。
💡 提示： 对有副作用的Skills使用
disable-model-invocation: true。这节省上下文并确保只有你触发它们。
MCP 服务器
何时： 会话启动。
加载内容： 已连接服务器的工具名称。完整的 JSON schema 保持延迟，直到 CSC 需要特定工具。
上下文成本： 工具搜索默认开启，因此空闲的 MCP 工具消耗最少的上下文。
可靠性说明： MCP 连接可能会在会话中静默失败。如果服务器断开连接，其工具会在没有警告的情况下消失。CSC 可能尝试使用不再存在的工具。如果你注意到 CSC 无法使用之前可以访问的 MCP 工具，请用 /mcp 检查连接。
💡 提示： 运行
/mcp查看每个服务器的 token 成本。断开你未积极使用的服务器。
Subagents
何时： 按需，当你或 CSC 为任务生成一个Subagents时。
加载内容： 新鲜的隔离上下文，包含：
- 系统提示（与父级共享以实现缓存效率）
- 代理
skills:字段中列出的Skills的完整内容 - AGENTS.md 和 git 状态（从父级继承）
- 主代理在提示中传递的任何上下文
上下文成本： 与主会话隔离。Subagents不继承你的对话历史或已调用的Skills。
💡 提示： 使用Subagents处理不需要完整对话上下文的工作。它们的隔离可以防止主会话膨胀。
Hooks
何时： 触发时。Hooks在特定的生命周期事件上触发，如工具执行、会话边界、提示提交、权限请求和压缩。完整列表请参阅Hooks。
加载内容： 默认不加载任何内容。Hooks作为外部脚本运行。
上下文成本： 零，除非Hooks返回的输出作为消息添加到你的对话中。
💡 提示： Hooks非常适合不需要影响 CSC 上下文的副作用（lint、日志记录）。