Agent 与 Skill 的使用边界

Agent 与 Skill 的使用边界及 DP 项目 `.claude/` 治理建议

1. 核心结论

Agent 和 Skill 不是简单的"复杂任务"和"简单任务"的区别。更准确的边界是：

Skill 是可复用能力包、流程手册、规则集合和工具封装。
Agent 是具备独立上下文、独立职责、可被委派执行任务的专家工作单元。

一句话概括：

Skill 负责"怎么做"，Agent 负责"谁去独立做"。Skill 可以编排 Agent，Agent 也可以按 Skill 的规范执行。

如果一项能力主要是在沉淀团队 SOP、触发条件、命令规范、检查清单、输出格式、脚本和模板，优先设计成 Skill。如果一项能力需要独立上下文、大范围搜索、并行探索、专家判断、只读深度诊断或上下文隔离，优先设计成 Agent。

2. 什么时候应该使用 Skill

2.1 稳定、可复用、可文档化的流程

当任务具有稳定流程、明确触发条件、固定输出格式，并且可以沉淀为项目经验时，应该优先使用 Skill。

典型例子包括：

每日代码审查；
更新中心导入失败诊断；
环境健康检查；
报表性能测试；
元数据获取；
分支差异分析；
TAPD 评论同步；
数据库连接获取；
前端问题诊断入口；
线上问题排查前切换环境分支。

这些任务可以很复杂，但复杂并不意味着一定要做成 Agent。只要它们本质上是"用户可复用的标准入口和操作手册"，Skill 就是合理形态。

2.2 需要封装项目约定和安全边界

Skill 非常适合沉淀项目内的硬性规范。例如 DP 项目中已有许多规则：

线上问题排查前必须先使用 common-switch-env-branch 切到环境对应分支；
临时文件必须写入 DP 主项目 .claude/tmp/；
数据库表结构优先从 dp-sql-upgrade 查；
前端问题优先收集 console、network、DOM、截图和组件元数据；
dp CLI 命令格式必须固定，避免臆造命令；
代码实施后如何同步 TAPD 评论；
每日代码审查报告写入哪个目录；
企业微信群 webhook 从环境变量或本地配置读取，不写入可跟踪文件。

这些都属于 Skill 的典型职责：把团队经验固化为流程和约束。

2.3 需要携带脚本、模板、参考文档

Skill 可以包含：

SKILL.md：入口说明和执行流程；
scripts/：确定性脚本；
references/：参考资料；
templates/：输出模板；
evals/：评测用例；
tests/：技能测试。

这类结构特别适合"脚本做确定性收集，AI 做语义判断"的工作流。例如每日代码审查可以先用脚本收集最近提交，再由 AI 或子 Agent 对 diff 做风险审查，最后由 Skill 汇总报告和发送通知。

2.4 用户直接触发的命令入口

如果用户习惯通过 /xxx 调用某项能力，通常应将它设计为 Skill。例如：

/unified-entry
/env-check
/daily-code-review
/diagnose-bi-frontend
/update-package-diagnose
/scheme-design
/test-pilot

这些入口承担用户意图识别、参数解释、流程启动、结果汇总的职责，适合由 Skill 承载。

3. 什么时候应该使用 Agent

3.1 需要独立上下文

Agent 的最大价值之一是上下文隔离。如果一项任务会读取大量日志、源码、SQL、diff 或历史会话，直接在主会话里做会污染上下文，影响后续对话。此时应该派 Agent 去完成。

典型场景包括：

分析复杂报表性能问题；
排查实时采集链路；
追踪多个服务之间的数据流；
审查大规模 diff；
扫描一个 submodule 的 API 知识；
对错误栈做跨仓库定位；
对多个模块分别做并行调查。

3.2 需要并行探索

如果有多个互不依赖的问题域，应该使用多个 Agent 并行处理，而不是主会话串行调查。

例如：

前端、后端、数据库、环境四条线并行排查；
15 个仓库的每日提交分别审查；
多个失败测试文件分别定位；
多个服务日志分别分析；
多个候选根因分别验证。

Agent 的并行能力可以节省时间，也能让每个 Agent 保持窄上下文和清晰目标。

3.3 需要专家角色和独立判断

Agent 适合有明确专业边界的任务，例如：

