Ship the agent plugin sub-agents to GitHub Copilot clients

Agent Plugins 1.0 standardizes skills, auto-discovered from skills/, but not
sub-agents: Copilot clients load those from com.github.copilot/agents, as
<name>.agent.md files. The plugin only declared them in the Claude Code and
Cursor manifests, which Copilot never reads, so a Copilot user got no sub-agent
at all while both the skill and its INSTALL.md told the agent to skip installing
them "because the plugin ships them".

The three definitions are now generated into com.github.copilot/agents from the
Claude Code ones, so the bodies can not drift, and validate_agent_plugins.py
fails when they are out of sync. Only the frontmatter differs: Copilot tool
aliases already accept the Claude tool names (Read -> read, Grep/Glob -> search,
Bash -> execute), but "haiku" is not a Copilot model id, so it is dropped.

Also corrected in the skills:

- installing the sub-agents by hand on Copilot needs the .agent.md suffix in
  .github/agents/ and no model override; tools are valid and portable as-is
- the install mode is no longer inferred from skill naming (only some platforms
  namespace plugin skills, and none exposes a skill's origin): it is read from
  the filesystem, and the user is asked when it stays ambiguous
- the frontmatter key `licence` is corrected to `license`, which is the spelling
  the agents actually read

CI now loads the repository as an external plugin in the GitHub Copilot CLI and
asserts it is accepted with no manifest error. It runs offline through
--plugin-dir, with no marketplace and no authentication. `plugins list` never
enumerates the skills a plugin provides, verified against a control plugin, so
the check asserts the plugin loads, not that each skill is exposed.

Author: nvuillam

.automation/agent_plugin_manifests.py

@@ -7,6 +7,8 @@
 
 REPO_HOME = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 REFERENCE_MANIFEST = "plugin.json"
+NEWLINE = chr(10)
+SEPARATOR = "---" + NEWLINE
 
 # Per-vendor plugin manifests mirroring the identity declared in the Agent Plugins
 # 1.0 manifest.
@@ -27,6 +29,22 @@
 SHARED_FIELDS = ["name", "version", "description", "license", "homepage", "repository"]
 SHARED_ENTRY_FIELDS = ["name", "description", "license", "homepage", "repository"]
 
+# Agent Plugins 1.0 standardizes skills, auto-discovered from skills/, but not
+# sub-agents: Copilot clients load those from com.github.copilot/agents, named
+# <name>.agent.md. Their bodies are identical to the Claude Code definitions, so
+# they are generated from them to avoid drift. Only the frontmatter differs:
+# Copilot tool aliases already accept the Claude tool names (Read -> read,
+# Grep/Glob -> search, Bash -> execute, WebFetch/WebSearch -> web), but "haiku"
+# is not a Copilot model id, so the model override is dropped.
+AGENT_SOURCE_DIR = "skills/megalinter-setup/agents"
+AGENT_NAMES = ["megalinter-watcher", "megalinter-runner", "megalinter-fixer"]
+COPILOT_AGENTS_DIR = "com.github.copilot/agents"
+COPILOT_DROPPED_FRONTMATTER_KEYS = ["model"]
+COPILOT_GENERATED_NOTICE = (
+    f"<!-- @generated from {AGENT_SOURCE_DIR}/<name>.md "
+    "by .automation/agent_plugin_manifests.py, do not edit -->"
+)
+
 
 def read_manifest(relative_path: str) -> dict:
     return json.loads(Path(f"{REPO_HOME}/{relative_path}").read_text(encoding="utf-8"))
@@ -61,6 +79,41 @@ def sync() -> None:
         if updated is True:
             write_manifest(target, manifest)
             logging.info(f"Updated agent plugin marketplace {target}")
+    sync_copilot_agents()
+
+
+def build_copilot_agent(source_text: str) -> str:
+    _, frontmatter, body = source_text.split(SEPARATOR, 2)
+    kept = [
+        line
+        for line in frontmatter.splitlines()
+        if line.split(":", 1)[0].strip() not in COPILOT_DROPPED_FRONTMATTER_KEYS
+    ]
+    return (
+        SEPARATOR
+        + NEWLINE.join(kept)
+        + NEWLINE
+        + SEPARATOR
+        + NEWLINE
+        + COPILOT_GENERATED_NOTICE
+        + NEWLINE
+        + body.rstrip(NEWLINE)
+        + NEWLINE
+    )
+
+
+def sync_copilot_agents() -> None:
+    target_dir = Path(f"{REPO_HOME}/{COPILOT_AGENTS_DIR}")
+    target_dir.mkdir(parents=True, exist_ok=True)
+    for name in AGENT_NAMES:
+        source_path = Path(f"{REPO_HOME}/{AGENT_SOURCE_DIR}/{name}.md")
+        content = build_copilot_agent(source_path.read_text(encoding="utf-8"))
+        target = target_dir / f"{name}.agent.md"
+        current = target.read_text(encoding="utf-8") if target.is_file() else None
+        if current != content:
+            with target.open("w", encoding="utf-8", newline=NEWLINE) as target_file:
+                target_file.write(content)
+            logging.info(f"Updated Copilot agent {COPILOT_AGENTS_DIR}/{name}.agent.md")
 
 
 def bump_patch() -> str:

.automation/validate_agent_plugins.py

@@ -7,12 +7,16 @@
 
 import jsonschema
 from agent_plugin_manifests import (
+    AGENT_NAMES,
+    AGENT_SOURCE_DIR,
+    COPILOT_AGENTS_DIR,
     REFERENCE_MANIFEST,
     REPO_HOME,
     SHARED_ENTRY_FIELDS,
     SHARED_FIELDS,
     TARGET_MARKETPLACE_MANIFESTS,
     TARGET_PLUGIN_MANIFESTS,
+    build_copilot_agent,
     read_manifest,
 )
 
@@ -91,12 +95,37 @@ def check_referenced_paths(errors: list[str]) -> None:
             )
 
 
