1. 为什么我要把团队规范塞进 Claude Code 插件里Claude Code 用久了会遇到一个尴尬每个人都在自己的终端里跟模型聊天但团队沉淀下来的东西——命名规范、迁移脚本模板、接口文档格式——全靠口头传达或者散落在 wiki 里。新人问「模型文件怎么写」老人甩一个链接链接里的示例还是两年前的。Claude Code Plugins 就是解决这个问题的。它是什么简单说插件是一个可分发的能力包把 Skills技能、Commands斜杠命令、Agents自定义代理、Hooks事件钩子打包在一起用一份 plugin.json 做清单。能做什么你可以把「创建模型」「生成迁移」「查询优化」这些团队私有能力做成插件别人claude plugin add一下就能用。适合谁想把团队最佳实践固化下来、又不想维护一堆脚本的开发者。我试过把数据库工具链做成插件从 plugin.json 骨架到 Hooks 触发链路跑通中间踩了几个坑。这篇就按「从零搭建 → 配置骨架 → 挂载 Hooks → 本地验证 → 排错」的顺序写最后用一次插件触发日志确认生态跑通。模型调用通道统一走 TaoTokenKey 和 API 地址集中管理省得每个插件各自配一遍。2. 前置准备TaoToken 统一 Key 与 API 通道插件里如果要调模型比如 Agent 里指定 model、Skill 里做生成最烦的是每个插件都要配一遍 base_url 和 key。我的做法是统一走 TaoToken一个 Key 管所有插件调用。先去控制台拿 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite拿到之后API 地址用https://taotoken.net/api注意这个不加 UTM。配置方式有两种看你习惯第一种是环境变量适合本地开发export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key第二种是写进 Claude Code 的 settings适合团队统一。在.claude/settings.json里{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key } }注意插件本身不存 KeyKey 放在环境或 settings 里插件通过${ANTHROPIC_API_KEY}引用。这样插件可以安全地分享出去不会泄露凭证。如果你还没配过可以先在模型对话页面确认通道通不通https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite3. 可复制配置plugin.json 骨架与目录结构插件的核心是 plugin.json它声明了这个插件提供哪些组件。先建目录mkdir -p db-tools-plugin/{skills,commands,agents,hooks,mcp,lib} cd db-tools-plugin目录结构长这样db-tools-plugin/ ├── plugin.json # 插件清单必需 ├── skills/ # 技能定义 │ ├── create-model.md │ └── create-migration.md ├── commands/ # 斜杠命令 │ └── db.md ├── agents/ # 自定义代理 │ └── query-optimizer.md ├── hooks/ # 钩子定义 │ └── pre-migration.json ├── mcp/ # MCP 服务器配置 │ └── db-server.json └── lib/ # 支持文件 └── helpers.js然后写 plugin.json。这是骨架字段别写错{ name: db-tools, version: 1.0.0, description: 数据库开发辅助工具支持模型生成、迁移管理和查询优化, author: Your Team, keywords: [database, migration, orm], license: MIT, claude: { minVersion: 1.0.0 }, contributions: { skills: [skills/*.md], commands: [commands/*.md], agents: [agents/*.md], hooks: [hooks/*.json], mcpServers: [mcp/*.json] }, config: { defaultOrm: { type: string, default: mongoose, description: 默认使用的 ORM, enum: [mongoose, sequelize, prisma] }, migrationsDir: { type: string, default: migrations, description: 迁移文件目录 } } }字段说明用表格对照更清楚字段必填说明name是插件名小写字母加短横线version是语义化版本号description是功能描述contributions是声明提供的组件路径config否用户可配置项claude.minVersion否最低兼容版本contributions里的路径支持 globskills/*.md表示 skills 目录下所有 md 文件都会被注册为技能。这一步写错后面加载会静默失败所以路径一定要对。4. 串联 Skills 与 Hooks 的注册与触发链路骨架有了接下来把 Skills 和 Hooks 串起来。Skills 是「被调用时执行」的能力Hooks 是「事件发生时触发」的自动化两者通过 plugin.json 的 contributions 注册到同一个插件里。先写一个 Skillskills/create-model.md--- name: create-model description: 创建数据库模型文件包含 Schema 定义和常用方法 triggers: - 创建模型 - 新建数据模型 arguments: - name: model_name description: 模型名称如 User、Product required: true - name: fields description: 字段定义如 name:string,age:number required: true --- 创建模型{{model_name}} 字段定义{{fields}} 请按以下模板创建文件 src/models/{{model_name}}.js 1. 包含 Schema 定义 2. 开启 timestamps 3. 添加常用静态方法 4. 符合项目现有模型风格再写一个 Hookhooks/pre-migration.json。Hook 的关键是 trigger 和 matcher它决定了什么时候触发{ name: pre-migration-check, trigger: PreToolUse, matcher: { toolName: Bash, command: *migrate* }, action: { type: prompt, prompt: 执行迁移前检查1. 确认数据库连接正常 2. 检查待执行迁移 3. 确认当前环境 } }触发链路是这样的当 Claude Code 准备执行一个 Bash 命令且命令里包含migrate时PreToolUse事件被触发matcher 匹配成功然后执行 action 里的 prompt。这样每次跑迁移前都会自动做一次检查不用人肉记。提示Hook 的 trigger 常见值有PreToolUse、PostToolUse、UserPromptSubmit。matcher 里的 command 支持通配符*migrate*能匹配npm run migrate、node migrate.js等。Skills 和 Hooks 都注册在同一个 plugin.json 的 contributions 里所以它们共享插件的 config 和生命周期。这就是「插件是整合形态」的意思——不是把功能堆一起而是让它们在一个清单下协同。5. 本地加载与验证一次插件触发日志确认跑通配置写完本地加载验证。Claude Code 加载本地插件用plugin add指向目录claude plugin add /path/to/db-tools-plugin加载后列出插件确认claude plugin list正常输出类似db-tools1.0.0 /path/to/db-tools-plugin loaded如果没显示先检查 plugin.json 的 JSON 语法用python -m json.tool plugin.json验证一下。接下来验证 Skill 触发。在 Claude Code 里输入/create-model model_nameProduct fieldsname:string,price:number,stock:number预期结果是模型文件被创建内容包含 Schema 定义和 timestamps。如果 Skill 没触发检查skills/*.md的 frontmatter 里 name 和 triggers 是否写对。然后验证 Hook 触发。执行一个包含 migrate 的命令npm run migrate这时候观察日志应该能看到 Hook 注入的检查提示。一次完整的触发日志大概长这样[PreToolUse] matcher hit: Bash *migrate* [hook:pre-migration-check] 执行迁移前检查 1. 确认数据库连接正常 2. 检查待执行迁移 3. 确认当前环境 [Bash] npm run migrate看到matcher hit这行说明 Hooks 挂载成功触发链路跑通了。如果 Hook 没触发大概率是 matcher 的 command 写得太死比如写成npm run migrate而不是*migrate*导致匹配不上。最后确认模型调用通道。在 Agent 里指定 model 时走的是 TaoToken 的通道。可以跑一个简单请求验证curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-6,max_tokens:64,messages:[{role:user,content:ping}]}返回正常就说明 Key 和 API 通道没问题插件里的模型调用也能走通。6. 本篇常见错排查plugin.json 加载失败plugin list 里看不到插件。九成是 JSON 语法错误比如多了个逗号、少了引号。用python -m json.tool plugin.json跑一遍报错行号直接指出来。另一个可能是 contributions 里的路径写错glob 匹配不到文件插件会加载但组件为空。Skill 不触发。先看 frontmatter 的name和调用时用的名字是否一致大小写敏感。再看triggers里的关键词有没有命中。如果 Skill 有必填 arguments 但没传也会静默不执行检查 arguments 的 required 字段。Hook 不触发。最常见是 matcher 写太具体。command字段是通配匹配建议用*关键词*的形式。另外 trigger 的值要写对PreToolUse不是preToolUse大小写错了不报错但也不触发。模型调用报 401 或 404。401 是 Key 问题检查ANTHROPIC_API_KEY有没有正确导出或者 settings.json 里的 env 有没有被覆盖。404 通常是 base_url 写错确认是https://taotoken.net/api不要多加路径。如果插件里硬编码了别的地址改成引用环境变量。插件加载了但 config 不生效。config 的默认值在 plugin.json 里用户覆盖要写在.claude/settings.json的plugins字段下键名是插件 name。层级写错的话插件读到的还是默认值。7. 把通道和插件生态接起来插件生态跑通之后日常开发里最常做的两件事一是调模型验证 Skill 输出二是长期跑 Agent 做代码分析。这两件事都依赖稳定的 API 通道。如果你只是偶尔验证一下模型返回用模型对话页面最省事https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你要把插件里的 Agent 长期挂起来跑比如 query-optimizer 定时分析查询性能建议用 Coding Plan额度更划算适合持续调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteKey 的管理和轮换在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite接入文档在这里插件里引用环境变量的细节可以对照看https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite插件开发本身不复杂难的是把团队规范拆成可复用的 Skill 和 Hook再用 plugin.json 串起来。跑通一次触发日志之后后面就是往里加组件的事了。