# Plugins

> Plugins are packages that extend goose with reusable components. A plugin can provide skills, hooks, or both.

- 网址：https://funcoding.ai/agents/goose/guides/context-engineering/plugins/
- 来源：goose 官方文档原文（英文），Apache-2.0 许可，同步于 2026-10-11
- 官方原文：https://goose-docs.ai/docs/guides/context-engineering/plugins

---
Plugins are packages that extend goose with reusable components. A plugin can provide [skills](https://funcoding.ai/agents/goose/guides/context-engineering/using-skills/), [hooks](https://funcoding.ai/agents/goose/guides/context-engineering/hooks/), or both.

Use plugins when you want to install, share, or update a bundle of goose functionality instead of copying individual files into your local skills or hooks directories.

<div class="callout callout-warning">

**Install trusted plugins only**

Plugins can include instructions that goose may load and hooks that execute local commands. Install plugins only from sources you trust, and review plugin contents before enabling them.

</div>

## What Plugins Can Provide

| Component | What it does |
|---|---|
| Skills | Reusable instructions and supporting files that teach goose how to perform a task or follow a workflow. |
| Hooks | Local commands that run when lifecycle events happen during a goose session. |

A plugin is the container. Skills and hooks are components inside that container.

## Plugin Structure

A plugin is a directory with a plugin manifest and optional component directories. A plugin that includes both skills and hooks can look like this:

```text
my-plugin/
├── plugin.json
├── skills/
│   └── review/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
└── scripts/
    └── notify.sh
```

The plugin manifest identifies the plugin:

```json title="plugin.json"
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Reusable skills and hooks for my team"
}
```

### Add a Skill to a Plugin

To add a skill to a plugin, place a skill directory under the plugin's `skills/` directory. Each skill directory contains a `SKILL.md` file:

```text
my-plugin/
└── skills/
    └── review/
        └── SKILL.md
```

```markdown title="skills/review/SKILL.md"
---
name: review
description: Review code changes for correctness, maintainability, and test coverage
---

Review the code changes. Prioritize correctness issues, security concerns, missing tests, and maintainability risks. Be direct and suggest concrete fixes.
```

For Open Plugins, goose namespaces imported skill names with the plugin name. The `review` skill in `my-plugin` is loaded as `my-plugin:review`.

### Add a Hook to a Plugin

To add a hook to a plugin, create `hooks/hooks.json` and map lifecycle events to commands:

```text
my-plugin/
├── hooks/
│   └── hooks.json
└── scripts/
    └── notify.sh
```

```json title="hooks/hooks.json"
{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${PLUGIN_ROOT}/scripts/notify.sh"
          }
        ]
      }
    ]
  }
}
```

Hook commands receive the event payload as JSON on stdin. Use `${PLUGIN_ROOT}` to reference files inside the plugin directory.

For supported events, payload details, and more hook examples, see the [Hooks guide](https://funcoding.ai/agents/goose/guides/context-engineering/hooks/).

## Plugin Locations

goose discovers plugins from these locations:

| Plugin type | Location | Notes |
|---|---|---|
| User plugin | `~/.agents/plugins/<plugin-name>/` | Includes plugins installed with `goose plugin install` and plugins manually copied into your user plugins directory. |
| Project plugin | `<project>/.agents/plugins/<plugin-name>/` | Available when goose is working in that project. |

Installed and manually placed user plugins use the same user plugins directory. Installed plugins include metadata created by `goose plugin install`; only installed git-backed plugins can be updated with `goose plugin update`.

## Install a Plugin

Install a plugin from a git repository with:

```bash
goose plugin install https://github.com/example/my-goose-plugin.git
```

The install command clones the repository, detects the plugin format, copies it into the plugins directory, and reports the imported components.

Example output:

```text
✓ Installed open-plugins plugin 'my-plugin' (1.0.0)
  Source: https://github.com/example/my-goose-plugin.git
  Location: /Users/you/.agents/plugins/my-plugin
  Imported skills:
    - my-plugin:review
    - my-plugin:test-plan
```

## Auto-Update a Plugin

To let goose check a plugin for updates automatically, install it with `--auto-update`:

```bash
goose plugin install --auto-update https://github.com/example/my-goose-plugin.git
```

When auto-update is enabled, goose checks that plugin for updates before plugin skills are loaded. Auto-update checks are rate-limited, so goose does not clone the repository on every session start.

If an auto-update fails, goose logs the failure and continues using the currently installed plugin.

<div class="callout callout-note">

Auto-update is available for git-backed plugins installed with `goose plugin install --auto-update`. Plugins copied manually into `.agents/plugins/` are discovered, but they are not managed by the plugin update command.

</div>

## Update a Plugin Manually

To update a git-backed plugin on demand, run:

```bash
goose plugin update <plugin-name>
```

For example:

```bash
goose plugin update my-plugin
```

The update command fetches the plugin from its original git source, replaces the installed copy, and preserves whether auto-update was enabled for that plugin.

## Disable a Plugin

To disable a plugin globally, add its name to `disabledPlugins` in your user goose settings file:

```json title="~/.config/goose/settings.json"
{
  "disabledPlugins": ["my-plugin"]
}
```

For project-specific settings, use:

```text
<project>/.config/goose/settings.json
```

For local-only project settings that should not be shared with teammates, use:

```text
<project>/.config/goose/settings.local.json
```

A disabled plugin is skipped during plugin discovery, so its skills are not loaded and its hooks do not run.

## Plugin Formats

goose supports these plugin formats:

| Format | Common files | Notes |
|---|---|---|
| Open Plugins | `plugin.json`, `.plugin/plugin.json`, `.goose-plugin/plugin.json`, `skills/`, `hooks/hooks.json` | Supports Open Plugins skills and hooks. |
| Gemini extensions | `gemini-extension.json`, `skills/` | Supports skills from Gemini-style extension repositories. |

For Open Plugins, imported skill names are namespaced with the plugin name, such as `my-plugin:review`. Use that full name when explicitly loading a plugin-provided skill. Gemini extension skills keep the skill name from `SKILL.md`; goose does not prefix them with the extension name.

Open Plugins can use `plugin.json` at the plugin root, `.plugin/plugin.json`, or `.goose-plugin/plugin.json`. Hook-only Open Plugins can be discovered from `hooks/hooks.json`; if no manifest is present, goose infers the plugin name from the source or directory name.

## When to Use Plugins, Skills, or Hooks

| Use | Best fit |
|---|---|
| Package and distribute reusable goose components | Plugin |
| Teach goose a reusable procedure or domain-specific workflow | Skill |
| Run a local command when goose session events happen | Hook |

Plugins are for packaging and distribution. Skills and hooks define the behavior goose can use once the plugin is installed or discovered.