diagnose-stream-monitor-agent：实时监听/实时清洗诊断；
diagnose-stream-datain-agent：CDC 实时采集诊断；
diagnose-package-import-export-agent：更新中心/数据包导入导出深度诊断；
diagnose-model-wide-table-agent：宽表模型端到端诊断；
git-investigation-agent：Git 变更追溯；
knowledge-indexing-agent：知识库构建和维护。

这些任务具有专业、复杂、独立、可委派的特征，适合设计为 Agent。

3.4 需要控制工具权限、模型或执行边界

Agent 可以被配置为只读、禁止编辑、专门查代码、专门查 Git、专门查环境、专门做 review。这比在 Skill 文档里写大量"不要做什么"更有隔离感。

尤其在安全敏感场景中，推荐将 Agent 作为"只读调查者"，Skill 作为"流程入口和安全门禁"。

4. 推荐组合模式

DP 项目中最推荐的模式是：

text 复制代码

用户请求
  ↓
Skill 作为入口：识别意图、收集参数、检查前置条件、声明安全边界
  ↓
Skill 先用确定性工具 / 脚本 / CLI 收集事实
  ↓
如果简单问题可以闭环，Skill 直接输出
  ↓
如果问题复杂、上下文大、需要并行或专家判断
  ↓
Skill 调用对应 Agent 深度分析
  ↓
Agent 返回 evidence / root cause / recommendation
  ↓
Skill 统一生成最终报告、评论或后续动作建议

这个模式的优势是：

用户只需要记住 Skill 入口；
Skill 负责统一体验和输出格式；
Agent 负责复杂分析和上下文隔离；
可复用脚本留在 Skill；
深度判断留给 Agent；
安全边界更容易治理。

update-package-diagnose 是比较理想的例子：它作为更新中心和数据包导入导出的 L1 统一诊断入口，先使用 dp CLI 和知识库进行快速定位；当 CLI 工具不足以定位根因时，再升级到深度分析 Agent。

5. 当前 `.claude/` 目录现状

当前 DP 项目 .claude/ 下主要包含：

text 复制代码

.claude/
├── CLAUDE.md
├── agents/
├── skills/
├── eval-kernel/
├── knowledge/
├── templates/
├── tmp/
└── worktrees/

其中：

.claude/agents/ 下有效 AGENT.md 有 8 个；
.claude/skills/ 下有效 SKILL.md 有 45 个；
.claude/worktrees/ 中存在嵌套 worktree 副本，不应纳入主统计口径，否则会重复统计。

当前有效 Agent 包括：

env-check-agent
diagnose-active-report-agent
diagnose-model-wide-table-agent
diagnose-package-import-export-agent
diagnose-stream-datain-agent
diagnose-stream-monitor-agent
git-investigation-agent
knowledge-indexing-agent

整体看，这些 Agent 多数符合预期：它们主要承担专业诊断、深度分析、跨链路排查、Git 追溯和知识库构建等任务。

当前 Skill 覆盖范围很广，包括：

分支对比、分支合并、容器云分支创建；
TAPD 需求设计、实现、评论同步、缺陷创建；
数据库连接、SQL schema 还原、MySQL 查询；
前端诊断、报表性能诊断、复杂报表诊断；
元数据获取与 review；
每日代码审查；
环境健康检查；
更新中心/数据包导入导出诊断；
测试用例生成与执行；
知识沉淀；
unified-entry 路由入口。

这说明当前项目已经形成了较完整的 Skill 生态。

6. 当前设计中做得较好的地方

6.1 `unified-entry` 明确了 Skill 和 Agent 的优先级

unified-entry 中已有非常关键的本地约定：

text 复制代码

1. Skill：需要与用户交互、登录、复现、浏览器操作、诊断流程编排。
2. Agent：独立、只读、可并行、局部分析任务，如 git 排查、API 归属识别、代码搜索。
3. internal：简单静态判断或继续主会话分析。

这说明当前项目并不是简单按"复杂度"划分 Agent/Skill，而是按"交互式入口 vs 独立只读子任务"划分。这一约定是合理的，建议提升为项目级规范。

6.2 多数 Agent 的定位是深度诊断

diagnose-package-import-export-agent、diagnose-model-wide-table-agent、diagnose-stream-monitor-agent 等都是典型复杂链路诊断者，需要自主分析多服务、多表、多日志、多配置，适合以 Agent 形式存在。

6.3 `common-*` 类 Skill 是标准工具流程

common-db-connection、common-dp-login、common-query-mysql-db、common-switch-env-branch、common-metadata-fetcher 等都符合 Skill 预期：它们是稳定、可复用、可组合的能力单元。

