Plugin System

Download

Focus Mode

Font Size

Last updated: 2026-09-30 18:41:46

AI-Translated

Plugins allow you to extend the features of CodeBuddy Code through custom skills, agents, hooks, and MCP servers. This guide covers how to create your own plugins.
To install existing plugins, see Plugin Marketplace. For the complete technical specification, see Plugin Reference.
When to Use Plugins vs. Standalone Configurations
CodeBuddy Code supports two ways to add custom skills, agents, and hooks: 
Method
Skill Name
Scenario
Standalone configuration (.codebuddy/ directory)
/hello
Personal workflows, project-specific customization, and quick experiments
Plugin (directory containing .codebuddy-plugin/plugin.json)
/plugin-name:hello
Team sharing, community distribution, versioned release, and cross-project reuse
Scenarios for using standalone configuration:
Customize CodeBuddy Code for a single project.
Configuration is personal and does not need to be shared.
Experiment with skills or hooks before packaging them as a plugin.
A short skill name is required, such as /hello or /deploy.
Scenarios for using plugins:
You need to share features with your team or community.
You need to use the same skills/agents across multiple projects.
Requires version control and a convenient update mechanism.
Distribute through the marketplace.
Namespaced skill names are accepted, such as /my-plugin:hello (namespaces prevent conflicts between plugins).
Note:
First, iterate quickly with a standalone configuration in .codebuddy/, and convert it to a plugin when you are ready to share.
Quick Start
This quickstart guides you through creating a plugin that includes a custom skill. You will create a manifest file (the configuration file that defines the plugin), add a skill, and test it locally using the --plugin-dir parameter.
Prerequisites
CodeBuddy Code is installed and authenticated.
Note:
If the /plugin command is not visible, update CodeBuddy Code to the latest version.
Creating Your First Plugin
Step 1: Creating the Plugin Directory
Each plugin has its own directory that contains the manifest file and your skills, agents, or hooks. Create one now:
mkdir my-first-plugin
Step 2: Creating the Plugin Manifest
The manifest file is located at .codebuddy-plugin/plugin.json and defines the plugin's identity information: name, description, and version. CodeBuddy Code uses this metadata to display your plugin in the plugin manager. Create the .codebuddy-plugin directory inside the plugin directory:
mkdir my-first-plugin/.codebuddy-plugin
Then create my-first-plugin/.codebuddy-plugin/plugin.json with the following content:
{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}
Field
Purpose
name
Unique identifier and skill namespace. Skills use this as a prefix (for example, /my-first-plugin:hello)
description
Displayed when the plugin is browsed or installed in the plugin manager.
version
Track releases using semantic versioning.
author
Optional. Used for attribution.
For more fields such as homepage, repository, and license, see the complete manifest Schema.
Step 3: Adding Skills
Skills are placed in the skills/ directory. Each skill is a folder that contains a SKILL.md file. The folder name becomes the skill name, prefixed with the plugin namespace (in a plugin named my-first-plugin, hello/ creates /my-first-plugin:hello). Create the skill directory in the plugin directory:
mkdir -p my-first-plugin/skills/hello
Then create my-first-plugin/skills/hello/SKILL.md with the following content:
---
description: Greet the user with a friendly message
disable-model-invocation: true
---
﻿
Greet the user warmly and ask how you can help them today.
Step 4: Testing Your Plugin
Run CodeBuddy Code with the --plugin-dir flag to load your plugin:
codebuddy --plugin-dir ./my-first-plugin
After startup, try your new skill:
/my-first-plugin:hello
You will see CodeBuddy reply with a greeting. Run /help to see your skill listed under the plugin namespace.
Why namespaces? Plugin skills always carry a namespace (such as /my-first-plugin:hello) to prevent conflicts between skills with the same name in different plugins. To change the namespace prefix, update the name field in plugin.json.
Step 5: Adding Skill Parameters
Make skills more dynamic by accepting user input. The $ARGUMENTS placeholder captures any text the user provides after the skill name. Update your SKILL.md file:
---
description: Greet the user with a personalized message
---
﻿
# Hello Skill
﻿
Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.
Run /reload-plugins to pick up the changes, then try the skill with your name:
/my-first-plugin:hello Alex
CodeBuddy will greet you by name. For more information about passing arguments to skills, see the Skills documentation.
You have successfully created and tested a plugin that includes the following key components:
Plugin manifest (.codebuddy-plugin/plugin.json): describes the plugin's metadata
Skills directory (skills/): contains your custom skills
Skill arguments ($ARGUMENTS): captures user input to enable dynamic behavior
The --plugin-dir parameter is intended for development and testing. When you are ready to share your plugin with others, see Plugin Marketplace.
Plugin Structure Overview
You have created a plugin that includes a skill, but plugins can contain much more: custom agents, hooks, MCP servers, and LSP servers.
Common mistake: Do not place commands/, agents/, skills/, or hooks/ inside the .codebuddy-plugin/ directory. Only plugin.json goes inside .codebuddy-plugin/. All other directories must be at the plugin root level.
Directory
Position
Purpose
.codebuddy-plugin/
Plugin root directory
Contains the plugin.json manifest
commands/
Plugin root directory
Slash commands in Markdown format
agents/
Plugin root directory
Custom agent definitions
skills/
Plugin root directory
Agent skills that include the SKILL.md file
hooks/
Plugin root directory
hooks.json event handler
.mcp.json
Plugin root directory
MCP server configuration
.lsp.json
Plugin root directory
LSP server configuration (code intelligence)
bin/
Plugin root directory
Executable files added to the Bash tool PATH when the plugin is enabled
settings.json
Plugin root directory
Default settings applied when the plugin is enabled
Example complete structure:
my-plugin/
├── .codebuddy-plugin/        # Metadata directory (required)
│   └── plugin.json           # Plugin manifest file
├── commands/                  # Commands directory (optional)
│   └── example.md
├── agents/                    # Agents directory (optional)
│   └── example.md
├── skills/                    # Skills directory (optional)
│   └── code-review/
│       └── SKILL.md
├── hooks/                     # Hooks directory (optional)
│   └── hooks.json
├── bin/                       # Executable files directory (optional)
│   └── my-tool
├── .mcp.json                  # MCP configuration file (optional)
├── .lsp.json                  # LSP configuration file (optional)
└── settings.json              # Default settings file (optional)
Developing More Complex Plugins
After mastering basic plugins, you can create more complex extensions.
Adding Skills
Plugins can include agent skills to extend the capabilities of CodeBuddy. Skills are invoked by the model: CodeBuddy automatically uses them based on the task context.
Add a skills/ directory in the plugin root directory, which contains skill folders with SKILL.md files:
my-plugin/
├── .codebuddy-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md
Each SKILL.md must contain frontmatter with name and description fields, followed by instructions:
---
name: code-review
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---
﻿
When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage
After installing the plugin, run /reload-plugins to load the skills. For a complete guide to writing skills, including progressive disclosure and tool limitations, see Agent Skills.
Adding Commands
Plugins can provide custom slash commands that users can trigger manually. Commands are defined as Markdown files.
Example: commands/example.md
---
description: "Example command description"
argument-hint: "[parameter]"
---
﻿
This is an example command. It is executed when the user enters /my-plugin:example.
﻿
Arguments: $ARGUMENTS
Commands are registered in the format /plugin-name:command-name. For details, see the Slash Commands documentation.
Adding Hooks
Hooks allow operations to be executed automatically when specific events occur. The command receives JSON data from the hook through standard input, and you can use jq to extract fields.
Example: hooks/hooks.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}
hooks in the plugin's hooks/hooks.json file are automatically merged with user-level and project-level hooks when the plugin is enabled (without overwriting them), and are not subject to the allowUntrustedFrontmatterHooks gate (which applies only to hooks declared in Agent / Skill frontmatter).
In addition to command, hooks also support three execution methods: type: prompt (semantic determination by a small model), type: agent (subagent validation), and type: http (POST/PUT/PATCH to a specified URL). For details, see the Hooks documentation. If your plugin also needs to carry frontmatter hooks with a Skill, see Skills documentation - Configuring Hooks in a Skill (note that this path is subject to a security gate). For detailed instructions, see the Hooks documentation.
Adding an LSP Server
For common languages such as TypeScript, Python, and Rust, install prebuilt LSP plugins directly from the official plugin marketplace. Create a custom LSP plugin only when you need to support a language that is not yet covered.
LSP (Language Server Protocol) plugins provide real-time code intelligence for CodeBuddy. To support a language that does not have an official LSP plugin, add a .lsp.json file to your plugin:
{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}
Users who install the plugin must have the language server binary preinstalled on their machines.
Multilingual Configuration Example
{
  "python": {
    "command": "pylsp",
    "args": [],
    "extensionToLanguage": {
      ".py": "python"
    }
  },
  "rust": {
    "command": "rust-analyzer",
    "args": [],
    "extensionToLanguage": {
      ".rs": "rust"
    }
  }
}
Installation Requirements
When installing a plugin that includes LSP configuration, users must have the corresponding language server binary preinstalled on their systems:
Go: go install golang.org/x/tools/gopls@latest
Python: pip install python-lsp-server
Rust: rustup component add rust-analyzer
Carrying Default Settings
A plugin can include a settings.json file in its root directory to apply default configuration when the plugin is enabled. Currently, only the agent key is supported. Setting agent activates one of the plugin's custom agents as the main thread, applying its system prompt, tool limits, and model. This allows the plugin to change the default behavior of CodeBuddy Code when the plugin is enabled.
{
  "agent": "security-reviewer"
}
This example activates the security-reviewer agent defined in the plugin's agents/ directory. Settings in settings.json take precedence over settings declared in plugin.json. Unknown keys are silently ignored.
Testing Plugins Locally
Use the --plugin-dir parameter to test your plugin during development. This loads your plugin directly without installation.
codebuddy --plugin-dir ./my-plugin
When a --plugin-dir plugin has the same name as an installed marketplace plugin, the local copy takes precedence in that session. This allows you to test changes to an installed plugin without uninstalling it. The only exception is a marketplace plugin that is force-enabled through managed settings, which cannot be overridden.
When modifying plugins, run /reload-plugins to get updates without restarting. This reloads plugins, skills, agents, hooks, plugin MCP servers, and plugin LSP servers. Test your plugin components:
Try the skill using /plugin-name:skill-name
Check whether the agent appears in /agents.
Verify that the hook works as expected.
You can load multiple plugins at the same time by specifying the parameter multiple times:
codebuddy --plugin-dir ./plugin-one --plugin-dir ./plugin-two
Debugging Plugin Issues
If the plugin does not work as expected:
1. Check the structure: Make sure the directories are at the plugin root, not inside .codebuddy-plugin/.
2. Test components individually: Check each command, agent, and hook separately.
3. Use debug mode: Start CodeBuddy with the --debug parameter to view detailed logs.
plugin.json Manifest Format
The plugin manifest file defines the plugin's metadata and included components, located at .codebuddy-plugin/plugin.json:
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": {
    "name": "Author name",
    "email": "author@example.com"
  },
  "homepage": "https://github.com/username/my-plugin",
  "repository": "https://github.com/username/my-plugin",
  "keywords": ["example"],
  "category": "Development Tools",
  "commands": [],
  "agents": [],
  "skills": [],
  "hooks": "./hooks/hooks.json"
}
For the complete manifest Schema, see the Plugin Reference.
Sharing Your Plugin
When the plugin is ready to be shared:
1. Add documentation: Include a README.md that explains installation and usage.
2. Version management: Use Semantic Versioning in plugin.json.
3. Create or use a marketplace: Distribute through the Plugin Marketplace.
4. Test with others: Have team members test the plugin before wider distribution.
After a plugin is published to the marketplace, others can install and use it by following the instructions in the Plugin Marketplace.
Converting Existing Configurations into Plugins
If you already have skills or hooks in the .codebuddy/ directory, you can convert them into plugins for easier sharing and distribution.
Migration Steps
Step 1: Creating the Plugin Structure
Create a new plugin directory:
mkdir -p my-plugin/.codebuddy-plugin
Create the manifest file my-plugin/.codebuddy-plugin/plugin.json:
{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}
Step 2: Copying Existing Files
Copy the existing configuration to the plugin directory:
# Copy the command
cp -r .codebuddy/commands my-plugin/
﻿
# Copy the agent (if any)
cp -r .codebuddy/agents my-plugin/
﻿
# Copy the skill (if any)
cp -r .codebuddy/skills my-plugin/
Step 3: Migrating Hooks
If your settings include hooks, create the hooks directory:
mkdir my-plugin/hooks
Create my-plugin/hooks/hooks.json and place the hooks configuration in it. Copy the hooks object from .codebuddy/settings.json or settings.local.json, as the format is the same. The command receives the hook input JSON data through standard input, and you can use jq to extract fields:
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}
Step 4: Testing the Migrated Plugin
Load the plugin and verify that everything works correctly:
codebuddy --plugin-dir ./my-plugin
Test each component: run your commands, check the agents in /agents, and verify that hooks trigger correctly.
Comparison Before and After Migration
Standalone Configuration (.codebuddy/)
Plugins
Available in only one project
Can be shared through the marketplace
Files are in .codebuddy/commands/
Files are in plugin-name/commands/
Hooks are in settings.json
Hooks are in hooks/hooks.json
Manual copy is required for sharing.
Install using /plugin install
After migration, you can delete the original files in .codebuddy/ to avoid duplication. The plugin version is used preferentially during loading.
Usage Recommendations
Plugin Development Recommendations
1. Follow naming conventions: Use clear, descriptive plugin names (kebab-case, no spaces).
2. Provide complete metadata: Provide detailed descriptions and author information in plugin.json.
3. Version management: Use Semantic Versioning.
4. Documentation completeness: Provide clear descriptions for each command and skill.
5. Test thoroughly: Test the plugin locally with --plugin-dir before publishing.
Security Considerations
1. Install plugins only from trusted sources: Plugins can run commands and access the file system.
2. Review plugin code: Inspect the plugin's commands and Hooks before installation.
3. Use permission control: Restrict plugin access through CodeBuddy's permission system.
Troubleshooting
Plugin Not Loading
Problem: The plugin is installed but not working.
Solutions:
Confirm that the plugin is enabled: Run /plugin and go to the "Installed" tab to check.
Check whether the format of plugin.json is correct.
Run /reload-plugins to reload plugins.
Use --debug mode to view loading logs.
Command Unavailable
Problem: The plugin is installed but its commands cannot be used.
Solutions:
Confirm that the command files are placed in commands/ at the plugin root, not inside .codebuddy-plugin/.
Check whether the command file exists and is in the correct format.
Run /reload-plugins to refresh.
Verification and Testing
Test your plugin before sharing it:
# Verify the plugin format
codebuddy plugin validate /path/to/plugin
﻿
# Test locally with --plugin-dir
codebuddy --plugin-dir ./my-plugin
﻿
# Test the plugin's skills
/my-plugin:skill-name
Following Steps
For Plugin Users
Plugin Marketplace - Browse the marketplace and install plugins.
Settings - Learn about plugin configuration options.
For Plugin Developers
Plugin Marketplace - Package and share your plugin.
Plugin Reference - Complete technical specification
Dive deeper into specific plugin components:
Skills - Skill development details
Subagent - Agent configuration and capabilities
Hooks - Event handling and automation
MCP - External tool integration
﻿