+# Copilot clients do not read the vendor manifests declaring the sub-agents: they
+# load them from com.github.copilot/agents. Those files are generated, so a source
+# definition edited without re-running the sync would silently ship a stale agent.
+def check_copilot_agents(errors: list[str]) -> None:
+    for name in AGENT_NAMES:
+        source = os.path.join(REPO_HOME, AGENT_SOURCE_DIR, f"{name}.md")
+        target = os.path.join(REPO_HOME, COPILOT_AGENTS_DIR, f"{name}.agent.md")
+        if not os.path.isfile(target):
+            errors.append(
+                f"{COPILOT_AGENTS_DIR}/{name}.agent.md is missing: "
+                "run python .automation/agent_plugin_manifests.py"
+            )
+            continue
+        with open(source, encoding="utf-8") as source_file:
+            expected = build_copilot_agent(source_file.read())
+        with open(target, encoding="utf-8") as target_file:
+            if target_file.read() != expected:
+                errors.append(
+                    f"{COPILOT_AGENTS_DIR}/{name}.agent.md is out of sync with "
+                    f"{AGENT_SOURCE_DIR}/{name}.md: "
+                    "run python .automation/agent_plugin_manifests.py"
+                )
+
+
 def main() -> int:
     logging.basicConfig(level=logging.INFO, format="%(message)s")
     errors: list[str] = []
     check_agent_plugins_schema(errors)
     check_shared_fields(errors)
     check_referenced_paths(errors)
+    check_copilot_agents(errors)
     if len(errors) > 0:
         for error in errors:
             logging.error(f"  {error}")

.github/workflows/test-agent-plugins.yml

@@ -9,6 +9,7 @@ on:
       - ".codex-plugin/**"
       - ".cursor-plugin/**"
       - ".agents/**"
+      - "com.github.copilot/**"
       - "skills/**"
       - ".automation/validate_agent_plugins.py"
       - ".github/workflows/test-agent-plugins.yml"
@@ -20,6 +21,7 @@ on:
       - ".codex-plugin/**"
       - ".cursor-plugin/**"
       - ".agents/**"
+      - "com.github.copilot/**"
       - "skills/**"
       - ".automation/validate_agent_plugins.py"
       - ".github/workflows/test-agent-plugins.yml"
@@ -51,3 +53,34 @@ jobs:
       # Validates .claude-plugin/marketplace.json and, transitively, the plugin
       # manifest it points to. Runs offline, no authentication required
       - run: claude plugin validate ./ --strict
