Claude Code Skill 与 Sub-Agent 深度解析

用户7511514

发布于 2026-07-09 15:43:59

180

Harry 整理 | 2026-06-07 | 基于官方文档与工程实践验证

一、整体架构：六层模型

Claude Code 的扩展体系由六层组成，各层职责明确：

层级 Layer	Surface / 实现模块	职责定位（中文语义）	📖 详细中文释义 · 到底在做什么？
🧠 上下文层Context Surface	CLAUDE.md + Rules	「始终刻在骨子里的认知」	🌍 是什么？这是Claude的“永久记忆与行为准则”。就像一个人的三观和工作守则，它永远存在于每轮对话的底层，无需每次重复提醒。📌 包含什么？项目宪章、用户偏好、安全红线、禁止行为、风格指南。任何任务开始前，这些规则已经自动注入，确保回答风格和底线一致。💡 简单理解：Claude 天生就知道这些事，不用再问“你该遵守什么规则”。
⚡ 行动层Action Surface	Tools + MCP	「能动手做的事」	🔧 是什么？所有Claude可以调用的外部能力与工具接口。包括计算器、数据库查询、发送HTTP请求、读写文件、调用第三方API等等。🎯 MCP协议让Claude能连接各种微服务，扩展实时动作边界。💡 类比：给你一双手和工具箱，这是Claude“做具体事情”的能力总集。
📚 知识层Knowledge Surface	Skills	「需要时才回忆的专项知识」	🗂️ 是什么？庞大的动态加载知识库，类似“书架上的参考书”。平时不占用注意力，当遇到特定领域问题（金融、医疗、代码库规范）时，Claude会按需检索相关技能文档并注入推理。⚡ 为什么重要？避免长上下文过载，保证主对话轻量，仅在必要时补充深度知识。💡 例子：聊Spring框架时，Claude自动调取Spring技能文档；不问则不加载，非常高效。
🎮 控制层Control Surface	Hooks	「必须严格执行的硬性动作」	⛓️ 是什么？确定性钩子函数，在关键环节强制注入行为（消息发出前、工具调用后）。例如：敏感词过滤、用户输入脱敏、审计日志记录、权限闸门、工作流检查点。🎛️ 作用保证关键动作绝对执行，不依赖模型自由意志，提升安全与合规性。💡 好比电梯的安全制动器：每次关门之前必须校验，无法跳过。
🔒 隔离层Isolation Surface	Sub-Agents	「独立脑子干脏活累活」	🏝️ 是什么？独立的子智能体沙箱环境，与主对话上下文隔离。复杂计算、代码执行、大规模检索、不确定性任务都交给它完成，避免主线程阻塞或污染。🔐 安全收益即使子任务出错或恶意行为也不会影响主会话核心状态。💡 理解：派一个徒弟去做耗时任务，徒弟自己带脑子，完成后只把结果交回师傅。
✅ 验证层Verification	Tests + CI	「怎么证明干得对」	🧪 是什么？自动化测试与持续集成流水线。对Claude的输出、工具调用链、代码生成结果进行自动化验证，确保正确性、鲁棒性和可复现性。🔄 CI机制每次改动都跑一遍测试，防止退化，提供质量报告。💡 就像工厂质检环节：不光生产东西，还要确认每个成品都是合格的。

🧠 六维架构 · 中文详解版 | 上下文层永久生效，行动层提供工具，知识层按需加载，控制层强制执行，隔离层独立运算，验证层确保质量

二、Skill 完整规范

2.1 定义

Skill 是按需加载的 Markdown 文档，通过渐进式披露（Progressive Disclosure）工作：description 始终在上下文里，正文只在触发后加载。

2.2 目录结构

my-skill/                    ← 目录名即 skill 名
├── SKILL.md                 ← 必须: 主入口
├── reference.md             ← 可选: 参考材料（按需读取）
├── examples.md              ← 可选: 示例
└── scripts/                 ← 可选: 辅助脚本（仅执行，不加载为上下文）
    └── helper.py

2.3 安装位置

作用域	路径	适用范围
个人（全局）	~/.claude/skills/<name>/SKILL.md	所有项目
项目级	.claude/skills/<name>/SKILL.md	当前项目
插件	<plugin>/skills/<name>/SKILL.md	随插件启用

2.4 Frontmatter 字段完整参考（16 个字段）

字段	类型	必填	说明
name	string	否	显示名+斜杠命令标识符。不填用目录名。最长64字符，仅小写字母/数字/连字符
description	string	推荐	Skill做什么、何时触发。Claude据此判断自动调用。不填取正文第一段
triggers	string	否	补充触发条件/短语，追加到description后，合计最长1536字符
argument-hint	string	否	自动补全提示参数，如[issue-number]
arguments	string/list	否	命名位置参数，正文中$ARGUMENTS替换
disable-model-invocation	boolean	否	true禁止自动调用，仅手动/name触发
user-invocable	boolean	否	false从/菜单隐藏，仅模型可调用
allowed-tools	string	否	免审核批准的工具列表（空格分隔），不限制范围
disallowed-tools	string/list	否	从此Skill可用工具中移除的工具
model	string	否	Skill运行的模型：haiku/sonnet/opus
effort	string	否	推理投入：low/medium/high/xhigh/max
context	string	否	fork在隔离sub-agent上下文运行
agent	string	否	配合context: fork，指定sub-agent类型
hooks	object	否	绑定到此Skill生命周期的hook（on-activate, on-complete）
paths	string/list	否	Glob模式，限制仅在操作匹配文件时激活
shell	string	否	bash（默认）或powershell