6.4 部分复杂 Skill 作为 SOP 入口也合理

例如 daily-code-review 虽然复杂，但它是明确的用户入口和团队 SOP，因此作为 Skill 可以成立。更好的做法是让 Skill 负责收集、分发、汇总和报告，让子 Agent 负责每个 commit 的深度 review。

7. 当前存在的问题

7.1 `agents/README.md` 与实际目录存在漂移

agents/README.md 中把 bug-explore-agent 描述为入口路由 Agent，但当前 .claude/agents/ 下没有看到对应有效 AGENT.md。

同时，项目 .claude/CLAUDE.md 仍描述两套入口并存：

unified-entry 是 Skill；
bug-explore 是 Agent 调度；
专业 Agent 包括 diagnose-bi-report、diagnose-active-report、env-check 等。

如果 bug-explore 已经迁移或废弃，应该清理引用；如果仍然需要，则应补齐 Agent 定义。

7.2 `diagnose-bi-report-agent` 被引用但缺少有效定义

agents/README.md 中仍把 diagnose-bi-report-agent 作为路由目标，但当前没有对应有效 AGENT.md。这会造成路由预期和实际可调用能力不一致。

建议二选一：

补齐 diagnose-bi-report-agent/AGENT.md；
如果能力已经迁移到其他 Skill 或 Agent，则删除旧引用并明确替代路径。

7.3 `common-sync-dp-bi-server-to-env` 目录残缺

.claude/skills/common-sync-dp-bi-server-to-env/ 当前只有 scripts/__pycache__/sync_to_env.cpython-39.pyc，没有 SKILL.md。但 code-implement 仍引用它作为同步代码到环境的能力。

这会导致用户或其他 Skill 误以为该能力存在，但实际无法作为 Skill 加载。

建议：

如果该同步能力仍需要使用，恢复完整 SKILL.md 和脚本源码；
如果已经废弃，删除或替换引用；
清理不应进入仓库的 __pycache__ 残留。

7.4 一些 Skill 实际承担了 Agent 编排器职责

以下 Skill 具备明显 Agent-like 特征：

code-implement：包含编码修复、提交、推送、TAPD 状态更新、环境同步等完整实施流程；
daily-code-review：扫描多仓库、多分支、多 commit，并做深度审查和通知；
metadata-review：明确采用多轮独立 agent review；
session-memory-scan：离线扫描历史会话并生成多类候选；
test-pilot：交互模式中基于页面文档自动操作，接近测试执行 Agent。

这些 Skill 不一定要迁移为 Agent，但应该明确分层：

Skill 是命令入口、流程门禁和报告生成器；
Agent 负责长上下文、深度分析、并行执行或独立判断；
高副作用操作必须经过用户确认。

7.5 同名 Skill 和 Agent 的边界不够清楚

当前存在同名或近似同名能力：

env-check
diagnose-active-report
diagnose-model-wide-table
diagnose-stream-monitor

这种组合本身合理：Skill 做入口，Agent 做深度执行。但每组能力都应该写清楚：

用户应该直接调用哪个？
unified-entry 默认路由哪个？
Skill 什么时候调用 Agent？
Agent 是否只读？
Agent 输出给谁？
二者内容谁是事实来源？
文档冲突时以哪个为准？

8. 治理建议

8.1 建立一页式 Agent/Skill 边界规范

建议在 .claude/agents/README.md 或 .claude/CLAUDE.md 中加入统一规范：

text 复制代码

Skill：
- 用户可直接触发的复用能力入口；
- 存放流程、规则、检查清单、模板、脚本、输出格式；
- 可以调用 Agent；
- 负责安全门禁和最终报告；
- 不应把大量深度搜索和长上下文分析都塞进主会话。

Agent：
- 独立上下文中的专家执行单元；
- 适合只读、并行、深度、跨文件、跨服务分析；
- 适合代码审查、日志诊断、Git 追溯、知识库构建；
- 返回结构化证据、根因、建议；
- 默认不做高副作用操作，除非明确授权。

同时保留当前 unified-entry 的本地约定：

text 复制代码

交互式、登录、复现、浏览器操作、诊断流程编排优先 Skill；
独立、只读、可并行、局部分析优先 Agent。

8.2 修复漂移引用

优先确认和处理：

