跳转到主要内容
插件将规则、技能、Agents、命令、MCP 服务器和钩子打包成可分发的捆绑包。你可以使用插件来扩展 Qoder 的能力——从代码审查、自动部署到连接企业内部系统。

​
插件包含的内容

组件说明
SkillsAI 的原子执行单元，定义”具体怎么做一件事”。每个 Skill 是一个 SKILL.md 文件
Rules注入 AI 上下文的指令，约束 AI 的行为和风格
Agents子代理定义，可被主 Agent 调度执行特定任务
Commands斜杠命令（/command-name），用户手动触发的快捷操作
MCP Servers连接外部服务的 MCP 服务器配置
Hooks事件钩子，在特定时机自动执行脚本

​
目录结构

my-plugin/
├── .qoder-plugin/
│   └── plugin.json         # 插件清单（必需）
├── skills/                 # 技能
│   ├── skill-a/
│   │   └── SKILL.md
│   └── skill-b/
│       └── SKILL.md
├── rules/                  # 规则（.md 文件）
├── agents/                 # 子代理（.md 文件）
├── commands/               # 斜杠命令（.md 文件）
├── hooks/
│   └── hooks.json          # 钩子配置
├── mcp.json                # MCP 服务器配置
├── qoder.md                # 项目指令文件（可选）
├── CONNECTORS.md           # Connector 依赖说明（可选）
└── README.md               # 插件说明文档（可选）
除 .qoder-plugin/ 以外，所有目录均为可选，按需创建。plugin.json 中可显式声明路径覆盖默认约定。

​
插件清单（plugin.json）

plugin.json 位于 .qoder-plugin/ 目录下，是插件的唯一必需文件。
字段类型必填说明
namestring是插件标识符，必须 kebab-case（小写字母、数字、连字符）
versionstring是语义化版本号，如 1.0.0
descriptionstring否插件简介
displayNamestring否展示名称（支持中文），用于客户端 UI 和市场展示
authorobject否作者信息
keywordsstring 数组否搜索关键词
homepagestring否主页或文档 URL
repositorystring否源码仓库 URL
licensestring否SPDX 许可证标识

​
组件路径声明

字段类型说明
skillsstring 或 string 数组技能目录路径。客户端根据此字段加载对应的 Skill
rulesstring 或 string 数组规则目录路径
agentsstring 或 string 数组Agent 文件路径
commandsstring、string 数组或 object命令文件/目录路径，或命令对象映射
hooksstring钩子配置 JSON 文件路径
mcpServersstringMCP 服务器配置 JSON 文件路径
skills 字段支持精确声明包含哪些 Skill 路径，客户端仅加载声明的 Skill： 
"skills": ["skills/提交需求", "skills/评估Backlog"]
若指向一个目录（如 "./skills"），则该目录下所有包含 SKILL.md 的子目录均被加载。

​
最小配置

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A simple Qoder plugin"
}

​
完整示例

{
  "name": "requirement-pool",
  "version": "2.3.0",
  "description": "需求池管理工具集",
  "displayName": "需求池管理",
  "author": { "name": "Product Team" },
  "keywords": ["requirement", "backlog"],
  "skills": ["skills/提交需求", "skills/评估Backlog"],
  "rules": "./rules",
  "agents": ["./agents/requirement-reviewer.md"],
  "commands": {
    "submit-req": {
      "source": "./commands/submit.md",
      "description": "提交新需求到需求池",
      "argumentHint": "[title]"
    }
  },
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./mcp.json"
}

​
技能（SKILL.md）

每个技能是一个独立目录，包含一个 SKILL.md 文件。文件使用 YAML frontmatter + Markdown 正文： 
---
description: 对当前项目执行代码规范检查并自动修复
name: lint-check
---

## 工作流程
1. 读取项目的 lint 配置
2. 运行检查，汇总问题
3. 经用户确认后自动修复
关键字段说明：
字段说明
description最重要的字段——Qoder 根据它决定何时自动调用该技能
name技能名称，默认取目录名

​
MCP 服务器配置

