From e998e47ea1ded8b1f323243bfb1b40baff1e218f Mon Sep 17 00:00:00 2001 From: Christopher Tso Date: Wed, 21 Oct 2026 12:07:00 +1100 Subject: [PATCH 1/2] docs(plugin): explain Copilot hooks in plain language --- docs/src/content/docs/docs/guides/plugins.mdx | 49 +++++++++++-------- .../content/docs/docs/reference/clients.mdx | 24 ++++++++- 2 files changed, 51 insertions(+), 22 deletions(-) diff --git a/docs/src/content/docs/docs/guides/plugins.mdx b/docs/src/content/docs/docs/guides/plugins.mdx index 323e3e3b..d705857d 100644 --- a/docs/src/content/docs/docs/guides/plugins.mdx +++ b/docs/src/content/docs/docs/guides/plugins.mdx @@ -12,37 +12,44 @@ 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) +├── hooks.json # Copilot hook configuration (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 +│ └── hooks/ # Copilot hooks for this project └── 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. +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/`](https://docs.github.com/en/copilot/reference/hooks-reference) +to run commands during agent sessions, such as when a session starts or before +a tool runs. [Git hooks](https://git-scm.com/docs/githooks), 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. + +AllAgents warns and skips a hook configuration if it cannot read or parse the +JSON, or if the file does not contain `version: 1` and a `hooks` object. Unless +hooks are disabled, each event's value must also be an array. AllAgents does not +fully validate individual hook entries. Skipping one plugin's hook configuration +still allows its other eligible files, including files under `.github/hooks/`, +and valid hooks from other plugins to sync. Client selection and file exclusions +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 diff --git a/docs/src/content/docs/docs/reference/clients.mdx b/docs/src/content/docs/docs/reference/clients.mdx index ff101617..7fdac412 100644 --- a/docs/src/content/docs/docs/reference/clients.mdx +++ b/docs/src/content/docs/docs/reference/clients.mdx @@ -237,7 +237,29 @@ state. Ambient `~/.codex`, project files, and operating-system keyrings remain outside the cleanup boundary. :::note -Skills are the cross-client way to share reusable prompts. GitHub overrides (`.github/prompts/`, `.github/agents/`, `.github/hooks/`, `copilot-instructions.md`) are copied to the workspace's `.github/` folder for Copilot/VSCode; package-only `.github/plugin/` metadata is omitted. Root `agents/` and `hooks/` also map to `.github/agents/` and `.github/hooks/` for Copilot. At project scope, plugin hook declarations from `hooks.json` or `hooks/hooks.json` are combined in `.github/hooks/allagents.json`. This translation does not require marketplace registration or `plugin.json`; a missing or disabled declaration adds no managed entries. AllAgents warns and omits a declaration that cannot be read or parsed, lacks the version-1 `hooks` object envelope, or—unless disabled—has a non-array event value. Skipping a declaration does not itself suppress other eligible plugin artifacts or valid declarations from other plugins. At user scope, root `hooks/` maps to `~/.copilot/hooks/`, while repository `.github/hooks/` remains project-scoped. +Skills let you share reusable prompts across clients. For Copilot and VSCode, +AllAgents copies `.github/prompts/`, `.github/agents/`, `.github/hooks/`, and +`copilot-instructions.md` into the workspace's `.github/` folder. Package metadata +under `.github/plugin/` is omitted. For Copilot, a plugin's root `agents/` and +`hooks/` directories also map to `.github/agents/` and `.github/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 `.github/hooks/*.json`](https://docs.github.com/en/copilot/reference/hooks-reference) +to run commands during agent sessions. Git hooks normally live in `.git/hooks/`. +The generated file uses local plugin paths and is not portable to Copilot cloud +agent or another checkout. + +No marketplace registration or `plugin.json` is required. Missing or disabled +hook configurations add no hooks to the generated file. AllAgents warns and +skips a configuration it cannot read or parse, or one without `version: 1` and a +`hooks` object. Unless hooks are disabled, each event's value must be an array. +Other eligible plugin files and valid hooks from other plugins still sync. See +[Plugin Structure](/docs/guides/plugins/#plugin-structure) for details. + +For user installations, a plugin's root `hooks/` directory maps to +`~/.copilot/hooks/`. Files under `.github/hooks/` apply only to the project. ::: ### Pi From 1185e891188bcfb938c1c6761190d1fd37fe4aab Mon Sep 17 00:00:00 2001 From: Christopher Tso Date: Wed, 21 Oct 2026 12:12:26 +1100 Subject: [PATCH 2/2] docs(plugin): give Copilot hooks their own section --- docs/src/content/docs/docs/guides/plugins.mdx | 6 +-- .../content/docs/docs/reference/clients.mdx | 42 +++++++------------ 2 files changed, 18 insertions(+), 30 deletions(-) diff --git a/docs/src/content/docs/docs/guides/plugins.mdx b/docs/src/content/docs/docs/guides/plugins.mdx index d705857d..b7283c24 100644 --- a/docs/src/content/docs/docs/guides/plugins.mdx +++ b/docs/src/content/docs/docs/guides/plugins.mdx @@ -19,11 +19,11 @@ my-plugin/ │ ├── instructions/ # Pattern-based instructions │ ├── prompts/ # Prompt files │ ├── agents/ # GitHub agent overrides -│ └── hooks/ # Copilot hooks for this project +│ └── hooks/ # Project Copilot hooks └── AGENTS.md ``` -:::note +## 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. @@ -55,8 +55,6 @@ 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 diff --git a/docs/src/content/docs/docs/reference/clients.mdx b/docs/src/content/docs/docs/reference/clients.mdx index 7fdac412..c862fb92 100644 --- a/docs/src/content/docs/docs/reference/clients.mdx +++ b/docs/src/content/docs/docs/reference/clients.mdx @@ -140,6 +140,22 @@ unknown content. ### GitHub Copilot CLI +#### Plugin files and hooks + +Skills let you share reusable prompts across clients. For Copilot and VSCode, +AllAgents copies `.github/prompts/`, `.github/agents/`, `.github/hooks/`, and +`copilot-instructions.md` into the workspace's `.github/` folder. Package metadata +under `.github/plugin/` is omitted. For Copilot, a plugin's root `agents/` and +`hooks/` directories also map to `.github/agents/` and `.github/hooks/`. + +For project installations, AllAgents writes plugin hooks to +`.github/hooks/allagents.json`. For user installations, a plugin's root `hooks/` +directory maps to `~/.copilot/hooks/`. Files under `.github/hooks/` apply only to +the project. See [Copilot hooks](/docs/guides/plugins/#copilot-hooks) for how +AllAgents generates and checks hook configuration. + +#### Global profiles + Copilot global profiles require GitHub Copilot CLI 1.0.74 or newer. AllAgents sets `COPILOT_HOME` to an owned configuration root and `COPILOT_CACHE_HOME` to a sibling owned cache directory. The generated launcher @@ -236,32 +252,6 @@ profile; removing that profile intentionally removes its isolated runtime state. Ambient `~/.codex`, project files, and operating-system keyrings remain outside the cleanup boundary. -:::note -Skills let you share reusable prompts across clients. For Copilot and VSCode, -AllAgents copies `.github/prompts/`, `.github/agents/`, `.github/hooks/`, and -`copilot-instructions.md` into the workspace's `.github/` folder. Package metadata -under `.github/plugin/` is omitted. For Copilot, a plugin's root `agents/` and -`hooks/` directories also map to `.github/agents/` and `.github/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 `.github/hooks/*.json`](https://docs.github.com/en/copilot/reference/hooks-reference) -to run commands during agent sessions. Git hooks normally live in `.git/hooks/`. -The generated file uses local plugin paths and is not portable to Copilot cloud -agent or another checkout. - -No marketplace registration or `plugin.json` is required. Missing or disabled -hook configurations add no hooks to the generated file. AllAgents warns and -skips a configuration it cannot read or parse, or one without `version: 1` and a -`hooks` object. Unless hooks are disabled, each event's value must be an array. -Other eligible plugin files and valid hooks from other plugins still sync. See -[Plugin Structure](/docs/guides/plugins/#plugin-structure) for details. - -For user installations, a plugin's root `hooks/` directory maps to -`~/.copilot/hooks/`. Files under `.github/hooks/` apply only to the project. -::: - ### Pi File sync writes project skills to `.pi/skills/` and user skills to