> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Plugins
Plugins bundle rules, skills, agents, commands, MCP servers, and hooks into distributable packages. Use plugins to extend Qoder's capabilities — from code review and automated deployment to connecting enterprise systems.
## What Plugins Contain
| Component | Description |
| --------------- | ----------------------------------------------------------------------------------------- |
| **Skills** | Atomic AI execution units defining "how to do something". Each skill is a `SKILL.md` file |
| **Rules** | Directives injected into AI context to constrain behavior and style |
| **Agents** | Sub-agent definitions that can be dispatched by the main agent |
| **Commands** | Slash commands (`/command-name`) — user-triggered shortcuts |
| **MCP Servers** | Configuration for external service connections via MCP |
| **Hooks** | Event hooks that automatically execute scripts at specific moments |
## Directory Structure
```plaintext theme={null}
my-plugin/
├── .qoder-plugin/
│ └── plugin.json # Plugin manifest (required)
├── skills/ # Skills
│ ├── skill-a/
│ │ └── SKILL.md
│ └── skill-b/
│ └── SKILL.md
├── rules/ # Rules (.md files)
├── agents/ # Sub-agents (.md files)
├── commands/ # Slash commands (.md files)
├── hooks/
│ └── hooks.json # Hook configuration
├── mcp.json # MCP server configuration
├── qoder.md # Project instructions (optional)
├── CONNECTORS.md # Connector dependency docs (optional)
└── README.md # Plugin documentation (optional)
```
All directories except `.qoder-plugin/` are optional. Paths can be explicitly declared in `plugin.json` to override defaults.
## Plugin Manifest (plugin.json)
Located at `.qoder-plugin/plugin.json`, this is the only required file.
| Field | Type | Required | Description |
| ----------- | ------------ | -------- | --------------------------------------------------- |
| name | string | Yes | Plugin identifier, must be kebab-case |
| version | string | Yes | Semantic version, e.g. 1.0.0 |
| description | string | No | Brief description |
| displayName | string | No | Display name (supports CJK), for UI and marketplace |
| author | object | No | Author info |
| keywords | string array | No | Search keywords |
| homepage | string | No | Homepage or documentation URL |
| repository | string | No | Source repository URL |
| license | string | No | SPDX license identifier |
### Component Path Declarations
| Field | Type | Description |
| ------------ | ------------------------------- | --------------------------------------------------- |
| `skills` | string or string array | Skill directory paths |
| `rules` | string or string array | Rule directory paths |
| `agents` | string or string array | Agent file paths |
| `commands` | string, string array, or object | Command file/directory paths, or command object map |
| `hooks` | string | Hook config JSON file path |
| `mcpServers` | string | MCP server config JSON file path |
The `skills` field supports explicit declaration of which skills to load:
```json theme={null}
"skills": ["skills/submit-request", "skills/review-backlog"]
```
If pointing to a directory (e.g. `"./skills"`), all subdirectories containing `SKILL.md` are loaded.
### Minimal Configuration
```json theme={null}
{
"name": "my-plugin",
"version": "1.0.0",
"description": "A simple Qoder plugin"
}
```
### Full Example
```json theme={null}
{
"name": "requirement-pool",
"version": "2.3.0",
"description": "Requirement pool management toolkit",
"displayName": "Requirement Pool",
"author": { "name": "Product Team" },
"keywords": ["requirement", "backlog"],
"skills": ["skills/submit-request", "skills/review-backlog"],
"rules": "./rules",
"agents": ["./agents/requirement-reviewer.md"],
"commands": {
"submit-req": {
"source": "./commands/submit.md",
"description": "Submit a new requirement",
"argumentHint": "[title]"
}
},
"hooks": "./hooks/hooks.json",
"mcpServers": "./mcp.json"
}
```
## Skills (SKILL.md)
Each skill is an independent directory containing a `SKILL.md` file with YAML frontmatter + Markdown body:
```markdown theme={null}
---
description: Run code lint checks and auto-fix for the current project
name: lint-check
---
## Workflow
1. Read the project's lint configuration
2. Run checks and summarize issues
3. Auto-fix after user confirmation
```
**Key fields:**
| Field | Description |
| ----------- | --------------------------------------------------------------------------- |
| description | The most important field — Qoder uses it to decide when to invoke the skill |
| name | Skill name, defaults to directory name |
## MCP Server Configuration
The MCP config file is `mcp.json` (or `.mcp.json`), using the top-level `mcpServers` field.
```json theme={null}
{
"mcpServers": {
"my-db": {
"command": "npx",
"args": ["-y", "@my-org/db-mcp-server"],
"env": { "DB_URL": "postgres://localhost:5432/mydb" }
}
}
}
```
When an MCP Server requires user credentials, use placeholders + `_setup` for guided configuration:
```json theme={null}
{
"mcpServers": {
"audit-log": {
"type": "streamable-http",
"url": "{{USER_CONFIG}}",
"_setup": {
"configUrl": "https://example.com/mcp-setup",
"guide": "Visit the link above to obtain your personal MCP Server URL",
"required": true
}
}
}
}
```
* `{{USER_CONFIG}}`: Placeholder — user fills in the actual URL during installation
* `_setup.configUrl`: Page guiding users to obtain credentials
* `_setup.guide`: Setup instruction text
* `_setup.required`: Whether configuration is mandatory
**Client behavior (QoderWork)**: When a Skill's required Connector is not configured, QoderWork displays a friendly prompt asking the user to configure it, rather than throwing a connection error.
## Hooks
Hook configuration file is `hooks/hooks.json`, executing commands automatically on specific events.
```json theme={null}
{
"description": "Simple Pre-Write Check",
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "node \"${QODER_PLUGIN_ROOT}/check.js\""
}
]
}
]
}
}
```
* `matcher`: Filters which tool names trigger the hook
* `${QODER_PLUGIN_ROOT}`: Absolute path to the plugin's installation directory. Use it to reference internal plugin resources (scripts, configs, etc.) — paths resolve correctly regardless of where the plugin is installed
For supported event types and detailed configuration, see the Hooks documentation.
## Project Instructions (qoder.md)
`qoder.md` is the plugin-level project instructions file, defining the agent persona, workflow orchestration, and guardrails. It is injected as the core system prompt when the plugin is activated. File name is `qoder.md`. QoderWork also recognizes `qoderwork.md`.
## Connector Dependencies (CONNECTORS.md)
`CONNECTORS.md` documents connector dependencies for plugin users — which skills depend on which connections, what resources are accessed, and how to configure them.
Example:
```markdown theme={null}
# Connector Dependencies
## Audit Log
- **Purpose**: skill "Query Logs" depends on this connector to read audit logs
- **Resource**: Audit log API
- **Setup**: Visit https://example.com/mcp-setup to obtain your personal MCP Server URL
## Enterprise Database
- **Purpose**: skill "Generate Reports" depends on this connector to query business data
- **Resource**: PostgreSQL read-only replica
- **Setup**: Contact your DBA to obtain a read-only connection string
```
This file helps users quickly understand which external connections need to be configured after installing the plugin, along with each connection's permissions and security boundaries.
## Commands Object Format
When `commands` is an object, each command can have detailed configuration:
| Field | Type | Description |
| -------------- | ------ | ----------------------------- |
| `source` | string | Command Markdown file path |
| `description` | string | Command description |
| `argumentHint` | string | Argument hint, e.g. `"[env]"` |
## Packaging and Distribution
### Package Format
Plugins are distributed as `.zip` files:
No extra nesting — the manifest sits directly under the zip root.
`.qoder-plugin/plugin.json` is required.
Recommended filename: `{name}-{version}.zip`.
Correct structure:
```plaintext theme={null}
deploy-helper-2.0.0.zip
├── .qoder-plugin/
│ └── plugin.json
├── skills/
├── hooks/
│ └── hooks.json
├── mcp.json
├── CONNECTORS.md
└── README.md
```
### Path Rules
* All relative paths must start with `./`
* `..` is not allowed (no path traversal)
* JSON paths must end with `.json`
* Markdown paths must end with `.md`
## FAQ
### What's the difference between a plugin and a standalone skill?
Standalone skills are for single-project use (placed in `.qoder/skills/`). Plugins are for cross-project sharing and enterprise distribution — bundling multiple skills and configurations as one unit.
### Where does plugin.json go?
It must be at `.qoder-plugin/plugin.json`.
### How to handle MCP Servers requiring personal credentials?
Use declarative Connector configuration (`{{USER_CONFIG}}` placeholder + `_setup` guidance). Each user fills in their own credentials during installation.
## Client Support Matrix
Supported Coming Soon N/A
| Component | Qoder Desktop | Qoder CLI | JetBrains Plugin | QoderWork |
| ------------------------------- | ------------------------------------- | ------------------------------------- | ------------------------------------- | ------------------------------------- |
| Skills (SKILL.md) | | | | |
| Rules (.md) | | | | |
| Agents (.md) | | | | |
| Commands | | | | |
| MCP Servers | | | | |
| Hooks (hooks.json) | | | | |
| Project Instructions (qoder.md) | | | | |