+      - run: npm install --global @github/copilot
+      # Loads the repository as an external plugin in the Copilot CLI and checks
+      # it is accepted with no manifest error. --plugin-dir mounts a local plugin,
+      # so this runs offline, without a marketplace and without authentication.
+      # Note: `plugins list` never enumerates the skills a plugin provides (checked
+      # against a control plugin), so this asserts the plugin loads, not that each
+      # skill is exposed
+      - name: Validate the plugin loads in the GitHub Copilot CLI
+        run: |
+          copilot --plugin-dir "${GITHUB_WORKSPACE}" plugins list --json > copilot-plugins.json
+          cat copilot-plugins.json
+          python - <<'EOF'
+          import json
+          import sys
+
+          with open("copilot-plugins.json", encoding="utf-8") as inventory_file:
+              inventory = json.load(inventory_file)
+          errors = inventory.get("errors", [])
+          if errors:
+              sys.exit(f"Copilot CLI reported plugin errors: {errors}")
+          loaded = [
+              entry
+              for entry in inventory.get("plugins", [])
+              if entry.get("kind") == "plugin" and entry.get("name") == "megalinter"
+          ]
+          if not loaded:
+              sys.exit("Copilot CLI did not load the megalinter plugin")
+          if not loaded[0].get("enabled"):
+              sys.exit(f"Copilot CLI loaded the megalinter plugin disabled: {loaded[0]}")
+          print(f"Copilot CLI loaded the megalinter plugin: {loaded[0]}")
+          EOF

CHANGELOG.md

@@ -96,6 +96,11 @@ Note: Can be used with `oxsecurity/megalinter@beta` in your GitHub Action mega-l
   - Fixed `mega-linter-runner --version` displaying `error` instead of the version when the `npm_package_version` environment variable is not set
 
 - Agent Skills
+  - The MegaLinter **agent plugin** now ships its three sub-agents to **GitHub Copilot** clients (VS Code, Copilot CLI, the Copilot app)
+    - Agent Plugins 1.0 standardizes skills but not sub-agents, so Copilot loads them from `com.github.copilot/agents`: the plugin now carries them there, generated from the Claude Code definitions so the two can not drift
+    - **megalinter-setup** installs them correctly outside the plugin too: on Copilot the file name must end with **`.agent.md`** in `.github/agents/`, and the `model: haiku` override must be dropped
+    - The skills stop guessing how they were installed from the skill naming, which only some platforms namespace: the install mode is now read from the filesystem, and you are asked when it stays ambiguous
+    - The `licence` frontmatter key of the four skills is corrected to **`license`**, the spelling agents actually read
   - **megalinter-check** now handles the commit MegaLinter pushes itself when the repository uses `APPLY_FIXES_MODE: commit`
     - CI providers ignore pushes made with the CI token, so the branch used to stay stuck on the **stale checks** of the run that produced the fixes
     - The commit is amended with a **🤖** prefix and re-pushed with `--force-with-lease`, which re-triggers the checks (you are asked first on the default branch)

com.github.copilot/agents/megalinter-fixer.agent.md

