Agent 与 Skill 详解：从概念到手搓，一文讲透
2026-06-18 16:00:00 · 标签：Claude Code、Agent、Skill、教程、Claude、Anthropic
很多人刚接触 Claude Code 时都会困惑：Agent 和 Skill 到底有什么区别？什么时候该用 Skill，什么时候该用 Agent？本文用大白话讲清两者的定位与差异，并带你手把手各搓一个出来。
一、先讲清楚：Agent 和 Skill 到底是什么
1.1 一句话定义
| 概念 | 一句话 | 类比 |
|---|---|---|
| Skill（技能） | 一份"说明书"，告诉 AI 怎么做事 | 菜谱：宫保鸡丁怎么做 |
| Agent（代理） | 一个独立的"打工人"，AI 派它去独立完成任务 | 厨师：你去做宫保鸡丁 |
1.2 生动比喻
想象你是餐厅老板（Claude Code 主进程）：
- Skill = 你放在后厨的那本菜谱。厨师翻开菜谱，按照步骤做菜。菜谱自己不干活，但它让干活的人不出错。
- Agent = 你雇了一个专门炒川菜的厨子。你跟他说"做一道宫保鸡丁"，他有自己的灶台、自己的工具、自己看菜谱——做完端上来，你验收。
核心差别：Skill 是被动加载的知识包；Agent 是主动执行任务的独立进程。
二、一张表讲清全部区别
+------------------------------------------------------------------+
| Skill vs Agent 全景对比 |
+------------------------------------------------------------------+
| | Skill（技能） | Agent（代理） |
+----------+------------------------+-------------------------------+
| 本质 | Markdown 说明书 + 脚本 | 独立子进程，带独立上下文 |
| 触发方式 | AI 自动检测相关性加载 | AI 决定分派任务时创建 |
| 运行方式 | 指令注入主 Agent 上下文 | 独立运行，有自己的上下文窗口 |
| 上下文 | 共享主 Agent 上下文 | 独立上下文，用完即销毁 |
| 工具权限 | 默认继承，可限制 | 可精细控制（allowlist） |
| 模型 | 跟随主 Agent | 可指定不同模型（Sonnet/Haiku） |
| 生命周期 | 对话期间持久可用 | 按需创建，任务结束销毁 |
| 成本 | 极低（首次加载后缓存） | 中等（每次创建新上下文） |
| 并行性 | 不能并行（共用上下文） | 可并行执行多个 Agent |
| 隔离性 | 无隔离 | worktree 文件隔离 / remote 全隔离|
+----------+------------------------+-------------------------------+什么时候用 Skill？
- 你有一套固定的操作流程需要 AI 遵守（比如 git commit 格式规范）
- 你需要 AI 能访问特定领域的知识（比如公司内部 API 文档）
- 你想把最佳实践沉淀成可复用的知识包
- 核心判断：你需要的是"让 AI 知道怎么做"
什么时候用 Agent？
- 任务可以独立完成，不需要实时交互
- 需要并行处理多个独立任务（比如同时审查 5 个文件）
- 需要隔离的环境（比如在 worktree 中修改代码）
- 核心判断：你需要的是"派人去独立干活"
三、手搓一个 Skill
下面我们从头构建一个实用的 Skill —— 自动生成规范 git commit message。
3.1 创建目录结构
# 项目级 Skill（跟随项目，团队共享）
mkdir -p .claude/skills/commit-message-writer
# 或者用户级 Skill（所有项目通用）
mkdir -p ~/.claude/skills/commit-message-writer3.2 编写 SKILL.md
在 .claude/skills/commit-message-writer/SKILL.md 中写入：
---
name: commit-message-writer
description: >
根据 git staged 变更生成符合 Conventional Commits 规范的 commit message。
当用户说"帮我写 commit"、"提交信息怎么写"、"summarize my staged changes"、
"生成 commit message"时自动触发。
---
# Commit Message Writer
你负责从 git staged 变更中生成结构化的 commit message。
## 执行流程
1. 执行 `git diff --staged` 获取暂存区变更
2. 如果没有暂存内容，提示用户先 `git add`
3. 分析变更内容，直接生成 commit message（不要先问问题再生成）
## 输出格式
```
type(scope): 简述
[正文 — 可选，非平凡变更时包含]
[脚注 — 可选]
```
## Type 选择规则
| Type | 使用场景 |
|------------|---------------------------------------|
| `feat` | 新增功能 |
| `fix` | 修复 bug |
| `docs` | 仅文档变更 |
| `refactor` | 重构（不修 bug、不加功能） |
| `test` | 添加或修改测试 |
| `chore` | 构建、依赖、工具链变更 |
| `style` | 格式调整（空格、分号等，不影响逻辑） |
| `perf` | 性能优化 |
## 质量规则
- 简述用祈使语气（"添加"而不是"添加了"）
- 简述不超过 50 个字符（中文约 25 个字）
- 简述不以句号结尾
- 绝对不要用"更新"、"修改"、"调整"这类模糊词汇——要说改了什么
- 正文说明 WHY（为什么改），而不是 WHAT（改了什么，看 diff 就知道）
## 反例（Do NOT do this）
```
// 错误示范
fix: 修改了一个问题
update: 更新了文件
// 正确示范
fix(auth): token 过期时未清除 sessionStorage 缓存
feat(profile): 支持微信扫码登录
```3.3 测试
在 Claude Code 中暂存一些改动后说：
帮我写个 commit messageClaude 会自动检测到 commit-message-writer Skill，加载它，然后执行 git diff --staged 并生成规范的 message。
3.4 进阶：加一个脚本
在 scripts/ 下放一个辅助脚本，Skill 可以引用它：
.claude/skills/commit-message-writer/
├── SKILL.md
└── scripts/
└── check_branch.sh # 检查当前分支是否需要特殊格式#!/bin/bash
# scripts/check_branch.sh
branch=$(git branch --show-current)
if [[ $branch == hotfix/* ]]; then
echo "WARNING: hotfix 分支，建议在 footer 加 Fixes #issue-number"
fi在 SKILL.md 中引用：
## 额外检查
生成 commit message 前，先执行 `bash scripts/check_branch.sh` 检查是否有分支特殊要求。四、手搓一个 Agent
下面构建一个 代码审查 Agent —— 专门负责审查代码质量和安全性。
4.1 创建 Agent 文件
mkdir -p .claude/agents4.2 编写 Agent 定义
在 .claude/agents/code-reviewer.md 中写入：
---
name: code-reviewer
description: >
审查代码质量和安全性。PROACTIVELY 在代码变更后自动触发，
或在用户说"review 一下"、"帮我审查"、"检查代码"时使用。
tools: Read, Grep, Glob
model: sonnet
permissionMode: acceptEdits
color: 35
---
# Code Reviewer Agent
你是一位资深代码审查者（Staff Engineer 级别）。你的审查报告直接决定代码是否合入。
## 核心原则
- **只看不改**：你只能读取和搜索，永远不要修改代码
- **具体到行**：每条意见必须指出具体文件和行号
- **分级标注**：每条意见标注严重程度
## 审查维度
### 1. 正确性（Critical）
- 逻辑错误、边界条件遗漏
- 空指针 / undefined 访问风险
- 异步处理不当（Promise 未 await、回调地狱）
### 2. 安全性（High）
- SQL 注入 / XSS / CSRF 风险
- 敏感信息硬编码（密钥、Token）
- 权限校验缺失
### 3. 性能（Medium）
- 不必要的重复计算或请求
- 大量数据未分页
- 未使用缓存的热点路径
### 4. 可维护性（Low）
- 函数过长（超过 50 行）
- 变量命名无意义（如 `a`, `tmp`, `data`）
- 缺少关键注释（Magic Number、业务规则）
## 输出格式
```markdown
## Code Review Report
### Summary
- 审查文件数：X
- Critical: N / High: N / Medium: N / Low: N
### Findings
#### 1. [严重程度] 问题简述
- **文件**：`path/to/file.ts:42`
- **问题**：具体描述
- **建议**：给出修改方案（最好附代码示例）
- **参考**：相关文档或最佳实践链接
```
## 审查流程
1. 先用 `Glob` 列出所有变更文件
2. 对每个文件逐一 `Read`
3. 对关键模式（SQL、fetch、密码等）用 `Grep` 搜索
4. 汇总成完整报告4.3 Agent 关键字段说明
name: code-reviewer # 唯一标识，用于 SubAgent 调用
description: ... # 包含 "PROACTIVELY" 表示主动触发
tools: Read, Grep, Glob # 工具白名单（Agent 只能用这些）
model: sonnet # 指定模型：haiku/sonnet/opus/inherit
permissionMode: acceptEdits # 权限模式
# default — 每次工具调用都询问用户
# acceptEdits — 自动接受编辑类操作
# bypassPermissions — 跳过权限检查（慎用！）
# plan — 只读模式，不能写文件
color: 35 # CLI 中终端输出的颜色编号
maxTurns: 20 # 最大对话轮数（防死循环）
background: true # 是否作为后台任务运行4.4 实际运行流程
当你在 Claude Code 中说"review 一下我今天的改动"，幕后发生的是：
主 Agent
|
| 匹配到 "review" 关键词
| 发现 .claude/agents/code-reviewer.md
|
+--> 创建 code-reviewer SubAgent
|
| 独享上下文窗口（不污染主 Agent 上下文）
| 只能使用 Read / Grep / Glob 工具
| 使用 Sonnet 模型
|
+--> Glob("src/**/*.ts") ← 找到变更文件
+--> Read("src/auth.ts") ← 逐文件审查
+--> Grep("fetch\(", "src/") ← 搜索网络请求
|
+--> 返回审查报告给主 Agent
|
销毁 SubAgent
释放上下文五、Skill 的渐进式加载机制
这是 Skill 最精巧的设计——三层渐进加载，保证上下文不被撑爆：
系统启动时
|
v
[第 1 层：Metadata（始终在内存）]
~100 字 / Skill
name + description
50 个 Skill 也只占 ~5000 tokens
|
| 用户说 "帮我写 commit message"
| AI 匹配到 commit-message-writer Skill
v
[第 2 层：SKILL.md 正文（按需加载）]
完整指令注入上下文
用户看不到这个过程，AI 自动完成
|
| AI 读到：先执行 bash scripts/check_branch.sh
v
[第 3 层：附件资源（按需加载/执行）]
scripts/ 下的脚本
references/ 下的文档
仅在实际需要时才读入这意味着你可以安装 50 个 Skill，但每次对话的实际上下文成本只有你当前用到的 1-2 个。
六、扩展机制全景：Skill 在整个体系中的位置
+==================================================================+
|| Claude Code 扩展体系 ||
|| ||
|| +-------------+ +-------------+ +-------------------------+ ||
|| | Command | | Skill | | Agent (SubAgent) | ||
|| | /deploy | | 自动触发 | | AI 分派，独立执行 | ||
|| | 用户必须 | | AI 判断 | | 独立上下文 + 工具白名单 | ||
|| | 显式输入 | | 何时加载 | | 可并行 / 可隔离 | ||
|| +------+------+ +------+------+ +-----------+-------------+ ||
|| | | | ||
|| v v v ||
|| +----------------------------------------------------------+ ||
|| | Hook（事件驱动，27 种生命周期） | ||
|| | PreToolUse / PostToolUse / SessionStart / PreCompact ... | ||
|| | 零上下文成本，任何扩展都不能绕过 Hook | ||
|| +----------------------------------------------------------+ ||
|| ||
|| 记忆层级：CLAUDE.md → .claude/rules/ → Auto-memory ||
|+==================================================================+七、实战练习
练习 1：手搓一个"新建博客文章"Skill
目标：当用户说"新建一篇文章"时，自动创建带 frontmatter 的 Markdown 文件。
在 .claude/skills/new-blog-post/SKILL.md 中：
---
name: new-blog-post
description: >
创建新的博客文章 Markdown 文件。当用户说"新建文章"、"写一篇新文章"、
"创建博客文章"时自动触发。
---
# New Blog Post
## 执行步骤
1. 询问用户文章标题
2. 生成文件名：`YYYY-MM-DD-{slug}.md`（slug 从标题提取英文/拼音）
3. 在 `posts/` 目录下创建文件，内容模板如下：
```markdown
---
title: {标题}
date: {当前日期时间，格式 YYYY-MM-DD HH:MM:SS}
tags: []
summary: ""
---
# {标题}
正文开始...
```
4. 打开文件供用户编辑
5. 提醒用户写完后更新 `index.json` 和 `posts.js`练习 2：手搓一个"翻译助手"Agent
目标：创建一个专门做中英文翻译的 Agent，使用 Haiku 模型（便宜快速）。
在 .claude/agents/translator.md 中：
---
name: translator
description: >
中英文翻译专家。PROACTIVELY 在用户说"翻译"、"translate"、
"翻一下"时使用。
tools: Read, Write
model: haiku
permissionMode: acceptEdits
---
# Translator Agent
## 规则
- 中文翻译成英文时：保持技术术语准确性，代码和变量名不翻译
- 英文翻译成中文时：使用流畅自然的中文，技术文章保持专业感
- 翻译 Markdown 文件时：保持原有的格式、代码块、链接不变
- 始终输出双语对照版本
## 输出格式
```
### 原文
{原文段落}
### 译文
{译文段落}
---
```练习 3：Skill + Agent 组合
高级用法：Skill 触发 Agent。
在 SKILL.md 中指定 context: fork，让 Skill 在独立 Agent 中运行：
---
name: adversarial-review
description: 对立审查——从最挑剔的角度审查代码
context: fork # 在独立 Agent 上下文中运行
allowed-tools: Read, Grep, Glob
model: sonnet
---
# Adversarial Review
你是一个"挑剔的反对者"。你的工作是对最近变更的代码进行对立审查。
## 策略
1. 假设每一个设计决定都是错的
2. 假设每一条边界条件都会被触发
3. 假设每一个性能假设在高负载下都会崩溃
4. 对每一条发现，给出具体反驳
## 输出
对每个发现标注：
- **严重性**：致命 / 严重 / 常规 / 吹毛求疵
- **触发条件**：什么情况下会出问题
- **修复建议**：具体代码示例八、常见问题
Q: Skill 和 MCP Server 有什么区别？
| Skill | MCP Server | |
|---|---|---|
| 本质 | Markdown 文件 + 可选脚本 | 独立进程（stdio/HTTP/WebSocket） |
| 能做什么 | 提供指令、参考信息、执行本地脚本 | 提供工具（tools）、资源（resources）、提示（prompts） |
| 能否调 API？ | 不能直接调（只能通过 Bash 工具间接触发脚本） | 可以，Server 进程内可以干任何事 |
| 适合场景 | 编码规范、领域知识、操作流程 | 数据库访问、外部 API、文件系统操作 |
选择建议：需要访问外部系统 → MCP。需要注入知识/流程 → Skill。
Q: 一个项目能有多少 Skill 和 Agent？
没有硬性限制。Skill 通过渐进式加载，50 个 Skill 也只占很少的启动上下文。Agent 按需创建，只在分配任务时才消耗上下文。
Q: Agent 跑飞了怎么办？
- 设置
maxTurns限制最大轮数 - 设置工具白名单
tools: Read, Grep限制破坏性操作 - 使用
permissionMode: plan（只读）进行安全审查
Q: Skill 不触发怎么办？
检查 description 字段是否包含了用户在对话中可能用的关键词。如果 description 是"帮助处理 PDF"，但用户说的是"帮我提取文档中的文字"，就不会触发。补救方法：在 description 中加入常见的触发词。
九、总结
+==================================================================+
|| ||
|| 想沉淀"怎么做"的知识 ───→ 写一个 Skill ||
|| 菜谱、规范、操作手册、领域知识 ||
|| ~/.claude/skills/<name>/SKILL.md ||
|| ||
|| 想分派"独立干"的任务 ───→ 定义一个 Agent ||
|| 审查、翻译、搜索、代码生成 ||
|| .claude/agents/<name>.md ||
|| ||
|| 两者可以组合：Skill 提供知识，Agent 独立执行 ||
|| ||
+==================================================================+一句话记住：Skill 是"菜的配方"（知识），Agent 是"炒菜的厨子"（执行者）。配方+厨子=一桌好菜。
参考资料 1. Anthropic 官方博客 — Lessons from building Claude Code: How we use skills 2. Anthropic 工程博客 — Equipping agents for the real world with Agent Skills 3. SitePoint — Claude Agent Skills Tutorial | Custom Skills Guide 4. Launch Vault — Claude Agent Skills Guide 2026: Build, Use & Share 5. 阿里云开发者 — Agent Skills 的一次工程实践 6. 腾讯云 — 2026 最强 Hooks、Skills、Agents 实战