截至 2026 年，MCP 服务器生态已超过 1200+ 个。本文精选了 9 个开发日常最高频使用的 MCP 服务器，每个都附带安装命令、配置说明和上手示例。

一、GitHub MCP —— 官方版

官方仓库：https://github.com/github/github-mcp-server

GitHub MCP 是 GitHub 官方维护的 MCP 服务器，提供了对 GitHub API 的完整访问能力。它可以创建 Issue、管理 PR、搜索代码、查看仓库信息等——是最值得安装的 MCP 服务器之一。

功能介绍

安装后 Claude Code 可以直接：

• 搜索代码仓库
• 创建和管理 Issue
• 创建、审查和合并 PR
• 列出文件、查看文件内容
• 搜索用户和仓库
• 读取 PR 评论和讨论

安装方式

方式一：远程服务器（推荐，最简单）

GitHub 官方提供了托管的远程 MCP 服务器，无需本地安装：

1
2
3
4

claude mcp add github -s user \
  --transport http \
  -e GITHUB_TOKEN=ghp_your_token_here \
  -- https://api.githubcopilot.com/mcp

方式二：本地 Docker

1
2
3
4
5

claude mcp add github -s user \
  -e GITHUB_TOKEN=ghp_your_token_here \
  -- docker run -i --rm \
    -e GITHUB_TOKEN \
    ghcr.io/github/github-mcp-server

获取 GITHUB_TOKEN

1. 访问 https://github.com/settings/tokens
2. 点击 Generate new token (classic)
3. 勾选以下权限：
   • repo（私有仓库需要）
   • read:org
   • read:user
   • read:project
4. 生成后复制 token 粘贴到上述命令中

试用示例

添加成功后，在 Claude Code 中尝试：

“显示这个仓库的所有 open issues”
“帮我创建一个 Issue，标题为 ‘优化登录页面性能’”
“搜索代码中所有 import requests 的位置”
“列出最新的 5 个 PR”

二、Playwright MCP —— 浏览器自动化

官方仓库：https://github.com/microsoft/playwright-mcp

由 Microsoft 官方维护的 Playwright MCP 服务器，让 Claude Code 能够启动和控制真实浏览器——导航页面、点击元素、填写表单、截图、提取数据、处理登录会话等。

功能介绍

• 启动 Chromium/Firefox/WebKit 浏览器
• 导航到任意 URL
• 点击按钮、链接、输入文本
• 截图和 PDF 导出
• 提取页面数据
• 处理 Cookie 和认证状态
• 跟踪网络请求

安装方式

1
2

# 使用 npx 安装（推荐）
claude mcp add playwright -s user -- npx @playwright/mcp@latest

如果需要指定浏览器路径或其他配置：

1
2
3

claude mcp add playwright -s user \
  -e PLAYWRIGHT_BROWSERS_PATH=/path/to/browsers \
  -- npx @playwright/mcp@latest

首次运行会自动下载浏览器二进制文件。

试用示例

“打开 https://example.com 并截图”
“搜索 ‘Claude Code MCP’ 并将搜索结果保存到文件”
“帮我登录到 https://myapp.com/login（用户名：admin，密码：****）"
“检查这个页面的所有链接是否有效”

三、Filesystem MCP —— 文件系统

官方仓库：https://github.com/modelcontextprotocol/servers

Filesystem 是 Anthropic 官方提供的 MCP 参考服务器，让 Claude Code 获得受限的文件系统访问能力。

功能介绍

• 读取文件内容
• 写入和编辑文件
• 创建目录
• 搜索文件
• 获取文件信息
• 移动和复制文件

安装方式

1
2

# 注意：最后一个参数是允许访问的目录路径
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects

可以指定多个目录：

1
2
3
4

claude mcp add filesystem -s user \
  -- npx -y @modelcontextprotocol/server-filesystem \
    /home/user/projects \
    /home/user/documents

试用示例

“读取 src/main.py 的内容”
“在 docs/ 目录下创建一个 README.md”
“搜索所有包含 ‘TODO’ 的 Python 文件”

安全提示

Filesystem MCP 只能访问配置时指定的目录，超出范围的路径会拒绝访问。这是重要的安全设计。

四、Brave Search MCP —— 网页搜索

官方仓库：https://github.com/modelcontextprotocol/servers

由 Brave 提供的官方 MCP 服务器，让 Claude Code 能够搜索互联网。

功能介绍

• 互联网搜索
• 获取搜索结果的标题、URL、摘要
• 支持本地化搜索

安装方式

需要先获取 Brave Search API Key：

1. 访问 https://brave.com/search/api/
2. 注册免费账户，获取 API Key（免费套餐每月 2000 次查询）

1
2
3

claude mcp add brave-search -s user \
  -e BRAVE_API_KEY=your_api_key_here \
  -- npx -y @modelcontextprotocol/server-brave-search

试用示例

“搜索最新的 Python 3.13 新特性”
“查找关于 Rust 异步编程的最佳实践”
“搜索今天的热门技术新闻”

五、PostgreSQL MCP —— 数据库查询

官方仓库：https://github.com/modelcontextprotocol/servers

让 Claude Code 直接连接到 PostgreSQL 数据库，执行查询、查看表结构、分析数据。

功能介绍

• 执行只读 SQL 查询
• 列出所有表
• 查看表结构（schema）
• 描述数据库整体架构

安装方式

1
2
3

claude mcp add postgres -s user \
  -e DATABASE_URL=postgresql://user:password@localhost:5432/mydb \
  -- npx -y @modelcontextprotocol/server-postgres

DATABASE_URL 格式：

1

postgresql://用户名:密码@主机:端口/数据库名

试用示例

“列出数据库中的所有表”
“显示 users 表的表结构”
“查询最近的 10 条订单记录”
“分析 orders 表的索引情况”

安全提示

PostgreSQL MCP 默认只允许执行 SELECT 查询，禁止写入操作。这是出于安全考虑的设计——你可以放心让 AI 查询生产数据库。

六、Memory MCP —— 持久化记忆

官方仓库：https://github.com/modelcontextprotocol/servers

Memory MCP 为 Claude 提供基于知识图谱的持久化记忆能力。它可以在对话之间保存实体关系和事实信息。

功能介绍

• 创建和读取实体
• 建立实体之间的关系
• 搜索记忆
• 持久化存储对话中的重要信息

安装方式

1
2

claude mcp add memory -s user \
  -- npx -y @modelcontextprotocol/server-memory

默认数据存储在本地 JSON 文件中。你也可以指定存储路径：

1
2
3

claude mcp add memory -s user \
  -e MEMORY_FILE_PATH=/home/user/.claude-memory.json \
  -- npx -y @modelcontextprotocol/server-memory

试用示例

“记住我的项目叫 ProjectX，使用 FastAPI 框架”
“我的 API Key 保存在 ~/.env 中”
“ProjectX 的数据库是 PostgreSQL 15”

七、Slack MCP —— 团队协作

官方仓库：https://github.com/modelcontextprotocol/servers

让 Claude Code 与 Slack 工作区交互——发送消息、查看频道历史、搜索对话。

功能介绍

• 发送消息到频道
• 读取频道历史
• 搜索消息
• 列出频道和成员

安装方式

需要创建 Slack App 并获取 Token：

1. 访问 https://api.slack.com/apps
2. 创建新 App → “From scratch”
3. 添加 OAuth Scopes：channels:history、channels:read、channels:write、chat:write
4. 安装 App 到工作区，获取 Bot Token

1
2
3

claude mcp add slack -s user \
  -e SLACK_BOT_TOKEN=xoxb-your-token-here \
  -- npx -y @modelcontextprotocol/server-slack

试用示例

“在 #general 频道发送一条 Hello”
“显示 #engineering 频道最近的 5 条消息”
“搜索关于 ‘deploy’ 的最近消息”

八、Sequential Thinking MCP —— 结构化推理

官方仓库：https://github.com/modelcontextprotocol/servers

Sequential Thinking MCP 提供了一个结构化的思维方式，帮助 Claude Code 在复杂问题上进行深度推理。它通过”思维链”的方式分解问题。

功能介绍

• 分步骤结构化推理
• 记录和回溯思考过程
• 支持分支探索
• 适用于复杂问题分析

安装方式

1
2

claude mcp add sequential-thinking -s user \
  -- npx -y @modelcontextprotocol/server-sequential-thinking

试用示例

当处理复杂问题时，Claude Code 会自动启用 Sequential Thinking。你可以主动要求：

“请使用 Sequential Thinking 分析这个数据库迁移方案的风险”

九、Sentry MCP —— 错误监控

官方仓库：https://github.com/modelcontextprotocol/servers

让 Claude Code 直接访问 Sentry 错误监控平台的数据。

功能介绍

• 查看最近的错误事件
• 获取错误详情和堆栈跟踪
• 查询 Issue 列表和统计
• 获取性能数据

安装方式

需要 Sentry Auth Token：

