Plugins

Plugins are packages of AI tooling that can be shared across projects and clients.

Plugin Structure

my-plugin/
├── skills/          # Cross-client skills
├── agents/          # Agent definitions (Claude, Copilot, Factory)
├── hooks/           # Hook definitions (Claude, Copilot, Factory)
├── hooks.json       # Copilot plugin hook declaration (optional)
├── commands/        # Commands (Claude, OpenCode)
├── .github/         # Project-scoped GitHub overrides (Copilot, VSCode)
│   ├── copilot-instructions.md
│   ├── instructions/    # Pattern-based instructions
│   ├── prompts/         # Prompt files
│   ├── agents/          # GitHub agent overrides
│   └── hooks/           # GitHub hook overrides
└── AGENTS.md

Note

At project scope, Copilot plugin hook declarations from hooks.json or hooks/hooks.json are combined in the AllAgents-owned .github/hooks/allagents.json file. Each entry receives its plugin-specific COPILOT_PLUGIN_ROOT, so declarations continue to resolve files from the plugin package. The generated file is tracked independently from other repository hook files. Package metadata under .github/plugin/ is not copied into the project overlay.

This does not require a marketplace manifest or plugin.json. Direct local and GitHub plugin sources continue to use conventional directory discovery. If a plugin has no supported hook declaration, its other artifacts still sync and it adds no entries to allagents.json. AllAgents warns and omits a declaration that cannot be read or parsed as JSON or lacks the version-1 hooks object envelope. A declaration with disableAllHooks: true adds no entries; otherwise, a non-array event value also warns and omits the declaration. AllAgents does not fully validate each hook entry. Skipping a declaration does not reject the plugin or itself suppress other eligible artifacts—including repository hook files—or valid declarations from other plugins. Ordinary client selection and exclusion settings still apply.

At user scope, root hooks/ entries sync to the client’s user hook directory. Repository hooks under .github/hooks/ stay project-scoped and are not copied to ~/.copilot/hooks/. Potential copies from older versions are left untouched and reported for manual review because their ownership was not tracked.

Marketplace Component Boundaries

AllAgents recognizes marketplace manifests at both .claude-plugin/marketplace.json and .github/plugin/marketplace.json. The GitHub Copilot location takes precedence when a repository contains both.

A marketplace entry with strict: false defines the complete set of plugin components. For example, this entry syncs the repository’s top-level skills without treating its top-level hooks or .github/ development configuration as plugin artifacts:

{
  "name": "skills-only",
  "source": "./",
  "strict": false,
  "skills": ["./skills/"]
}

Without strict: false, AllAgents retains conventional plugin-directory discovery for compatibility. Top-level hooks/ remains the portable hook location; .github/ represents repository-scoped GitHub content. Component kind filtering currently uses AllAgents’ conventional root directories, so custom marketplace component paths are not yet remapped.

Duplicate Skill Handling

When multiple plugins define skills with the same folder name, AllAgents automatically resolves naming conflicts:

Conflict Type	Resolution	Example
Same skill folder, different plugins	{plugin}_{skill}	plugin-a_coding-standards
Same skill folder AND plugin name	{org}_{plugin}_{skill} (GitHub)	acme_my-plugin_coding-standards
Same skill folder AND plugin name	{hash}_{plugin}_{skill} (local)	a1b2c3_my-plugin_coding-standards

Skills with unique folder names keep their original names unchanged.

Example:

workspace.yaml

plugins:
  - ./plugin-a    # has skills/coding-standards/
  - ./plugin-b    # has skills/coding-standards/
  - ./plugin-c    # has skills/testing/

After sync:

.claude/skills/
├── plugin-a_coding-standards/   # renamed (conflict)
├── plugin-b_coding-standards/   # renamed (conflict)
└── testing/                     # unchanged (unique)

Note

This rename-based deduplication applies to plugin skills (copied to .claude/skills/). Repository skills embedded in the WORKSPACE-RULES index use a different strategy — they pick a single winner rather than keeping all copies. See Repository Skill Discovery for details.

Git remotes for file installations

File installations accept SSH URLs with custom ports, SCP-style remotes, and HTTPS remotes on Git servers such as Forgejo and GitLab. Git uses your existing SSH identity, agent, and credential helpers. A marketplace manifest is optional; ordinary plugin directories and collections of SKILL.md files are discovered after cloning.

allagents plugin install 'ssh://git@git.example.com:2222/team/skills.git' \
  --scope project --client codex,pi --skill fixture --yes

allagents plugin install 'git@git.example.com:team/skills.git' \
  --scope user --client codex --yes

allagents plugin install 'https://git.example.com/team/skills.git#ref=release%2Fstable&subdir=collections%2Fteam' \
  --scope project --client codex --yes

Generic Git URLs treat the entire repository path as the remote. Select a repository subdirectory with #subdir=..., and a branch or tag with #ref=.... Percent-encode each value and quote the complete source in shell commands. Subdirectories must stay inside the checkout. An object-form ref supplies a ref when the source has no inline ref.