bug-explore-agent 是否仍存在；
diagnose-bi-report-agent 是否需要补齐；
common-sync-dp-bi-server-to-env 是否需要恢复；
unified-entry 中引用的 systematic-debugging、verification-before-completion 是否依赖外部 superpowers，如果是，应明确写成外部 Skill 或改成当前环境可识别的名称。

8.3 为同名 Skill/Agent 增加关系说明

建议每个同名 Skill 增加：

markdown 复制代码

## 与同名 Agent 的关系

本 Skill 是用户入口和流程编排层。
当 CLI、页面、基础检查无法定位根因，或需要跨服务深度分析时，调用 `xxx-agent`。
本 Skill 负责最终报告和用户交互，Agent 只返回证据、根因和建议。

对应 Agent 增加：

markdown 复制代码

## 与 Skill 的关系

本 Agent 不作为普通用户入口。
由 `xxx` Skill 或 `unified-entry` 调用。
默认只读，不直接修改环境、数据库、代码或 TAPD。

8.4 将复杂编排型 Skill 拆成"入口 Skill + 执行 Agent"

建议优先评估：

code-implement
daily-code-review
metadata-review
session-memory-scan
test-pilot

它们可以继续保留为 Skill 入口，但应明确：

哪些步骤由 Skill 负责；
哪些步骤由 Agent 执行；
哪些步骤需要用户确认；
哪些动作禁止自动执行；
产物写到哪里；
失败后如何降级。

8.5 统一高副作用操作的安全模板

凡涉及以下动作的 Skill 或 Agent，都应该增加统一安全边界：

git push
创建或合并分支；
更新 TAPD；
发送企业微信；
重启服务；
修改环境配置；
数据库写入；
发布、部署、同步代码到环境；
删除、重置、清理。

推荐模板：

markdown 复制代码

## 安全边界

- 默认只读，除非用户明确要求执行变更。
- 变更前必须说明影响范围、风险、验证方式和回滚方式。
- 不自动执行破坏性操作。
- 不自动覆盖用户未提交变更。
- 涉及外部系统可见动作时必须二次确认。

9. 推荐决策树

维护新能力时，可以按以下顺序判断：

text 复制代码

1. 这是可复用流程、知识、模板、脚本吗？
   是 → Skill

2. 这个任务会消耗大量上下文、读取大量文件或日志吗？
   是 → Agent

3. 这个任务需要独立权限、只读边界、不同模型或专属系统提示吗？
   是 → Agent

4. 这个任务需要并行处理多个方向吗？
   是 → Agent

5. 这个任务只是让 Claude 按固定 SOP 做事吗？
   是 → Skill

6. 两者都需要？
   用 Skill 做入口和流程编排，用 Agent 做隔离执行。

10. 最终评价

当前 DP 项目的 Agent/Skill 体系整体方向是正确的：

Agents 侧已经覆盖多个专业诊断、Git 追溯、知识库构建等深度任务；
Skills 侧沉淀了大量项目 SOP、通用工具、诊断入口和自动化流程；
unified-entry 已经具备比较清晰的路由意识和分层原则。

但当前也存在治理问题：

agents/README.md 与实际目录有漂移；
bug-explore-agent、diagnose-bi-report-agent、common-sync-dp-bi-server-to-env 等引用和实际定义不一致；
多个同名 Agent/Skill 的边界说明不足；
一些 Skill 实际承担复杂自主编排任务；
高副作用操作的安全边界还应进一步统一。

因此，建议后续治理目标不是简单地"把复杂 Skill 全部改成 Agent"，而是建立更清晰的分层：

Skill 保留为用户入口、SOP、脚本和安全门禁；Agent 承担独立上下文中的深度分析、并行执行和专家判断。

这样既能保留当前 Skill 生态的可用性，又能充分发挥 Agent 在复杂诊断和上下文隔离方面的价值。

11. 参考来源

Claude Code Subagents 官方文档：https://docs.anthropic.com/en/docs/claude-code/sub-agents
Claude Code Skills 官方文档：https://docs.claude.com/en/docs/claude-code/skills
Claude Agent SDK Subagents 文档：https://code.claude.com/docs/en/agent-sdk/subagents
Claude Agent SDK Skills 文档：https://docs.claude.com/en/api/agent-sdk/skills
Claude 官方博客：Skills explained: How Skills compares to prompts, Projects, MCP, and subagents
Claude 官方博客：How and when to use subagents in Claude Code

Agent 与 Skill 的使用边界