@tencent-ai/codebuddy-code 2.97.0-next.943311f.20260514 → 2.97.0-next.bcf636d.20260514

package/dist/web-ui/docs/en/cli/plugins.md

@@ -1,427 +1,269 @@
-# CodeBuddy Plugin System
+# Creating Plugins
 
-CodeBuddy Code supports a powerful plugin system that allows you to extend and customize the CLI's functionality. Through plugins, you can add new commands, skills, and hooks, creating a personalized development environment that fits your workflow.
+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.
 
-## Core Concepts
+To install existing plugins, see [Plugin Marketplaces](plugin-marketplaces.md). For complete technical specifications, refer to the [Plugin Reference Documentation](plugins-reference.md).
 
-### What is a Plugin?
+## When to Use Plugins vs Standalone Configuration
 
-A plugin is a reusable functionality package that can contain the following components:
+CodeBuddy Code supports two ways to add custom skills, agents, and hooks:
 
-- **Commands**: Slash commands that users can manually trigger
-- **Skills**: Specialized capabilities that the AI automatically recognizes and invokes
-- **Hooks**: Operations that automatically execute when specific events are triggered
+| Method | Skill Name | Suitable Scenarios |
+|--------|------------|--------------------|
+| **Standalone configuration** (`.codebuddy/` directory) | `/hello` | Personal workflows, project-specific customizations, quick experiments |
+| **Plugin** (directory containing `.codebuddy-plugin/plugin.json`) | `/plugin-name:hello` | Team sharing, community distribution, versioned releases, cross-project reuse |
 
-### What is a Plugin Marketplace?
+**Use standalone configuration when**:
 