1. 访问 https://sentry.io/settings/account/api/auth-tokens/
2. 创建 Token，勾选 event:read 和 issue:read 权限

1
2
3
4

claude mcp add sentry -s user \
  -e SENTRY_AUTH_TOKEN=your_token_here \
  -e SENTRY_ORG=your_org_slug \
  -- npx -y @modelcontextprotocol/server-sentry

试用示例

“显示最近 24 小时的错误事件”
“查看 Issue ID 12345 的详细堆栈信息”
“当前项目的错误率是多少？”

十、安装与使用速查表

一键安装汇总

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 1. GitHub（远程推荐）
claude mcp add github -s user --transport http -e GITHUB_TOKEN=ghp_xxx -- https://api.githubcopilot.com/mcp

# 2. Playwright（浏览器自动化）
claude mcp add playwright -s user -- npx @playwright/mcp@latest

# 3. Filesystem（文件系统）
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /path/to/projects

# 4. Brave Search（网页搜索）
claude mcp add brave-search -s user -e BRAVE_API_KEY=xxx -- npx -y @modelcontextprotocol/server-brave-search

# 5. PostgreSQL（数据库）
claude mcp add postgres -s user -e DATABASE_URL=postgresql://user:pass@localhost:5432/db -- npx -y @modelcontextprotocol/server-postgres

# 6. Memory（持久记忆）
claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory

# 7. Sequential Thinking（结构化推理）
claude mcp add sequential-thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking

验证安装

1
2

# 列出所有已安装的 MCP 服务器
claude mcp list

移除不需要的服务器

1

claude mcp remove <服务器名称>

十一、选型建议

新手入门建议：先安装 GitHub 和 Filesystem 这两个最基础的，用熟了再逐步添加。不要一次加太多，以免增加 Claude Code 的上下文负担。

十二、常见问题

Q: MCP 服务器需要 Node.js 吗？

很多基于 npx 安装的 MCP 服务器需要 Node.js 18+。通过 Docker 运行的则不需要。

Q: 安装后 Claude Code 不调用工具怎么办？

确保用 claude mcp list 确认状态为 connected。如果是 disconnected，重启 Claude Code 或检查环境变量是否正确。

Q: 不同项目可以用不同的 MCP 配置吗？

可以。项目级配置（-s project）会创建 .mcp.json 文件，不同项目可以有各自独立的 MCP 配置。

Q: MCP 服务器会占用大量资源吗？

大部分 MCP 服务器按需启动，空闲时不占用资源。Playwright（浏览器自动化）会比较耗资源，建议按需使用。

Q: 在哪里可以找到更多 MCP 服务器？

• 官方参考：https://github.com/modelcontextprotocol/servers
• MCP 注册中心：https://mcp.so
• Awesome MCP：https://mcpservers.org
• Smithery：https://smithery.ai

总结

本文精选了 9 个在 2026 年最值得安装的 MCP 服务器，覆盖了日常开发的各个方面。从 GitHub 代码管理到 Playwright 浏览器自动化，从文件系统到数据库查询——每个工具都配有完整的安装命令和上手示例。

记住：先装最需要的，用熟了再扩展。GitHub + Filesystem 的组合已经能覆盖大部分日常开发场景。随着你对 Claude Code 的使用深入，再逐步探索更多 MCP 服务器带来的可能性。

一、什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 于 2024 年 11 月推出的开源标准协议，旨在统一 AI 大模型与外部工具、数据源之间的通信方式。你可以把 MCP 理解为 AI 世界的 USB-C 接口——通过一个标准化的协议，让 AI 助手能够直接访问文件系统、数据库、API、浏览器等各种外部资源。

在 Claude Code 中，MCP 是其扩展能力的核心机制。通过连接 MCP 服务器，Claude Code 可以：

• 读取和写入本地文件
• 操作 GitHub 仓库（创建 Issue、PR、代码搜索）
• 查询数据库
• 控制浏览器进行自动化操作
• 调用各种 Web API

MCP 分为三个角色：MCP 主机（如 Claude Code、Claude Desktop）、MCP 客户端（协议客户端）、MCP 服务器（提供具体工具和资源的中间件）。

二、Claude Code 中的 MCP 配置方式

Claude Code 支持多种配置 MCP 服务器的方式，从简单到高级，满足不同场景需求。

2.1 使用 claude mcp 命令（推荐）

这是最简单、最推荐的方式。Claude Code 提供了专门的交互式 CLI 命令来管理 MCP：

1
2
3
4
5
6
7
8
9
10
11

# 查看所有已配置的 MCP 服务器
claude mcp list

# 添加一个新的 MCP 服务器
claude mcp add <服务器名称> [选项] -- <启动命令>

# 移除一个 MCP 服务器
claude mcp remove <服务器名称>

# 交互式 MCP 配置界面
claude mcp

作用域（Scope）选项

MCP 配置有三个作用域层级：

示例：

1
2
3
4
5
6
7
8

# 项目级：仅供当前项目使用
claude mcp add filesystem -s project -- npx -y @modelcontextprotocol/server-filesystem /path/to/project

# 用户级：当前用户的所有项目都可用
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /path/to/project

# 全局级：所有用户和项目都可用
claude mcp add filesystem -s global -- npx -y @modelcontextprotocol/server-filesystem /path

2.2 两种传输方式（Transport）

MCP 服务器可以通过两种方式与 Claude Code 通信：

stdio 传输（本地服务器）

服务器作为子进程运行，通过标准输入/输出通信。适用于运行在本地机器上的工具。

1

claude mcp add myserver -- npx -y @modelcontextprotocol/server-filesystem /path

HTTP 传输（远程服务器）

服务器运行在远程，通过 HTTP/SSE 通信。适用于云服务。

1

claude mcp add myserver --transport http -- https://api.example.com/mcp

2.3 手动编辑配置文件

如果你更喜欢手动编辑，也可以直接修改配置文件。

项目级配置（.mcp.json，放在项目根目录）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

用户级配置（~/.claude/settings.json）：

1
2
3
4
5
6
7
8

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}

三、添加 MCP 服务器的完整流程

3.1 查找可用的 MCP 服务器

• 官方参考服务器：https://github.com/modelcontextprotocol/servers
• MCP 注册中心：https://mcp.so
• Awesome MCP Servers：https://mcpservers.org

3.2 添加一个 MCP 服务器

以添加文件系统服务器为例：

1
2
3
4
5
6
7
8

# Step 1: 确认 Node.js 已安装
node --version

# Step 2: 使用 claude mcp add 命令添加
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects

# Step 3: 验证是否成功
claude mcp list

3.3 添加需要环境变量的服务器

有些 MCP 服务器需要 API Key 等敏感信息，可以通过 -e 或 --env 参数传入：

1

claude mcp add github -s project -e GITHUB_TOKEN=ghp_your_token_here -- npx -y @modelcontextprotocol/server-github

你也可以指定多个环境变量：

1
2
3
4

claude mcp add myserver \
  -e API_KEY=abc123 \
  -e API_BASE=https://api.example.com \
  -- npx -y my-mcp-server

3.4 在对话中使用 MCP 工具

添加成功后，在 Claude Code 的对话中直接描述你的需求即可——Claude Code 会自动调用已安装的 MCP 工具。

例如添加了 GitHub MCP 后，你可以说：

“列出这个仓库最近的 issues”
“帮我创建一个 PR”
“搜索代码中包含 ‘auth’ 的所有文件”

Claude Code 会识别你的意图，自动选择合适的 MCP 工具来执行。

3.5 查看当前连接的 MCP 服务器

1

claude mcp list

这会显示所有已配置的 MCP 服务器及其连接状态。

四、MCP 配置详解

4.1 配置文件结构

.mcp.json 或 settings.json 中的 MCP 配置结构如下：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name", "arg1", "arg2"],
      "env": {
        "KEY": "value"
      },
      "transport": "stdio"
    }
  }
}

4.2 配置文件优先级

Claude Code 按照以下顺序合并配置（后面的覆盖前面的）：

1. 全局配置
2. 用户级配置（~/.claude/settings.json）
3. 项目级配置（./.mcp.json）

五、高级用法

5.1 使用 Docker 运行 MCP 服务器

有些 MCP 服务器推荐使用 Docker 运行：

1
2
3
4
5

claude mcp add github-mcp \
  -e GITHUB_TOKEN=ghp_your_token_here \
  -- docker run -i --rm \
    -e GITHUB_TOKEN \
    ghcr.io/github/github-mcp-server

5.2 通过插件安装 MCP

Claude Code 的插件（plugin）可以自动捆绑 MCP 服务器配置。安装插件后，MCP 服务器会自动配置好，无需手动操作：

1
2

# 安装 Figma 插件（自动配置 Figma MCP）
claude plugins install figma

5.3 修改 MCP 输出 Token 限制

Claude Code 默认在 MCP 工具输出超过 10,000 tokens 时会显示警告。如果需要，可以通过环境变量增加限制：

1

export MAX_MCP_OUTPUT_TOKENS=50000

