通俗版 Claude Code 文档

结构照原 docs，内容改成真能照着做的人话版。
查看原始文档 目录顺序与官方保持一致

参考

插件参考

插件字段和结构的参考表。

页面信息

对应原页

Plugins reference

页面性质

第三方中文解释页

使用建议

先看人话解释，再对照原页命令和代码

这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。

如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。

这一页先讲明白

这页是插件参考表，适合做插件或查插件结构时用。

字段怎么写、结构怎么摆，这里最关键。

它像装配图，不是给你讲故事，而是给你照着拼。

如果前面"创建插件"那页讲的是思路，这页讲的就是细节和格式。

要真正落文件时，这页比空谈更有用。

先按最小插件结构做通，再往里加复杂字段。

字段名和格式别自己想象，照参考表来。

创建插件和插件参考最好配着看，一个讲方向，一个讲落地。

目录怎么摆

原页关键片段：Skills

这一段主要是认目录和文件摆放位置。先把地方放对，后面才不容易串。

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md
改配置

原页关键片段：Agents

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.
改配置

原页关键片段：Hooks

这会儿轮到改配置了，字段名和关键字别自己乱换。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}
改配置

原页关键片段：MCP servers

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}
改配置

原页关键片段：LSP servers 1

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}
改配置

原页关键片段：LSP servers 2

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}
改配置

原页关键片段：Monitors

这一段说完，最后还得写到配置里才算真的生效。

[
  {
    "name": "deploy-status",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]
改配置

原页关键片段：Themes

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}
改配置

原页关键片段：Complete schema

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
改配置

原页关键片段：User configuration

这一段说完，最后还得写到配置里才算真的生效。

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}
改配置

原页关键片段：Channels

这会儿轮到改配置了，字段名和关键字别自己乱换。

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}
改配置

原页关键片段：Path behavior rules

这会儿轮到改配置了，字段名和关键字别自己乱换。

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

预留广告位

正文中段响应式广告 等你后面真接 AdSense，这里再放正式广告。

Documentation Index

这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

Plugin components reference

这种内容最怕想当然，老老实实照它列的格式走最稳。

Skills

这里不是让你背"Skills"这个词，而是让你看它真干活时怎么使。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

目录怎么摆

Skills

这一段主要是认目录和文件摆放位置。先把地方放对，后面才不容易串。

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

Agents

这里不是让你背"Agents"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Agents

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

Hooks

这一段主要是在把"Hooks"讲实，不是只摆个标题给你看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Hooks

这会儿轮到改配置了，字段名和关键字别自己乱换。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

MCP servers

这里不是让你背"MCP servers"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

MCP servers

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

LSP servers

这一块主要是在说"LSP servers"真到手上该怎么用，哪里最容易踩坑。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

改配置

LSP servers 1

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}
改配置

LSP servers 2

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Monitors

看到这里，就把"Monitors"当成一件真要上手的活来看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Monitors

这一段说完，最后还得写到配置里才算真的生效。

[
  {
    "name": "deploy-status",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

Themes

这里不是让你背"Themes"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Themes

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Plugin installation scopes

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Plugin manifest schema

看到这里，就别靠猜了，字段、格式和写法都得按说明来。

Complete schema

这种内容最怕想当然，老老实实照它列的格式走最稳。

改配置

Complete schema

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Required fields

这一段就是给你查规矩的，像看说明书那样一项项对着来。

Metadata fields

这种内容最怕想当然，老老实实照它列的格式走最稳。

Component path fields

看到这里，就别靠猜了，字段、格式和写法都得按说明来。

Experimental components

这一段主要是在把"Experimental components"讲实，不是只摆个标题给你看。

User configuration

别把这段只当成标题看，它其实是在给"User configuration"划边界。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

User configuration

这一段说完，最后还得写到配置里才算真的生效。

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

Channels

这段看着像个标题，其实是在说"Channels"管到哪儿。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Channels

这会儿轮到改配置了，字段名和关键字别自己乱换。

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

Path behavior rules

这一段主要是在把"Path behavior rules"讲实，不是只摆个标题给你看。

如果你打算把外接能力往里挂，这里提到的 hooks、MCP、skills、memory 都要分清各自负责哪一摊。

改配置

Path behavior rules

这会儿轮到改配置了，字段名和关键字别自己乱换。

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Environment variables

这里不是让你背"Environment variables"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Environment variables 1

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}
改配置

Environment variables 2

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}
改配置