-A plugin marketplace is a publishing and distribution channel for plugins. CodeBuddy supports multiple types of plugin marketplaces:
+- 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`
 
-- **Local Directory Marketplace**: Load plugins from the local filesystem
-- **GitHub Repository Marketplace**: Fetch plugins from GitHub repositories
-- **HTTP/HTTPS Marketplace**: Fetch plugin manifests and packages from HTTP(S) servers
+**Use plugins when**:
 
-## Quick Start
-
-There are three ways to manage plugins: **Team Configuration Auto-Installation**, **Interactive Interface**, and **Command-Line Subcommands**.
-
-### Method 1: Team Configuration Auto-Installation (Recommended)
-
-Teams can configure `extraKnownMarketplaces` and `enabledPlugins` in the project's `.codebuddy/settings.json` to enable automatic plugin installation and activation. When team members start CodeBuddy, the system automatically installs the plugin marketplaces and plugins specified in the configuration.
-
-#### Configuration Example
-
-Add the following configuration to `.codebuddy/settings.json`:
-
-```json
-{
-  "extraKnownMarketplaces": {
-    "team-marketplace": {
-      "source": {
-        "source": "github",
-        "repo": "your-org/team-plugins-marketplace"
-      }
-    },
-    "custom-marketplace": {
-      "source": {
-        "source": "git",
-        "url": "https://git.example.com/plugins-marketplace"
-      }
-    }
-  },
-  "enabledPlugins": {
-    "team-plugin-a@team-marketplace": true,
-    "team-plugin-b@team-marketplace": true
-  }
-}
-```
-
-#### Configuration Explanation
-
-- **`extraKnownMarketplaces`**: Define additional plugin marketplaces
-  - Key is the marketplace name (e.g., `team-marketplace`)
-  - `source.source`: Marketplace type, supports `github`, `git`, and `url`
-  - `source.repo`: GitHub repository path (format: `owner/repo`, only when source is `github`)
-  - `source.url`: Git repository URL or HTTP(S) marketplace.json URL (only when source is `git` or `url`)
-
-- **`enabledPlugins`**: Specify plugins to enable
-  - Key format: `plugin-name@marketplace-name`
-  - Value `true` means enabled, `false` means disabled
-
-#### Automatic Installation Flow
-
-1. **Startup Detection**: CodeBuddy automatically detects the configuration file on startup
-2. **Marketplace Installation**: Automatically installs marketplaces from `extraKnownMarketplaces` that are not yet installed
-3. **Plugin Installation**: Automatically installs enabled plugins from `enabledPlugins` that are not yet installed
-4. **Background Execution**: The installation process executes asynchronously in the background without blocking the startup flow
-5. **Logging**: The installation process logs detailed information, viewable with `--debug`
-
-#### Advantages
-
-- **Team Consistency**: Ensures team members use the same plugin configuration
-- **Automation**: No manual installation needed, improving development efficiency
-- **Version Control**: Configuration files can be committed to Git for team collaboration
-- **Flexible Override**: Individuals can override team configuration in their local configuration
-
-### Method 2: Interactive Interface
-
-Enter `/plugin` in CodeBuddy conversation to open the interactive plugin management interface.
-
-#### Opening the Management Interface
+- 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)
 
-```bash
-/plugin
-```
+> **Tip**: Start with standalone configuration in `.codebuddy/` for fast iteration, then [convert to a plugin](#converting-existing-configuration-to-a-plugin) when you're ready to share.
 
-#### Interface Features
-
-The interactive interface contains the following 6 tabs:
+## Quick Start
 
-1. **Discover** - Browse all available plugins, view installation counts, descriptions, and more
-   - Real-time plugin search
-   - Display plugin installation statistics
-   - Quick plugin installation
+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.
 
-2. **Browse** - Browse and install plugins from configured marketplaces
-   - Browse by marketplace category
-   - View plugin details
-   - Install plugins
+### Prerequisites
 
-3. **Installed** - Manage installed plugins
-   - View installed plugin list and status
-   - Enable/disable plugins
-   - Uninstall plugins
-   - View plugin details
+- CodeBuddy Code [installed and authenticated](quickstart.md)
 
-4. **Marketplaces** - Manage plugin marketplaces
-   - View configured marketplace list
-   - Update marketplace information
-   - Remove marketplaces
+> If you don't see the `/plugin` command, update CodeBuddy Code to the latest version. See [Troubleshooting](troubleshooting.md) for upgrade instructions.
 
-5. **Add Marketplace** - Add new plugin marketplace sources
-   - Support local paths, GitHub repositories, Git URLs, and HTTP URLs
-   - Automatic marketplace source type detection
-   - Set marketplace display name
+### Create Your First Plugin
 
-6. **Errors** - View errors that occurred during plugin loading and operations
-   - Detailed error information and error types
-   - Error timestamps and related context
-   - Help diagnose and resolve issues
+#### Step 1: Create the plugin directory
 
-#### Interactive Command Examples
+Each plugin has its own directory containing the manifest file and your skills, agents, or hooks. Create one now:
 
 ```bash
-/plugin                                    # Open management interface
-/plugin install my-plugin                  # Install plugin
-/plugin install my-plugin@marketplace      # Install from specified marketplace
-/plugin enable my-plugin                   # Enable disabled plugin
-/plugin disable my-plugin                  # Disable enabled plugin
-/plugin uninstall my-plugin                # Uninstall plugin
-/plugin marketplace add <source>           # Add marketplace
-/plugin marketplace list                   # List marketplaces
-/plugin marketplace update <name>          # Update marketplace
-/plugin marketplace remove <name>          # Remove marketplace
+mkdir my-first-plugin
 ```
 
-### Method 3: Command-Line Subcommands
+#### Step 2: Create the plugin manifest
 
-Use the `codebuddy plugin` command in the terminal for management.
+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.
 
-#### Plugin Operations
+Create the `.codebuddy-plugin` directory inside the plugin directory:
 
 ```bash
