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

文章目录一篇吃透Claude Code Agents与Skills核心区别、落地场景、完整配置代码实战前言 一、核心定义与底层本质 1. Skills技能包2. Agents智能子代理二、Agents vs Skills 全方位对比表 三、核心工作流程Mermaid流程图3.1 整体调度流程图用户输入→Skills匹配→Agent派生3.2 Skill内部执行流程图3.3 Agent独立任务流程图四、分模块完整使用说明命令配置代码4.1 Skills 完整使用指南4.1.1 目录创建命令终端执行4.1.2 SKILL.md 标准配置模板可直接复制4.1.3 Skill 操作核心命令4.1.4 Skill 典型落地场景4.2 Agents 完整使用指南4.2.1 Agent目录创建命令4.2.2 AGENT.md 完整配置示例带派生Skill能力4.2.3 Agent 核心操作命令4.2.4 Agent 典型落地场景五、实战项目完整案例Java后端项目案例需求步骤1创建TDD Skill步骤2创建安全审计Agent步骤3项目实操运行命令六、Agents与Skills组合使用最佳实践 ⚙️组合逻辑Skill做全局约束Agent做专项执行七、常见问题答疑 ❓Q1什么时候用Skill什么时候用AgentQ2Skill可以手动调用吗Q3Agent能读取项目里的Skill规则吗Q4Agent运行占用大量token怎么办八、总结 ✅一篇吃透Claude Code Agents与Skills核心区别、落地场景、完整配置代码实战前言 使用Claude Code做项目开发时绝大多数开发者都会混淆Agents和Skills二者看似都是扩展能力但底层运行逻辑、生命周期、触发方式、适用场景完全割裂。本文从底层原理、对比表格、流程图、实操命令、完整案例、项目落地规范一次性讲透所有关键字、命令、配置代码统一用xxx包裹可直接复制到项目使用。一、核心定义与底层本质 1.Skills技能包本质可复用的领域知识/流程模板依附主对话上下文被动自动加载存储路径项目目录.claude/skills/xxx/SKILL.md运行载体当前主会话不隔离上下文触发逻辑AI自动识别任务关键词、场景、文件类型无需手动调用匹配即注入规则、规范、步骤生命周期跟随当前对话清空会话则失效定位给主AI补充「行业规范、项目流程、编码标准」相当于团队内置Runbook2.Agents智能子代理本质独立隔离的小型AI实例拥有专属System Prompt、独立上下文、独立任务循环存储路径项目目录.claude/agents/xxx/AGENT.md运行载体fork全新隔离会话不污染主对话上下文触发逻辑手动通过/agents命令拉起或在Skill中配置自动派生子Agent生命周期独立进程主会话清空不影响正在运行的Agent定位垂直专项任务执行者独立完成复杂长流程代码审计、架构重构、测试全流程二、Agents vs Skills 全方位对比表 对比维度SkillsAgents上下文隔离共享主会话上下文无隔离独立fork上下文完全隔离数据触发方式AI自动匹配场景隐性加载手动/agents显式启动或配置自动派生System Prompt无独立prompt仅注入流程规则专属独立system prompt有专属角色定位任务长度短流程、单步规范、代码标准长周期、多步骤复杂任务重构、全量审计资源开销极低仅加载文本规则较高独立AI会话占用token互相调用Skill内可配置派生AgentAgent无法调用Skill仅能读取项目Skill规则典型命令/skill list、自动触发/agents list、/agents run xxx、/agents stop项目定位全局规范约束、通用知识库垂直专项任务工人三、核心工作流程Mermaid流程图3.1 整体调度流程图用户输入→Skills匹配→Agent派生是否简单短任务复杂专项任务用户输入开发指令Claude Code加载CLAUDE.md自动扫描.claude/skills目录匹配Skill是否匹配到对应Skill?注入Skill流程规则到主会话使用默认通用编码逻辑任务是否复杂长周期?主会话直接执行代码操作读取.claude/agents配置执行/agents run 派生独立AgentAgent隔离上下文独立循环执行Agent完成后输出结果回传给主会话输出最终代码/文档3.2 Skill内部执行流程图用户修改Java代码AI检测到后端编码场景自动匹配java-lint SKILL.md注入规范命名、异常处理、注释规范生成代码时强制遵循Skill规则3.3 Agent独立任务流程图用户执行/agents run code-audit创建独立隔离会话加载Agent专属System Prompt循环执行读取代码→漏洞扫描→生成报告使用/goal持续迭代直到审计完成输出完整安全审计报告返回主会话四、分模块完整使用说明命令配置代码4.1 Skills 完整使用指南4.1.1 目录创建命令终端执行# 创建skill标准目录结构mkdir-p.claude/skills/tdd-dev# 进入目录创建配置文件cd.claude/skills/tdd-devtouchSKILL.md4.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-dev4.1.4 Skill 典型落地场景团队代码规范Java/前端Lint、注释、Git提交规范Skill固定开发流程TDD、CodeReview、接口文档生成Skill项目私有知识库数据库表设计、中间件使用规范SkillCI/CD配套自动生成Dockerfile、部署脚本Skill4.2 Agents 完整使用指南4.2.1 Agent目录创建命令# 创建代码审计Agent目录mkdir-p.claude/agents/security-auditcd.claude/agents/security-audittouchAGENT.md4.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 典型落地场景大型代码重构独立Agent负责全模块迁移、API改造安全审计隔离会话扫描全项目漏洞不污染主对话自动化测试批量生成单元、集成测试用例架构梳理读取全项目代码生成架构图、依赖分析批量文档生成接口文档、数据库文档、运维手册五、实战项目完整案例Java后端项目案例需求Java微服务项目需要自动强制TDD编码规范Skill自动触发独立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创建安全审计Agentmkdir-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项目实操运行命令日常开发自动触发TDD Skill无需手动执行写代码自动生效手动触发TDD规范校验/tdd-java启动安全审计Agent全项目扫描/agents run java-sec-audit 扫描整个微服务后端所有代码漏洞搭配/goal让Agent自动迭代修复漏洞/agents run java-sec-audit 扫描并自动修复所有高危漏洞 /goal 审计报告无高危漏洞查看Agent运行状态/agents status六、Agents与Skills组合使用最佳实践 ⚙️组合逻辑Skill做全局约束Agent做专项执行全局通用规则全部放入Skill编码规范、Git提交规范、项目目录约定、通用开发流程全部配置为SkillAI写代码时自动遵守不用每次重复说明。长周期、隔离性任务交给Agent全量重构、安全扫描、批量测试、架构分析派生独立Agent避免主会话上下文爆炸、token溢出。Agent内部自动加载Skill在AGENT.md配置auto_load_skills让Agent执行时自动遵循项目统一规范保证输出标准统一。禁止反模式不要把复杂长流程写进Skill会导致主会话上下文臃肿不要用Agent存储通用编码规范资源消耗过高不要多个Agent共享主会话数据隔离失效出现数据污染七、常见问题答疑 ❓Q1什么时候用Skill什么时候用AgentA短流程、全局通用规范、每次编码都要遵守 →Skills多步骤、长时间、需要独立隔离环境、批量处理任务 →Agents。Q2Skill可以手动调用吗A可以配置user_invocable: true后使用/skill名称手动触发例如/tdd-java。Q3Agent能读取项目里的Skill规则吗A能通过auto_load_skills: [skill-name]配置Agent启动自动加载对应Skill规范。Q4Agent运行占用大量token怎么办AAgent上下文独立执行完成后手动执行/agents stop xxx释放资源单次任务拆分避免单Agent遍历百万行代码。八、总结 ✅Skills 项目全局规则手册自动加载、轻量、共享主会话约束日常编码行为Agents 独立专项工人隔离上下文、长任务自动化负责复杂批量工程项目落地标准搭配Skills打底规范 Agents处理重型专项任务配合/goal、/agents、/skill系列命令实现全自动开发流水线所有配置文件统一存放于项目.claude目录提交Git后团队全员共享AI扩展能力统一开发标准。