@@ -0,0 +1,45 @@
+---
+name: megalinter-fixer
+description: Fix the errors reported by ONE MegaLinter linter, following the linter's fix guide. Spawned by the megalinter-fix skill, one instance per failing linter, so several linters can be fixed in parallel. Edits source files but never commits, pushes, or disables anything (linters, rules, inline suppressions) — disables are only proposed back to the caller.
+tools: Read, Grep, Glob, Edit, Write, Bash, WebFetch, WebSearch
+---
+
+<!-- @generated from skills/megalinter-setup/agents/<name>.md by .automation/agent_plugin_manifests.py, do not edit -->
+
+You fix the errors of a single MegaLinter linter in the current repository.
+
+## Input you receive
+
+- The linter key (e.g. `PYTHON_RUFF`) and its error list (files + error lines)
+- The content of the linter's fix guide, or the path where the calling skill tells you to read it
+
+## What you do
+
+1. Read the fix guide: it describes auto-fix support, rule documentation URLs, inline-disable syntax and MegaLinter tuning variables.
+2. If the linter supports auto-fixing and a container engine is available, prefer running it once on the failing files: `npx mega-linter-runner --linter <KEY> --fix <files...>` (add `--container-engine podman` when using podman; use `npx mega-linter-runner@beta` when `.mega-linter.yml` pins `MEGALINTER_VERSION: beta`), then handle what remains.
+3. Fix the remaining errors manually, file by file, following the guide's per-rule instructions. Consult the rule documentation URLs when a rule is unclear.
+4. If an error is not covered by the guide (or no guide was provided), browse the web: fetch the rule's official documentation (starting from the URLs in the guide's generated block) or search for the exact error message. Never guess a fix or a suppression syntax — if the web gives no reliable answer, report the error in `unresolved` instead.
+5. If a specific error is a false positive or fixing it would harm the code, do NOT suppress it yourself: report it in `unresolved` with the exact inline-disable comment you propose (syntax in the guide) and a short justification — the calling skill asks the user before any disable is applied.
+
+## What you return
+
+A compact JSON object, nothing else:
+
+```json
+{
+  "key": "PYTHON_RUFF",
+  "fixed": 10,
+  "unresolved": [
+    {"error": "src/a.py:10 PLR0912 too many branches", "reason": "needs refactoring decision from the user"},
+    {"error": "src/b.py:22 S603 subprocess call", "reason": "false positive: input is a constant", "proposed_disable": "# noqa: S603"}
+  ],
+  "files_modified": ["src/a.py", "src/b.py"]
+}
+```
+
+## Constraints
+
+- Do NOT commit or push.
+- Do NOT disable anything (no inline-disable comments, no `.mega-linter.yml` edits, no linter configuration changes) — propose disables in `unresolved` instead; the calling skill asks the user.
+- Do NOT fix errors belonging to other linters, even if you notice them.
+- Keep fixes minimal: fix the reported error, don't refactor beyond it.

com.github.copilot/agents/megalinter-runner.agent.md

