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 hook configuration (optional)
├── commands/        # Commands (Claude, OpenCode)
├── .github/         # Project-scoped assistant resources (Copilot, VSCode)
│   ├── copilot-instructions.md
│   ├── instructions/    # Pattern-based instructions
│   ├── prompts/         # Reusable prompt files
│   ├── agents/          # Custom agents and GitHub agent overrides
│   ├── skills/          # Assistant skills
│   ├── hooks/           # Project Copilot hooks
│   ├── scripts/         # Supporting assistant scripts
│   └── tools/           # Supporting assistant tools
└── AGENTS.md

Single-skill repositories

A repository with SKILL.md at its root can be installed as a single skill when it has no skills/ directory or nested skill directories. The skill name comes from the frontmatter name, falling back to the repository directory name.

File installation copies the skill directory, including supporting scripts, assets, and other files referenced by relative paths. Root .git entries (directories or worktree pointer files), .github/, and .allagents/ are omitted from the skill copy. The same content is available in both copy and symlink sync modes. Plugin exclude patterns apply relative to the repository root:

plugins:
  - source: /path/to/my-skill
    install: file
    exclude:
      - test
      - docs/**
      - design

Other repository content is included unless excluded; .gitignore does not filter the copy. Keep the source separate from its installation destination: AllAgents reports an error when a root skill’s recursive copy would overlap its source directory.

Copilot hooks

When you install a plugin for Copilot in a project, AllAgents reads its hooks.json or hooks/hooks.json and writes the hooks to .github/hooks/allagents.json. Hooks from multiple plugins share this file. Copilot reads JSON files in .github/hooks/ to run commands during agent sessions, such as when a session starts or before a tool runs. Git hooks, such as pre-commit, normally live in .git/hooks/.

AllAgents manages the generated file separately from your other hook files. It sets COPILOT_PLUGIN_ROOT for each hook so commands can find files in their plugin’s installation directory. These paths are local to your machine; the generated file is not portable to Copilot cloud agent or another checkout. AllAgents leaves package metadata under .github/plugin/ out of the project.

No marketplace manifest or plugin.json is required. AllAgents also finds hooks in the usual directories of plugins installed directly from local paths or GitHub. A missing hook configuration or one with disableAllHooks: true adds no hooks to the generated file.

Selected hook files must contain a hooks object whose event values are arrays. The plugin input may omit version; if supplied for Copilot it must be 1. AllAgents emits its managed project file with version: 1. Unreadable, malformed, or unsafe selected hook configuration fails file-plugin validation before owned artifacts are removed. It is not silently skipped while other plugins are partially reconciled. Individual hook entries still follow the target adapter’s supported format. Client selection, file exclusions, and hooks: false 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 discovery

AllAgents prefers .github/plugin/marketplace.json over .claude-plugin/marketplace.json. An invalid preferred marketplace fails resolution; it does not fall back to the other file.

strict is not a component allowlist. Omitted components are discovered from their conventional locations under strict: false, strict: true, and the default mode. The Copilot CLI reference describes strict as a validation mode. Copilot 1.0.103 fixture installs showed no install-time distinction between these modes; malformed marketplace component fields were rejected in every mode. AllAgents never relaxes source containment or user exclusions based on strict.

For legacy plugins, the first plugin manifest is selected in this order: .plugin/plugin.json, plugin.json, .github/plugin/plugin.json, then .claude-plugin/plugin.json. Invalid preferred manifests and escaping paths fail closed in AllAgents, even where native feature loading falls back.

Component	Conventional source	Explicit plugin-manifest form
Skills	skills/, with a root SKILL.md fallback	A path or array of skill directories
Commands	commands/	A path or array of directories or Markdown files
Agents	agents/	A path or array of directories or agent files
Hooks	hooks.json, then hooks/hooks.json	A configuration path or inline event map
MCP	.mcp.json, then .github/mcp.json	A configuration path or inline server map

Explicit skill, command, and agent paths replace the conventional sources. An empty array disables that component. An explicit hook map replaces default hooks; an empty map disables them. A missing hook configuration path falls back to the conventional hook declaration. Paths resolve from the plugin root and must stay inside it, including through symlinks.

Conventional MCP files take precedence over mcpServers in the plugin manifest. The marketplace entry’s mcpServers is used only when neither a conventional file nor a plugin-manifest MCP declaration supplies configuration. This matches the legacy file locations. Marketplace skill, command, agent, and hook declarations do not override the plugin’s component discovery in the observed Copilot 1.0.103 loader. Put custom paths for those components in the plugin manifest.

AllAgents discovers supported .github/ assistant resources independently of marketplace/plugin manifests and strict: agents/, instructions/, prompts/, skills/, hooks/, scripts/, tools/, and copilot-instructions.md. These resources remain eligible on both fresh installs and existing-workspace updates; an omitted manifest component does not suppress them. Supporting scripts and tools remain available for assistant resources, and GitHub agents retain their existing precedence over root agent definitions.

The directory name alone does not make its contents development-only: GitHub documents repository-wide instructions in .github/copilot-instructions.md and path-specific instructions in .github/instructions/. These files provide Copilot with repository guidance rather than CI jobs. GitHub identifies .github/prompts/*.prompt.md as reusable prompt templates, and VS Code documents .github/prompts/ as their workspace location. GitHub creates custom agent profiles in .github/agents/*.agent.md; VS Code likewise uses .github/agents/ for custom agent configurations. These are assistant configuration, not workflow definitions.

This is a supported assistant-root boundary, not a whole-directory copy. GitHub Actions workflows in .github/workflows/, package metadata in .github/plugin/, and other unsupported .github/ entries are not copied as repository overlays, whether or not a manifest is present. Use exclude to filter assistant resources you do not want distributed. Client/scope support, original plugin-relative exclusions, ownership tracking and cleanup, source containment, and copy-time source safety checks are unchanged. Preflight validates selected supported roots without traversing unrelated workflows. Recognized package manifests are still validated as declaration metadata. Previously untracked metadata from older installations is left untouched; this boundary prevents new distribution rather than claiming ownership of existing user files.

Migrating from the component allowlist

Older AllAgents versions treated strict: false as a list of component kinds to distribute. It no longer suppresses undeclared root hooks, commands, agents, or MCP. Keep development-only configuration outside the plugin’s distributable root, or exclude it in the workspace declaration:

plugins:
  - source: /path/to/plugin
    install: file
    hooks: false
    exclude:
      - commands/**
      - agents/**
      - .github/**
    mcpServers:
      exclude: [development-server]

hooks: false disables copied and generated plugin hook components, including raw .github/hooks/ files. It does not disable instructions, prompts, agents, skills, supporting scripts/tools, or inline MCP from the same manifest. File exclusions remain relative to the original plugin root, including custom component paths. Excluding the manifest that declares an inline configuration also excludes that inline configuration. Individual inline hook events are not selectable.

Hook command dependencies are not inferred from arbitrary shell text. If an excluded script is outside the selected hook resources, use hooks: false to prevent the declaration from invoking it.

A missing, invalid, or unsafe configured file-plugin source fails sync before existing owned artifacts are removed. Previously installed files and tracking remain intact; repair or remove the declaration before retrying. AllAgents does not partially purge a workspace when another configured source cannot resolve.

Client support, project/user scope, and JSON schema translation still apply. Commands and hook formats are only installed where the existing client adapter supports them; a Claude hook event map is not automatically a Copilot hook map. LSP declarations and other unsupported manifest components are not installed. This legacy discovery support does not adopt the portable Agent Plugins mcp.json format or its schemas.

AllAgents does not supply native MCP PLUGIN_ROOT environment variables, substitute them in commands/arguments, or implicitly set the plugin working directory. Use an executable on PATH or explicit paths and environment values supported by the target adapter. This discovery change does not add those runtime conventions; user CLI adapters also do not forward MCP cwd.

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.

Updates and Local Customizations

For ordinary file installations, the declared plugin or skill source is the source of truth. Client directories such as .agents/skills/, .claude/skills/, and .codex/skills/ contain installed copies. An update can replace edits made directly to those copies without a local-edit confirmation; uninstall can remove modified copies that AllAgents previously installed.

Keep lasting customizations in a local source directory or a fork, then point the plugin declaration at that source. Edit the source files and run allagents update to sync them to the selected clients. See Git remotes for file installations for remote source formats. Native installs use the selected client’s own plugin lifecycle; named profiles have separate modified-resource protections.

Track configuration and optional snapshots in Git

Commit .allagents/workspace.yaml in the project’s Git repository so the team shares source declarations and client selections. AllAgents keeps its local .allagents/sync-state.json out of Git.

You can also commit snapshots of installed project skills for review and recovery. Use the directory for your selected client; .agents/skills/ is one possible destination, not the destination for every client. For a project that uses .agents/skills/:

git add .allagents/workspace.yaml .agents/skills/
git commit -m "Track agent setup and installed skills"

Use the project’s existing repository; a separate repository inside .agents/ is not required. If the installed directory is ignored, keep that policy and version the source instead. A symlink committed to Git records its link target, not a snapshot of the linked files.

Git can recover committed, tracked content after an update. For example, to inspect changes and restore the last committed project skill snapshot:

git diff -- .agents/skills/
git restore --source=HEAD -- .agents/skills/

Restoring returns those files to the committed snapshot. Git does not prevent AllAgents from replacing working files, and it cannot recover edits that were never committed or files outside the repository, such as user-global installs.

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
    install: file
    mcpServers:
      exclude: [optional-search]

After editing YAML, run allagents mcp update --scope project (or --scope user). The TUI saves the same setting and reconciles MCP automatically. Other plugin servers remain enabled, including new servers added by an update.

Existing MCP servers

Within a scope, AllAgents matches servers by name, not URL. If both your workspace declaration and a plugin define search, your declaration wins, even if their URLs differ. Different names with the same URL produce separate entries.

An entry added directly to a client’s configuration stays yours if AllAgents does not already track it. AllAgents neither overwrites nor removes it when a plugin uses the same name. Excluding a plugin server does not disable that manual entry or a workspace-level declaration. Editing an AllAgents-managed entry does not remove its ownership tracking.

See the configuration reference for declaration and filter options.

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.