-# Install plugin
-codebuddy plugin install <plugin>              # Install from default marketplace
-codebuddy plugin install <plugin>@<marketplace> # Install from specified marketplace
-codebuddy plugin i <plugin>                    # Shorthand form
-
-# Enable and disable plugins
-codebuddy plugin enable <plugin>               # Enable plugin
-codebuddy plugin disable <plugin>              # Disable plugin
-
-# Uninstall plugin
-codebuddy plugin uninstall <plugin>            # Uninstall plugin
-codebuddy plugin remove <plugin>               # Alias form
-
-# Validate plugin or marketplace manifest
-codebuddy plugin validate <path>               # Validate local plugin or marketplace
+mkdir my-first-plugin/.codebuddy-plugin
 ```
 
-#### Marketplace Management
+Then create `my-first-plugin/.codebuddy-plugin/plugin.json` with the following content:
 
-```bash
-# Add marketplace
-codebuddy plugin marketplace add <source>
-codebuddy plugin marketplace add <source> -n <name>   # Specify marketplace name
-
-# List marketplaces
-codebuddy plugin marketplace list
-
-# Update marketplace
-codebuddy plugin marketplace update <name>
-
-# Remove marketplace
-codebuddy plugin marketplace remove <name>
-codebuddy plugin marketplace rm <name>                # Alias form
+```json
+{
+  "name": "my-first-plugin",
+  "description": "A greeting plugin to learn the basics",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name"
+  }
+}
 ```
 