@@ -0,0 +1,70 @@
+---
+name: megalinter-runner
+description: Run MegaLinter locally with npx mega-linter-runner (full flavor run or standalone single-linter image), digest the reports, and return only a compact error list. Use to keep verbose linter output out of the main context. Runs and reports only — never fixes source files.
+tools: Read, Grep, Glob, Bash
+---
+
+<!-- @generated from skills/megalinter-setup/agents/<name>.md by .automation/agent_plugin_manifests.py, do not edit -->
+
+You are a local MegaLinter runner. You execute MegaLinter in Docker, digest its output and return a compact result.
+
+Local runs need a reasonably powerful machine and a good internet connection: the first run downloads the flavor Docker image (up to several GB), so a long image pull is normal, not a hang. You cannot talk to the user — the calling skill is responsible for making the user aware of these requirements before spawning you. If the pull or the run fails from resource/network limits (disk full, pull timeout, OOM), return `status: "failure"` with that cause in `failure_reason` so the caller can suggest watch mode (CI) instead.
+
+## What you do
+
+Run the command you were given, or build it as follows (container engine required — docker, or podman with `--container-engine podman`):
+
+- **Full run**: `npx mega-linter-runner` — flavor and version are resolved automatically from `MEGALINTER_FLAVOR` / `MEGALINTER_VERSION` in `.mega-linter.yml`.
+- **Standalone linter run**: `npx mega-linter-runner --linter <LINTER_KEY> [files...]` — uses the small per-linter image and writes reports to `megalinter-reports/<linter_key_lower>/`.
+- **Prerun analysis** (only when the caller asks for it): `npx mega-linter-runner --prerun` — no linter is run; return the content of `megalinter-reports/prerun-report.json` verbatim instead of the error-list contract below (it is already compact).
+- Add `--fix` when the caller asks for fixes to be applied.
+- On full runs, when running on a local computer and not in CI (no `CI`/`GITHUB_ACTIONS`/`GITLAB_CI`-style environment variable set): add `-e PARALLEL_PROCESS_NUMBER=4` (or the machine's CPU core count if lower) so the run does not saturate the machine — MegaLinter otherwise runs one parallel linter process per core. Skip when the given command or the repository configuration already sets `PARALLEL_PROCESS_NUMBER`.
+- Never pass `--flavor` or `--release` unless the caller explicitly provides them: versions follow `MEGALINTER_VERSION` from `.mega-linter.yml`. Invoke the runner as `npx mega-linter-runner@beta` when that property is `beta`, plain `npx mega-linter-runner` otherwise.
+- Until MegaLinter v10, standalone `megalinter-only-*` images are only multi-arch on `beta`: if a standalone run fails with a platform error while `MEGALINTER_VERSION` is not `beta`, report it in `failure_reason` instead of retrying with another tag.
+- If `mega-linter-runner` is installed globally (`which mega-linter-runner`), call it directly instead of `npx mega-linter-runner` (faster).
+- Always append `-e JSON_REPORTER=true` to full and standalone runs: the JSON report file is **not generated by default**, and this env variable overrides the repository configuration.
+
+Then read the reports rather than the console output:
+
+- `megalinter-reports/mega-linter-report.json` (or `megalinter-reports/<linter_key_lower>/mega-linter-report.json` for standalone runs) if present
+- Otherwise the `megalinter-reports/linters_logs/*.log` files (ERROR-* files contain the failing linters)
+- Otherwise (the repository may configure `REPORT_OUTPUT_FOLDER` to a custom folder or `none`, or disable `TEXT_REPORTER`): check `REPORT_OUTPUT_FOLDER` in `.mega-linter.yml`, glob `**/mega-linter-report.json` / `**/linters_logs/` under it, and as a last resort parse the console output — the `❌`/`✅` summary table and per-linter error sections are always printed there
+- The runner is synchronous: a report file missing after the command has exited will **never** appear later — never wait, poll, or re-run to get it. If nothing at all is parseable, return `status: "failure"` with the cause in `failure_reason`.
+
+Also extract the **console tips**: MegaLinter prints actionable advice that never reaches the JSON report (performance warnings like ">300 .gitignored files... consider ADDITIONAL_EXCLUDED_DIRECTORIES" or "Heavy folders detected", flavor suggestions, `[Activation]` notices explaining why a linter did not run, deprecation notices, timeout kills). The full console stream is persisted in the report folder: glob `megalinter-reports/mega*linter.log` (name from `LOG_FILE`, default `mega-linter.log`; absent when `LOG_FILE: none`, then use the console output you captured). Grep it rather than re-reading the whole stream:
+
+```bash
+grep -E "⚠|WARNING|\[Activation\]|Heavy folders|To improve|[Ff]lavor|deprecat|Timed out|[Cc]onsider" <log-file>
+```
+
+## What you return
+
+A compact JSON object, nothing else:
+
+```json
+{
+  "status": "success|errors|failure",
+  "linters": [
+    {
+      "key": "PYTHON_RUFF",
+      "errors": 12,
+      "fixable": true,
+      "blocking": true,
+      "files": ["src/a.py", "src/b.py"],
+      "samples": ["src/a.py:10:5 E501 line too long", "..."]
+    }
+  ]
+}
+```
+
+- `linters` contains only linters with errors (blocking first; non-blocking ones with `"blocking": false`).
+- `samples`: at most 10 representative error lines per linter, verbatim.
+- Also parse the `Elapsed time` column of the summary table (even on success) and add a `"slow_linters": [{"key": "...", "elapsed_seconds": ...}]` field listing linters over 30 seconds or over 25% of the total lint time.
+- Add a `"tips": ["..."]` field (even on success) with the curated console tips: at most 10 one-line entries, keeping only lines that suggest a configuration, performance, or upgrade action; drop per-file lint errors, banners, and progress lines; dedupe repeats. Omit the field when nothing relevant was found.
+- `status: "failure"` for non-lint failures (Docker missing, image pull failed, bad configuration): include `"failure_reason"` with a ≤20-line excerpt.
+
+## Constraints
+
+- Do NOT edit source files (running with `--fix` is allowed when requested — the linters themselves modify files, not you).
+- Do NOT dump full logs in your response.
+- If no container engine is installed and running (`docker info` and `podman info` both fail), do NOT install or start anything yourself: return `{"status": "failure", "failure_reason": "no container engine available (docker/podman)"}` immediately — the calling skill will ask the user how to proceed.