5.4 动态工具更新

Claude Code 支持 MCP 的 list_changed 通知——MCP 服务器可以动态更新其可用工具、提示和资源，无需你断开重连。

5.5 排查 MCP 连接问题

如果 MCP 服务器连接失败，可以按以下步骤排查：

1. 检查服务器是否安装正确

   1	claude mcp list

2. 检查环境变量是否正确

   1 2	# 手动运行命令测试 npx -y @modelcontextprotocol/server-github

3. 重新启动 Claude Code
   有时需要重启会话才能加载新配置。

4. 检查配置文件语法
   确保 JSON 格式正确，没有多余的逗号。

5. 查看 Node.js 版本

   1	node --version # 需要 Node.js 18+

六、安全和最佳实践

6.1 安全注意事项

• 只添加可信的 MCP 服务器——特别是那些需要网络访问或文件系统权限的服务器
• 谨慎使用全局作用域——只需要在多个项目中使用的工具才设为 global
• 定期审计配置——运行 claude mcp list 检查当前启用了哪些 MCP 服务器
• API Key 安全——使用 -e 参数而不是在配置文件中硬编码密钥

6.2 最佳实践

• 项目级 vs 用户级：团队共享的工具用 project 作用域，个人工具用 user 作用域
• 按需添加：不要一次性添加太多 MCP 服务器，以免增加上下文负担
• 验证可用性：添加后立即测试，确保服务器正常工作
• 定期更新：MCP 服务器生态发展很快，定期检查更新
• 利用 Tool Search：Claude Code 的 Tool Search 功能会自动从已配置的 MCP 服务器中搜索最相关的工具，保持上下文高效

七、总结

MCP 是 Claude Code 扩展能力的关键。通过本文介绍的 claude mcp add 命令和配置文件方式，你可以轻松地将 Claude Code 连接到文件系统、GitHub、数据库、浏览器等各种外部工具。

核心记忆口诀：

• 添加：claude mcp add <名称> [选项] -- <启动命令>
• 查看：claude mcp list
• 移除：claude mcp remove <名称>
• 作用域：project（默认）、user、global
• 传输：stdio（本地）、http（远程）

下一篇文章我将介绍最推荐的 MCP 服务器及其详细的安装步骤和使用手册。

Claude Code Agents（子代理系统）是 Claude Code 的高级特性，允许你定义专用子代理来并行执行子任务。本文从基础概念到高级实战，带你全面掌握多代理协作技术。

目录

1. 什么是 Agents？
2. Agents 的工作原理
3. 前置要求与环境准备
4. 创建你的第一个 Agent
5. Agent 定义详解
6. 实战：项目级 Agent 体系搭建
7. 并行任务编排技巧
8. 调试与优化
9. 常见问题

一、什么是 Agents？

Agents（子代理）是 Claude Code 中的专用子代理系统。你可以为特定任务类型（如代码审查、测试编写、文档生成）定义专门的子代理，每个子代理拥有独立的指令、工具权限和上下文窗口。

核心优势

适用场景

• 大型重构：将代码拆分为多个独立模块并行修改
• 多文件测试：同时为多个组件编写单元测试
• 全栈开发：前端/后端/数据库工作并行进行
• 代码审查：多个 PR 同时审查
• 文档生成：为多个模块同时生成文档

Agents vs Skills vs Hooks

二、Agents 的工作原理

执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

主会话
  │
  ├── @agent-1 "为 UserService 写测试"  ──→ 子代理 1（测试编写）
  │                                          ├─ 读取 UserService 源码
  │                                          ├─ 编写测试用例
  │                                          └─ 返回：已创建 5 个测试文件
  │
  ├── @agent-2 "重构 ProductService"    ──→ 子代理 2（代码重构）
  │                                          ├─ 分析 ProductService
  │                                          ├─ 执行重构
  │                                          └─ 返回：重构完成，通过测试
  │
  └── @agent-3 "更新 API 文档"          ──→ 子代理 3（文档编写）
                                             ├─ 扫描路由定义
                                             ├─ 生成 OpenAPI 文档
                                             └─ 返回：API 文档已更新

通信模型

1
2
3

主会话 ←→ Agent 1    （并行）
主会话 ←→ Agent 2    （并行）
主会话 ←→ Agent 3    （并行）

Agent 之间不直接通信，所有结果汇总到主会话。主会话负责协调和整合。

关键限制

• Agent 数量限制：同时运行的 Agent 数量受 Claude Code 计划限制（通常 3-5 个）
• Agent 无法创建子 Agent（不支持嵌套）
• Agent 的上下文限制是独立的，不计入主会话

三、前置要求与环境准备

版本要求

1
2
3
4
5

# 检查 Claude Code 版本（确保 >= 0.2.0）
claude --version

# 如果版本过低，更新
npm update -g @anthropic-ai/claude-code

目录结构

Agents 定义存储在 .claude/agents/ 目录下：

1
2
3
4
5
6
7
8
9
10
11

项目根目录/
├── .claude/
│   ├── agents/           ← Agents 定义文件夹
│   │   ├── tester.md       ── 测试编写 Agent
│   │   ├── reviewer.md     ── 代码审查 Agent
│   │   ├── refactorer.md   ── 重构 Agent
│   │   └── documenter.md   ── 文档编写 Agent
│   ├── skills/           ← Skills 定义
│   ├── commands/         ← 自定义命令
│   └── rules/            ← 项目规则
└── ...

四、创建你的第一个 Agent

步骤 1：创建 Agents 目录

1

mkdir -p .claude/agents

步骤 2：编写 Agent 定义文件

创建一个代码审查 Agent：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

cat > .claude/agents/reviewer.md << 'EOF'
---
name: Reviewer
description: 专业的代码审查员，擅长发现 bug、安全漏洞和性能问题
---

# Reviewer Agent

你是代码审查专家。你的职责是对代码进行彻底审查。

## 审查流程

1. **理解代码**：先阅读完整文件，理解业务逻辑
2. **逐行检查**：逐行审查代码，关注以下方面：
   - 逻辑错误和边界条件
   - 安全漏洞（SQL 注入、XSS、权限问题等）
   - 性能问题（不必要的循环、内存泄漏等）
   - 代码风格和可读性
   - 测试覆盖度
3. **提供反馈**：按优先级分类输出：

   ### 🔴 严重问题（必须修复）
   ### 🟡 建议优化
   ### ⚪ 次要问题（风格相关）
   ### ✅ 好的实践

## 输出格式要求

使用 Markdown 列表，每个问题附带：
- 文件路径和行号
- 问题描述
- 修复建议（含代码示例）
- 优先级标签

## 禁止行为

- 不要修改代码（只审查）
- 不要添加自己的风格偏好（除非项目规范要求）
- 不要过度审查（只关注实际问题）
EOF

步骤 3：使用 Agent

在主会话中调用：

1
2
3
4
5

# 让审查 Agent 审查某个文件
@reviewer 请审查 src/user-service.ts

# 也可以传递多个文件
@reviewer 请审查 API 层的所有文件

五、Agent 定义详解

完整的 Agent 定义文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

---
name: Agent名称            # 必填，唯一标识，用于 @引用
description: 简短描述      # 必填，帮助 Claude 理解何时使用
model: sonnet             # 可选，指定模型（默认继承主会话）
temperature: 0.3          # 可选，温度参数（0-1）
max_tokens: 4096          # 可选，最大输出 tokens
tools:                    # 可选，限制可用工具
  - Read                # 只读工具（推荐用于审查类 Agent）
  # 完整工具列表见下文
---

# Agent 名称

完整的指令内容...

## 行为规范

定义 Agent 的行为准则...

## 输出格式

定义 Agent 的输出规范...

工具权限配置

Agent 的 tools 字段可以限制其可用的工具集：

工具权限组合示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 只读 Agent（审查员）
tools:
  - Read
  - Search

# 全功能 Agent（开发者）
tools:
  - Read
  - Edit
  - Command
  - Search

# 测试 Agent
tools:
  - Read
  - Edit
  - Command

完整的 Agent 示例合集

测试编写 Agent：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

---
name: Tester
description: 专业测试工程师，擅长编写单元测试和集成测试
tools:
  - Read
  - Edit
  - Command
---

# Tester Agent

你是测试专家。按照以下流程编写测试：

## 测试策略

1. 阅读目标文件，理解其功能和接口
2. 检查已有测试文件，避免重复
3. 编写测试用例，覆盖以下场景：
   - 正常路径（Happy Path）
   - 边界条件（Edge Cases）
   - 错误处理（Error Cases）
4. 运行测试确保通过

## 测试规范

- 使用项目已有的测试框架（Jest/Vitest/Pytest）
- 遵循项目的测试命名规范
- 每个测试函数只测试一个行为
- 使用 Arrange-Act-Assert 模式
- 避免测试实现细节

重构 Agent：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

---
name: Refactorer
description: 代码重构专家，擅长提取函数、优化结构和消除重复
tools:
  - Read
  - Edit
  - Search
  - Command
