Plugins

Plugins are packages that extend goose with reusable components. A plugin can provide skills, 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.

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.

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:

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

The plugin manifest identifies the plugin:

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:

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

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:

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

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.

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:

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:

✓ 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:

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.

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.

Update a Plugin Manually

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

goose plugin update <plugin-name>

For example:

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:

~/.config/goose/settings.json

{
  "disabledPlugins": ["my-plugin"]
}

For project-specific settings, use:

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

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

<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.