-## Plugin Management
+| Field | Purpose |
+|-------|---------|
+| `name` | Unique identifier and skill namespace. Skills are prefixed with this (e.g., `/my-first-plugin:hello`) |
+| `description` | Displayed when browsing or installing the plugin in the plugin manager |
+| `version` | Track releases using [semantic versioning](plugins-reference.md#version-management) |
+| `author` | Optional. Used for attribution |
 
-### Adding a Plugin Marketplace
+For more fields like `homepage`, `repository`, and `license`, see the [complete manifest schema](plugins-reference.md).
 
-#### Using the Interactive Interface
+#### Step 3: Add a skill
 
-1. Enter `/plugin`
-2. Select "3. Add marketplace"
-3. Enter the marketplace source address
-4. Wait for automatic marketplace type recognition and plugin manifest loading
+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`).
 
-#### Using Subcommands
+Create the skill directory in your plugin directory:
 
 ```bash
-# Add GitHub repository marketplace
-codebuddy plugin marketplace add https://github.com/username/plugin-repo
-
-# Add marketplace and specify display name
-codebuddy plugin marketplace add https://github.com/username/plugin-repo -n my-marketplace
-
-# Add local directory marketplace
-codebuddy plugin marketplace add /path/to/local/plugins
-
-# Add HTTP marketplace
-codebuddy plugin marketplace add https://example.com/plugins
+mkdir -p my-first-plugin/skills/hello
 ```
 
-**Parameter Explanation**:
-- `<source>`: Marketplace source address (local path, GitHub URL, or HTTP(S) URL)
-- `-n, --name <name>`: Optional, specify a display name for the marketplace
-
-### Installing Plugins
-
-#### Using the Interactive Interface
-
-1. Enter `/plugin`
-2. Select "1. Browse and install plugins"
-3. Select the plugin marketplace
-4. Browse available plugins and select to install
-
-#### Using Subcommands
-
-```bash
-# Install from default marketplace
-codebuddy plugin install my-plugin
+Then create `my-first-plugin/skills/hello/SKILL.md` with the following content:
 
-# Install from specified marketplace
-codebuddy plugin install my-plugin@marketplace-name
+```markdown
 
-# Using alias
-codebuddy plugin i my-plugin
+Greet the user warmly and ask how you can help them today.
 ```
 
-### Enabling and Disabling Plugins
-
-#### Using the Interactive Interface
+#### Step 4: Test your plugin
 
-1. Enter `/plugin`
-2. Select "2. Manage plugins"
-3. Select the plugin to enable or disable
-
-#### Using Subcommands
+Run CodeBuddy Code with the `--plugin-dir` argument to load your plugin:
 
 ```bash
-# Enable plugin
-codebuddy plugin enable my-plugin
-
-# Disable plugin
-codebuddy plugin disable my-plugin
+codebuddy --plugin-dir ./my-first-plugin
 ```
 
-**Note**: CodeBuddy must be restarted after enabling/disabling plugins for changes to take effect.
+After startup, try your new skill:
 
-### Uninstalling Plugins
+```
+/my-first-plugin:hello
+```
 
-#### Using the Interactive Interface
+You'll see CodeBuddy reply with a greeting. Run `/help` to see your skill listed under the plugin namespace.
 
-1. Enter `/plugin`
-2. Select "2. Manage plugins"
-3. Select the plugin to uninstall and confirm uninstallation
+> **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`.
 
-#### Using Subcommands
+#### Step 5: Add skill arguments
 
-```bash
-# Uninstall plugin
-codebuddy plugin uninstall my-plugin
+Make the skill more dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the skill name.
 
-# Using alias
-codebuddy plugin remove my-plugin
-```
-
-### Managing Plugin Marketplaces
+Update your `SKILL.md` file:
 
-#### List Marketplaces
+```markdown
+---
+description: Greet the user with a personalized message
+---
 
-Using the interactive interface:
-1. Enter `/plugin`
-2. Select "4. Manage marketplaces"
+# Hello Skill
 
-Using subcommands:
-```bash
-codebuddy plugin marketplace list
+Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.
 ```
 
-#### Update Marketplace
+Run `/reload-plugins` to pick up the changes, then try the skill with your name:
 
-Using the interactive interface:
-1. Enter `/plugin`
-2. Select "4. Manage marketplaces"
-3. Select the marketplace to update
-
-Using subcommands:
-```bash
-codebuddy plugin marketplace update my-marketplace
+```
+/my-first-plugin:hello Alex
 ```
 
-#### Remove Marketplace
+CodeBuddy will greet you by name. For more information about passing arguments to skills, see the [Skills documentation](skills.md).
 
-Using the interactive interface:
-1. Enter `/plugin`
-2. Select "4. Manage marketplaces"
-3. Select the marketplace to remove and confirm removal
+---
 
-Using subcommands:
-```bash
-codebuddy plugin marketplace remove my-marketplace
-codebuddy plugin marketplace rm my-marketplace
-```
+You've successfully created and tested a plugin containing the following key components:
 
-### Validating Plugin or Marketplace Manifests
+- **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
 
-```bash
-# Validate plugin manifest format
-codebuddy plugin validate /path/to/plugin
+> The `--plugin-dir` argument is for development and testing. When you're ready to share your plugin with others, see [Plugin Marketplaces](plugin-marketplaces.md).
 
-# Validate marketplace manifest format
-codebuddy plugin validate /path/to/marketplace
+## Plugin Structure Overview
 
-# Validate plugin manifest from GitHub
-codebuddy plugin validate https://github.com/username/plugin-repo
-```
+You've created a plugin containing a skill, but plugins can include much more: custom agents, hooks, MCP servers, and LSP servers.
 
-The validate command checks the format and completeness of `plugin.json` or `marketplace.json`.
+> **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.
 
-## Plugin Structure
+| Directory | Location | Purpose |
+|-----------|----------|---------|
+| `.codebuddy-plugin/` | Plugin root | Contains the `plugin.json` manifest |
+| `commands/` | Plugin root | Slash commands in Markdown format |
+| `agents/` | Plugin root | Custom agent definitions |
+| `skills/` | Plugin root | Agent skills containing `SKILL.md` files |
+| `hooks/` | Plugin root | `hooks.json` event handlers |
+| `.mcp.json` | Plugin root | MCP server configuration |
+| `.lsp.json` | Plugin root | LSP server configuration (code intelligence) |
+| `bin/` | Plugin root | Executables added to the Bash tool's `PATH` when the plugin is enabled |
+| `settings.json` | Plugin root | Default [settings](settings.md) applied when the plugin is enabled |
 
-### Standard Plugin Directory Structure
+**Example complete structure**:
 
 ```
 my-plugin/
-├── .codebuddy-plugin/     # Metadata directory (required)
-│   └── plugin.json        # Plugin manifest file
-├── commands/              # Commands directory (optional)
+├── .codebuddy-plugin/        # Metadata directory (required)
+│   └── plugin.json           # Plugin manifest file
+├── commands/                  # Commands directory (optional)
 │   └── example.md
-├── agents/                # Agents directory (optional)
+├── agents/                    # Agents directory (optional)
 │   └── example.md
-├── skills/                # Skills directory (optional)
-│   └── example/
+├── skills/                    # Skills directory (optional)
+│   └── code-review/
 │       └── SKILL.md
-├── hooks/                 # Hooks directory (optional)
+├── hooks/                     # Hooks directory (optional)
 │   └── hooks.json
-├── .mcp.json              # MCP configuration file (optional)
-└── .lsp.json              # LSP configuration file (optional)
+├── bin/                       # Executables directory (optional)
+│   └── my-tool
+├── .mcp.json                  # MCP configuration file (optional)
+├── .lsp.json                  # LSP configuration file (optional)
+└── settings.json              # Default settings file (optional)
 ```
 
-### plugin.json Format
+## Developing More Complex Plugins
 
-The plugin manifest file defines the plugin's metadata and included components, located at `.codebuddy-plugin/plugin.json`:
+Once you've mastered basic plugins, you can create more sophisticated extensions.
 
-```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"
-}
-```
+### Adding Skills
 
-### Commands
+Plugins can include [agent skills](skills.md) to extend CodeBuddy's capabilities. Skills are model-invoked: CodeBuddy automatically uses them based on task context.
 
-Plugins can provide custom slash commands that users can manually trigger. Commands are defined as Markdown files.
+Add a `skills/` directory at the plugin root containing skill folders with `SKILL.md` files:
 
-**Example**: `commands/example.md`
+```
+my-plugin/
+├── .codebuddy-plugin/
+│   └── plugin.json
+└── skills/
+    └── code-review/
+        └── SKILL.md
+```
 
-```markdown
+Each `SKILL.md` needs frontmatter containing `name` and `description` fields, followed by instructions:
 
