claude code 使用指南
1. claude code安装
- 命令行配置vpn
export https_proxy=http://127.0.0.1:7897
export http_proxy=http://127.0.0.1:7897
export ALL_PROXY=socks5://127.0.0.1:7897
- 查看是否可以连接 claude.io
# 立即测试
curl -I https://claude.ai
- mac 安装claude code
# 查看详细输出，了解卡在哪里
curl -fsSL https://claude.ai/install.sh | bash -x
# 通过homebrew安装
brew install --cask claude-code
2. claude code交互式会话中三种模式区别
3. claude code 配置三方模型
- minimax coding plan配置： platform.minimaxi.com/docs/token-…
4. claude code 常用交互式命令
5. 技能（skills）介绍
5.1 什么是 skills？
Claude Code 中的 Skills 是什么？
Skills 是一些文件夹形式的指令集，包含脚本和资源，Claude 可以动态加载它们来提升在特定任务上的表现。简单说，就是给 Claude Code 安装"专业技能包"。
它长什么样？
每个 Skill 是一个包含 SKILL.md 文件的目录，以及可选的支持脚本或资源。SKILL.md 文件以 YAML frontmatter 开头，定义了 skill 的名称和描述，后面跟着 Claude 执行时遵循的 Markdown 指令。
放在项目里的路径是 .claude/skills/你的技能名/SKILL.md。
它怎么工作？
启动时，Claude 扫描所有可用的 skill，只读取每个的名称和描述（大约每个 skill 消耗 100 个 token）。当你给 Claude 一个任务时，它会判断是否有匹配的 skill。如果匹配，就加载完整指令；如果不匹配，则什么都不加载，保持 context 干净。
和自定义命令的关系？
自定义命令已经并入 Skills。.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会创建 /deploy 命令，效果一样。你原有的 .claude/commands/ 文件仍然可以用，Skills 额外支持：支持文件目录、控制调用方式的 frontmatter、以及 Claude 自动识别加载等功能。
有哪些来源？
Anthropic 提供了针对常见文档任务（PowerPoint、Excel、Word、PDF）的预置 Skills，你也可以创建自己的自定义 Skills。两者的使用方式相同，Claude 会在任务相关时自动调用它们。
目前社区已有数百个 skills，分布在 claudemarketplace.com、GitHub 和 Anthropic 官方文档中，涵盖 git 工作流、代码审查、测试生成等各种场景。
存放位置
一句话总结： Skills 就是你给 Claude Code 装的"专业插件"，定义好之后，Claude 遇到相关任务会自动激活，省去每次重新解释工作方式的麻烦。
5.2 skills渐进式加载策略
Skills 的核心设计理念就是按需加载、节省 context。整个过程分三个阶段：
阶段一：启动时只加载元数据（~100 tokens）
Claude 启动时扫描所有可用 Skills，只读取每个 Skill 的名称和描述，大约每个 Skill 消耗 100 个 token。这意味着你可以安装很多 Skills，而不会撑满 context window。
阶段二：任务匹配时加载 SKILL.md 主体（<5k tokens）
当用户发出请求，Claude 判断某个 Skill 匹配后，才通过 bash 读取该 SKILL.md 的完整内容，加载到 context 中。不匹配的 Skill 则完全不加载。
阶段三：执行中按需加载支撑文件
当用户询问特定内容时，Claude 读取 SKILL.md，发现其中引用了某个文件（如 finance.md），才去读取那个文件。其他未被引用到的文件（如 sales.md、product.md）则留在文件系统上，不消耗任何 context token。
下面是这三个阶段的可视化：
文件结构如何支撑渐进式加载
官方建议保持 SKILL.md 主体在 500 行以内。超出部分应拆分到独立文件，通过引用链接按需加载。一个典型的 PDF 处理 Skill 目录结构是这样的：
pdf/
├── SKILL.md # 主入口，触发时加载
├── FORMS.md # 表单专项指南，按需加载
├── REFERENCE.md # API 参考，按需加载
├── examples.md # 示例，按需加载
└── scripts/
├── fill_form.py # 直接执行，不占 context
└── validate.py # 直接执行，不占 context
这套基于文件系统的架构让渐进式加载成为可能——Claude 像浏览入职指南一样选择性地读取各章节，只把每个任务真正需要的内容加载进来。
脚本文件的特殊优势
可执行脚本（如 .py 文件）由 Claude 通过 bash 运行，而不是读入 context——脚本提供确定性操作，完全不消耗 context token。这是渐进式加载里很重要的一点：指令靠语言理解，计算靠脚本执行，两者各司其职。
Description 是触发器，不是简介
Skill 的 description 字段是给模型看的触发器（"我什么时候该激活？"），而不是给人看的摘要。写得越精准，Stage 1 的匹配越准确，整个渐进式加载才能正确启动。
5.3 如何自定义一个skills？
5.3.1 skills 目录结构
5.3.2 自定义skills举例说明
以自定义一个code-review skills为例，目录结构如下：
SKILL.md文件
---
name: code-review
description: >
审查代码质量、潜在 bug、性能问题和可维护性。
当用户提交 PR、询问"帮我看看这段代码"、
或提到"代码审查/code review"时自动触发。
argument-hint: "[文件路径或 PR 编号]"
allowed-tools: Read Grep Glob Bash(git *)
effort: medium
---
# Code Review Skill
审查 $ARGUMENTS 的代码质量。
## 审查流程
1. **读取代码**：用 Read 工具读取目标文件
2. **运行 git diff**：了解本次变更范围
3. **对照清单审查**：见 [CHECKLIST.md](CHECKLIST.md)
4. **生成报告**：执行脚本生成结构化上下文
python ${CLAUDE_SKILL_DIR}/scripts/summary.py "$ARGUMENTS"
## 输出格式
按以下结构输出审查结果：
- 🔴 **严重问题**：需要立即修复的 bug 或安全漏洞
- 🟡 **改进建议**：性能、可读性、重构机会
- 🟢 **做得好的地方**：值得肯定的实践
如需参考具体示例，见 [EXAMPLES.md](EXAMPLES.md)。
CHECKLIST.md文件
# 代码审查清单
## 正确性
- [ ] 边界条件是否处理（null、空数组、越界）
- [ ] 异常是否被正确捕获和处理
- [ ] 并发场景是否考虑（竞态条件）
## 安全性
- [ ] 用户输入是否经过校验/转义
- [ ] 敏感信息是否硬编码（密钥、密码）
- [ ] SQL/命令注入风险
## 性能
- [ ] 循环内是否有不必要的 IO 操作
- [ ] N+1 查询问题
- [ ] 大数据集处理是否有分页/流式处理
## 可维护性
- [ ] 函数是否单一职责
- [ ] 变量命名是否清晰
- [ ] 是否有必要的注释（复杂逻辑）
- [ ] 测试覆盖是否充分
EXAMPLES.md文件
# 审查示例
## 示例：发现 N+1 查询
**问题代码：**
for user in users:
orders = db.query(f"SELECT * FROM orders WHERE user_id={user.id}")
**审查意见（🔴 严重）：**
> 循环内执行数据库查询，100 个用户将产生 101 次查询。
> 建议改为 JOIN 或 IN 查询一次性获取所有数据。
**修复方案：**
user_ids = [u.id for u in users]
orders = db.query("SELECT * FROM orders WHERE user_id = ANY(%s)", [user_ids])
---
## 示例：输出格式
## 代码审查报告：src/auth/login.py
🔴 严重问题（1）
- 第 42 行：密码以明文存储，需使用 bcrypt 哈希
🟡 改进建议（2）
- 第 15 行：login() 函数超过 80 行，建议拆分
- 第 67 行：捕获了 Exception 基类，过于宽泛
🟢 做得好（1）
- JWT 过期时间设置合理（24h）
scripts/summary.py脚本
#!/usr/bin/env python3
"""生成代码审查摘要报告 - 收集 git 上下文供 Claude 使用"""
import sys
import subprocess
from pathlib import Path
from datetime import datetime
def run(cmd: list) -> str:
try:
return subprocess.run(cmd, capture_output=True, text=True).stdout.strip()
except Exception:
return ""
def get_git_stats(filepath: str) -> dict:
diff_stat = run(["git", "diff", "HEAD~1", "--stat", "--", filepath])
diff_content = run(["git", "diff", "HEAD~1", "--", filepath])
recent_commits = run(["git", "log", "--oneline", "-5", "--", filepath])
branch = run(["git", "branch", "--show-current"])
return {
"diff_stat": diff_stat or "（无变更或非 git 仓库）",
"diff_content": diff_content[:3000] if diff_content else "（无 diff）",
"recent_commits": recent_commits or "（无提交记录）",
"branch": branch or "unknown",
}
def count_lines(filepath: str) -> int:
try:
p = Path(filepath)
if p.is_file():
return len(p.read_text(encoding="utf-8", errors="ignore").splitlines())
except Exception:
pass
return 0
def main():
target = sys.argv[1] if len(sys.argv) > 1 else "."
stats = get_git_stats(target)
lines = count_lines(target)
print(f"""
╔══════════════════════════════════════╗
║ 代码审查上下文摘要 ║
╚══════════════════════════════════════╝
目标： {target}
总行数： {lines if lines else "（目录）"}
当前分支： {stats['branch']}
审查时间： {datetime.now().strftime('%Y-%m-%d %H:%M')}
── 最近 5 次提交 ──────────────────────
{stats['recent_commits']}
── Git 变更摘要 ────────────────────────
{stats['diff_stat']}
── Diff 内容（前 3000 字符）────────────
{stats['diff_content']}
""")
if __name__ == "__main__":
main()
6. 子代理（subagent）介绍
6.1 subagent简介
什么是 Subagent
Subagent 是处理特定类型任务的专门 AI 助手。每个 Subagent 在自己独立的 context window 中运行，拥有自定义的 system prompt、特定的工具访问权限和独立的权限控制。当 Claude 遇到匹配某个 Subagent 描述的任务时，会将该任务委托给这个 Subagent，后者独立完成工作并返回结果。
内置 Subagent
Claude Code 包含几个内置 Subagent，Claude 会在适当时候自动使用它们，每个都继承父会话的权限并附加工具限制：
- Explore：快速只读 Agent，使用 Haiku 模型，只能用只读工具，专为文件发现和代码搜索优化
- Plan：计划模式下的研究 Agent，只读工具，用于在提出计划前收集代码库上下文
- General-purpose：拥有全部工具的通用 Agent，适合需要探索和修改的复杂多步骤任务
核心价值
Subagent 帮助你：
- 保留主对话 context：把探索和实现过程隔离在单独的 context window 里
- 强制约束：限制 Subagent 可以使用的工具
- 跨项目复用：用户级 Subagent 可在所有项目中使用
- 专业化行为：为特定领域定制专注的 system prompt
- 控制成本：把任务路由到更快更便宜的模型（如 Haiku）
文件结构
Subagent 文件使用 YAML frontmatter 配置，后跟 Markdown 格式的 system prompt：
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
frontmatter 定义 Subagent 的元数据和配置，正文成为指导 Subagent 行为的 system prompt。Subagent 只接收这个 system prompt，不会继承完整的 Claude Code system prompt。
存放位置与优先级
存储位置决定了 Subagent 的适用范围，同名时高优先级覆盖低优先级：
| 位置 | 范围 | 优先级 |
|---|---|---|
| Managed settings | 组织全局 | 1（最高） |
--agents CLI 参数 | 当前会话 | 2 |
.claude/agents/ | 当前项目 | 3 |
~/.claude/agents/ | 所有个人项目 | 4 |
Plugin 的 agents/ 目录 | 插件启用处 | 5（最低） |
Frontmatter 全字段说明
只有 name 和 description 是必填项，其余均为可选：
| 字段 | 说明 |
|---|---|
name | 唯一标识符，小写字母和连字符 |
description | Claude 判断何时委托的依据 |
tools | 允许的工具白名单，省略则继承全部工具 |
disallowedTools | 工具黑名单 |
model | 使用的模型：sonnet/opus/haiku/完整模型ID/inherit |
permissionMode | 权限模式：default/acceptEdits/auto/bypassPermissions/plan |
maxTurns | 最大执行轮次 |
skills | 启动时预加载到 context 的 Skills 列表 |
mcpServers | 该 Subagent 可用的 MCP 服务器 |
memory | 持久化记忆范围：user/project/local |
background | true 表示始终以后台任务运行 |
effort | 推理力度：low/medium/high/max |
isolation | worktree 表示在独立 git worktree 中运行 |
color | 任务列表中的显示颜色 |
hooks | Subagent 生命周期钩子 |
三种调用方式
自然语言调用：在 prompt 中提到 Subagent 名，Claude 决定是否委托：
Use the code-reviewer subagent to review my recent changes
@-mention 调用：保证该 Subagent 运行，不依赖 Claude 的判断：
@"code-reviewer (agent)" look at the auth changes
会话级启动：用 --agent 参数让整个会话都运行在该 Subagent 的 system prompt 下：
claude --agent code-reviewer
前台与后台运行
前台 Subagent：阻塞主对话直到完成，权限提示和询问会透传给用户。
后台 Subagent：并发运行，不阻塞主对话。启动前 Claude Code 会预先请求所有所需的工具权限，运行后自动拒绝未预授权的操作。按 Ctrl+B 可将正在运行的任务切到后台。
持久化记忆
通过 memory 字段可以给 Subagent 一个跨对话存活的持久化目录，用来积累知识（代码库模式、调试经验、架构决策等）：
---
name: code-reviewer
memory: user
---
三种范围对应不同场景：
user：存在~/.claude/agent-memory/<agent-name>/，跨所有项目共用project：存在.claude/agent-memory/<agent-name>/，项目专属，可提交到 gitlocal：存在.claude/agent-memory-local/<agent-name>/，项目专属但不提交 git
6.2 skills 和 subagent 主要区别？
核心机制区别 —— Skill 在主 context 内执行，Subagent 跨越边界在独立 context 中运行再返回摘要。
7. 模型上下文协议（MCP）介绍
7.1 MCP 是什么
MCP（Model Context Protocol）是一个开源标准，用于 AI 与工具的集成。Claude Code 通过 MCP 服务器连接到外部工具、数据库和 API。
一句话：MCP 是给 Claude 装插座的标准，让 Claude 能直接操作 GitHub、数据库、Slack、Figma 等外部系统，而不只是生成代码。
三种连接方式
HTTP 服务器（推荐，适合云端服务）：
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
stdio 服务器（本地进程，适合需要直接系统访问的工具）：
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:pass@host:5432/analytics"
SSE 服务器（已废弃，尽量用 HTTP 替代）：
claude mcp add --transport sse asana https://mcp.asana.com/sse
三个作用域
| 作用域 | 存储位置 | 适合场景 |
|---|---|---|
local（默认） | ~/.claude.json | 个人用、含敏感凭证、仅当前项目 |
project | .mcp.json（提交 git） | 团队共享、项目专属工具 |
user | ~/.claude.json | 个人跨项目复用 |
用 --scope 指定：claude mcp add --scope project ...
三个完整示例
示例一：连接 Sentry 监控错误
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
然后在 Claude Code 里 /mcp 完成 OAuth 认证，之后就可以直接问：
过去 24 小时最常见的错误是什么？
哪次部署引入了这些新错误？
示例二：连接 GitHub 做代码审查
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
认证后：
Review PR #456 并给出改进建议
帮我创建一个 issue，描述刚刚发现的 bug
示例三：查询 PostgreSQL 数据库
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:pass@host:5432/analytics"
配置后可以自然语言查询：
本月总收入是多少？
找出 90 天内没有下单的用户
7.2 MCP如何加入到prompt中？
基本原理
MCP Server 定义的工具，在 Claude Code 调用模型时会通过 Anthropic API 的 tools 字段传递给模型。模型通过读取这些工具的 name、description、input_schema 来决定何时调用哪个工具。
这和你自己用 API 时手动定义 tools 是完全一样的结构：
{
"model": "claude-sonnet-4-6",
"tools": [
{
"name": "mcp__github__create_issue",
"description": "Create a new GitHub issue",
"input_schema": {
"type": "object",
"properties": {
"title": { "type": "string" },
"body": { "type": "string" }
}
}
},
{
"name": "mcp__sentry__get_errors",
"description": "Fetch recent errors from Sentry",
"input_schema": { ... }
}
],
"messages": [...]
}
但有一个关键优化：MCP Tool Search
前面介绍 MCP 时提到过，Claude Code 默认开启了 Tool Search，它改变了"全部放进去"这个行为：
Tool Search 默认启用。MCP 工具会被延迟加载而非在会话开始时全部放入 context，Claude 使用一个搜索工具按需发现相关工具。只有 Claude 实际使用的工具才进入 context。
所以实际行为分两种情况：
关闭 Tool Search（ENABLE_TOOL_SEARCH=false） ： 所有 MCP 工具的完整定义（name + description + input_schema）全部放进 tools 字段，随每次请求发送给模型。
开启 Tool Search（默认） ：
- 会话启动时只加载工具名称列表，不加载完整 schema
- Claude 先用一个内置的
ToolSearch工具搜索相关工具 - 搜到后才把那几个工具的完整定义加载进 context
- 最终只有用到的工具会出现在
tools字段里
为什么这个设计很重要
假设你接了 10 个 MCP Server，总共有 200 个工具。
没有 Tool Search 时，每次请求都要把 200 个工具的完整 schema 塞进 tools 字段，会大量消耗 context window，也拖慢响应速度。
有了 Tool Search，添加更多 MCP 服务器对 context window 的影响极小，Claude 只在任务需要时才搜索并加载相关工具。
MCP 工具的命名规则
工具名不是 MCP Server 定义的原始名，而是 Claude Code 加了命名空间前缀：
mcp__{服务器名}__{工具名}
比如 GitHub MCP Server 里的 create_issue 工具，在 tools 字段里的名字是 mcp__github__create_issue。这也是为什么 Hooks 里 matcher 可以用 mcp__github__.* 来匹配所有 GitHub 相关工具调用。
7.3 MCP Tool Search基本原理
8. 钩子（Hooks）介绍
8.1 Hooks 简介
Hooks 是用户定义的 shell 命令，在 Claude Code 生命周期的特定时间点自动执行。它们提供对 Claude Code 行为的确定性控制，确保某些动作一定会发生，而不是依赖 LLM 来决定是否执行。
简单说：Skill 是给 Claude 看的指令，Hook 是绕过 Claude 直接执行的自动化脚本。
全部 Hook 事件
| 事件 | 触发时机 |
|---|---|
SessionStart | 会话开始或恢复时 |
UserPromptSubmit | 提交 prompt 后、Claude 处理前 |
PreToolUse | 工具调用执行前，可拦截阻止 |
PermissionRequest | 权限对话框出现时 |
PermissionDenied | 工具调用被自动模式分类器拒绝时 |
PostToolUse | 工具调用成功后 |
PostToolUseFailure | 工具调用失败后 |
Notification | Claude Code 发送通知时 |
SubagentStart | Subagent 启动时 |
SubagentStop | Subagent 完成时 |
Stop | Claude 完成响应时 |
StopFailure | 因 API 错误结束时 |
ConfigChange | 配置文件在会话中变更时 |
CwdChanged | 工作目录变更时（如执行 cd） |
FileChanged | 被监视的文件在磁盘上变更时 |
PreCompact / PostCompact | context 压缩前/后 |
SessionEnd | 会话终止时 |
InstructionsLoaded | CLAUDE.md 被加载到 context 时 |
Elicitation / ElicitationResult | MCP server 请求用户输入时/后 |
WorktreeCreate / WorktreeRemove | worktree 创建/删除时 |
TeammateIdle | Agent 团队成员即将空闲时 |
TaskCreated / TaskCompleted | 任务创建/完成时 |
通信方式：输入与输出
Hook 通过 stdin、stdout、stderr 和退出码与 Claude Code 通信。事件触发时，Claude Code 把事件数据以 JSON 格式传给脚本的 stdin，脚本读取数据、完成工作，再通过退出码告诉 Claude Code 下一步怎么做：
- 退出 0：操作继续执行。
UserPromptSubmit和SessionStart事件中，写到 stdout 的内容会被加入 Claude 的 context - 退出 2：操作被阻止。把原因写到 stderr，Claude 收到该反馈后可以调整策略
- 其他退出码：操作继续，stderr 被记录但不展示给 Claude
四种 Hook 类型
type: "command" （最常用）：运行 shell 命令。
type: "prompt" ：不执行脚本，而是把你的 prompt 和 hook 输入数据发给 Claude 模型（默认 Haiku）来做判断，适合需要推理的决策场景。模型只需返回 {"ok": true} 或 {"ok": false, "reason": "..."} 。
type: "agent" ：比 prompt hook 更强，会启动一个 Subagent，它可以读文件、搜索代码、执行命令来核验条件，最后返回相同的 ok/reason 格式。
type: "http" ：把事件数据 POST 到 HTTP 端点，适合接入外部服务或团队共享的审计系统。
配置位置与范围
| 位置 | 范围 | 可共享 |
|---|---|---|
~/.claude/settings.json | 所有个人项目 | 否，仅本机 |
.claude/settings.json | 当前项目 | 是，可提交 git |
.claude/settings.local.json | 当前项目 | 否，被 gitignore |
| 托管策略设置 | 组织全局 | 是，管理员控制 |
Plugin 的 hooks/hooks.json | 插件启用处 | 是，随插件打包 |
| Skill 或 Agent 的 frontmatter | Skill/Agent 活跃期间 | 是，定义在组件文件里 |
典型使用场景
编辑后自动格式化：用 PostToolUse + Edit|Write matcher，每次 Claude 修改文件后自动跑 Prettier。
阻止修改敏感文件：用 PreToolUse hook，检查目标路径是否匹配 .env、package-lock.json 等保护模式，退出码 2 阻止操作并反馈原因给 Claude。
compaction 后重新注入 context：用 SessionStart + compact matcher，把项目规范、当前 sprint 重点等关键信息重新注入。
桌面通知：用 Notification hook，Claude 等待输入时发系统通知，可以放心去干别的事。
自动审批特定权限：用 PermissionRequest hook，对 ExitPlanMode 等固定操作直接返回 {"behavior": "allow"}，省去每次确认。
防止 Stop 死循环：Stop hook 需检查 stop_hook_active 字段，如果为 true 则直接退出 0，避免无限循环。
一个完整示例：阻止 drop table
#!/bin/bash
# .claude/hooks/validate-sql.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -qi "drop table"; then
echo "Blocked: dropping tables is not allowed" >&2
exit 2 # 阻止执行，原因反馈给 Claude
fi
exit 0 # 允许执行
注册到 settings.json：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": ""$CLAUDE_PROJECT_DIR"/.claude/hooks/validate-sql.sh"
}
]
}
]
}
}
PreToolUse hook 在任何权限模式检查之前触发。返回 permissionDecision: "deny" 的 hook 即使在 bypassPermissions 模式下也能阻止工具调用，这让你可以强制执行用户无法通过更改权限模式来绕过的策略。
8.2 hooks调用流程图
9. 插件（plugins）介绍
9.1 Plugins 简介
Plugin 让你把自定义功能打包成可以跨项目、跨团队共享的扩展包。一个 Plugin 可以包含 Skills、Agents、Hooks 和 MCP 服务器。
和直接写 .claude/ 配置的本质区别：Plugin 是为了分发和复用，.claude/ 配置是单项目本地用的。
Plugin vs 独立配置
独立配置（.claude/） | Plugin | |
|---|---|---|
| 技能命名 | /hello | /my-plugin:hello（带命名空间） |
| 适合场景 | 单项目、个人实验 | 团队共享、社区发布 |
| 跨项目复用 | 需要手动复制 | /plugin install 一键安装 |
| 版本管理 | 无 | 支持语义化版本 |
命名空间（如 /my-plugin:hello）是为了防止多个 Plugin 之间的命名冲突。
目录结构
Plugin 的目录结构如下，注意 .claude-plugin/ 里只放 plugin.json，其他目录都在插件根目录下：
my-plugin/
├── .claude-plugin/
│ └── plugin.json # 插件清单（必须）
├── skills/ # Agent Skills
│ └── code-review/
│ └── SKILL.md
├── agents/ # 自定义 Subagent
├── commands/ # 技能（Markdown 文件）
├── hooks/
│ └── hooks.json # Hook 配置
├── .mcp.json # MCP 服务器配置
├── .lsp.json # LSP 语言服务器配置
├── bin/ # 可执行文件，加入 PATH
└── settings.json # 插件启用时的默认设置
plugin.json 清单
{
"name": "my-first-plugin",
"description": "插件描述，显示在插件管理器中",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
name 字段同时也是 Skill 的命名空间前缀。
包含哪些组件
Skills：放在 skills/ 目录，每个 Skill 是一个包含 SKILL.md 的子目录。Claude 根据任务上下文自动调用。
Agents：放在 agents/ 目录，自定义 Subagent 定义。安装 Plugin 后在 /agents 中可见。
Hooks：放在 hooks/hooks.json，格式与 settings.json 里的 hooks 配置完全相同，Plugin 启用时这些 Hook 生效。
MCP 服务器：通过 .mcp.json 配置，Plugin 启用时自动连接对应的 MCP 服务器。
LSP 服务器：通过 .lsp.json 配置，给 Claude 提供实时代码智能（如语言补全、类型检查）。对常见语言如 TypeScript、Python、Rust，建议安装官方预置的 LSP Plugin，只有需要支持尚未覆盖的语言时才自己写。
默认设置：settings.json 支持 agent 字段，可以把 Plugin 里定义的某个 Agent 设为启用时的默认主线程，改变 Claude Code 的默认行为方式。
本地开发与测试
用 --plugin-dir 参数加载本地 Plugin，不需要安装：
claude --plugin-dir ./my-plugin
# 同时加载多个
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
修改后运行 /reload-plugins 热加载，无需重启。如果本地 Plugin 和已安装的 Plugin 同名，本地版本优先。
分发方式
Plugin 通过"marketplace"（本质是一个 Git 仓库）分发。用户用 /plugin marketplace add <org>/<repo> 注册 marketplace，再用 /plugin install <plugin-name>@<marketplace> 安装。提交到 Anthropic 官方 marketplace 可以通过 claude.ai 或 platform.claude.com 的提交表单完成。
和 .claude/ 独立配置的迁移
迁移步骤很简单：创建 Plugin 目录和 plugin.json，把 .claude/commands/、.claude/agents/、.claude/skills/ 直接复制过去，把 settings.json 里的 hooks 配置移到 hooks/hooks.json，然后用 --plugin-dir 测试验证即可。
9.2 plugins从开发到安装使用完整生命周期
10. 记忆系统（Memory）
10.1 两套记忆机制
10.2 记忆文件加载与写入时机
参考文档
- claude code官方参考文档：code.claude.com/docs/zh-CN/…
- claude code rust实现：github.com/ultraworker…