---

# Refactorer Agent

你是代码重构专家。遵循以下原则：

## 重构原则

1. **不改变功能**：重构前后功能必须完全一致
2. **小步提交**：每次只做一种重构操作
3. **测试保障**：重构前确保有测试覆盖
4. **可逆操作**：每个修改都可以回滚

## 重构流程

1. 分析代码结构，识别重构机会
2. 运行现有测试，确保 baseline
3. 执行重构（每次一步）
4. 运行测试验证
5. 重复直到完成

六、实战：项目级 Agent 体系搭建

场景：全栈 Web 应用功能开发

假设你要实现一个”用户管理”模块的前后端功能。传统方式需要一步步执行，使用 Agents 可以并行加速。

步骤 1：准备 Agent 定义

创建 .claude/agents/ 目录下的 3 个 Agent：

frontend.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

---
name: Frontend
description: 前端开发工程师，擅长 React/Vue 组件开发
tools:
  - Read
  - Edit
  - Search
  - Command
---

# Frontend Agent

你是资深前端工程师。按照以下规范开发：

## 开发规范

- 使用项目已有的组件库和样式系统
- 遵循项目的目录结构约定
- 使用 TypeScript 类型定义
- 添加错误边界和加载状态
- 编写组件的单元测试

## 工作流程

1. 阅读后端 API 定义
2. 创建类型定义文件
3. 实现业务逻辑 hooks/utilities
4. 编写 UI 组件
5. 添加单元测试
6. 确保 TypeScript 编译通过

backend.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

---
name: Backend
description: 后端开发工程师，擅长 API 设计和数据库操作
tools:
  - Read
  - Edit
  - Search
  - Command
---

# Backend Agent

你是资深后端工程师。项目使用 Express.js + Prisma ORM。

## 开发规范

- 遵循 RESTful API 设计原则
- 所有路由使用 try-catch 错误处理
- 使用 Zod 进行请求体验证
- 数据库迁移使用 Prisma Migrate
- 编写集成测试

## 工作流程

1. 定义数据模型和数据库迁移
2. 实现数据访问层（Repository）
3. 实现业务逻辑层（Service）
4. 实现 API 路由（Controller）
5. 添加请求体验证
6. 编写测试

database.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

---
name: Database
description: 数据库管理员，擅长 Schema 设计和数据迁移
tools:
  - Read
  - Edit
  - Command
---

# Database Agent

你是数据库专家。项目使用 PostgreSQL + Prisma。

## 工作规范

- 所有数据模型需要考虑索引优化
- 大表需要设计合适的索引
- 外键关系必须明确定义
- 考虑数据增长和查询性能
- 软删除实现使用 deletedAt 字段

## 工作流程

1. 分析业务需求的数据模型
2. 更新 Prisma Schema
3. 生成迁移文件
4. 编写种子数据
5. 验证迁移可以正常执行

步骤 2：在主会话中并行调度

1
2
3
4
5
6
7

我在项目中需要实现"用户管理"模块，包含基本的 CRUD 功能。

@Database 请定义 User 模型，包含：id、name、email、role（枚举：ADMIN/USER）、status、createdAt、updatedAt、deletedAt。以及角色相关的 Role 模型。

@Backend 请实现用户管理的完整 API：GET /users（分页）、GET /users/:id、POST /users、PUT /users/:id、DELETE /users/:id（软删除）。使用 Express + Prisma，参考 database 的 schema。

@Frontend 请实现用户管理页面：用户列表表格（分页、搜索）、创建用户表单、编辑用户表单、删除确认对话框。等待 backend API 就绪后对接。

步骤 3：整合结果

三个 Agent 并行工作，完成后主会话汇总结果：

1
2
3
4
5

✅ @Database 完成：创建了 User 模型，生成了迁移文件
✅ @Backend 完成：实现了 5 个 API 端点，所有测试通过
✅ @Frontend 完成：创建了 4 个组件，TypeScript 编译通过

下一步：运行端到端测试验证完整功能。

场景：大型代码库重构

1
2
3
4
5
6
7
8
9
10

@Refactorer 请将 utils/helpers.ts 中的工具函数按职责拆分到 utils/ 目录下：
- string-helpers.ts（字符串处理）
- array-helpers.ts（数组处理）
- date-helpers.ts（日期处理）
- validation.ts（验证逻辑）
保留原来的 helpers.ts 作为入口重新导出。

@Tester 请为 utils/ 目录下的所有工具函数编写单元测试。

@Reviewer 重构完成后，审查新的目录结构。完成后运行 `npm test`。

七、并行任务编排技巧

1. 依赖管理

任务之间存在依赖关系时，使用主会话编排：

1
2
3
4
5
6
7
8
9

# 第一步：并行执行独立任务
@Database 定义数据模型
@Backend 准备基础框架

# 第二步（等待第一步完成）：执行依赖任务
@Backend 实现 API（使用已定义的数据模型）

# 第三步（等待第二步完成）：执行依赖任务
@Frontend 实现页面（对接 backend API）

2. 分治法

将大型任务拆分为可并行的小任务：

1
2
3
4
5
6
7

# 不推荐：一个大任务
@Agent 请重构整个项目

# 推荐：拆分为多个并行子任务
@Refactorer 请重构 auth 模块
@Refactorer 请重构 user 模块
@Refactorer 请重构 payment 模块

3. 结果验证

Agent 返回结果后，验证其工作质量：

1

@Reviewer 请审查 @Refactorer 对 auth 模块的重构结果

4. 批量处理模式

1
2
3
4

# 为 5 个组件并行编写测试
@Tester 为 components/Button 编写单元测试
@Tester 为 components/Modal 编写单元测试
@Tester 为 components/Table 编写单元测试

八、调试与优化

监控 Agent 运行状态

1
2
3

# 在 Claude Code 会话中使用
/agents
# 显示所有 Agent 的运行状态和结果

常见问题排查

优化技巧

1. 精确定义描述：description 字段帮助 Claude 判断何时调用 Agent
2. 限制工具集：只读 Agent 不要给 Edit 权限，降低风险
3. 指定输出格式：结构化输出（JSON/YAML）方便主会话处理
4. 设置合理温度：代码任务用 temperature: 0.2-0.3，创意任务用 0.5-0.7

九、常见问题

Q1：Agent 可以调用其他 Agent 吗？

不可以。Agent 不能创建或调用其他 Agent（不支持嵌套）。所有并行 Agent 从主会话触发。

Q2：Agent 运行期间主会话可以做什么？

Agent 在后台异步运行，主会话可以继续工作或发出更多 Agent 请求。所有 Agent 的结果最终回到主会话。

Q3：Agent 之间的上下文会互相干扰吗？

不会。每个 Agent 拥有独立的会话和上下文窗口。一个 Agent 的操作不会影响另一个 Agent 的状态。

Q4：Agent 超出上下文限制怎么办？

每个 Agent 有自己的上下文限制（取决于模型和计划）。如果超出，可以：

• 缩短 Agent 的指令
• 减少 Agent 一次处理的文件数
• 使用更高效的提示词

Q5：如何确保 Agent 的工作一致性？

建立统一的项目规范和约束文件：

1
2
3
4
5
6
7
8
9
10
11
12

# .claude/rules/project-standards.md
# 项目级规则，所有 Agent 都会遵循

## 前端规范
- 使用 Tailwind CSS，不使用内联样式
- 所有组件使用 TypeScript
- 使用 React Query 管理服务端状态

## 后端规范
- 使用 Zod 进行输入验证
- 所有 API 响应统一格式 { success, data, error }
- 使用 Prisma 作为 ORM

Q6：Agent 的 token 消耗如何计算？

Agent 的 token 消耗独立于主会话。每个 Agent 有独立的输入/输出计数。批量使用 Agent 时要注意总 token 消耗。

Q7：如何为不同项目共享 Agent 定义？

1
2
3

# 创建全局 Agent（所有项目可用）
mkdir -p ~/.claude/agents/
ln -s ~/.claude/agents/tester.md .claude/agents/tester.md

总结

Claude Code Agents 是实现并行开发工作流的核心工具。合理运用多代理协作可以显著提升开发效率：

• 单 Agent 模式：适合明确的专业化任务（审查、测试）
• 多 Agent 并行：适合大型功能的模块化开发
• Agent + 主会话编排：适合包含依赖链路的复杂项目

记住最佳实践：精确定义 → 合理拆分 → 验证结果，逐步将你的开发工作流推向新高度。

Claude Code Hooks 是 Claude Code 提供的生命周期脚本机制，允许你在特定时机自动执行自定义脚本。通过 Hooks，你可以实现代码保存时自动格式化、运行前自动检查、任务完成后自动通知等场景，将重复性工作完全自动化。

目录

1. 什么是 Hooks？
2. Hooks 的类型与触发时机
3. 环境配置与前置要求
4. 创建你的第一个 Hook
5. Hook 脚本编写指南
6. 实战案例
7. 调试与排查
8. 安全注意事项
9. 常见问题