-This is an example command. It executes when the user enters /my-plugin:example.
+```markdown
+---
+name: code-review
+description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
+---
 
-Argument: $1
+When reviewing code, check for:
+1. Code organization and structure
+2. Error handling
+3. Security concerns
+4. Test coverage
 ```
 
-Commands are registered in the format `/plugin-name:command-name`.
-
-For detailed information, refer to: [Slash Commands Documentation](slash-commands.md)
+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](skills.md).
 
-### Skills
+### Adding Commands
 
-Skills are specialized capability templates that the AI can automatically recognize and invoke.
+Plugins can provide custom slash commands that users can manually trigger. Commands are defined as Markdown files.
 
-**Example**: `skills/SKILL.md`
+**Example**: `commands/example.md`
 
 ```markdown
 ---
-description: "Skill description"
+description: "Example command description"
+argument-hint: "[argument]"
 ---
 
-Detailed skill description and usage scenarios...
+This is an example command. It executes when the user enters /my-plugin:example.
+
+Argument: $ARGUMENTS
 ```
 
-For detailed information, refer to: [Skills Documentation](skills.md)
+Commands are registered in the format `/plugin-name:command-name`.
+
+For detailed information, refer to the [Slash Commands documentation](slash-commands.md).
 
-### Hooks
+### Adding Hooks
 
