diff --git a/skills/github-release/references/ecosystem-detection.md b/skills/github-release/references/ecosystem-detection.md
index ea369a0..7bc3f7a 100644
--- a/skills/github-release/references/ecosystem-detection.md
+++ b/skills/github-release/references/ecosystem-detection.md
@@ -103,9 +103,17 @@ Note: Update `Cargo.lock` by running `cargo check` after bumping `Cargo.toml`, n
 
 | File | Field/Pattern | Example |
 |------|--------------|---------|
+| `plugin.json` | `"version": "X.Y.Z"` | `"version": "0.1.0"` |
 | `.claude-plugin/plugin.json` | `"version": "X.Y.Z"` | `"version": "0.1.0"` |
 | `skills/*/SKILL.md` | `version: "X.Y.Z"` (in frontmatter `metadata`) | `version: "0.1.0"` |
 
+Note: repos carry **two** manifests. The root `plugin.json` is the
+[Agent Plugins 1.0.0](https://agent-plugins.org) manifest and the source of
+truth; `.claude-plugin/plugin.json` is Claude Code's and is generated from it by
+`skill-repo-skill`'s `sync-plugin-manifest.sh`. Bump the root file, run the sync,
+and both agree. Repos that have not adopted the portable manifest yet only have
+the `.claude-plugin` one — the detector reports whichever exist.
+
 Note: `skills/*/SKILL.md` is a glob — a repo may ship **multiple** skills (e.g. `jira-communication` + `jira-syntax`). Bump the `metadata.version` in **every** SKILL.md so each equals `plugin.json`.
 
 Note: On GitHub this match is a **required CI check** — `Skill Validation` runs a step *"Validate SKILL.md metadata.version matches plugin.json"*, so a bump PR that touches only `plugin.json` is BLOCKED until every SKILL.md is bumped too. On GitLab the `ci-components/claude-code-skill` pipeline's `validate:version` only checks `plugin.json` (v-stripped) against the tag, not SKILL.md — bump SKILL.md anyway for consistency.
diff --git a/skills/github-release/scripts/detect-ecosystem.sh b/skills/github-release/scripts/detect-ecosystem.sh
index 460c75c..0ff035e 100755
--- a/skills/github-release/scripts/detect-ecosystem.sh
+++ b/skills/github-release/scripts/detect-ecosystem.sh
@@ -94,10 +94,17 @@ if [[ -f ext_emconf.php ]]; then
 fi
 
 # ---------------------------------------------------------------------------
-# Skill repo (.claude-plugin/plugin.json)
+# Skill repo (plugin.json + .claude-plugin/plugin.json)
 # ---------------------------------------------------------------------------
 if [[ -f .claude-plugin/plugin.json ]]; then
     echo "ecosystem:skill"
+    # Root plugin.json is the Agent Plugins 1.0.0 manifest and the source of
+    # truth for the version; .claude-plugin/plugin.json is generated from it.
+    # A repo that has not adopted the portable manifest only reports the latter.
+    if [[ -f plugin.json ]]; then
+        pver=$(json_field plugin.json version)
+        echo "version-file:plugin.json:${pver}"
+    fi
     sver=$(json_field .claude-plugin/plugin.json version)
     echo "version-file:.claude-plugin/plugin.json:${sver}"