Creating Plugins ​

Plugins let you extend CodeBuddy Code's functionality with custom skills, agents, hooks, and MCP servers. This guide covers how to create your own plugins.

To install existing plugins, see Plugin Marketplaces. For complete technical specifications, refer to the Plugin Reference Documentation.

When to Use Plugins vs Standalone Configuration ​

CodeBuddy Code supports two ways to add custom skills, agents, and hooks:

MethodSkill NameSuitable Scenarios
Standalone configuration (.codebuddy/ directory)/helloPersonal workflows, project-specific customizations, quick experiments
Plugin (directory containing .codebuddy-plugin/plugin.json)/plugin-name:helloTeam sharing, community distribution, versioned releases, cross-project reuse

Use standalone configuration when:

  • Customizing CodeBuddy Code for a single project
  • The configuration is personal and doesn't need to be shared
  • Experimenting with skills or hooks before packaging them as a plugin
  • You need short skill names like /hello or /deploy

Use plugins when:

  • Sharing functionality with a team or community
  • The same skills/agents need to be used across multiple projects
  • Version control and convenient update mechanisms are required
  • Distributing through a marketplace
  • You can accept namespaced skill names like /my-plugin:hello (namespacing prevents conflicts between plugins)

Tip: Start with standalone configuration in .codebuddy/ for fast iteration, then convert to a plugin when you're ready to share.

Quick Start ​

This quick start walks you through creating a plugin that contains a custom skill. You'll create a manifest file (the configuration file that defines the plugin), add a skill, and test it locally with the --plugin-dir argument.

Prerequisites ​

If you don't see the /plugin command, update CodeBuddy Code to the latest version. See Troubleshooting for upgrade instructions.

Create Your First Plugin ​

Step 1: Create the plugin directory ​

Each plugin has its own directory containing the manifest file and your skills, agents, or hooks. Create one now:

bash
mkdir my-first-plugin

Step 2: Create the plugin manifest ​

The manifest file is located at .codebuddy-plugin/plugin.json and defines the plugin's identity: 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:

bash
mkdir my-first-plugin/.codebuddy-plugin

Then create my-first-plugin/.codebuddy-plugin/plugin.json with the following content:

json
{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}
FieldPurpose
nameUnique identifier and skill namespace. Skills are prefixed with this (e.g., /my-first-plugin:hello)
descriptionDisplayed when browsing or installing the plugin in the plugin manager
versionTrack releases using semantic versioning
authorOptional. Used for attribution

For more fields like homepage, repository, and license, see the complete manifest schema.

Step 3: Add a skill ​

Skills are placed in the skills/ directory. Each skill is a folder containing a SKILL.md file. The folder name becomes the skill name and is prefixed with the plugin namespace (in a plugin named my-first-plugin, hello/ creates /my-first-plugin:hello).

Create the skill directory in your plugin directory:

bash
mkdir -p my-first-plugin/skills/hello

Then create my-first-plugin/skills/hello/SKILL.md with the following content:

markdown
---
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: Test your plugin ​

Run CodeBuddy Code with the --plugin-dir argument to load your plugin:

bash
codebuddy --plugin-dir ./my-first-plugin

After startup, try your new skill:

/my-first-plugin:hello

You'll see CodeBuddy reply with a greeting. Run /help to see your skill listed under the plugin namespace.

Why namespacing? Plugin skills are always namespaced (e.g., /my-first-plugin:hello) to prevent conflicts when multiple plugins have skills with the same name. To change the namespace prefix, update the name field in plugin.json.

Step 5: Add skill arguments ​

Make the skill more dynamic by accepting user input. The $ARGUMENTS placeholder captures any text the user provides after the skill name.

Update your SKILL.md file:

markdown
---
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've successfully created and tested a plugin containing the following key components:

  • Plugin manifest (.codebuddy-plugin/plugin.json): Metadata describing the plugin
  • Skill directory (skills/): Contains your custom skills
  • Skill arguments ($ARGUMENTS): Capture user input for dynamic behavior

The --plugin-dir argument is for development and testing. When you're ready to share your plugin with others, see Plugin Marketplaces.