Environment variables 3

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

Plugin caching and file resolution

看到这里，就把"Plugin caching and file resolution"当成一件真要上手的活来看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Path traversal limitations

这里不是让你背"Path traversal limitations"这个词，而是让你看它真干活时怎么使。

Working with external dependencies

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

关键片段

Working with external dependencies

先看下面这块原始片段，等会儿再回头看解释会顺得多。

ln -s /path/to/shared-utils ./shared-utils

Plugin directory structure

这一块主要是在说"Plugin directory structure"真到手上该怎么用，哪里最容易踩坑。

Standard plugin layout

这里不是让你背"Standard plugin layout"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

目录怎么摆

Standard plugin layout

这一段主要是认目录和文件摆放位置。先把地方放对，后面才不容易串。

enterprise-plugin/
├── .claude-plugin/           # Metadata directory (optional)
│   └── plugin.json             # plugin manifest
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills as flat .md files
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent definitions
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Output style definitions
│   └── terse.md
├── themes/                   # Color theme definitions
│   └── dracula.json
├── monitors/                 # Background monitor configurations
│   └── monitors.json
├── hooks/                    # Hook configurations
│   ├── hooks.json           # Main hook config
│   └── security-hooks.json  # Additional hooks
├── bin/                      # Plugin executables added to PATH
│   └── my-tool               # Invokable as bare command in Bash tool
├── settings.json            # Default settings for the plugin
├── .mcp.json                # MCP server definitions
├── .lsp.json                # LSP server configurations
├── scripts/                 # Hook and utility scripts
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # License file
└── CHANGELOG.md             # Version history

File locations reference

这一段就是给你查规矩的，像看说明书那样一项项对着来。

CLI commands reference

这种内容最怕想当然，老老实实照它列的格式走最稳。

plugin install

这一段就是安装 a plugin from available marketplaces.。这种地方最怕跳步骤，最好老老实实按顺序来。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

plugin install 1

真到动手的时候了，下面这条直接敲一遍，看它回什么。

claude plugin install <plugin> [options]
终端里敲

plugin install 2

真到动手的时候了，下面这条直接敲一遍，看它回什么。

# Install to user scope (default)
claude plugin install formatter@my-marketplace

# Install to project scope (shared with team)
claude plugin install formatter@my-marketplace --scope project

# Install to local scope (gitignored)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

这一块主要是在说"plugin uninstall"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

plugin uninstall

看到这里，别光点头，下面这条命令先跑起来再说。

claude plugin uninstall <plugin> [options]

plugin prune

这一块主要是在说"plugin prune"真到手上该怎么用，哪里最容易踩坑。

终端里敲

plugin prune

看到这里，别光点头，下面这条命令先跑起来再说。

claude plugin prune [options]

plugin enable

这里不是让你背"plugin enable"这个词，而是让你看它真干活时怎么使。

终端里敲

plugin enable

真到动手的时候了，下面这条直接敲一遍，看它回什么。

claude plugin enable <plugin> [options]

照着做一遍

如果你不想来回翻，就先照这几步顺着做。

每做完一步就看一下结果，再决定要不要继续往下。

目录怎么摆

第 1 步：Skills

这一段主要是认目录和文件摆放位置。先把地方放对，后面才不容易串。

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md
改配置

第 2 步：Agents

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.
改配置

第 3 步：Hooks

这会儿轮到改配置了，字段名和关键字别自己乱换。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}
改配置

第 4 步：MCP servers

光知道意思还不够，这里得把规矩落进配置里，下面这块照着填。

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

一眼看懂这一页

先把这页到底在讲什么看明白，再去碰具体命令和配置，最不容易绕晕。

Plugins reference
   |
   v
这是 Reference 里的一摊要紧活
   |
   v
先弄懂，再下手

文末提醒

这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。

人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。

预留广告位

文末横幅广告 适合放在文章读完以后，不抢首屏注意力。