🎉 init: 初始存档

2025-12-12 03:15:49 +08:00
commit 7b89510ffd
17 changed files with 3057 additions and 0 deletions
--- a/guide/01-自定义斜杠命令指南.md
+++ b/guide/01-自定义斜杠命令指南.md
@@ -0,0 +1,303 @@
+# Claude Code 自定义斜杠命令指南
+
+## 概述
+
+斜杠命令允许你将常用的提示定义为 Markdown 文件，Claude Code 可以直接执行这些命令。命令支持项目级和个人级两种范围，并通过目录结构支持命名空间。
+
+**基本语法：**
+```
+/<命令名称> [参数]
+```
+
+## 命令类型与存储位置
+
+| 命令类型 | 存储位置 | 说明 | 在 `/help` 中显示 |
+|---------|----------|------|-------------------|
+| 项目命令 | `.claude/commands/` | 存储在项目仓库中，与团队共享 | `(project)` |
+| 个人命令 | `~/.claude/commands/` | 存储在用户目录，跨所有项目可用 | `(user)` |
+
+> **优先级**：当项目命令和个人命令同名时，**项目命令优先**。
+
+## 快速开始
+
+### 创建项目命令
+
+```bash
+# 创建命令目录
+mkdir -p .claude/commands
+
+# 创建一个简单的优化命令
+echo "分析这段代码的性能问题并提出优化建议：" > .claude/commands/optimize.md
+```
+
+### 创建个人命令
+
+```bash
+# 创建个人命令目录
+mkdir -p ~/.claude/commands
+
+# 创建安全审查命令
+echo "审查这段代码的安全漏洞：" > ~/.claude/commands/security-review.md
+```
+
+## Frontmatter 配置
+
+在命令文件开头使用 YAML frontmatter 来配置命令行为：
+
+```yaml
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+argument-hint: [message]
+description: 创建一个 git 提交
+model: claude-3-5-haiku-20241022
+disable-model-invocation: false
+---
+
+命令内容在这里
+```
+
+### 配置参数说明
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `allowed-tools` | 命令可使用的工具列表 | 继承自当前对话 |
+| `argument-hint` | 参数提示信息（显示在自动补全中） | 无 |
+| `description` | 命令的简短描述 | 提示内容的第一行 |
+| `model` | 指定使用的模型 | 继承自当前对话 |
+| `disable-model-invocation` | 是否禁止 SlashCommand 工具调用此命令 | false |
+
+## 参数用法
+
+### 获取所有参数：`$ARGUMENTS`
+
+```markdown
+# .claude/commands/fix-issue.md
+修复问题 #$ARGUMENTS，遵循我们的编码规范
+```
+
+**使用方式：**
+```
+> /fix-issue 123 high-priority
+# $ARGUMENTS 会被替换为: "123 high-priority"
+```
+
+### 获取单个参数：`$1`, `$2`, `$3` ...
+
+```markdown
+# .claude/commands/review-pr.md
+审查 PR #$1，优先级为 $2，分配给 $3
+```
+
+**使用方式：**
+```
+> /review-pr 456 high alice
+# $1 = "456", $2 = "high", $3 = "alice"
+```
+
+## 高级功能
+
+### 文件引用
+
+使用 `@` 前缀引用项目文件：
+
+```markdown
+# 引用单个文件
+审查 @src/utils/helpers.js 的实现
+
+# 引用多个文件
+比较 @src/old-version.js 和 @src/new-version.js
+```
+
+### 执行 Bash 命令
+
+使用 `` !`command` `` 语法执行 bash 命令并将结果嵌入：
+
+```markdown
+---
+allowed-tools: Bash(git add:*), Bash(git status:*)
+---
+
+当前状态: !`git status`
+变更内容: !`git diff`
+```
+
+> **注意**：使用 Bash 命令嵌入时，必须在 `allowed-tools` 中包含 `Bash` 工具。
+
+### 命名空间（子目录组织）
+
+通过子目录组织命令，形成命名空间：
+
+```
+.claude/commands/
+├── frontend/
+│   └── component.md      # /component (project:frontend)
+├── backend/
+│   └── api.md            # /api (project:backend)
+└── optimize.md           # /optimize (project)
+```
+
+### 扩展思考
+
+斜杠命令可以通过在命令内容中包含扩展思考关键词来触发 Claude 的扩展思考模式。
+
+## 插件命令
+
+插件可以提供自定义斜杠命令：
+
+- **格式**：`/plugin-name:command-name`（如无冲突，前缀可省略）
+- **位置**：插件根目录的 `commands/` 目录
+- **功能**：支持所有命令特性（参数、frontmatter、bash、文件引用）
+
+## MCP 斜杠命令
+
+MCP 服务器可以将 prompts 暴露为斜杠命令：
+
+```
+/mcp__<server-name>__<prompt-name> [arguments]
+```
+
+### 示例
+
+```bash
+/mcp__github__list_prs
+/mcp__github__pr_review 456
+/mcp__jira__create_issue "Bug title" high
+```
+
+使用 `/mcp` 命令可以：
+- 查看已配置的 MCP 服务器
+- 检查连接状态
+- 进行 OAuth 服务器认证
+- 查看可用的工具和 prompts
+
+## SlashCommand 工具集成
+
+Claude 可以通过 `SlashCommand` 工具程序化地执行自定义斜杠命令。
+
+### 支持的命令
+
+- 仅支持自定义用户定义命令（不支持内置命令如 `/compact`）
+- 必须在 frontmatter 中填写 `description` 字段
+
+### 禁用 SlashCommand 工具
+
+```bash
+/permissions
+# 在拒绝规则中添加: SlashCommand
+```
+
+### 禁用特定命令被工具调用
+
+在命令 frontmatter 中添加：
+
+```markdown
+---
+disable-model-invocation: true
+---
+```
+
+### 权限规则
+
+```
+SlashCommand:/commit          # 精确匹配（无参数）
+SlashCommand:/review-pr:*     # 前缀匹配（带任意参数）
+```
+
+### 字符预算
+
+- **默认限制**：15,000 字符
+- **自定义限制**：通过 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量设置
+- 用于防止可用命令过多时的 token 溢出
+
+## 实用示例
+
+### 示例1：Git 提交命令
+
+```markdown
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+argument-hint: [提交信息]
+description: 创建 git 提交
+---
+
+## 上下文
+
+- 当前 git 状态: !`git status`
+- 当前变更 (暂存和未暂存): !`git diff HEAD`
+- 当前分支: !`git branch --show-current`
+- 最近提交: !`git log --oneline -10`
+
+## 任务
+
+根据以上变更，创建一个 git 提交，提交信息为: $ARGUMENTS
+```
+
+### 示例2：代码审查命令
+
+```markdown
+---
+argument-hint: [pr编号] [优先级] [负责人]
+description: 审查 Pull Request
+---
+
+审查 PR #$1，优先级为 $2，分配给 $3。
+重点关注：安全性、性能和代码风格。
+```
+
+### 示例3：性能分析命令
+
+```markdown
+---
+description: 分析代码性能问题
+---
+
+分析这段代码的性能问题并提出优化建议：
+- 识别性能瓶颈
+- 建议算法改进方案
+- 推荐缓存策略
+- 识别不必要的计算
+```
+
+### 示例4：生成测试命令
+
+```markdown
+---
+description: 为函数生成单元测试
+argument-hint: [文件路径]
+---
+
+为 @$ARGUMENTS 中的函数生成完整的单元测试：
+- 覆盖正常情况
+- 覆盖边界情况
+- 覆盖错误处理
+- 使用项目现有的测试框架
+```
+
+## 斜杠命令与技能的区别
+
+| 方面 | 斜杠命令 | Agent Skills |
+|------|----------|--------------|
+| **调用方式** | 用户显式调用（`/command`） | 模型自动调用 |
+| **发现机制** | 基于 `/` 前缀 | 基于 description |
+| **复杂度** | 简单提示 | 复杂能力包 |
+| **文件结构** | 单个 .md 文件 | 目录 + SKILL.md + 资源 |
+| **适用场景** | 快速重复任务 | 扩展 Claude 能力 |
+
+**选择建议**：
+- 使用**斜杠命令**：快速、常用的提示（review、explain、optimize）
+- 使用 **Skills**：包含脚本、跨文件知识、团队标准化的综合工作流
+
+## 最佳实践
+
+1. **命名清晰**：使用简短、有意义的命令名称
+2. **提供描述**：始终在 frontmatter 中添加 `description`
+3. **限制工具**：仅授予命令必需的工具权限
+4. **参数提示**：使用 `argument-hint` 帮助用户理解参数用法
+5. **组织结构**：使用子目录为相关命令分组
+
+## 相关资源
+
+- [Skills 技能指南](./02-技能指南.md)
+- [Plugins 插件指南](./03-插件指南.md)
+- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
+- [官方文档：斜杠命令](https://code.claude.com/docs/en/slash-commands)
--- a/guide/02-技能指南.md
+++ b/guide/02-技能指南.md
@@ -0,0 +1,457 @@
+# Claude Code 技能（Skills）指南
+
+## 概述
+
+Agent Skills（技能）是模块化的能力包，用于扩展 Claude 的功能。与斜杠命令不同，技能是由 Claude 根据用户请求**自动激活**的，而非用户显式调用。
+
+### 核心特性
+
+- **模型调用**：Claude 根据任务上下文自主决定何时使用技能
+- **可发现性**：Claude 通过技能的 description 了解何时使用
+- **可共享**：通过 git 或插件在团队间分发
+- **可组合**：多个技能可以协同处理复杂任务
+
+## 技能存储位置
+
+| 类型 | 位置 | 适用场景 |
+|------|------|----------|
+| 个人技能 | `~/.claude/skills/` | 个人工作流、实验性技能、跨所有项目可用 |
+| 项目技能 | `.claude/skills/` | 团队工作流、项目特定专业知识、通过 git 自动共享 |
+| 插件技能 | 插件 `skills/` 目录 | 通过插件安装自动可用 |
+
+## 技能文件结构
+
+### 基本结构
+
+每个技能是一个包含 `SKILL.md` 文件的目录：
+
+```
+my-skill/
+├── SKILL.md           # 必需：技能定义文件
+├── FORMS.md           # 可选：专题文档
+├── REFERENCE.md       # 可选：API 参考
+└── scripts/           # 可选：辅助脚本
+    └── helper.py
+```
+
+### SKILL.md 文件格式
+
+```yaml
+---
+name: your-skill-name
+description: 简要描述技能的功能和使用场景。当用户需要...时使用。
+allowed-tools: Read, Grep, Glob    # 可选：限制可用工具
+---
+
+# 技能名称
+
+## 说明
+提供清晰的分步指导。
+
+## 示例
+展示具体的使用示例。
+```
+
+### 字段要求
+
+| 字段 | 要求 | 限制 |
+|------|------|------|
+| `name` | 必需 | 小写字母、数字和连字符，最多 64 字符 |
+| `description` | 必需 | 描述功能和使用时机，最多 1024 字符 |
+| `allowed-tools` | 可选 | 逗号分隔的工具列表，限制技能可使用的工具 |
+
+## Description 编写指南
+
+> **关键原则**：`description` 是技能的**主要发现机制**，Claude 根据它决定何时使用技能。
+
+### 必须包含的内容
+
+1. **技能做什么** - 核心功能描述
+2. **什么时候使用它** - 明确的触发条件
+3. **用户可能提到的关键词** - 帮助匹配用户请求
+
+### 示例对比
+
+❌ **太模糊**：
+```yaml
+description: Helps with documents
+```
+
+✅ **具体明确**：
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+✅ **另一个好例子**：
+```yaml
+description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
+```
+
+## 渐进式披露
+
+技能使用渐进式披露来高效管理上下文：
+
+- **SKILL.md** 仅在技能被触发时加载
+- **附加文件**（如 FORMS.md、REFERENCE.md）仅在 Claude 需要时按需加载
+
+这意味着你可以在技能目录中包含大量参考资料，而不会浪费上下文空间。
+
+## 快速开始
+
+### 创建个人技能
+
+```bash
+# 创建技能目录
+mkdir -p ~/.claude/skills/commit-helper
+
+# 创建 SKILL.md 文件
+cat > ~/.claude/skills/commit-helper/SKILL.md << 'EOF'
+---
+name: commit-helper
+description: 从 git diff 生成清晰的提交信息。当编写提交信息或审查暂存变更时使用。
+---
+
+# 提交信息生成器
+
+## 说明
+
+1. 运行 `git diff --staged` 查看变更
+2. 我会建议一个提交信息，包含：
+   - 50 字符以内的摘要
+   - 详细描述
+   - 受影响的组件
+
+## 最佳实践
+
+- 使用现在时态
+- 说明"做了什么"和"为什么"，而非"怎么做"
+EOF
+```
+
+### 创建项目技能
+
+```bash
+# 创建项目技能目录
+mkdir -p .claude/skills/code-reviewer
+
+# 创建 SKILL.md 文件
+cat > .claude/skills/code-reviewer/SKILL.md << 'EOF'
+---
+name: code-reviewer
+description: 审查代码的最佳实践和潜在问题。当审查代码、检查 PR 或分析代码质量时使用。
+allowed-tools: Read, Grep, Glob
+---
+
+# 代码审查器
+
+## 审查清单
+
+1. 代码组织和结构
+2. 错误处理
+3. 性能考虑
+4. 安全隐患
+5. 测试覆盖率
+
+## 说明
+
+1. 使用 Read 工具查看目标文件
+2. 使用 Grep 搜索模式
+3. 使用 Glob 查找相关文件
+4. 提供详细的代码质量反馈
+EOF
+```
+
+## 技能工作原理
+
+### 自动发现机制
+
+Claude 自动发现三个位置的技能：
+- `~/.claude/skills/`（个人）
+- `.claude/skills/`（项目）
+- 已安装插件的技能目录
+
+### 查看可用技能
+
+```
+有哪些可用的技能？
+```
+或
+```
+列出所有可用的技能
+```
+
+### 智能激活
+
+技能通过 description 匹配自动激活：
+
+```
+# 用户请求
+帮我从这个 PDF 中提取文本
+
+# Claude 自动激活匹配的技能（如 pdf-processing 技能）
+```
+
+## 工具限制
+
+使用 `allowed-tools` 限制技能可以使用的工具：
+
+```yaml
+---
+name: safe-file-reader
+description: 只读方式访问文件。当需要只读文件访问且不进行修改时使用。
+allowed-tools: Read, Grep, Glob
+---
+```
+
+**适用场景**：
+- 只读技能（不应修改文件）
+- 限定范围技能（仅数据分析，不写文件）
+- 安全敏感工作流
+
+## 实用示例
+
+### 示例1：简单技能（单文件）
+
+```yaml
+---
+name: api-documenter
+description: 为 API 端点生成文档。当需要记录 REST API、GraphQL 接口或函数签名时使用。
+---
+
+# API 文档生成器
+
+## 说明
+
+1. 分析代码中的 API 端点
+2. 生成包含以下内容的文档：
+   - 端点路径和方法
+   - 请求参数
+   - 响应格式
+   - 示例请求
+
+## 文档格式
+
+使用 OpenAPI 3.0 规范格式。
+```
+
+### 示例2：带工具限制的技能
+
+```yaml
+---
+name: safe-file-reader
+description: 只读方式访问文件。当需要只读文件访问且不进行修改时使用。
+allowed-tools: Read, Grep, Glob
+---
+
+# 安全文件读取器
+
+## 说明
+
+此技能仅使用只读工具：
+- Read：读取文件内容
+- Grep：搜索文件内容
+- Glob：查找文件
+
+## 使用场景
+
+- 代码审查（不修改）
+- 日志分析
+- 配置检查
+```
+
+### 示例3：多文件技能
+
+**目录结构：**
+```
+pdf-processing/
+├── SKILL.md
+├── FORMS.md
+├── REFERENCE.md
+└── scripts/
+    ├── fill_form.py
+    └── validate.py
+```
+
+**SKILL.md：**
+```yaml
+---
+name: pdf-processing
+description: 提取文本、填写表单、合并 PDF。当处理 PDF 文件、表单或文档提取时使用。需要 pypdf 和 pdfplumber 包。
+---
+
+# PDF 处理
+
+## 快速开始
+
+提取文本：
+```python
+import pdfplumber
+with pdfplumber.open("doc.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+表单填写请参阅 [FORMS.md](FORMS.md)。
+详细 API 参考请参阅 [REFERENCE.md](REFERENCE.md)。
+
+## 依赖
+
+```bash
+pip install pypdf pdfplumber
+```
+```
+
+### 示例4：数据库操作技能
+
+```yaml
+---
+name: db-migration-helper
+description: 帮助创建和管理数据库迁移。当需要创建迁移脚本、修改数据库架构或执行数据迁移时使用。
+---
+
+# 数据库迁移助手
+
+## 支持的数据库
+
+- PostgreSQL
+- MySQL
+- SQLite
+
+## 迁移流程
+
+1. 分析当前架构
+2. 生成迁移脚本
+3. 验证迁移安全性
+4. 提供回滚方案
+
+## 最佳实践
+
+- 始终创建回滚脚本
+- 在测试环境先验证
+- 大表修改分批进行
+```
+
+## 团队共享技能
+
+### 方式1：通过 Git（项目技能）
+
+```bash
+# 添加到项目
+mkdir -p .claude/skills/team-skill
+# 创建 SKILL.md...
+
+# 提交到仓库
+git add .claude/skills/
+git commit -m "添加团队技能"
+git push
+
+# 团队成员拉取后自动可用
+git pull
+claude  # 技能立即可用
+```
+
+### 方式2：通过插件（推荐）
+
+1. 创建包含 `skills/` 目录的插件
+2. 将插件添加到市场
+3. 团队成员安装插件即可使用
+
+## 管理技能
+
+### 更新技能
+
+```bash
+# 编辑 SKILL.md
+code ~/.claude/skills/my-skill/SKILL.md
+
+# 重启 Claude Code 使更改生效
+```
+
+### 删除技能
+
+```bash
+# 删除个人技能
+rm -rf ~/.claude/skills/my-skill
+
+# 删除项目技能
+rm -rf .claude/skills/my-skill
+git commit -m "移除不再使用的技能"
+```
+
+## 故障排除
+
+### Claude 没有使用我的技能
+
+**检查1：Description 是否足够具体**
+- 包含 WHAT（做什么）和 WHEN（何时使用）
+- 使用用户可能提到的具体关键词
+- 避免模糊描述
+
+**检查2：YAML 语法是否有效**
+```bash
+# 查看 frontmatter
+cat .claude/skills/my-skill/SKILL.md | head -n 15
+
+# 常见问题：
+# - 缺少开头/结尾的 ---
+# - 使用 Tab 而非空格
+# - 特殊字符未加引号
+```
+
+**检查3：文件路径是否正确**
+```bash
+# 个人技能
+ls ~/.claude/skills/*/SKILL.md
+
+# 项目技能
+ls .claude/skills/*/SKILL.md
+```
+
+**检查4：使用调试模式**
+```bash
+claude --debug
+```
+
+### 技能执行出错
+
+- 检查依赖项是否已安装
+- 确保脚本有执行权限：`chmod +x scripts/*.py`
+- 使用正斜杠路径：`scripts/helper.py` ✅（而非 `scripts\helper.py` ❌）
+
+## 技能与斜杠命令的区别
+
+| 方面 | Agent Skills | 斜杠命令 |
+|------|--------------|----------|
+| **调用方式** | 模型自动调用 | 用户显式调用（`/command`） |
+| **发现机制** | 基于 description | 基于 `/` 前缀 |
+| **复杂度** | 复杂能力包 | 简单提示 |
+| **文件结构** | 目录 + SKILL.md + 资源 | 单个 .md 文件 |
+| **适用场景** | 扩展 Claude 能力 | 快速重复任务 |
+
+**选择建议**：
+- 使用**斜杠命令**：快速、常用的提示（review、explain、optimize）
+- 使用 **Skills**：包含脚本、跨文件知识、团队标准化的综合工作流
+
+## 最佳实践
+
+| 实践 | 说明 |
+|------|------|
+| **保持专注** | 一个技能解决一个能力（如"PDF 表单填充"而非"文档处理"） |
+| **清晰描述** | 包含具体触发条件，如"当处理 Excel 文件、电子表格时使用" |
+| **测试验证** | 技能是否在预期情况下激活？说明是否清晰？ |
+| **版本记录** | 在 SKILL.md 中记录版本历史 |
+
+```markdown
+# 我的技能
+
+## 版本历史
+- v2.0.0 (2025-10-01): 重大 API 变更
+- v1.1.0 (2025-09-15): 添加新功能
+- v1.0.0 (2025-09-01): 初始版本
+```
+
+## 相关资源
+
+- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
+- [Plugins 插件指南](./03-插件指南.md)
+- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
+- [官方文档：Agent Skills](https://code.claude.com/docs/en/skills)
--- a/guide/03-插件指南.md
+++ b/guide/03-插件指南.md
@@ -0,0 +1,436 @@
+# Claude Code 插件（Plugins）指南
+
+## 概述
+
+插件是 Claude Code 的扩展功能系统，允许用户通过自定义命令、代理、钩子、技能和 MCP 服务器来扩展平台功能。插件可以在项目和团队之间共享，是分发 Claude Code 扩展的标准方式。
+
+## 插件目录结构
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json          # 必需：插件元数据
+├── commands/                 # 可选：自定义斜杠命令
+│   └── hello.md
+├── agents/                   # 可选：自定义代理
+│   └── helper.md
+├── skills/                   # 可选：Agent Skills
+│   └── my-skill/
+│       └── SKILL.md
+├── hooks/                    # 可选：事件处理器
+│   └── hooks.json
+└── .mcp.json                 # 可选：MCP 服务器配置
+```
+
+## 插件组件说明
+
+| 组件 | 功能 | 位置 |
+|------|------|------|
+| **Commands** | 自定义斜杠命令 | `commands/*.md` |
+| **Agents** | 专门的代理（显示在 `/agents`） | `agents/*.md` |
+| **Skills** | 扩展 Claude 能力（模型自动调用） | `skills/skill-name/SKILL.md` |
+| **Hooks** | 事件处理和自动化 | `hooks/hooks.json` |
+| **MCP** | 外部工具集成 | `.mcp.json` |
+
+## 快速开始：创建第一个插件
+
+### 步骤1：创建目录结构
+
+```bash
+# 创建插件目录
+mkdir -p my-first-plugin/.claude-plugin
+mkdir -p my-first-plugin/commands
+mkdir -p my-first-plugin/skills/greeting-skill
+```
+
+### 步骤2：创建插件清单
+
+```bash
+cat > my-first-plugin/.claude-plugin/plugin.json << 'EOF'
+{
+  "name": "my-first-plugin",
+  "description": "一个简单的问候插件，用于学习基础知识",
+  "version": "1.0.0",
+  "author": {
+    "name": "你的名字"
+  }
+}
+EOF
+```
+
+### 步骤3：添加自定义命令
+
+```bash
+cat > my-first-plugin/commands/hello.md << 'EOF'
+---
+description: 用个性化消息问候用户
+argument-hint: [用户名]
+---
+
+# 问候命令
+
+热情地问候用户 $ARGUMENTS，并询问今天有什么可以帮助的。让问候变得个性化和鼓励性。
+EOF
+```
+
+### 步骤4：添加技能
+
+```bash
+cat > my-first-plugin/skills/greeting-skill/SKILL.md << 'EOF'
+---
+name: greeting-skill
+description: 生成友好的问候语。当用户需要问候模板或社交礼仪建议时使用。
+---
+
+# 问候技能
+
+## 说明
+
+根据场景生成合适的问候语：
+- 正式场合
+- 非正式场合
+- 电子邮件开头
+- 即时消息
+EOF
+```
+
+## plugin.json 配置详解
+
+### 基本配置
+
+```json
+{
+  "name": "plugin-name",
+  "description": "插件功能描述",
+  "version": "1.0.0",
+  "author": {
+    "name": "作者名称",
+    "email": "author@example.com"
+  }
+}
+```
+
+### 完整配置示例
+
+```json
+{
+  "name": "enterprise-tools",
+  "description": "企业级工作流自动化工具",
+  "version": "2.1.0",
+  "author": {
+    "name": "企业团队",
+    "email": "team@company.com"
+  },
+  "homepage": "https://docs.company.com/plugins/enterprise-tools",
+  "repository": "https://github.com/company/enterprise-plugin",
+  "license": "MIT",
+  "keywords": ["enterprise", "workflow", "automation"]
+}
+```
+
+### 配置字段说明
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `name` | 是 | 插件标识符（kebab-case 格式） |
+| `description` | 否 | 插件功能简述 |
+| `version` | 否 | 语义化版本号 |
+| `author` | 否 | 作者信息对象（含 `name` 字段） |
+| `homepage` | 否 | 文档或主页 URL |
+| `repository` | 否 | 源代码仓库 URL |
+| `license` | 否 | 许可证类型 |
+| `keywords` | 否 | 关键词数组 |
+
+## 安装和管理插件
+
+### 安装插件
+
+```bash
+# 通过交互菜单浏览
+/plugin
+
+# 从市场直接安装
+/plugin install formatter@your-org
+
+# 从本地市场安装
+/plugin install my-first-plugin@test-marketplace
+```
+
+### 管理已安装插件
+
+```bash
+# 启用插件
+/plugin enable plugin-name@marketplace-name
+
+# 禁用插件
+/plugin disable plugin-name@marketplace-name
+
+# 卸载插件
+/plugin uninstall plugin-name@marketplace-name
+```
+
+### 验证安装
+
+```bash
+# 查看新命令是否出现
+/help
+
+# 管理插件
+/plugin
+```
+
+## 本地开发和测试
+
+### 开发工作流
+
+```bash
+# 1. 创建开发目录结构
+mkdir dev-marketplace
+cd dev-marketplace
+mkdir my-plugin
+
+# 2. 创建市场清单
+mkdir .claude-plugin
+cat > .claude-plugin/marketplace.json << 'EOF'
+{
+  "name": "dev-marketplace",
+  "owner": {"name": "Developer"},
+  "plugins": [{
+    "name": "my-plugin",
+    "source": "./my-plugin",
+    "description": "开发中的插件"
+  }]
+}
+EOF
+
+# 3. 从父目录启动 Claude Code
+claude
+
+# 4. 添加市场
+/plugin marketplace add ./dev-marketplace
+
+# 5. 安装插件
+/plugin install my-plugin@dev-marketplace
+```
+
+### 迭代开发
+
+```bash
+# 修改插件代码后，重新安装
+/plugin uninstall my-plugin@dev-marketplace
+/plugin install my-plugin@dev-marketplace
+```
+
+## 高级功能
+
+### 添加钩子（Hooks）
+
+在 `hooks/hooks.json` 中定义事件处理器：
+
+```json
+{
+  "PostToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+> **注意**：`${CLAUDE_PLUGIN_ROOT}` 环境变量指向插件安装目录。
+
+### 添加 MCP 服务器
+
+在插件根目录创建 `.mcp.json`：
+
+```json
+{
+  "servers": {
+    "my-server": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
+      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
+    }
+  }
+}
+```
+
+### 添加自定义代理
+
+在 `agents/` 目录创建代理定义：
+
+```markdown
+# agents/code-assistant.md
+---
+description: 专注于代码质量的智能助手
+allowed-tools: Read, Grep, Glob, Edit
+---
+
+# 代码助手代理
+
+你是一个专注于代码质量的助手。
+
+## 职责
+
+1. 代码审查
+2. 重构建议
+3. 最佳实践指导
+```
+
+## 完整插件示例
+
+### 示例：代码格式化插件
+
+**目录结构：**
+```
+code-formatter/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   ├── format.md
+│   └── lint.md
+├── skills/
+│   └── formatting-rules/
+│       └── SKILL.md
+└── scripts/
+    └── prettier-wrapper.sh
+```
+
+**plugin.json：**
+```json
+{
+  "name": "code-formatter",
+  "description": "自动代码格式化和 lint 检查",
+  "version": "1.0.0",
+  "author": {
+    "name": "DevTools Team"
+  },
+  "keywords": ["format", "lint", "prettier", "eslint"]
+}
+```
+
+**commands/format.md：**
+```markdown
+---
+description: 格式化当前文件或目录
+argument-hint: [文件或目录路径]
+allowed-tools: Bash(npx prettier:*), Read, Write
+---
+
+# 格式化命令
+
+格式化指定的文件或目录：$ARGUMENTS
+
+使用项目的 Prettier 配置进行格式化。
+```
+
+**commands/lint.md：**
+```markdown
+---
+description: 运行 ESLint 检查
+argument-hint: [文件或目录路径]
+allowed-tools: Bash(npx eslint:*)
+---
+
+# Lint 检查命令
+
+对指定的文件或目录运行 ESLint：$ARGUMENTS
+
+报告所有问题并提供修复建议。
+```
+
+**skills/formatting-rules/SKILL.md：**
+```yaml
+---
+name: formatting-rules
+description: 了解项目的代码格式化规则。当需要手动格式化代码或解释格式化规则时使用。
+---
+
+# 格式化规则
+
+## 常用规则
+
+- 缩进：2 空格
+- 分号：必需
+- 引号：单引号
+- 尾随逗号：ES5 兼容
+
+## 配置文件
+
+检查以下文件了解项目规则：
+- `.prettierrc`
+- `.eslintrc`
+- `package.json` 中的 `prettier` 和 `eslintConfig`
+```
+
+## 团队插件配置
+
+在仓库的 `.claude/settings.json` 中配置自动安装：
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "team-tools": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/claude-plugins"
+      }
+    }
+  }
+}
+```
+
+当团队成员信任该仓库后：
+- 市场会自动安装
+- 通过 `enabledPlugins` 字段指定的插件会自动安装
+
+## 调试和验证
+
+### 调试技巧
+
+1. **检查结构**：确保目录在插件根目录，而非 `.claude-plugin/` 内部
+2. **单独测试**：分别检查每个命令、代理和钩子
+3. **使用验证工具**：参见插件参考文档了解 CLI 调试命令
+4. **验证安装**：运行 `/help` 查看新命令是否列出
+
+### 检查清单
+
+- [ ] `.claude-plugin/plugin.json` 存在且格式正确
+- [ ] 组件目录（commands/、skills/ 等）在插件根目录
+- [ ] 命令文件为 `.md` 格式
+- [ ] 技能目录包含 `SKILL.md` 文件
+- [ ] YAML frontmatter 语法正确
+
+### 常见问题
+
+**命令不显示：**
+- 检查文件扩展名是否为 `.md`
+- 验证 frontmatter 格式正确
+- 重启 Claude Code
+
+**技能不激活：**
+- 检查 `description` 是否足够具体
+- 验证 `SKILL.md` 路径正确
+
+## 分享插件前的准备
+
+在分发插件之前：
+- 添加 `README.md` 包含安装和使用说明
+- 在 `plugin.json` 中使用语义化版本号
+- 创建或使用市场进行分发
+- 在更广泛发布前与他人测试
+
+## 相关资源
+
+- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
+- [Skills 技能指南](./02-技能指南.md)
+- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
+- [官方文档：插件系统](https://code.claude.com/docs/en/plugins)
+- [官方文档：子代理](https://code.claude.com/docs/en/sub-agents)
+- [官方文档：钩子](https://code.claude.com/docs/en/hooks)
+- [官方文档：MCP](https://code.claude.com/docs/en/mcp)
--- a/guide/04-插件市场指南.md
+++ b/guide/04-插件市场指南.md
@@ -0,0 +1,382 @@
+# Claude Code 插件市场（Plugin Marketplaces）指南
+
+## 概述
+
+插件市场是基于 JSON 的目录，用于集中发现、版本管理和团队分发 Claude Code 扩展。它支持来自多种来源（Git 仓库、GitHub、本地路径、包管理器）的插件。
+
+### 核心功能
+
+- **集中发现**：在一个地方浏览来自多个来源的插件
+- **版本管理**：自动跟踪和更新插件版本
+- **团队分发**：跨组织共享所需插件
+- **灵活来源**：支持 Git 仓库、GitHub、本地路径等多种来源
+- **环境变量**：使用 `${CLAUDE_PLUGIN_ROOT}` 引用插件安装目录
+
+## 快速命令参考
+
+```bash
+# 添加 GitHub 市场
+/plugin marketplace add owner/repo
+
+# 添加 Git 仓库
+/plugin marketplace add https://gitlab.com/company/plugins.git
+
+# 添加本地市场
+/plugin marketplace add ./my-marketplace
+/plugin marketplace add ./path/to/marketplace.json
+
+# 添加远程 URL
+/plugin marketplace add https://url.of/marketplace.json
+
+# 从市场安装插件
+/plugin install plugin-name@marketplace-name
+
+# 列出已配置市场
+/plugin marketplace list
+
+# 更新市场
+/plugin marketplace update marketplace-name
+
+# 删除市场
+/plugin marketplace remove marketplace-name
+```
+
+## 市场结构
+
+### 基本目录结构
+
+在仓库根目录创建 `.claude-plugin/marketplace.json`：
+
+```
+my-marketplace/
+├── .claude-plugin/
+│   └── marketplace.json     # 必需：市场索引文件
+├── plugin-a/                # 本地插件 A
+│   └── .claude-plugin/
+│       └── plugin.json
+├── plugin-b/                # 本地插件 B
+│   └── .claude-plugin/
+│       └── plugin.json
+└── README.md                # 可选：市场说明
+```
+
+### marketplace.json 基本格式
+
+```json
+{
+  "name": "company-tools",
+  "owner": {
+    "name": "DevTools Team",
+    "email": "team@example.com"
+  },
+  "plugins": [
+    {
+      "name": "code-formatter",
+      "source": "./plugins/formatter",
+      "description": "自动代码格式化"
+    }
+  ]
+}
+```
+
+## 市场索引字段说明
+
+### 必需字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | 市场标识符（kebab-case，无空格） |
+| `owner` | object | 市场维护者信息 |
+| `plugins` | array | 可用插件列表 |
+
+### 可选元数据字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `metadata.description` | string | 市场简介 |
+| `metadata.version` | string | 市场版本 |
+| `metadata.pluginRoot` | string | 相对插件来源的基础路径 |
+
+## 插件条目配置
+
+### 必需字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | 插件标识符（kebab-case，无空格） |
+| `source` | string\|object | 插件来源位置 |
+
+### 可选元数据字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `description` | string | 插件功能描述 |
+| `version` | string | 插件版本 |
+| `author` | object | 插件作者信息 |
+| `homepage` | string | 插件主页或文档 URL |
+| `repository` | string | 源代码仓库 URL |
+| `license` | string | SPDX 许可证标识符（MIT、Apache-2.0 等） |
+| `keywords` | array | 发现和分类标签 |
+| `category` | string | 插件分类 |
+| `tags` | array | 搜索标签 |
+| `strict` | boolean | 是否要求文件夹中有 plugin.json（默认：true） |
+
+### 组件配置字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `commands` | string\|array | 命令文件或目录的自定义路径 |
+| `agents` | string\|array | 代理文件的自定义路径 |
+| `hooks` | string\|object | 钩子配置或钩子文件路径 |
+| `mcpServers` | string\|object | MCP 服务器配置或 MCP 配置文件路径 |
+
+## 插件来源配置
+
+### 相对路径（同一仓库内）
+
+```json
+{
+  "name": "my-plugin",
+  "source": "./plugins/my-plugin"
+}
+```
+
+### GitHub 仓库
+
+```json
+{
+  "name": "github-plugin",
+  "source": {
+    "source": "github",
+    "repo": "owner/plugin-repo"
+  }
+}
+```
+
+### Git 仓库（任意服务）
+
+```json
+{
+  "name": "git-plugin",
+  "source": {
+    "source": "url",
+    "url": "https://gitlab.com/team/plugin.git"
+  }
+}
+```
+
+## 完整配置示例
+
+### 市场配置
+
+```json
+{
+  "name": "enterprise-marketplace",
+  "owner": {
+    "name": "Enterprise Team",
+    "email": "enterprise@company.com"
+  },
+  "metadata": {
+    "description": "企业级 Claude Code 插件集合",
+    "version": "2.0.0"
+  },
+  "plugins": [
+    {
+      "name": "code-formatter",
+      "source": "./plugins/formatter",
+      "description": "自动代码格式化",
+      "version": "2.1.0"
+    },
+    {
+      "name": "security-scanner",
+      "source": {
+        "source": "github",
+        "repo": "company/security-plugin"
+      },
+      "description": "代码安全扫描"
+    }
+  ]
+}
+```
+
+### 高级插件条目
+
+```json
+{
+  "name": "enterprise-tools",
+  "source": {
+    "source": "github",
+    "repo": "company/enterprise-plugin"
+  },
+  "description": "企业工作流自动化工具",
+  "version": "2.1.0",
+  "author": {
+    "name": "Enterprise Team",
+    "email": "team@company.com"
+  },
+  "homepage": "https://docs.company.com/plugins/enterprise-tools",
+  "repository": "https://github.com/company/enterprise-plugin",
+  "license": "MIT",
+  "keywords": ["enterprise", "workflow", "automation"],
+  "category": "productivity",
+  "commands": [
+    "./commands/core/",
+    "./commands/enterprise/",
+    "./commands/experimental/preview.md"
+  ],
+  "agents": [
+    "./agents/security-reviewer.md",
+    "./agents/compliance-checker.md"
+  ],
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "mcpServers": {
+    "enterprise-db": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
+      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
+    }
+  },
+  "strict": false
+}
+```
+
+## 创建和使用市场
+
+### 创建本地市场
+
+```bash
+# 1. 创建市场目录
+mkdir -p my-marketplace/.claude-plugin
+
+# 2. 创建市场索引
+cat > my-marketplace/.claude-plugin/marketplace.json << 'EOF'
+{
+  "name": "my-marketplace",
+  "owner": {
+    "name": "Your Name"
+  },
+  "plugins": []
+}
+EOF
+
+# 3. 添加插件到市场
+mkdir -p my-marketplace/hello-plugin/.claude-plugin
+# ... 创建插件文件 ...
+
+# 4. 更新市场索引添加插件条目
+```
+
+### 从市场安装插件
+
+```bash
+# 从已知市场安装
+/plugin install plugin-name@marketplace-name
+
+# 交互式浏览
+/plugin
+```
+
+## 团队市场配置
+
+在项目的 `.claude/settings.json` 中配置自动安装：
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "team-tools": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/claude-plugins"
+      }
+    },
+    "project-specific": {
+      "source": {
+        "source": "git",
+        "url": "https://git.company.com/project-plugins.git"
+      }
+    }
+  }
+}
+```
+
+当团队成员信任该仓库文件夹后，Claude Code 会自动安装这些市场，以及通过 `enabledPlugins` 字段指定的任何插件。
+
+## 托管和分发
+
+### GitHub 托管（推荐）
+
+1. 创建 GitHub 仓库
+2. 添加 `.claude-plugin/marketplace.json`
+3. 添加插件目录
+4. 用户通过以下命令添加：
+   ```bash
+   /plugin marketplace add owner/repo
+   ```
+
+### 其他 Git 服务
+
+```bash
+/plugin marketplace add https://gitlab.com/company/plugins.git
+```
+
+### 本地开发测试
+
+```bash
+/plugin marketplace add ./my-local-marketplace
+/plugin install test-plugin@my-local-marketplace
+```
+
+## 验证和测试
+
+```bash
+# 验证市场 JSON 语法和结构
+claude plugin validate .
+
+# 添加本地市场测试
+/plugin marketplace add ./path/to/marketplace
+
+# 测试插件安装
+/plugin install test-plugin@marketplace-name
+```
+
+## 故障排除
+
+### 市场无法加载
+
+- 验证市场 URL 可访问
+- 检查 `.claude-plugin/marketplace.json` 存在
+- 验证 JSON 语法有效
+- 私有仓库需确保有访问权限
+
+### 插件安装失败
+
+- 验证插件源 URL 可访问
+- 检查插件目录包含必需文件
+- GitHub 源需确保仓库公开或有权限
+- 验证插件来源可手动下载
+
+## 最佳实践
+
+1. **清晰命名**：使用有意义的市场和插件名称
+2. **完整描述**：为每个插件提供清晰的功能描述
+3. **版本管理**：使用语义化版本号
+4. **文档齐全**：提供 README 和使用说明
+5. **定期更新**：保持插件和市场元数据最新
+
+## 相关资源
+
+- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
+- [Skills 技能指南](./02-技能指南.md)
+- [Plugins 插件指南](./03-插件指南.md)
+- [官方文档：插件市场](https://code.claude.com/docs/en/plugin-marketplaces)