Plugin Structure Overview ​

You've created a plugin containing a skill, but plugins can include much more: custom agents, hooks, MCP servers, and LSP servers.

Common mistake: Don't put 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.

DirectoryLocationPurpose
.codebuddy-plugin/Plugin rootContains the plugin.json manifest
commands/Plugin rootSlash commands in Markdown format
agents/Plugin rootCustom agent definitions
skills/Plugin rootAgent skills containing SKILL.md files
hooks/Plugin roothooks.json event handlers
.mcp.jsonPlugin rootMCP server configuration
.lsp.jsonPlugin rootLSP server configuration (code intelligence)
bin/Plugin rootExecutables added to the Bash tool's PATH when the plugin is enabled
settings.jsonPlugin rootDefault 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/                       # Executables 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 ​

Once you've mastered basic plugins, you can create more sophisticated extensions.

Adding Skills ​

Plugins can include agent skills to extend CodeBuddy's capabilities. Skills are model-invoked: CodeBuddy automatically uses them based on task context.

Add a skills/ directory at the plugin root containing skill folders with SKILL.md files:

my-plugin/
├── .codebuddy-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

Each SKILL.md needs frontmatter containing name and description fields, followed by instructions:

markdown
---
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 skill. For a complete guide to writing skills, including progressive disclosure and tool restrictions, see Agent Skills.

Adding Commands ​

Plugins can provide custom slash commands that users can manually trigger. Commands are defined as Markdown files.

Example: commands/example.md

markdown
---
description: "Example command description"
argument-hint: "[argument]"
---

This is an example command. It executes when the user enters /my-plugin:example.

Argument: $ARGUMENTS

Commands are registered in the format /plugin-name:command-name.

For detailed information, refer to the Slash Commands documentation.

Adding Hooks ​

Hooks allow operations to be automatically executed when specific events occur. Commands receive hook input JSON data via standard input and can use jq to extract fields.

Example: hooks/hooks.json

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

Hooks in a plugin's hooks/hooks.json are automatically merged (not overwritten) with user- and project-level hooks when the plugin is enabled, and are not subject to the allowUntrustedFrontmatterHooks gate (which only applies to hooks declared in Agent / Skill frontmatter).

In addition to command, hooks also support type: prompt (small-model semantic decisions), type: agent (subagent validation), and type: http (POST/PUT/PATCH to a specified URL). See the Hooks documentation for details. If your plugin also needs to ship frontmatter hooks bundled with a Skill, refer to the Skills documentation - Configuring Hooks in a Skill (note that this path is subject to the security gate).

For detailed information, refer to the Hooks documentation.

Adding LSP Servers ​

For common languages such as TypeScript, Python, and Rust, it is recommended to install pre-built LSP plugins directly from the official plugin marketplace. Only create custom LSP plugins when you need to support languages not yet covered.

LSP (Language Server Protocol) plugins provide real-time code intelligence to CodeBuddy. If you need support for a language without an official LSP plugin, you can add a .lsp.json file to the plugin:

json
{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Users who install the plugin must have the language server binaries pre-installed on their machine.

Multi-Language Configuration Example ​

json
{
  "python": {
    "command": "pylsp",
    "args": [],
    "extensionToLanguage": {
      ".py": "python"
    }
  },
  "rust": {
    "command": "rust-analyzer",
    "args": [],
    "extensionToLanguage": {
      ".rs": "rust"
    }
  }
}

Installation Requirements ​

When users install plugins that include LSP configurations, they must have the corresponding language server binaries pre-installed on their system:

  • Go: go install golang.org/x/tools/gopls@latest
  • Python: pip install python-lsp-server
  • Rust: rustup component add rust-analyzer

Bundling Default Settings ​

Plugins can include a settings.json file at the root that applies 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 restrictions, and model. This allows the plugin to change CodeBuddy Code's default behavior when enabled.

json
{
  "agent": "security-reviewer"
}

This example activates the security-reviewer agent defined in the plugin's agents/ directory. Settings in settings.json take precedence over the settings declared in plugin.json. Unknown keys are silently ignored.

Testing Plugins Locally ​

Use the --plugin-dir argument to test plugins during development. This loads your plugin directly without installation.

bash
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 lets you test changes to an installed plugin without uninstalling it. Marketplace plugins force-enabled via managed settings are the only exception and cannot be overridden.

While modifying a plugin, run /reload-plugins to pick up updates without restarting. This reloads plugins, skills, agents, hooks, plugin MCP servers, and plugin LSP servers. Test your plugin components:

  • Try skills with /plugin-name:skill-name
  • Check that agents appear in /agents
  • Verify hooks work as expected

You can load multiple plugins simultaneously by specifying the argument multiple times:

bash
codebuddy --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Debugging Plugin Issues ​

If a plugin is not working as expected:

  1. Check structure: Make sure 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 argument to see detailed logs

plugin.json Manifest Format ​

The plugin manifest file defines the plugin's metadata and included components, located at .codebuddy-plugin/plugin.json:

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 complete manifest schema documentation, see the Plugin Reference Documentation.

Sharing Your Plugin ​

When your plugin is ready to share:

  1. Add documentation: Include a README.md describing installation and usage
  2. Version management: Use semantic versioning in plugin.json
  3. Create or use a marketplace: Distribute via plugin marketplaces
  4. Test with others: Have team members test the plugin before broader distribution

Once your plugin is published to a marketplace, others can install and use it by following the instructions in Plugin Marketplaces.

Converting Existing Configuration to a Plugin ​

If you already have skills or hooks in the .codebuddy/ directory, you can convert them to a plugin for easier sharing and distribution.

Migration Steps ​

Step 1: Create the plugin structure ​

Create a new plugin directory:

bash
mkdir -p my-plugin/.codebuddy-plugin

Create the manifest file my-plugin/.codebuddy-plugin/plugin.json:

json
{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

Step 2: Copy existing files ​

Copy your existing configuration to the plugin directory:

bash
# Copy commands
cp -r .codebuddy/commands my-plugin/

# Copy agents (if any)
cp -r .codebuddy/agents my-plugin/

# Copy skills (if any)
cp -r .codebuddy/skills my-plugin/

Step 3: Migrate Hooks ​

If you have hooks in your settings, create the hooks directory:

bash
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 — the format is the same. Commands receive hook input JSON data via standard input and can use jq to extract fields:

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

Step 4: Test the migrated plugin ​

Load the plugin to verify everything works:

bash
codebuddy --plugin-dir ./my-plugin

Test each component: run your commands, check agents in /agents, and verify hooks trigger correctly.

Before vs After Migration ​

Standalone Configuration (.codebuddy/)Plugin
Available in only one projectShareable via marketplaces
Files in .codebuddy/commands/Files in plugin-name/commands/
Hooks in settings.jsonHooks in hooks/hooks.json
Manual copy required for sharingInstall via /plugin install

After migration, you can delete the original files in .codebuddy/ to avoid duplication. The plugin version takes precedence when loaded.

Best Practices ​

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 (Semantic Versioning)
  4. Complete documentation: Provide clear descriptions for each command and skill
  5. Thorough testing: Test plugins locally with --plugin-dir before publishing

Security Considerations ​

  1. Only install plugins from trusted sources: Plugins can execute commands and access the filesystem
  2. Review plugin code: Check plugin commands and hooks before installation
  3. Use permission controls: Limit plugin access through CodeBuddy's permission system

Troubleshooting ​

Plugin Not Loading ​

Problem: Plugin is installed but not working

Solution:

  • Confirm the plugin is enabled: run /plugin and go to the "Installed" tab
  • Check that plugin.json format is correct
  • Run /reload-plugins to reload plugins
  • Use --debug mode to view loading logs

Command Not Available ​

Problem: Plugin is installed but commands are unavailable

Solution:

  • Confirm command files are placed in the plugin root's commands/, not inside .codebuddy-plugin/
  • Check that command files exist and have the correct format
  • Run /reload-plugins to refresh

Validation and Testing ​

Test your plugin before sharing:

bash
# Validate 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

Next Steps ​

For Plugin Users ​

For Plugin Developers ​