MCP 配置文件为 mcp.json（或 .mcp.json），顶层使用 mcpServers 字段。 
{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@my-org/db-mcp-server"],
      "env": { "DB_URL": "postgres://localhost:5432/mydb" }
    }
  }
}
客户端行为（QoderWork）：Skill 依赖的 Connector 未配置时，QoderWork 会友好提示”此功能需要先配置「XXX」连接器，请前往插件详情页完成配置”，而非直接抛出连接错误。

​
钩子（Hooks）

钩子配置文件为 hooks/hooks.json，在特定事件发生时自动执行命令。 
{
  "description": "Simple Pre-Write Check",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${QODER_PLUGIN_ROOT}/check.js\""
          }
        ]
      }
    ]
  }
}
  • matcher：过滤触发的工具名
  • ${QODER_PLUGIN_ROOT}：当前插件安装目录的绝对路径。用于在命令中引用插件内部的资源文件（脚本、配置等），无论插件安装在何处，路径都能正确解析
支持的事件类型及详细配置，请参阅 Hooks 文档。

​
项目指令文件（qoder.md）

qoder.md 是插件级别的项目指令文件，定义 Agent 人设、工作流编排和护栏规则。当用户整体调起插件时，它作为核心 system prompt 注入，赋予 AI 统一的角色认知和任务编排能力。 文件名为 qoder.md。QoderWork 客户端同时识别 qoderwork.md。

​
Connector 依赖说明（CONNECTORS.md）

CONNECTORS.md 是面向插件使用者的 Connector 依赖说明文档。它标明每个 Skill 依赖哪些连接、操作哪些资源、如何配置。 示例： 
# Connector 依赖

## 钉钉日志
- **用途**：skill「查询日志」依赖此连接器读取钉钉审计日志
- **资源**：钉钉开放平台审计日志 API
- **配置方式**：前往 https://aihub.dingtalk.com 获取个人 MCP Server URL

## 企业数据库
- **用途**：skill「生成报表」依赖此连接器查询业务数据
- **资源**：PostgreSQL 只读副本
- **配置方式**：联系 DBA 获取只读连接串
此文件帮助使用者在安装插件后快速了解需要配置哪些外部连接，以及各连接的权限和安全边界。

​
Commands 对象格式

当 commands 为对象时，可以为每个命令定义详细配置：
字段类型说明
sourcestring命令 Markdown 文件路径
descriptionstring命令描述
argumentHintstring参数提示，如 "[env]"

​
打包与分发

​
打包格式

插件以 .zip 格式分发。要求：
1

zip 根目录即插件根目录

不要额外嵌套一层目录。
2

包含 plugin.json

.qoder-plugin/plugin.json 必须存在。
3

规范文件名

建议文件名：{name}-{version}.zip。
正确结构： 
deploy-helper-2.0.0.zip
├── .qoder-plugin/
│   └── plugin.json
├── skills/
├── hooks/
│   └── hooks.json
├── mcp.json
├── CONNECTORS.md
└── README.md

​
路径规则

  • 所有相对路径必须以 ./ 开头
  • 不允许包含 ..（禁止路径穿越）
  • JSON 路径必须以 .json 结尾
  • Markdown 路径必须以 .md 结尾

​
常见问题

​
插件和独立 Skill 有什么区别？

独立 Skill 适合单项目使用（直接放在项目的 .qoder/skills/ 下）。插件适合跨项目共享和企业分发——它将多个 Skill 及相关配置打包为一个整体。

​
plugin.json 放在哪里？

必须放在 .qoder-plugin/plugin.json。

​
MCP Server 需要个人凭证怎么办？

使用声明式 Connector 配置（{{USER_CONFIG}} 占位符 + _setup 引导），每个用户安装时填入自己的凭证，避免硬编码。

​
客户端支持情况

已支持　 即将支持　 不适用
组件Qoder DesktopQoder CLIJetBrains PluginQoderWork
Skills (SKILL.md)
Rules (.md)
Agents (.md)
Commands (斜杠命令)
MCP Servers
Hooks (hooks.json)
项目指令文件 (qoder.md)