一、什么是 Hooks？

Hooks 是 Claude Code 的生命周期回调系统。你可以为特定事件（如文件保存前、任务完成后）注册自定义脚本，Claude Code 会在对应时机自动调用这些脚本。

Hooks vs Skills vs Commands

工作流程示意

1
2
3
4
5
6

用户编辑代码 → 文件保存 → [before_write Hook 触发]
                              ↓ 自动格式化/检查
                 文件写入磁盘 → [after_write Hook 触发]
                              ↓ 自动编译/lint
                 任务完成 → [after_task Hook 触发]
                            ↓ 自动总结/通知

二、Hooks 的类型与触发时机

Claude Code 支持以下 7 种 Hook 类型：

重要：Hook 的执行顺序

1
2
3

任务开始 → before_read → after_read → ... → before_write → 写入
→ after_write → ... → before_command → 执行命令
→ after_command → ... → after_task → 任务完成

三、环境配置与前置要求

系统要求

• Claude Code CLI 已安装（npm install -g @anthropic-ai/claude-code）
• Node.js 18+（部分 Hook 需要）
• Bash/Zsh shell 环境

配置位置

Hooks 配置在 Claude Code 的 settings.local.json 文件中：

• 项目级：<项目根目录>/.claude/settings.local.json
• 全局级：~/.claude/settings.local.json

⚠️ 优先级：项目级配置覆盖全局级配置。settings.local.json 不会被提交到 Git（已添加到 .gitignore），适合存放个人配置。

配置文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "hooks": {
    "before_write": {
      "command": "node scripts/pre-format.js",
      "timeout": 5000,
      "blocking": true,
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"]
    },
    "after_write": {
      "command": "./scripts/lint-check.sh",
      "timeout": 10000,
      "blocking": false
    },
    "before_command": {
      "command": "bash scripts/command-guard.sh",
      "timeout": 3000,
      "blocking": true,
      "exclude_commands": ["git*", "npm*", "pnpm*"]
    },
    "after_task": {
      "command": "node scripts/task-summary.js",
      "timeout": 15000,
      "blocking": false
    }
  }
}

配置字段说明

四、创建你的第一个 Hook

步骤 1：创建配置目录

1
2

# 在项目根目录下创建 .claude 目录
mkdir -p .claude/hooks

步骤 2：编写 Hook 脚本

创建一个通用的格式化 Hook 脚本：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

cat > .claude/hooks/format-code.sh << 'SCRIPT'
#!/bin/bash
# Claude Code Hook: 在写入文件前自动格式化代码
# 用途：保证所有写入代码的格式一致性

FILE_PATH="$1"
FILE_EXT="${FILE_PATH##*.}"

case "$FILE_EXT" in
  js|jsx|ts|tsx)
    npx prettier --write "$FILE_PATH" 2>/dev/null || true
    ;;
  py)
    python -m black --quiet "$FILE_PATH" 2>/dev/null || true
    ;;
  go)
    gofmt -w "$FILE_PATH" 2>/dev/null || true
    ;;
  rs)
    rustfmt "$FILE_PATH" 2>/dev/null || true
    ;;
esac

echo "[Hook] 已格式化: $FILE_PATH"
SCRIPT

chmod +x .claude/hooks/format-code.sh

步骤 3：注册 Hook

创建或编辑 .claude/settings.local.json：

1
2
3
4
5
6
7
8
9
10

{
  "hooks": {
    "before_write": {
      "command": "bash .claude/hooks/format-code.sh \"$CLAUDE_HOOK_FILE\"",
      "timeout": 5000,
      "blocking": true,
      "files": ["*.js", "*.ts", "*.tsx", "*.py", "*.go", "*.rs"]
    }
  }
}

步骤 4：验证 Hook 生效

在 Claude Code 中让 Claude 修改一个代码文件：

1
2
3

# Claude Code 会自动调用 before_write Hook
# 你应该在终端中看到类似输出：
# [Hook] 已格式化: src/app.ts

五、Hook 脚本编写指南

环境变量

Hook 脚本可以访问以下环境变量：

脚本签名规范

1
2
3
4
5
6
7
8
9
10
11
12

#!/bin/bash
# 对于 before_write / after_write：
# 第一个参数通常是文件路径，也可以通过 $CLAUDE_HOOK_FILE 获取

set -euo pipefail  # 推荐：严格模式

# 日志输出（会显示在 Claude Code 终端中）
echo "[Hook:$CLAUDE_HOOK_TYPE] 开始处理 $CLAUDE_HOOK_FILE"

# 你的逻辑...

echo "[Hook:$CLAUDE_HOOK_TYPE] 处理完成"

返回值约定

• 退出码 0：Hook 执行成功，主流程继续
• 退出码非 0（仅在 blocking=true 时）：Hook 执行失败，主流程停止并报错

1
2
3
4
5
6
7

# before_write Hook 返回非 0 会阻止文件写入！
# 适用于：检查到安全问题、格式校验失败等场景

if ! npx eslint "$CLAUDE_HOOK_FILE"; then
  echo "[Hook] ESLint 检查失败，阻止写入"
  exit 1  # ❌ 这会阻止文件保存
fi

超时处理

为所有 Hook 设置合理的超时时间：

六、实战案例

案例 1：Python 项目自动格式化 + 类型检查

.claude/hooks/python-check.sh：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

#!/bin/bash
set -euo pipefail

FILE="$CLAUDE_HOOK_FILE"
if [[ ! "$FILE" =~ \.py$ ]]; then
  exit 0
fi

echo "[Hook] Python 格式化检查: $FILE"

# 第一步：自动格式化
black --quiet "$FILE"

# 第二步：排序 import
isort --quiet "$FILE"

# 第三步：类型检查（非阻塞，仅提示）
mypy "$FILE" --show-error-codes 2>&1 | head -5 || true

echo "[Hook] Python 文件处理完成"

注册配置：

1
2
3
4
5
6
7
8
9
10

{
  "hooks": {
    "before_write": {
      "command": "bash .claude/hooks/python-check.sh",
      "timeout": 10000,
      "blocking": true,
      "files": ["*.py"]
    }
  }
}

案例 2：安全命令守卫

.claude/hooks/command-guard.sh：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

#!/bin/bash
set -euo pipefail

COMMAND="$CLAUDE_HOOK_COMMAND"

# 危险命令列表
DANGEROUS_COMMANDS=(
  "rm -rf /"
  "sudo rm"
  "dd if=/dev/zero"
  "chmod -R 777"
  ">.*/dev/"
  "DROP DATABASE"
  "TRUNCATE TABLE"
  "git push --force"
)

echo "[安全卫士] 检查命令: ${COMMAND:0:100}..."

for pattern in "${DANGEROUS_COMMANDS[@]}"; do
  if echo "$COMMAND" | grep -iqE "$pattern"; then
    echo "[安全卫士] ⚠️  检测到危险命令: $pattern"
    echo "[安全卫士] 操作已阻止！如需执行，请在 Claude Code 中手动确认。"
    exit 1
  fi
done

echo "[安全卫士] 命令安全检查通过 ✓"

案例 3：任务完成自动生成摘要

.claude/hooks/task-summary.sh：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

#!/bin/bash
set -euo pipefail

SUMMARY_FILE="$CLAUDE_PROJECT_ROOT/.claude/task-summary.md"
TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S")

{
  echo "## 任务完成报告 — $TIMESTAMP"
  echo ""
  echo "**项目**: $CLAUDE_PROJECT_ROOT"
  echo "**Hook 类型**: $CLAUDE_HOOK_TYPE"
  echo ""
  echo "### 修改的文件"
  git diff --name-only 2>/dev/null || echo "(未检测到 Git 仓库)"
  echo ""
  echo "---"
  echo ""
} >> "$SUMMARY_FILE"

echo "[Hook] 任务摘要已追加到 $SUMMARY_FILE"

案例 4：TypeScript/React 项目全流程自动化

完整的 .claude/settings.local.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "hooks": {
    "before_write": {
      "command": "bash .claude/hooks/pre-write.sh",
      "timeout": 8000,
      "blocking": true,
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx", "*.css", "*.json"]
    },
    "after_write": {
      "command": "bash .claude/hooks/post-write.sh",
      "timeout": 15000,
      "blocking": false,
      "files": ["*.ts", "*.tsx"]
    },
    "before_command": {
      "command": "bash .claude/hooks/command-guard.sh",
      "timeout": 3000,
      "blocking": true,
      "exclude_commands": ["npm*", "pnpm*", "yarn*", "git status*", "ls*", "cat*"]
    },
    "after_task": {
      "command": "bash .claude/hooks/task-summary.sh",
      "timeout": 5000,
      "blocking": false
    }
  }
}

七、调试与排查

检查 Hook 是否生效

1
2
3
4
5

# 查看当前 Claude Code 配置
claude config list

# 查看 settings.local.json 内容
cat .claude/settings.local.json