plugin update refreshes the selected checkout and reconciles its owned client artifacts. workspace sync --offline uses an existing cache and fails if that source/ref has never been cached. Uninstall removes the declaration and owned artifacts. Different remote URLs and refs have separate caches; subdirectories of the same remote/ref share a checkout.

Use install: file to declare this behavior explicitly when clients have native installation configured. Native package transport retains the client’s own source syntax and lifecycle.

Choosing Install Scope and Clients

allagents plugin install asks where to save a new declaration and which clients should receive it. The review step shows the exact config path, clients, effective install methods, and targeting behavior before anything changes.

# Interactive
allagents plugin install code-review@claude-plugins-official

# Auto-register a marketplace from its GitHub URL, then install its plugin
allagents plugin install 'my-plugin@https://github.com/owner/marketplace'

# Prompt-free automation
allagents plugin install code-review@claude-plugins-official \
  --scope project --client claude,codex --yes

--scope and --client bypass their respective choosers. The final confirmation defaults to Yes, so Enter accepts the displayed plan; --yes skips that prompt entirely. JSON, CI, and non-TTY runs never prompt and retain the command’s deterministic defaults when a target flag is omitted.

Clients normally inherit the selected scope’s top-level clients list. A different selection is stored on that plugin declaration as a clients override. On the first install into a new scope, the selected clients initialize the top-level list. Reinstalling an existing plugin preserves its other fields.

Adding Skills

You can add a specific skill from a GitHub repo without installing the full plugin first:

# Add a skill by name, specifying the plugin source
allagents skill add reddit --from ReScienceLab/opc-skills

# Or pass a GitHub URL directly
allagents skill add https://github.com/owner/repo/tree/main/skills/my-skill

Source-backed skill installs use the same scope, client, review, and confirmation flow as plugin install. Pass --scope, --client, and --yes for prompt-free automation. Re-enabling a skill from an already installed plugin does not introduce a declaration, so it keeps the existing scope and client targeting.

See the CLI reference for all source formats.

Disabling Individual Skills

You can disable specific skills from a plugin without uninstalling the entire plugin:

Individual skill selection is available only with file installation. Native plugin managers install the whole plugin; use install: file to enable skill filters or toggle individual skills in the interactive menus.

# List all skills with their status
allagents plugin skills list

# Disable a skill
allagents plugin skills remove brainstorming

# Re-enable a skill
allagents plugin skills add brainstorming

Disabled skills are stored in disabledSkills in workspace.yaml and are excluded from sync:

plugins:
  - superpowers@official

disabledSkills:
  - superpowers:brainstorming

When a skill exists in multiple plugins, use --plugin to specify which one:

allagents plugin skills remove coding-standards --plugin my-plugin

Selecting Plugin MCP Servers

In the interactive Plugins menu, open an installed plugin and choose MCP servers to select which servers from its .mcp.json remain enabled. This action appears when the plugin targets at least one file-installed client with an MCP destination. Native plugin systems install the whole plugin, so a native-only install has no per-server selector. On a mixed install, only file-installed client MCP entries change.

You can also exclude individual plugin servers in either project or user workspace.yaml:

plugins:
  - source: my-plugin@official
    mcpServers:
      exclude: [optional-search]

All other servers remain enabled, including new servers added by a plugin update. Workspace-level MCP declarations are not excluded by this setting.

Plugin Spec Format

Plugins use the plugin@marketplace format:

Format	Example
Well-known	code-review@claude-plugins-official
owner/repo	my-plugin@owner/repo
GitHub marketplace URL	my-plugin@https://github.com/owner/repo

First-party Plugin Catalogue

Reusable plugins live in allagentsdev/agent-plugins. The CLI-specific allagents guidance plugin remains in this repository under plugins/allagents, installed as allagents@allagentsdev/allagents. Workspace templates remain in allagentsdev/allagents/examples/workspaces and select capabilities from that catalogue:

plugins:
  - finance@allagentsdev/agent-plugins

Existing marketplace declarations such as finance@allagentsdev/allagents continue to use the allagents marketplace, whose entries forward to the new catalogue. Upgrade AllAgents before refreshing that marketplace: external plugin paths require the updated resolver. Native Claude and Copilot clients use their own marketplace source formats; update those clients if their installed versions do not support external plugin subdirectories.

Direct old paths such as allagentsdev/allagents/plugins/deepwiki must be changed to deepwiki@allagentsdev/agent-plugins. The four reusable plugin directories move out of the CLI repository. Git refs that predate the move retain their original contents.

External marketplace entries accept github, url and git-subdir source objects. AllAgents preserves their ref and path, resolves only the selected subdirectory for online and offline file installations, and rejects paths that escape the checkout. File installations currently reject explicit sha pins; use a branch or tag in ref instead. This limitation does not alter what native clients support themselves.

For contributors, merge the catalogue extraction into agent-plugins/main before merging the CLI relocation: the forwarding entries follow the new repository’s default branch.