-Hooks allow automatic execution of operations when specific events occur.
+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": {
-    "user-prompt-submit-hook": [
+    "PostToolUse": [
       {
+        "matcher": "Write|Edit",
         "hooks": [
           {
             "type": "command",
-            "command": "echo 'User submitted: $INPUT'",
-            "timeout": 5000
+            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
           }
         ]
       }
@@ -430,21 +272,17 @@ Hooks allow automatic execution of operations when specific events occur.
 }
 ```
 
-For detailed information, refer to: [Hooks Documentation](hooks.md)
+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).
 
-### LSP (Language Server Protocol)
+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](hooks.md) 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](skills.md#configuring-hooks-in-a-skill) (note that this path is subject to the security gate).
 
-LSP plugins provide real-time code intelligence for the AI, enabling it to understand code structure, type definitions, function signatures, and more.
+For detailed information, refer to the [Hooks documentation](hooks.md).
 
-#### Usage Recommendations
+### Adding LSP Servers
 
-For common languages (such as TypeScript, Python, Rust, etc.), it's recommended to install pre-built LSP plugins directly from the official plugin marketplace. You only need to create custom LSP plugins when supporting languages not yet covered.
+> 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.
 
-#### Configuring LSP Servers
-
-Configure LSP servers by adding a `.lsp.json` file to the plugin root directory:
-
-**Example**: `.lsp.json`
+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
 {
@@ -458,12 +296,7 @@ Configure LSP servers by adding a `.lsp.json` file to the plugin root directory:
 }
 ```
 
-#### Configuration Field Descriptions
-
-- **Language Identifier** (e.g., `"go"`): Defines the language supported by the LSP server
-  - `command`: The command name of the LSP server executable
-  - `args`: Array of arguments passed to the command
-  - `extensionToLanguage`: Mapping of file extensions to language identifiers
+Users who install the plugin must have the language server binaries pre-installed on their machine.
 
 #### Multi-Language Configuration Example
 
@@ -488,201 +321,248 @@ Configure LSP servers by adding a `.lsp.json` file to the plugin root directory:
 
 #### Installation Requirements
 
-When installing plugins that include LSP configurations, users must have the corresponding language server binaries pre-installed on their system. For example:
+When users install plugins that include LSP configurations, they must have the corresponding language server binaries pre-installed on their system:
 
-- **Go**: Requires `gopls` (`go install golang.org/x/tools/gopls@latest`)
-- **Python**: Requires `python-lsp-server` (`pip install python-lsp-server`)
-- **Rust**: Requires `rust-analyzer` (`rustup component add rust-analyzer`)
+- **Go**: `go install golang.org/x/tools/gopls@latest`
+- **Python**: `pip install python-lsp-server`
+- **Rust**: `rustup component add rust-analyzer`
 
-#### How It Works
+### Bundling Default Settings
 
-1. CodeBuddy reads the `.lsp.json` configuration on startup
-2. Automatically starts the corresponding LSP server based on file extensions
-3. AI obtains code intelligence information via the LSP protocol
-4. Provides more accurate code suggestions and modifications
+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.
 
-#### Best Practices
+Setting `agent` activates one of the plugin's [custom agents](sub-agents.md) 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.
 
-1. **Provide Installation Instructions**: Clearly document the required language servers in the plugin's README
-2. **Version Compatibility**: Document the supported language server version range
-3. **Use Official Plugins**: Prefer officially maintained LSP plugins to avoid duplicate work
-4. **Thorough Testing**: Ensure LSP configurations work correctly across different operating systems
-
-## Plugin Marketplace Types
+```json
+{
+  "agent": "security-reviewer"
+}
+```
 
-### GitHub Marketplace
+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.
 
-Publish and fetch plugins from GitHub repositories.
+### Testing Plugins Locally
 
-**Repository Structure**:
+Use the `--plugin-dir` argument to test plugins during development. This loads your plugin directly without installation.
 
+```bash
+codebuddy --plugin-dir ./my-plugin
 ```
-plugin-repo/
-├── .codebuddy-plugin/
-│   └── marketplace.json       # Marketplace manifest
-└── plugins/
-    ├── plugin1/
-    │   ├── .codebuddy-plugin/
-    │   │   └── plugin.json
-    │   └── ...
-    └── plugin2/
-        ├── .codebuddy-plugin/
-        │   └── plugin.json
-        └── ...
-```
 
-**marketplace.json** Format:
+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 Marketplace",
-  "plugins": [
-    {
-      "name": "plugin1",
-      "source": "plugins/plugin1",
-      "description": "Plugin 1 description"
-    },
-    {
-      "name": "plugin2",
-      "source": "plugins/plugin2",
-      "description": "Plugin 2 description"
-    }
-  ]
+  "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"
 }
 ```
 
-### HTTP Marketplace
+For complete manifest schema documentation, see the [Plugin Reference Documentation](plugins-reference.md).
+
+## Sharing Your Plugin
+
+When your plugin is ready to share:
 
-Provide plugins through HTTP(S) servers.
+1. **Add documentation**: Include a `README.md` describing installation and usage
+2. **Version management**: Use [semantic versioning](plugins-reference.md#version-management) in `plugin.json`
+3. **Create or use a marketplace**: Distribute via [plugin marketplaces](plugin-marketplaces.md)
+4. **Test with others**: Have team members test the plugin before broader distribution
 
-**Server Requirements**:
+Once your plugin is published to a marketplace, others can install and use it by following the instructions in [Plugin Marketplaces](plugin-marketplaces.md).
 
-- Provide `/marketplace.json` - Marketplace manifest
-- Provide `/plugins/<plugin-name>/plugin.json` - Plugin manifest
-- Provide plugin file downloads
+## Converting Existing Configuration to a Plugin
 
-### Local Directory Marketplace
+If you already have skills or hooks in the `.codebuddy/` directory, you can convert them to a plugin for easier sharing and distribution.
 
-Load plugins from the local filesystem, suitable for development and testing.
+### Migration Steps
 
-**Directory Structure**:
+#### Step 1: Create the plugin structure
 
+Create a new plugin directory:
+
+```bash
+mkdir -p my-plugin/.codebuddy-plugin
 ```
-local-plugins/
-├── .codebuddy-plugin/
-│   └── marketplace.json
-└── plugins/
-    └── my-plugin/
-        ├── .codebuddy-plugin/
-        │   └── plugin.json
-        └── ...
+
+Create the manifest file `my-plugin/.codebuddy-plugin/plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "description": "Migrated from standalone configuration",
+  "version": "1.0.0"
+}
 ```
 
-## Best Practices
+#### Step 2: Copy existing files
 
-### Plugin Development Recommendations
+Copy your existing configuration to the plugin directory:
 
-1. **Follow Naming Conventions**: Use clear, descriptive plugin names
-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 in local marketplace before publishing
+```bash
+# Copy commands
+cp -r .codebuddy/commands my-plugin/
 
-### Security Considerations
+# Copy agents (if any)
+cp -r .codebuddy/agents my-plugin/
 
-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
+# Copy skills (if any)
+cp -r .codebuddy/skills my-plugin/
+```
 
-### Plugin Publishing Workflow
+#### Step 3: Migrate Hooks
 
-1. Create plugin directory and files
-2. Write `plugin.json`
-3. Test plugin in local marketplace
-4. Create GitHub repository or HTTP server
-5. Add `marketplace.json`
-6. Share marketplace address with users
+If you have hooks in your settings, create the hooks directory:
 
-## Troubleshooting
+```bash
+mkdir my-plugin/hooks
+```
 
-### Marketplace Not Loading
+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:
 
-**Problem**: Unable to add marketplace or can't see plugins from it
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
 
-**Solution**:
+#### Step 4: Test the migrated plugin
 
-* Verify marketplace URL is accessible
-* Check if `.codebuddy-plugin/marketplace.json` exists at the specified path
-* Use `codebuddy plugin validate` to ensure JSON syntax is valid
-* For private repositories, confirm you have access permissions
+Load the plugin to verify everything works:
 
-#### Plugin Installation Failed
+```bash
+codebuddy --plugin-dir ./my-plugin
+```
 
-**Problem**: Marketplace appears but plugin installation fails
+Test each component: run your commands, check agents in `/agents`, and verify hooks trigger correctly.
 
-**Solution**:
+### Before vs After Migration
 
-* Verify plugin source URL is accessible
-* Check if plugin directory contains required files
-* For GitHub sources, ensure repository is public or you have access permissions
-* Test plugin source by manually cloning/downloading
+| Standalone Configuration (`.codebuddy/`) | Plugin |
+|-------------------------------------------|--------|
+| Available in only one project | Shareable via marketplaces |
+| Files in `.codebuddy/commands/` | Files in `plugin-name/commands/` |
+| Hooks in `settings.json` | Hooks in `hooks/hooks.json` |
+| Manual copy required for sharing | Install via `/plugin install` |
 
-### Plugin Not Loading
+> After migration, you can delete the original files in `.codebuddy/` to avoid duplication. The plugin version takes precedence when loaded.
 
-**Problem**: Plugin is installed but not working
+## Best Practices
 
-**Solution**:
+### Plugin Development Recommendations
 
-* Confirm plugin is enabled: `/plugin` → "3. Installed"
-* Check that `plugin.json` format is correct
-* Restart CodeBuddy to load new plugins
-* Use `--debug` mode to view loading logs
+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
 
-### Command Not Available
+### Security Considerations
 
-**Problem**: Plugin is installed but commands are unavailable
+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 command path is correctly configured in `plugin.json`
-* Check that command file exists
-* Verify command file format follows Markdown specifications
+- 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
 
-### Marketplace Connection Failed
+### Command Not Available
 
-**Problem**: Unable to connect to marketplace or fetch plugin list
+**Problem**: Plugin is installed but commands are unavailable
 
 **Solution**:
 
-* **GitHub marketplace**: Check network connection and repository access permissions
-* **HTTP marketplace**: Confirm server is accessible
-* **Local marketplace**: Verify directory path and permissions
+- 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 marketplace and plugins before sharing:
+Test your plugin before sharing:
 
 ```bash
-# Validate marketplace JSON syntax
-codebuddy plugin validate .
-
-# Validate specific plugin
+# Validate plugin format
 codebuddy plugin validate /path/to/plugin
 
-# Add local marketplace for testing
-codebuddy plugin marketplace add ./path/to/marketplace
+# Test locally with --plugin-dir
+codebuddy --plugin-dir ./my-plugin
 
-# Test plugin installation
-codebuddy plugin install test-plugin@marketplace-name
+# Test the plugin's skills
+/my-plugin:skill-name
 ```
 
-## Related Documentation
+## Next Steps
 
-- **[Plugin Reference Documentation](plugins-reference.md)** - Complete technical specification for plugin development
-- **[Slash Commands](slash-commands.md)** - Learn about the command system
-- **[Skills](skills.md)** - Learn about the skills system
-- **[Hooks](hooks.md)** - Master the hooks mechanism
+### For Plugin Users
 
----
+- [Plugin Marketplaces](plugin-marketplaces.md) - Browse marketplaces and install plugins
+- [Settings](settings.md) - Learn about plugin configuration options
+
+### For Plugin Developers
 
-*Make CodeBuddy more powerful through the plugin system 🚀*
+- [Plugin Marketplaces](plugin-marketplaces.md) - Package and share your plugin
+- [Plugin Reference Documentation](plugins-reference.md) - Complete technical specification
+- Dive deeper into specific plugin components:
+  - [Skills](skills.md) - Skill development details
+  - [Sub-agents](sub-agents.md) - Agent configuration and capabilities
+  - [Hooks](hooks.md) - Event handling and automation
+  - [MCP](mcp.md) - External tool integration