查看 Hook 执行日志

Claude Code 会在终端输出 Hook 的执行信息。如果 Hook 出错，你会看到类似：

1
2

[Hook] before_write: ❌ 退出码 1
[Hook] 错误: ESLint 检查失败

常用调试技巧

1. 先跑脚本本身：在终端直接运行 Hook 脚本，确保它独立工作正常

1
2

# 模拟 Hook 环境变量
CLAUDE_HOOK_FILE="src/app.ts" bash .claude/hooks/format-code.sh

2. 逐步减少复杂性：先用一个简单的 echo "Hello" 脚本确认 Hook 机制工作，再替换为真实逻辑

3. 检查路径：Hook 脚本的工作目录是项目根目录，不是脚本所在目录。使用绝对路径或 $CLAUDE_PROJECT_ROOT

4. 日志重定向：将日志写入文件而非仅输出到终端

1
2
3

# 在 Hook 脚本中
exec >> "$CLAUDE_PROJECT_ROOT/.claude/hooks.log" 2>&1
echo "[$(date)] Hook 开始: $CLAUDE_HOOK_TYPE"

常见错误与解决方案

八、安全注意事项

正确做法

• ✅ 使用 files 字段限制 Hook 只作用于特定文件类型
• ✅ 使用 exclude_commands 跳过已知安全的命令
• ✅ 在开发和测试阶段使用 blocking: false
• ✅ 为脚本设置合理的 timeout 值
• ✅ 定期审查 Hook 脚本的内容

错误做法

• ❌ 在 Hook 中执行 rm -rf 等破坏性操作
• ❌ Hook 脚本读取敏感信息（密码、密钥）
• ❌ 设置过长（> 60 秒）的 blocking 超时
• ❌ 跳过错误处理（不使用 set -e）
• ❌ 在生产环境中调试未测试的 Hook

九、常见问题

Q1：Hook 脚本可以访问网络吗？

可以。Hook 脚本可以执行任何 shell 命令，包括网络请求。但建议将网络操作放在 blocking: false 的 Hook 中，避免阻塞主流程。

Q2：多个 Hook 可以同时注册吗？

是的。可以为同一个事件注册多个 Hook，但每个事件只能有一个 command 配置。如果需要执行多个操作，请在脚本内部串联：

1
2
3
4
5

#!/bin/bash
# 在单个 Hook 脚本中执行多个操作
npm run format
npm run lint
npm run test:quick

Q3：如何在不同项目间共享 Hook？

你可以将 Hook 脚本放在 Git 仓库中共享，或者创建一个模板项目：

1
2
3
4
5
6

