Claude Code 中的 Skill 与 Agent

2026-05-14 Skill / Agent

这份说明聚焦在 Claude Code（终端/IDE 里的 Claude 编程 Agent）生态，而不是泛泛的"AI Agent 理论"。

1. 心智模型：Claude Code 本身就是一个 Agent

Claude Code 是一个 agentic coding assistant：你用自然语言给目标，它在终端里读文件、做针对性编辑、跑命令（Bash）、搜代码（Grep/Glob）、必要时还能走网络/调度子任务，在一个"思考→选工具→执行→评估结果→继续"的循环里推进到你定义的任务完成。

它要"懂你项目"，主要靠一套 memory/规则层：

在此之上，Claude Code 提供了两种最常见的"扩展/复用"机制：

Skill（Agent Skills / SKILL.md） — 把"专业知识/流程/模板"封装成可被发现、可复用的工作包。适用于固化工作流/规范/交付物标准。

MCP（Model Context Protocol） — 给 Claude Code 挂载"外部能力/数据源"，例如连 Jira/GitHub/Drive/DB 等。需要调用外部系统 API 时使用。

Skill 不是函数式代码，更像"非常结构化、可复用的大段系统提示 + 参考资料 +（可选）脚本入口"。核心是 SKILL.md，可带脚本/模板/参考文档。

2. Skill（Agent Skills）是什么？怎么被触发？

每个 Skill 本质上是一个 目录 + 一个必有的 SKILL.md：

触发分两类：

  1. 模型驱动（model-invocation）：Claude 根据你的请求 + Skill 的 description 自行判断
  2. 用户驱动（斜杠显式调用）：你敲 /something 明确触发（更多团队偏好这种可控性）

官方文档提醒：description 极其重要——Claude 靠它来决定什么时候该用这个 Skill。

3. Skill 存放在哪：全局 vs 项目级

个人全局（跨项目可用）

~/.claude/skills/
              my-skill/
                SKILL.md
                (可选) reference.md
                (可选) scripts/helper.py

            mkdir -p ~/.claude/skills/my-skill

用途：个人偏好、通用小工具、你在多项目都要用的流程模板。

项目级（团队共享，进 git）

your-project/
              .claude/
                skills/
                  code-review-acme/
                    SKILL.md
                    checklists/
                      security.md

            mkdir -p .claude/skills/code-review-acme

提交到仓库后，队友打开项目就能继承同一套 Skill（不需要每人手工装一遍）。

旧形态 .claude/commands/*.md（自定义斜杠命令）在很多资料里也能见到；官方 Agent Skills 路线更倾向于 .claude/skills/<name>/SKILL.md 这种目录化、可携带资源的包结构。

4. 创建 Skill：最小可运行步骤

下面用一个实战例子：explain-code（用"类比 + ASCII 图示"解释代码）。

Step 1：建目录

# 个人全局示例
            mkdir -p ~/.claude/skills/explain-code

Step 2：写 SKILL.md

---
            name: explain-code
            description: >
              当需要把一段代码解释给人类（尤其非编译器思维）时用我：
              用直观类比 + 控制流/数据流的 ASCII 图 + 逐段对应源码来讲解；
              默认语言不限，若上下文明显则用项目语言。
            ---

            ## Explain Code — 标准做法

            1) 先**不改动代码**：只复述结构
            2) 画一个最小但够用的 **ASCII 数据流/调用链**
            3) 对每段关键逻辑给：
               - 它在做什么（意图）
               - 为什么这么做（tradeoff / 约束）
               - 常见误会在哪（边界条件 / 副作用 / async / error path）
            4) 结尾给一句"如果你愿意，我可以再补一份 refactoring 建议（仍不改文件）"

Step 3：验证

在 Claude Code 交互里直接说：

用 explain-code 给我讲讲 src/auth.ts 的 login 分支

或确认 Skill 出现：

/skills

5. 进阶：给 Skill 加参考文件 / 脚本

Skill 目录里可以放 reference.md / 示例 / scripts / templates，需要时再从 SKILL.md 里引用路径让 Claude 去读或去执行。

.claude/skills/release-check/
              SKILL.md
              checklists/
                backend.md
                frontend.md
              scripts/
                changelog-from-git.sh

SKILL.md 里可以写类似指引：

1. 读 checklists/backend.md 作为检查口径
2. 运行：bash scripts/changelog-from-git.sh origin/main..HEAD
3. 对照输出逐项确认，给出放行/打回结论

6. Agent / Subagent 在这里指什么？

这与 Skill 的定位不同：Skill 更像"知识包/流程包"；Subagent 更像"角色隔离的执行者"。

如果要"写一个 Agent"（长期运行、带专属工具/记忆/目标的角色），通常走两条路：

  1. 用 CLAUDE.md + 规范 + 允许的工具集塑造行为（最简单、最稳）
  2. 用 Subagents / 任务编排（更复杂的并行/隔离）

7. 快速对照：Skill vs MCP vs CLAUDE.md

项目规范/代码风格/审查口径 → CLAUDE.md +（可选）SKILL.md（知识/流程，不需要外部 API）

可复用跨项目的工作流包 → ~/.claude/skills/ 的 Skill（便于携带、版本化、团队共享）

操作 Jira / GitHub / DB / 本地 App → MCP server（需要把外部系统能力映射成 tools）

角色化 + 上下文隔离 → Subagent 思路

8. 团队内部标准建议（避坑）

← 返回笔记列表 返回主界面