一篇吃透Claude Code Agents与Skills：核心区别、落地场景、完整配置+代码实战

前言 📝

使用Claude Code做项目开发时，绝大多数开发者都会混淆 Agents 和 Skills，二者看似都是扩展能力，但底层运行逻辑、生命周期、触发方式、适用场景完全割裂。本文从底层原理、对比表格、流程图、实操命令、完整案例、项目落地规范一次性讲透，所有关键字、命令、配置代码统一用 xxx 包裹，可直接复制到项目使用。

一、核心定义与底层本质 🔍

1. Skills（技能包）

本质：可复用的领域知识/流程模板，依附主对话上下文，被动自动加载

• 存储路径：项目目录 .claude/skills/xxx/SKILL.md
• 运行载体：当前主会话，不隔离上下文
• 触发逻辑：AI自动识别任务关键词、场景、文件类型，无需手动调用，匹配即注入规则、规范、步骤
• 生命周期：跟随当前对话，清空会话则失效
• 定位：给主AI补充「行业规范、项目流程、编码标准」，相当于团队内置Runbook

2. Agents（智能子代理）

本质：独立隔离的小型AI实例，拥有专属System Prompt、独立上下文、独立任务循环

• 存储路径：项目目录 .claude/agents/xxx/AGENT.md
• 运行载体：fork全新隔离会话，不污染主对话上下文
• 触发逻辑：手动通过 /agents 命令拉起，或在Skill中配置自动派生子Agent
• 生命周期：独立进程，主会话清空不影响正在运行的Agent
• 定位：垂直专项任务执行者，独立完成复杂长流程（代码审计、架构重构、测试全流程）

二、Agents vs Skills 全方位对比表 📊

对比维度	Skills	Agents
上下文隔离	共享主会话上下文，无隔离	独立fork上下文，完全隔离数据
触发方式	AI自动匹配场景，隐性加载	手动/agents显式启动，或配置自动派生
System Prompt	无独立prompt，仅注入流程规则	专属独立system prompt，有专属角色定位
任务长度	短流程、单步规范、代码标准	长周期、多步骤复杂任务（重构、全量审计）
资源开销	极低，仅加载文本规则	较高，独立AI会话占用token
互相调用	Skill内可配置派生Agent	Agent无法调用Skill，仅能读取项目Skill规则
典型命令	/skill list、自动触发	/agents list、/agents run xxx、/agents stop
项目定位	全局规范约束、通用知识库	垂直专项任务工人

三、核心工作流程Mermaid流程图

3.1 整体调度流程图（用户输入→Skills匹配→Agent派生）

3.2 Skill内部执行流程图

3.3 Agent独立任务流程图

四、分模块完整使用说明（命令+配置代码）

4.1 Skills 完整使用指南

4.1.1 目录创建命令（终端执行）

# 创建skill标准目录结构
mkdir -p .claude/skills/tdd-dev
# 进入目录创建配置文件
cd .claude/skills/tdd-dev && touch SKILL.md

4.1.2 SKILL.md 标准配置模板（可直接复制）

---
name: tdd-dev
version: 1.0
description: 项目TDD开发规范，自动执行先写测试再编码重构流程
invoked_by: auto # auto自动触发 / manual手动斜杠命令触发
trigger_keywords: ["新增接口","开发业务模块","编写代码"]
tools: [Read, Write, Grep, Bash]
user_invocable: true # 是否支持手动/tdd调用
---
# TDD开发强制流程
1. 读取需求文档，提取测试用例
2. 编写单元测试，执行测试全部失败
3. 编写业务代码，保证测试全部通过
4. 代码重构，不改动测试逻辑
5. 执行lint、格式化、提交规范校验
# 禁止行为
- 禁止跳过测试直接编写业务代码
- 禁止测试覆盖率低于80%提交代码

4.1.3 Skill 操作核心命令

# 查看项目所有已加载Skills
/skill list
# 手动强制触发指定skill
/tdd
# 重载所有skill配置（修改SKILL.md后执行）
/reload-skills
# 临时禁用单个skill
/skill disable tdd-dev

4.1.4 Skill 典型落地场景

1. 团队代码规范：Java/前端Lint、注释、Git提交规范Skill
2. 固定开发流程：TDD、CodeReview、接口文档生成Skill
3. 项目私有知识库：数据库表设计、中间件使用规范Skill
4. CI/CD配套：自动生成Dockerfile、部署脚本Skill

4.2 Agents 完整使用指南

4.2.1 Agent目录创建命令

# 创建代码审计Agent目录
mkdir -p .claude/agents/security-audit
cd .claude/agents/security-audit && touch AGENT.md

4.2.2 AGENT.md 完整配置示例（带派生Skill能力）

---
name: security-audit
version: 1.2
role: 专业代码安全审计智能代理
system_prompt: |
  你是资深安全开发工程师，独立完成项目全量代码漏洞扫描，
  输出包含SQL注入、XSS、权限越权、密码明文存储的完整报告，
  每一个漏洞标注文件路径、行数、修复方案。
context: fork # 强制隔离独立上下文
auto_load_skills: ["java-sec-check"] # 自动加载对应Skill规则
max_iter: 20 # 最大循环次数
---
# Agent执行步骤
1. 遍历项目所有源码文件
2. 调用安全检测规则扫描风险点
3. 分类整理高危/中危/低危漏洞
4. 生成Markdown审计报告保存到audit-report.md
5. 汇总修复优先级清单

4.2.3 Agent 核心操作命令