# 创建 Hook 模板
mkdir -p ~/.claude-templates/hooks/
cp my-hooks/* ~/.claude-templates/hooks/

# 在新项目中引用
ln -s ~/.claude-templates/hooks/ .claude/hooks/

Q4：before_write Hook 修改了文件内容会怎样？

Claude Code 会将你修改后的内容写入磁盘。这意味着 Hook 可以修改即将写入的内容——这是格式化和代码注入的基础机制。

Q5：生产环境 vs 开发环境需要不同的 Hook 配置？

推荐使用 Git 分支或环境变量区分：

1
2
3
4
5
6
7
8
9
10

{
  "hooks": {
    "before_write": {
      "command": "bash .claude/hooks/pre-write.sh --env ${NODE_ENV:-development}",
      "timeout": 10000,
      "blocking": true,
      "files": ["*.ts", "*.tsx"]
    }
  }
}

然后在脚本内根据 $NODE_ENV 执行不同的逻辑。

Q6：Hook 执行失败会影响我正在编辑的代码吗？

• blocking: true：如果 Hook 返回非 0 退出码，会阻止操作进行（如阻止文件写入）。你的代码不会被修改。
• blocking: false：Hook 异步执行，即使失败也不影响主流程。

总结：Hooks 是 Claude Code 中极具威力的自动化工具。通过合理配置 before_write 实现格式化自动化、before_command 提供安全防护、after_task 生成报告总结，你可以大幅减少重复性工作，将精力集中在真正需要创造力的编码任务上。

作者： CaoZH
版本： 2026-06-01
适用平台： macOS / Windows / Linux

Claude Code 是 Anthropic 推出的 AI 编程助手 CLI（命令行界面），它可以直接在你的终端中理解代码、修改文件、运行命令、管理 Git 仓库。本文将详细介绍在 macOS 和 Windows 上安装 Claude Code 的四种方式，以及如何通过 CC Switch 工具管理多套环境配置。

目录

1. 安装前准备
2. 方法一：CLI 命令行安装
3. 方法二：VSCode 插件安装
4. 方法三：JetBrains IDEA 插件安装
5. 方法四：Desktop 桌面版
6. CC Switch：一键切换环境变量
7. 常见问题

一、安装前准备

系统要求

通用前置依赖

无论哪种安装方式，Claude Code 都需要 **Node.js 18+**：

1
2
3
4
5
6
7
8
9
10
11
12

# macOS — 使用 Homebrew
brew install node

# macOS — 使用 nvm（推荐，方便版本管理）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
nvm install 22

# Windows — 使用 winget
winget install OpenJS.NodeJS.LTS

# Windows — 或下载安装包
# 访问 https://nodejs.org/ 下载 LTS 版本

验证安装：

1
2

node --version   # 应输出 v18.x.x 或更高
npm --version

二、方法一：CLI 命令行安装

这是最核心的安装方式。CLI 安装后，其他 IDE 插件都以此为基础运行。

2.1 npm 全局安装（所有平台通用）

1

npm install -g @anthropic-ai/claude-code

安装完成后验证：

1

claude --version

2.2 macOS 专用安装方式

方式 A：npm（推荐）

1

npm install -g @anthropic-ai/claude-code

方式 B：Homebrew

1
2
3
4
5

brew install anthropic/claude-code/claude

# 或通过新式 tap
brew tap anthropic/claude-code
brew install claude-code

方式 C：从官网下载原生安装包
访问 code.claude.com 下载 macOS 的 .dmg 或 .pkg 安装包。

2.3 Windows 专用安装方式

方式 A：npm（推荐）

1

npm install -g @anthropic-ai/claude-code

⚠️ Windows 注意事项：

• 建议以 管理员身份 运行 PowerShell 或 CMD
• 如遇到执行策略限制，先运行：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
• npm 全局包安装后，确保 npm 全局 node_modules 目录在 PATH 中

方式 B：winget（Windows 包管理器）

1

winget install Anthropic.ClaudeCode

方式 C：原生安装包
从 code.claude.com 下载 Windows 安装程序（.exe / .msi），双击安装即可。

2.4 验证安装

1

claude --version

2.5 更新与卸载

1
2
3
4
5
6
7
8
9
10

# 更新 Claude Code
claude update
# 或
claude upgrade

# 查看健康状态
claude doctor

# 卸载（npm 安装方式）
npm uninstall -g @anthropic-ai/claude-code

三、方法二：VSCode 插件安装

3.1 安装步骤

1. 打开 Visual Studio Code
2. 点击左侧活动栏的 扩展 图标（Ctrl+Shift+X / Cmd+Shift+X）
3. 搜索 “Claude Code”
4. 找到官方 Anthropic 发布的扩展（图标为紫色火花 ✨ 或 Anthropic 标志，已发布者验证）
5. 点击 Install

也可以直接访问 VSCode Marketplace：
https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code

3.2 使用方式

安装后，侧边栏会出现一个 火花图标（Spark），点击即可打开 Claude Code 面板：

• Prompt Box（提示框）— 直接在 VSCode 内输入你的需求
• Terminal Mode（终端模式）— 切换到完整终端 REPL
• 参考文件 — 可以 @ 引用当前打开的文件

3.3 VSCode 插件 vs CLI 的切换

你可以在 VSCode 中使用 --code 参数在不同模式间切换：

1
2
3
4
5

# 从 CLI 切换到 VSCode 扩展模式
claude --code

# 在 VSCode 终端中打开 Claude Code
# 直接用 VSCode 内置终端运行 claude 即可

3.4 设置项

VSCode 扩展支持在 settings.json 中配置：

1
2
3
4
5

{
  "claude-code.theme": "dark",
  "claude-code.language": "zh-CN",
  "claude-code.autoOpenTerminal": true
}

3.5 前置条件

VSCode 插件需要系统已安装 Claude Code CLI。如果未安装，插件会提示你先运行 npm install -g @anthropic-ai/claude-code。

四、方法三：JetBrains IDEA 插件安装

Claude Code 官方提供了 JetBrains 系列 IDE 的插件，支持 IntelliJ IDEA、PyCharm、WebStorm、GoLand 等所有 JetBrains IDE。

4.1 安装步骤

方式 A：从 IDE 内安装

1. 打开 IntelliJ IDEA（或其他 JetBrains IDE）
2. 进入 File → Settings → Plugins（Windows/Linux）或 IntelliJ IDEA → Settings → Plugins（macOS）
3. 切换到 Marketplace 标签
4. 搜索 “Claude Code”
5. 找到官方插件「Claude Code [Beta]」，点击 Install
6. 重启 IDE

方式 B：从 JetBrains Marketplace 安装
访问 plugins.jetbrains.com/plugin/27310-claude-code-beta- 在线安装。

4.2 前置条件

⚠️ 重要：JetBrains 插件 仅是一个集成界面，它要求 Claude Code CLI 已单独安装。请先完成第二章的 CLI 安装。

4.3 配置 Claude 命令路径

安装插件后，进入 Settings → Tools → Claude Code 配置 CLI 路径：

• macOS：默认自动识别 /usr/local/bin/claude 或 ~/.npm-global/bin/claude
• Windows：默认自动识别 %APPDATA%\npm\claude 或 %USERPROFILE%\AppData\Roaming\npm\claude
• WSL 用户：需设置为 wsl -d Ubuntu -- bash -lic "claude"（将 Ubuntu 替换为你的 WSL 发行版名称）

4.4 使用方式

• 快捷键：Ctrl+Shift+C（Windows/Linux）或 Cmd+Shift+C（macOS）打开 Claude Code 面板
• 在 JetBrains 内置终端中直接输入 claude 使用
• ESC 键问题：如果 ESC 无法中断 Claude Code 操作，请在插件设置中检查终端兼容性

4.5 自动更新

插件默认启用自动更新，设置路径：Settings → Tools → Claude Code → Enable automatic updates

五、方法四：Desktop 桌面版

Claude Code 也提供了独立的桌面应用程序，适合不想使用终端或 IDE 的用户。

下载方式

访问 code.claude.com：

• macOS：下载 .dmg 安装包
• Windows：下载 .exe 安装程序

桌面版内置了完整的 Claude Code 功能，并提供图形化界面。不过对于编程任务，CLI 和 IDE 插件仍然是更主流的选择。

六、CC Switch：一键切换环境变量

CC Switch 是一个开源的跨平台环境管理工具，专门用于 管理 Claude Code、Codex、Gemini CLI 等多个 AI 编程工具的环境配置。当你需要使用不同的 API 提供商（如官方 API、中转 API、企业代理等）时，不需要手动修改配置文件，一键即可切换。

CC Switch 有两个版本：

6.1 CC Switch Desktop（桌面版）

支持 Windows / macOS / Linux，提供图形化界面。

安装方式：

• macOS：从 GitHub Releases 下载 .dmg，拖入 Applications
• Windows：下载 .exe 或 .msi 安装包，双击安装
• Linux：下载 .AppImage 或 .deb 包

核心功能：

6.2 使用场景示例

场景：在官方 API 和中转 API 之间切换

打开 CC Switch 桌面版，在提供商管理界面中添加你的 API Key 和端点地址，然后一键切换即可。切换后 Claude Code 会自动生效，无需重启。

七、常见问题

Q1：安装后命令行找不到 claude 命令？

macOS：

1
2
3

# 检查 npm 全局安装路径是否在 PATH 中
export PATH="$PATH:$(npm config get prefix)/bin"
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc

Windows：

1
2
3

# 将 npm 全局路径添加到 PATH
$npmPath = "$(npm config get prefix)"
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$npmPath", "User")

Q2：Windows 上使用 WSL 如何安装？

如果你使用 WSL（Windows Subsystem for Linux），直接在 WSL 终端中按 Linux 方式安装：

1
2
3
4
5
6
7
8
9

# 在 WSL 中安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# JetBrains 用户需要在插件设置中指定 WSL 命令路径
# 设置为: wsl -d Ubuntu -- bash -lic "claude"

Q3：VSCode 插件安装后看不到火花图标？

• 确保已安装 Claude Code CLI（第二章）
• 重启 VSCode
• 检查 VSCode 版本是否 ≥ 1.85.0
• 在扩展管理器中确认 Claude Code 扩展已启用

Q4：JetBrains 插件提示找不到 claude？

• 确认 CLI 已安装：在终端运行 claude --version
• 检查插件设置中的 Claude 命令路径是否正确
• WSL 用户按 4.3 节配置 wsl -d ... 格式

Q5：CC Switch 切换后没有生效？

• 切换后需要在新终端会话中启动 Claude Code
• 在 CC Switch 桌面版中确认当前激活的提供商
• 检查提供商 API Key 是否有效

Q6：如何同时使用多个 Claude Code 配置？

• 使用 CC Switch 在不同的提供商之间快速切换
• 直接设置环境变量 ANTHROPIC_API_KEY 手动切换
• 在 CI/CD 环境中，通过设置环境变量来指定不同的 API Key

总结

推荐安装流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 第 1 步：确保有 Node.js
node --version

# 第 2 步：安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 第 3 步：验证
claude --version

# 第 4 步（可选）：安装 IDE 插件
# VSCode: 扩展市场搜索 "Claude Code"
# JetBrains: Settings → Plugins → 搜索 "Claude Code"

# 第 5 步（可选）：安装 CC Switch 桌面版管理多环境
# 访问 https://ccswitch.io 下载桌面版

安装完成后，就可以开始体验 AI 编程助手的强大功能了！建议继续阅读 《Claude Code Skills 使用教程——从入门到进阶》 来进一步了解如何通过技能系统提升效率。

本文首发于 CaoZH 的笔记

作者： CaoZH
版本： 2026-05-31
适用平台： Claude Code CLI / Claude Desktop

目录

1. 什么是 Skills？
2. 内置命令：开箱即用
3. 安装社区技能
4. 编写自己的技能
5. SKILL.md 前端配置详解
6. 技能类型与设计模式
7. 技能存放位置与作用域
8. 实战：一步步创建技能
9. 调试与优化技能
10. 常见问题

一、什么是 Skills？

Skills（技能）是 Claude Code 的能力扩展系统。本质上，它是一个包含 SKILL.md 文件的目录，该文件使用 YAML 前端配置 + Markdown 指令 告诉 Claude 如何完成特定任务。

Skills vs 其他概念

两种技能来源

Skills 有两种来源：

1. 社区安装的技能——通过插件市场安装（如 Superpowers、webapp-testing 等），详见第三章
2. 自己编写的技能——手动创建 SKILL.md 文件放在 ~/.claude/skills/ 下，详见第四章

⚠️ 注意：Claude Code 的 /review、/plan、/compact 等斜杠命令是 CLI 内置功能，不属于 Skills 系统。Slash Commands 是手动调用的，Skills 是基于自然语言自动触发的，两者是不同的机制。

技能的工作机制

当你与 Claude 对话时，它会扫描所有已安装技能的 name 和 description（仅消耗约 100 tokens/技能 的上下文）。当对话内容匹配某个技能的描述时，Claude 会按需加载该技能的完整 SKILL.md 内容。

这意味着：

• ✅ 装几十个技能也几乎不占上下文
• ✅ 只有触发时才加载完整指令
• ✅ 技能之间可以联动和组合

二、内置命令：开箱即用

Claude Code 自带了一套内置的斜杠命令（Slash Commands），安装后直接通过 / 前缀访问。这些是 CLI 内置功能，与 Skills（技能系统）是不同的概念——Skills 是 SKILL.md 文件驱动的自动触发工作流，而这里是手动调用的命令。

内置命令列表

会话与上下文管理

开发与审查

配置与工具

用法示例

1
2
3
4
5
6

# 在 Claude Code 终端中直接输入
/review              # 审查当前更改（注意是 /review 不是 /code-review）
/security-review     # 安全审计
/plan "重构用户模块"  # 先规划再执行
/compact focus on auth  # 压缩上下文，聚焦认证模块
/rewind              # 回退到之前的状态

内置命令无需安装，开箱即用，但注意它们不是 Skills（技能系统）——你不能像覆盖自定义技能那样覆盖它们。想要扩展 Claude Code 的行为，应该通过编写自定义 Skills（见第四章）或自定义 Slash 命令（见第四章）来实现。

三、安装社区技能

Claude Code 使用 Plugin（插件）系统 来分发技能。社区技能托管在 GitHub 仓库中，可以被添加为”市场”（Marketplace）。

3.1 从官方市场安装

Anthropic 官方维护了一个技能市场：

1
2
3
4
5
6

# 第一步：添加市场源
/plugin marketplace add anthropics/skills

# 第二步：安装技能
/plugin install webapp-testing@anthropics-skills
/plugin install frontend-design@anthropics-skills

3.2 从社区仓库安装

1
2
3
4
5
6
7
8
9
10
11
12

# 添加 Superpowers 市场
/plugin marketplace add obra/superpowers

# 安装技能
/plugin install superpowers
/plugin install writing-plans@obra-superpowers

# 添加 Addy Osmani 的工程技能
/plugin marketplace add addyosmani/agent-skills
/plugin install spec-driven-development@addy-agent-skills
/plugin install code-review-and-quality@addy-agent-skills
/plugin install security-hardening@addy-agent-skills

3.3 常用社区市场

3.4 管理已安装的技能

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 查看所有已安装的插件
/plugin list

# 查看所有可用技能
/skills

# 启用/禁用某个技能
/plugin enable superpowers
/plugin disable superpowers

# 移除技能
/plugin remove superpowers

# 移除市场源
/plugin marketplace remove obra/superpowers

3.5 直接从 GitHub 手动安装

你也可以从 GitHub 直接下载技能：

1
2
3
4
5
6

# 克隆技能仓库
git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers

# 或只安装其中某个子技能
mkdir -p ~/.claude/skills/my-tdd
cp superpowers/skills/test-driven-development/SKILL.md ~/.claude/skills/my-tdd/

四、编写自己的技能

这是最强大的部分——为你的团队或项目定制专属技能。

4.1 最简单的技能

创建一个文件 ~/.claude/skills/hello/SKILL.md：

1
2
3
4
5
6
7
8
9
10

---
name: hello
description: |
  一个测试技能。当用户说"你好"或"hello"时触发。
  打印欢迎信息并询问今天的工作内容。
---

# Hello Skill

当用户问候时，热情回应，并询问今天需要做什么。

重启 Claude Code 后，说”你好”就会触发这个技能。

4.2 实用技能示例：Git 提交规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

---
name: git-commit-convention
description: |
  当用户要求提交 Git commit 时使用。
  检查暂存区更改，生成符合 Conventional Commits 格式的提交信息。
  格式: type(scope): description
---

# Git Commit Convention

当需要提交代码时，遵循以下步骤：

1. 运行 `git diff --cached` 查看暂存区更改
2. 根据更改类型确定 commit type：
   - `feat`: 新功能
   - `fix`: Bug 修复
   - `docs`: 文档更改
   - `style`: 代码格式（不影响功能）
   - `refactor`: 重构
   - `test`: 测试相关
   - `chore`: 构建/工具
3. 生成格式: `type(scope): description`

示例：

feat(auth): add OAuth2 login support
fix(parser): handle null input in JSON parser
docs(readme): update installation instructions

1
2
3
4
5
6

```

### 4.3 更复杂的技能：带脚本和引用文件

技能目录可以包含多个文件：

~/.claude/skills/deploy-check/
├── SKILL.md # 核心指令
├── scripts/
│ └── check-health.sh # 健康检查脚本
└── references/
└── deployment-checklist.md # 部署检查清单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

在 `SKILL.md` 中引用这些文件：

```markdown
---
name: deploy-check
description: |
  部署前的全面检查。当用户要求"部署"、"发布"或"deploy"时触发。
  运行健康检查脚本并核对部署清单。
---

# Deployment Pre-flight Check

部署前执行以下步骤：

## 1. 运行健康检查
执行脚本 `{skilldir}/scripts/check-health.sh` 并分析输出。

## 2. 核对部署清单
阅读 `{skilldir}/references/deployment-checklist.md`
逐项确认每个检查点。

## 3. 生成部署报告
汇总检查结果，标记通过/失败的项。

注意： {skilldir} 是 Claude Code 自动注入的变量，指向技能目录的路径。

五、SKILL.md 前端配置详解

YAML 前端配置（Frontmatter）是 SKILL.md 的核心控制区域，位于文件开头的 --- 之间。

全部前端字段

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

---
# === 必需字段 ===
name: my-awesome-skill
description: |
  清晰描述技能做什么以及在何种情况下触发。
  好的描述是技能被正确调用的关键。

# === 触发控制 ===
when_to_use: |
  额外的触发条件说明，补充 description。
  描述越精准，误触发越少。

disable-model-invocation: true
# true: Claude 不会自动触发，只能用户手动 /command 调用
# 适用于破坏性操作或需要用户确认的技能

user-invocable: false
# false: 隐藏斜杠命令，只有 Claude 可以自动触发
# 适用于后台工作流，不需要用户主动调用的技能

# === 权限控制 ===
allowed-tools: "Read, Grep, Bash, Glob"
# 限制技能可使用的工具，用逗号分隔
# 常见值: Read, Grep, Glob, Bash, Write, Edit, Execute
# 默认为全部工具（不设置此字段时）
# 可细化: "Bash(python:*)" 表示只能运行 Python

# === 执行模式 ===
context: fork
# 不设置: 在主线对话中执行（默认）
# fork: 在独立的子代理中执行，隔离上下文
# 适用于长时间运行的任务，不影响主线对话

# === 生命周期钩子 ===
hooks:
  on_skill_start: echo "技能开始执行"
  on_skill_end: echo "技能执行完毕"
  on_error: |
    echo "出错时间: $(date)" >> /tmp/skill-errors.log

# === 其他 ===
model: claude-sonnet-4
# 覆盖当前使用的模型，特定技能用更合适的模型

argument-hint: "<文件名> [选项]"
# 为斜杠命令显示参数提示

version: 1.0.0
author: CaoZH
license: MIT
compatible-with: claude-code, codex, openclaw
---

关键字段详解

description —— 决定技能是否被触发

这是最重要的字段。Claude 在每次对话中只读 name 和 description，如果描述不够精准，技能永远不会被激活。

好的描述：

1
2
3
4

description: |
  处理 PDF 发票：解析发票 PDF，提取行项目，生成对账报告。
  在处理供应商发票或月度结算时使用。
  触发词：'process invoices'、'reconciliation'、'invoice PDF'

差的描述：

1

description: 处理文件

allowed-tools —— 安全沙箱

通过限制工具来防止误操作：

1
2
3
4
5
6
7

# 只读模式：查看文件，不能修改
allowed-tools: "Read, Grep, Glob"

# 只允许执行特定命令
allowed-tools: "Read, Bash(python:*,node:*)"

# 完全开放（不设置此字段即为默认）

context: fork —— 隔离执行

适合以下场景：

• 长时间运行的批量操作：不阻塞主线对话
• 高风险操作：即使子代理崩溃，主线对话不受影响
• 并行任务：多个 skill 可以 fork 后并行执行

hooks —— 自动化钩子

支持三个生命周期事件：

六、技能类型与设计模式

根据功能分类，Claude Code 技能通常有四种设计模式：

6.1 参考型（Reference Skill）

目的：提供知识背景，让 Claude 按特定风格工作。

1
2
3
4
5
6
7
8
9
10
11
12

---
name: react-best-practices
description: |
  React 开发最佳实践。当项目包含 React 代码时自动生效。
---
# React 编码规范

- 使用函数组件和 Hooks，避免 class 组件
- 使用 TypeScript 定义 Props 接口
- 组件文件命名: PascalCase.tsx
- 优先使用 React Query 管理服务端状态
- ...

特点：

• 通常设置 disable-model-invocation: false（自动触发）
• 不定义具体流程，只提供规范
• 触发后 Claude 会自动按规范行事

6.2 工作流型（Workflow Skill）

目的：定义多步骤的执行流程。

1
2
3
4
5
6
7
8
9
10
11
12

---
name: api-endpoint-workflow
description: 当用户要求创建新的 API 端点时使用。
---
# 创建 API 端点流程

1. 定义请求/响应类型（DTO）
2. 编写 Controller/Handler
3. 编写 Service 层逻辑
4. 添加参数验证
5. 编写单元测试
6. 注册路由

特点：

• 步骤明确、顺序执行
• 每个步骤可能有验证条件
• 适合重复性开发任务

6.3 斜杠命令型（Slash Command）

目的：用户主动触发，通常带有参数。

1
2
3
4
5
6
7
8
9
10
11
12
13

---
name: generate-component
user-invocable: true
disable-model-invocation: true
argument-hint: "<组件名> [选项]"
---
# 生成 React 组件

根据参数创建新的 React 组件，包含：
- 组件文件
- 样式文件（CSS Module）
- 测试文件
- Storybook stories

特点：

• disable-model-invocation: true 防止自动触发
• argument-hint 提示用户输入参数
• 适合用户主动调用的工具

6.4 代理型（Agent Skill）

目的：在独立子代理中执行复杂任务。

1
2
3
4
5
6
7
8
9
10
11

---
name: dependency-audit
description: 依赖安全检查。当项目有 package.json 时周期性检查。
context: fork
---
# 依赖审计

在子代理中独立运行：
1. 运行 `npm audit` 或 `pip audit`
2. 分析报告，标记严重漏洞
3. 生成修复建议

特点：

• context: fork 隔离执行
• 适合耗时或计算密集的任务
• 不干扰主对话

七、技能存放位置与作用域

技能可以放在不同的位置，决定其作用范围：

7.1 用户级（全局生效）

1

~/.claude/skills/<skill-name>/SKILL.md

放在此处的技能在所有项目中都可用。

7.2 项目级

1

<project-root>/.claude/skills/<skill-name>/SKILL.md

仅在该项目目录下生效。项目级技能优先级高于用户级。

7.3 团队级（通过 Git 共享）

将技能放在项目仓库中：

1
2
3
4
5
6
7
8