⚠️ allowed-tools 关键理解 Skill 的 allowed-tools 不是白名单（不限制可用工具范围）——是对列出的工具免审核自动批准。未列出的工具仍可调用，但会弹权限提示。对比：Sub-Agent 的 tools 字段 是真正的白名单——不在列表里的工具完全不可用。这是 Skill 和 Sub-Agent 的一个重要设计差异。

# 基本语法（空格分隔）
allowed-tools: Read Grep Glob

# Bash 子命令白名单（推荐）
allowed-tools: Read Write Bash(git *) Bash(npm run *)

# MCP 工具（双下划线格式）
allowed-tools: Read mcp__linear__create_issue mcp__memory__store

2.6 触发机制

方式	配置	场景
自动触发	保持默认	参考型 skill（API约定、代码规范）
手动触发	disable-model-invocation: true	任务型 skill（部署、提交）
路径触发	paths: "*.py"	仅操作匹配文件时激活

Claude 判断触发只依赖 description 和 when_to_use（正文触发前不在上下文里）。

2.7 官方文档

Skills 文档 · Agent Skills 开放标准 · 官方插件仓库示例

三、Sub-Agent 完整规范

3.1 定义

Sub-Agent 是一个独立的 Claude 实例，拥有自己的 200K 上下文窗口、系统 prompt、工具集和权限。与主 Agent 上下文完全隔离，结果仅通过摘要返回。

3.2 目录结构

.claude/agents/
├── code-reviewer.md        # 代码审查专用
├── coder/                  # 目录形式同样支持
│   ├── AGENT.md
│   └── memory/
│       └── MEMORY.md
├── security-auditor.md
└── trd-writer.md

3.3 安装位置

<project>/.claude/agents/<name>.md

3.4 Frontmatter 字段完整参考（15 个字段，其中 2 个必填）

字段	类型	必填	说明
name	string	是	唯一标识符，仅小写字母/数字/连字符，最长64字符
description	string	是	何时派发到此子Agent，最长1024字符
model	string	否	haiku/sonnet/opus/inherit
tools	string[]	否	白名单——Agent仅能使用这些工具。省略则继承全部
disallowedTools	string[]	否	黑名单——Agent可使用除这些外的所有工具
context	string	否	fork（隔离副本）或默认（共享）
maxTurns	number	否	最大回合数，防止死循环
permissionMode	string	否	default/acceptEdits/dontAsk/bypassPermissions/plan
memory	string	否	user/project/local——启用独立持久记忆
skills	string[]	否	启动时预加载到上下文的Skill名称列表
mcpServers	string[]	否	此Agent可用的MCP Server名称
background	boolean	否	true始终作为后台任务运行
color	string	否	UI显示颜色（hex代码）
effort	string	否	low/medium/high
isolation	string	否	唯一有效值worktree——在独立git worktree中运行
agentType	string	否	显式标记格式类型为agent

3.6 Tool 描述来源

AGENT.md 的 tools: 只写工具名字，Harness层统一维护所有工具的定义，MCP工具同理。

3.7 内置 Sub-Agent

名称	用途	特点
Explore	只读代码扫描	不加载CLAUDE.md/GitStatus/Memory，极省token（~3K）
Plan	规划与研究	同上，轻量级
General-purpose	默认通用	继承全部上下文

四、主 Agent 与 Sub-Agent 上下文对比

4.1 主 Agent 上下文组成

组件	~Token消耗	说明
System Prompt	~2,600	核心行为+工具使用规范
工具定义Schema	~17,600	所有工具的参数定义
MCP工具Schema	0~51,000	取决于MCP Server数量
Skill描述列表	~1,000	仅description
~/.claude/CLAUDE.md	~320	个人偏好
./CLAUDE.md	~1,800	项目约定
环境信息	~280	工作目录、OS、Git状态
对话历史	动态增长	工具调用、文件读取
纯净会话合计	~7,850	可用空间约160-170K token

4.2 Sub-Agent 上下文组成

组件	是否继承	说明
自己的System Prompt	✅ 独立	来自AGENT.md body
CLAUDE.md（全局+项目）	✅ 继承	无条件继承
User/Project Memory	✅ 继承	记忆内容继承
Git Status	✅ 继承	父会话git状态
工具集	⚙️ 可配	通过tools/disallowedTools
MCP Servers	⚙️ 可配	通过mcpServers
Skills	⚙️ 可配	预加载
父对话历史	❌ 不继承	完全隔离

内置Agent特殊规则 Explore和Plan故意跳过CLAUDE.md/Git/Memory以保持轻量（~3K token），General-purpose和自定义Agent则全部加载。

五、Plugin 与 MCP

5.1 MCP 配置：mcp.json

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

5.4 Sub-Agent 引用 MCP Tool

推荐方式：mcpServers 字段 — 按Server级别控制，精确且清晰。

5.6 MCP Tool 在主/子/Skill中的行为对比

场景	MCP Tool可用性	控制字段
主Agent	✅ 全部注册的MCP Server	mcp.json
Sub-Agent（自定义）	⚠️ 不可靠（已知bug #30280）	mcpServers或tools
Skill内直接调用	✅ 继承主Agent	allowed-tools 免审核

已知限制绕过方案：主编排器先调MCP拿到结果，再作为文本传入Sub-Agent的prompt。

5.8 Anthropic 官方 MCP Server（7个）

Server	领域	npm包
Everything	参考（演示全部特性）	@modelcontextprotocol/server-everything
Fetch	Web抓取	@modelcontextprotocol/server-fetch
Filesystem	安全文件操作	@modelcontextprotocol/server-filesystem
Git	Git仓库操作	@modelcontextprotocol/server-git
Memory	知识图谱记忆	@modelcontextprotocol/server-memory
Sequential Thinking	分步推理	@modelcontextprotocol/server-sequential-thinking
Time	时间/时区	@modelcontextprotocol/server-time