# 查看本地所有Agent列表
/agents list
# 启动指定Agent执行任务
/agents run security-audit 扫描整个后端代码安全漏洞
# 查看正在运行的Agent状态
/agents status
# 终止卡死/长时间运行的Agent
/agents stop security-audit
# 重载Agent配置文件
/reload-agents
# 搭配/goal让Agent自动迭代完成任务
/agents run refactor-agent 重构用户模块 && /goal 所有测试用例执行通过

4.2.4 Agent 典型落地场景

1. 大型代码重构：独立Agent负责全模块迁移、API改造
2. 安全审计：隔离会话扫描全项目漏洞，不污染主对话
3. 自动化测试：批量生成单元、集成测试用例
4. 架构梳理：读取全项目代码生成架构图、依赖分析
5. 批量文档生成：接口文档、数据库文档、运维手册

五、实战项目完整案例（Java后端项目）

案例需求

Java微服务项目，需要：

1. 自动强制TDD编码规范（Skill自动触发）
2. 独立Agent做安全审计，每周批量扫描漏洞

步骤1：创建TDD Skill

执行目录命令：

mkdir -p .claude/skills/tdd-java

写入 .claude/skills/tdd-java/SKILL.md：

---
name: tdd-java
version: 1.0
description: Java后端TDD开发规范，自动约束测试先行
invoked_by: auto
trigger_keywords: ["新增Controller","新增Service","开发业务接口"]
tools: [Read, Write, Bash, Grep]
user_invocable: true
---
## Java TDD强制流程
1. 根据需求定义接口出入参DTO
2. 编写JUnit5单元测试，模拟入参
3. 运行测试，全部预期失败
4. 编写Service/Controller业务代码
5. 重新执行测试，保证100%通过
6. 执行mvn spotless格式化代码
7. 校验mvn lint无告警
## 项目约束
- 所有业务方法必须配套单元测试
- 禁止直接写业务代码不写测试
- 异常必须全局统一捕获，不抛原生Exception

步骤2：创建安全审计Agent

mkdir -p .claude/agents/java-sec-audit

写入 .claude/agents/java-sec-audit/AGENT.md：

---
name: java-sec-audit
version: 1.0
role: Java后端安全审计代理
system_prompt: |
  你是Java安全专家，独立扫描项目所有Java、XML、yml配置文件，
  识别SQL注入、明文密码、未校验入参、接口权限缺失、硬编码密钥等漏洞，
  输出标准化漏洞报告，附带可直接复制的修复代码。
context: fork
auto_load_skills: ["tdd-java"]
max_iter: 30
---
# 审计执行流程
1. 遍历src/main/java、src/main/resources全部文件
2. 检测application.yml、bootstrap.yml明文密钥
3. 扫描Mybatis SQL拼接漏洞
4. 校验接口是否添加权限校验注解
5. 生成audit/security-report.md报告
6. 汇总高危漏洞优先修复清单

步骤3：项目实操运行命令

1. 日常开发自动触发TDD Skill（无需手动执行，写代码自动生效）
2. 手动触发TDD规范校验：

/tdd-java

3. 启动安全审计Agent全项目扫描：

/agents run java-sec-audit 扫描整个微服务后端所有代码漏洞

4. 搭配 /goal 让Agent自动迭代修复漏洞：

/agents run java-sec-audit 扫描并自动修复所有高危漏洞 && /goal 审计报告无高危漏洞

5. 查看Agent运行状态：

/agents status

六、Agents与Skills组合使用最佳实践 ⚙️

组合逻辑：Skill做全局约束，Agent做专项执行

1. 全局通用规则全部放入Skill
   编码规范、Git提交规范、项目目录约定、通用开发流程，全部配置为Skill，AI写代码时自动遵守，不用每次重复说明。
2. 长周期、隔离性任务交给Agent
   全量重构、安全扫描、批量测试、架构分析，派生独立Agent，避免主会话上下文爆炸、token溢出。
3. Agent内部自动加载Skill
   在AGENT.md配置 auto_load_skills，让Agent执行时自动遵循项目统一规范，保证输出标准统一。
4. 禁止反模式
   • 不要把复杂长流程写进Skill（会导致主会话上下文臃肿）
   • 不要用Agent存储通用编码规范（资源消耗过高）
   • 不要多个Agent共享主会话数据（隔离失效，出现数据污染）

七、常见问题答疑 ❓

Q1：什么时候用Skill，什么时候用Agent？

A：短流程、全局通用规范、每次编码都要遵守 → Skills；多步骤、长时间、需要独立隔离环境、批量处理任务 → Agents。

Q2：Skill可以手动调用吗？

A：可以，配置 user_invocable: true 后，使用 /skill名称 手动触发，例如 /tdd-java。

Q3：Agent能读取项目里的Skill规则吗？

A：能，通过 auto_load_skills: ["skill-name"] 配置，Agent启动自动加载对应Skill规范。

Q4：Agent运行占用大量token怎么办？

A：Agent上下文独立，执行完成后手动执行 /agents stop xxx 释放资源；单次任务拆分，避免单Agent遍历百万行代码。

八、总结 ✅

1. Skills = 项目全局规则手册，自动加载、轻量、共享主会话，约束日常编码行为；
2. Agents = 独立专项工人，隔离上下文、长任务自动化，负责复杂批量工程；
3. 项目落地标准搭配：Skills打底规范 + Agents处理重型专项任务，配合 /goal、/agents、/skill 系列命令实现全自动开发流水线；
4. 所有配置文件统一存放于项目 .claude 目录，提交Git后团队全员共享AI扩展能力，统一开发标准。