Help and Support

Was this page helpful?

You can also Contact sales or Submit a Ticket for help.

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Standalone Configuration (`.codebuddy/`)	Plugins
Available in only one project	Can be shared through the marketplace
Files are in `.codebuddy/commands/`	Files are in `plugin-name/commands/`
Hooks are in `settings.json`	Hooks are in `hooks/hooks.json`
Manual copy is required for sharing.	Install using `/plugin install`

Method	Skill Name	Scenario
Standalone configuration (`.codebuddy/` directory)	`/hello`	Personal workflows, project-specific customization, and quick experiments
Plugin (directory containing `.codebuddy-plugin/plugin.json`)	`/plugin-name:hello`	Team sharing, community distribution, versioned release, and cross-project reuse

Field	Purpose
`name`	Unique identifier and skill namespace. Skills use this as a prefix (for example, `/my-first-plugin:hello`)
`description`	Displayed when the plugin is browsed or installed in the plugin manager.
`version`	Track releases using semantic versioning.
`author`	Optional. Used for attribution.

Directory	Position	Purpose
`.codebuddy-plugin/`	Plugin root directory	Contains the `plugin.json` manifest
`commands/`	Plugin root directory	Slash commands in Markdown format
`agents/`	Plugin root directory	Custom agent definitions
`skills/`	Plugin root directory	Agent skills that include the `SKILL.md` file
`hooks/`	Plugin root directory	`hooks.json` event handler
`.mcp.json`	Plugin root directory	MCP server configuration
`.lsp.json`	Plugin root directory	LSP server configuration (code intelligence)
`bin/`	Plugin root directory	Executable files added to the Bash tool `PATH` when the plugin is enabled
`settings.json`	Plugin root directory	Default settings applied when the plugin is enabled

tencent cloud

Tencent WorkBuddy Enterprise

Plugin System

When to Use Plugins vs. Standalone Configurations

Quick Start

Prerequisites

Creating Your First Plugin

Step 1: Creating the Plugin Directory

Step 2: Creating the Plugin Manifest

Step 3: Adding Skills

Step 4: Testing Your Plugin

Step 5: Adding Skill Parameters

Plugin Structure Overview

Developing More Complex Plugins

Adding Skills

Adding Commands

Adding Hooks

Adding an LSP Server

Multilingual Configuration Example

Installation Requirements

Carrying Default Settings

Testing Plugins Locally

Debugging Plugin Issues

plugin.json Manifest Format

Sharing Your Plugin

Converting Existing Configurations into Plugins

Migration Steps

Step 1: Creating the Plugin Structure

Step 2: Copying Existing Files

Step 3: Migrating Hooks

Step 4: Testing the Migrated Plugin

Comparison Before and After Migration

Usage Recommendations

Plugin Development Recommendations

Security Considerations

Troubleshooting

Plugin Not Loading

Command Unavailable

Verification and Testing

Following Steps

For Plugin Users

For Plugin Developers

Help and Support