jpantsjoha · jpantsjoha · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
     {
       "name": "googlecloud-plugin",
       "description": "A full Google Cloud delivery team for your coding agent: solution designer, GCP architect, agent architect, security, SRE, and QA — wired into a design-first, security-first delivery gate, with eleven service skills and MCP server setup.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "source": "./",
       "author": {
         "name": "Jaroslav Pantsjoha",

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "googlecloud-plugin",
   "description": "A full Google Cloud delivery team for your coding agent: vendor-objective solution designer, GCP architect, agentic-systems architect (ADK / Agent Runtime / MCP / A2A / AP2), plus security, SRE, and QA — wired into a design-first, security-first delivery gate. Eleven service skills (Cloud Run, GKE, IAM, BigQuery, Cloud Storage, Vertex AI, networking, observability), MCP server setup, and a self-validating research pipeline that keeps every reference current.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": {
     "name": "Jaroslav Pantsjoha",
     "url": "https://uk.linkedin.com/in/johas"

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -1,7 +1,8 @@
 # GoogleCloud Plugin — Construction Guide
 
 This file advises AI agents working ON the plugin (building, researching, validating skills).
-It is gitignored and never committed to the public repo.
+It is committed, and public — write it for contributors, not as a scratchpad.
+For local notes you don't want published, use `.claude/local-CLAUDE.md`, which is gitignored.
 
 ## Your Role
 
@@ -32,14 +33,27 @@ Before any skill merges to main:
 
 ## Skill Contract
 
-Every `skills/<name>/SKILL.md` must have valid YAML frontmatter with:
-- `name` — matches directory name exactly
-- `description` — >20 chars, meaningful
-- `version` — string or number
-- `triggers` — non-empty list of routing phrases
-- `required_scopes` — list (can be empty `[]` for non-IAM skills)
+Frontmatter follows the [Agent Skills specification](https://agentskills.io/specification).
+The field set is **closed** — adding a top-level key outside
+`{name, description, license, compatibility, allowed-tools, metadata}` makes the
+skill non-conformant, and a conformant client MUST skip it. Everything specific
+to this plugin is namespaced under `metadata` as **string** values:
 
-Run `make validate` after any SKILL.md edit.
+- `name` — matches directory name exactly
+- `description` — what it does AND when to use it, max 1024 chars, ending with
+  `Use when the user mentions: …`. This is the only thing a conformant client
+  routes on. Where two skills overlap, name the other and draw the line.
+- `metadata["googlecloud-plugin/version"]`
+- `metadata["googlecloud-plugin/triggers"]` — comma-joined, non-empty
+- `metadata["googlecloud-plugin/required-scopes"]` — comma-joined, `""` if none
+- `metadata["googlecloud-plugin/mcp-servers"]` — comma-joined, omit if none
+- persona skills add `persona`, `tier`, `gate` under the same namespace
+
+Never reintroduce a top-level `triggers`, `version` or `required_scopes` field —
+that is the exact regression `make validate` exists to catch. See
+[ADR-007](../architecture/decisions/ADR-007-agent-plugins-conformance.md).
+
+Run `make spec && make validate` after any SKILL.md or manifest edit.
 
 ## Safety Rules (Non-Negotiable)
 

diff --git a/.kimi-plugin/plugin.json b/.kimi-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "googlecloud-plugin",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A full Google Cloud delivery team for your coding agent: solution designer, GCP architect, agentic-systems architect (ADK / Agent Runtime / MCP / A2A / AP2), plus security, SRE, and QA — wired into a design-first, security-first delivery gate, with eleven service skills and MCP server setup.",
   "author": {
     "name": "Jaroslav Pantsjoha",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to this plugin are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — 2026-08-07
+
+**Standards release.** The plugin now conforms to
+[Agent Plugins 1.0.0](https://agent-plugins.org/specification) and the
+[Agent Skills specification](https://agentskills.io/specification), the open
+vendor-neutral packaging standards co-maintained by Amazon, Cursor, Google,
+Microsoft, OpenAI and Vercel.
+
+Before this release, a conformant Agent Plugins client would have loaded
+**nothing** from this plugin. Two independent fatal faults:
+
+1. `plugin.json` omitted the required `$schema`. The manifest schema is closed,
+   so §5.2 makes the omission fatal — the client rejects the plugin outright.
+2. All 17 skills carried top-level frontmatter outside the closed Agent Skills
+   field set. §6.1 requires clients to **skip** every non-conforming skill.
+
+### Added
+
+- `mcp.json` — the portable MCP manifest, with an explicit `stdio` transport
+  discriminator.
+- `make spec` — Agent Plugins 1.0.0 conformance gate, reporting against the
+  specification's own failure boundaries (FATAL / MCP / SKILL).
+- `scripts/validate_agent_plugins.py` — dependency-free conformance checker;
+  no network call needed in CI.
+- README **Standards and compliance** section, with commands to verify
+  conformance without trusting this repo's own scripts.
+- [ADR-007](architecture/decisions/ADR-007-agent-plugins-conformance.md) —
+  the adoption decision and its trade-offs.
+- `skills/mcp-servers/references/agent-plugins-mcp.md` — the placeholder-expansion
+  trap, and Toolbox as a documented opt-in.
+- This changelog.
+
+### Changed
+
+- **BREAKING (skill authors and downstream tooling).** SKILL.md frontmatter is
+  reduced to `{name, description, license, metadata}`. The top-level `version`,
+  `triggers`, `required_scopes`, `mcp_servers`, `persona`, `tier`, `gate` and
+  `owns_eval` fields are gone. The same data is retained under `metadata`,
+  namespaced and comma-joined:
+
+  ```yaml
+  metadata:
+    "googlecloud-plugin/required-scopes": "run.services.create, run.services.get"
+  ```
+
+  Anything reading the old YAML lists must now read the namespaced key and split
+  on `", "`.
+- Routing keywords moved from `triggers` into `description` — the only field a
+  conformant client routes on.
+- Eight skill descriptions gained explicit boundary clauses after cross-harness
+  routing tests showed four pairs where both skills matched the same request:
+  `iam`↔`gcp-security`, `gcp-ops`↔`logging-monitoring`,
+  `vertex-ai`↔`agent-architect`, `gcp-architect`↔`solution-designer`.
+- `scripts/validate_skills.py` inverted — it now enforces the closed Agent Skills
+  field set instead of requiring the fields that broke conformance.
+- Smoke tests expanded from 136 to 195, covering both specifications.
+- `make manifest` no longer claims the plugin is "installable across 4
+  harnesses". It verifies manifests parse and agree, and now says so.
+
+### Fixed
+
+- `.claude/CLAUDE.md` described itself as gitignored and never committed. It is
+  tracked and public; `.gitignore` covers `.claude/local-CLAUDE.md`. Corrected.
+- `vertex-ai` advertised "Agent Builder" while directing agentic work elsewhere.
+  Agent Builder now belongs to `agent-architect` in both descriptions.
+
+### Compatibility
+
+No action required for existing users. The per-harness manifests
+(`.claude-plugin/`, `.kimi-plugin/`, `gemini-extension.json`, `.agents/`) are
+unchanged and remain alongside the portable layout — Agent Plugins closes the
+`plugin.json` field set and fixes component locations, but says nothing about
+sibling directories.
+
+`mcp.json` deliberately declares only the `gcloud` server. Toolbox needs a
+user-specific `tools.yaml` path that no Agent Plugins placeholder can express,
+so it stays an opt-in documented in `skills/mcp-servers/`. `mcp.json` also
+declares no `env`: only `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` expand, so
+`CLOUDSDK_CORE_PROJECT: "${GCP_PROJECT_ID}"` would have been passed through
+literally and mis-set the project. Export it in your shell instead.
+
+### Verification
+
+| Check | Result |
+|---|---|
+| `skills-ref` (official Agent Skills reference validator) | 17/17 valid |
+| `check-jsonschema` vs published `plugin.schema.json` / `mcp.schema.json` | pass |
+| `agy plugin validate` (Antigravity loader) | 17 skills, 2 mcpServers, exit 0 |
+| Antigravity routing | 17 skills visible, 6/6 routed correctly |
+| Kimi routing (`--skills-dir`) | 17 skills loaded, 7/7 routed correctly |
+| Live MCP handshake | `gcloud-mcp-server` v0.5.3, protocol 2025-06-18, `run_gcloud_command` |
+| `make gate` | spec + validate + manifest + mermaid + 102 URLs + 195 tests |
+
+Not verified: Codex (usage limit at time of release) and Toolbox (opt-in).
+
+## [0.1.0] — 2026-07-23
+
+Initial release. Six persona skills, eleven service skills, MCP server setup,
+and a self-validating research pipeline.
+
+[0.2.0]: https://github.com/jpantsjoha/googlecloud-plugin/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/jpantsjoha/googlecloud-plugin/releases/tag/v0.1.0
diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: all gate validate manifest preflight lint mermaid test check crawl crawl-dry hooks help
+.PHONY: all gate spec validate manifest preflight lint mermaid test check crawl crawl-dry hooks help
 
 PYTHON  := python3
 SCRIPTS := scripts
@@ -7,12 +7,16 @@ TESTS   := tests/skill-smoke-tests
 # ─── 3-minute validation gate (validate + manifest + lint + test) ───────────
 # This is the pre-commit gate. Install the hook once with: make hooks
 
-gate: validate manifest mermaid lint test
+gate: spec validate manifest mermaid lint test
 	@echo ""
-	@echo "Gate passed: validate + manifest + mermaid + lint + test"
+	@echo "Gate passed: spec + validate + manifest + mermaid + lint + test"
 
 # ─── Individual targets ──────────────────────────────────────────────────────
 
+spec:
+	@echo "==> Validating Agent Plugins 1.0.0 conformance..."
+	@$(PYTHON) $(SCRIPTS)/validate_agent_plugins.py
+
 validate:
 	@echo "==> Validating SKILL.md contracts..."
 	@$(PYTHON) $(SCRIPTS)/validate_skills.py
@@ -66,8 +70,9 @@ help:
 	@echo ""
 	@echo "GoogleCloud Plugin — Makefile Targets"
 	@echo ""
-	@echo "  make gate        Pre-commit gate: validate + manifest + mermaid + lint + test"
-	@echo "  make validate    Validate all SKILL.md frontmatter (contract check)"
+	@echo "  make gate        Pre-commit gate: spec + validate + manifest + mermaid + lint + test"
+	@echo "  make spec        Validate Agent Plugins 1.0.0 conformance (plugin.json + mcp.json)"
+	@echo "  make validate    Validate all SKILL.md frontmatter (Agent Skills + plugin contract)"
 	@echo "  make manifest    Validate plugin is installable (Claude/AGY/Codex/Kimi)"
 	@echo "  make mermaid     Lint Mermaid diagrams for GitHub render-safety"
 	@echo "  make lint        Check all reference URLs resolve (HTTP 200)"

diff --git a/README.md b/README.md
@@ -146,13 +146,45 @@ The rule underneath every gate: **infer intent, never infer permission.** An AI
 
 ---
 
+## Standards and compliance
+
+This plugin conforms to the open, vendor-neutral packaging standards — not to any
+single vendor's plugin format.
+
+| Standard | Version | What conforms | How it's verified |
+|---|---|---|---|
+| [Agent Plugins](https://agent-plugins.org/specification) | 1.0.0 | `plugin.json`, `mcp.json`, the `skills/` layout | `make spec` + [`plugin.schema.json`](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json) / [`mcp.schema.json`](https://agent-plugins.org/schemas/1.0.0/mcp.schema.json) |
+| [Agent Skills](https://agentskills.io/specification) | current | all 17 `SKILL.md` files | `make validate` + the official [`skills-ref`](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference validator |
+| [Model Context Protocol](https://modelcontextprotocol.io) | stdio transport | `mcp.json` server declarations | `make spec` transport + placeholder checks |
+
+Agent Plugins 1.0.0 is co-maintained by Amazon, Cursor, Google, Microsoft, OpenAI
+and Vercel. Conforming to it means one directory layout works across conformant
+clients instead of a bespoke wrapper per harness. The per-harness manifests
+(`.claude-plugin/`, `.kimi-plugin/`, `gemini-extension.json`, `.agents/`) remain
+alongside it, so existing installs are unaffected.
+
+Verify it yourself, without trusting this repo's own scripts:
+
+```bash
+uvx --from "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref" \
+    skills-ref validate skills/cloud-run
+uvx check-jsonschema --schemafile https://agent-plugins.org/schemas/1.0.0/plugin.schema.json plugin.json
+```
+
+See [ADR-007](architecture/decisions/ADR-007-agent-plugins-conformance.md) for the
+adoption decision and its trade-offs.
+
+---
+
 ## Validation
 
 The plugin validates itself. Every skill conforms to a machine-readable contract; every reference URL is checked live; every source carries a retrieval date and content hash for audit.
 
 ```bash
-make gate       # the 3-minute gate: validate + lint + test
-make validate   # SKILL.md frontmatter contract
+make gate       # the full gate: spec + validate + manifest + mermaid + lint + test
+make spec       # Agent Plugins 1.0.0 conformance (plugin.json + mcp.json + skills/)
+make validate   # SKILL.md frontmatter vs the Agent Skills specification
+make manifest   # per-harness manifests present and consistent
 make lint       # every reference URL resolves (HTTP 200)
 make test       # skill smoke tests
 make check      # freshness: content-hash drift vs live GCP docs

diff --git a/SPEC.md b/SPEC.md
@@ -273,19 +273,20 @@ Every skill has a `SKILL.md` with YAML frontmatter:
 ```yaml
 ---
 name: cloud-run
-description: "Deploy and manage containerized workloads on Cloud Run"
-version: 0.1
-triggers: ["deploy to cloud run", "create cloud run service", "scale cloud run"]
-required_scopes:
-  - run.services.create
-  - run.services.delete
-  - run.services.get
-  - run.services.list
-  - run.services.update
-mcp_servers: []
+description: "Deploy and manage containerized workloads on Cloud Run. … Use when the user mentions: deploy to cloud run, create cloud run service, scale cloud run."
+license: MIT
+metadata:
+  "googlecloud-plugin/version": "0.1"
+  "googlecloud-plugin/triggers": "deploy to cloud run, create cloud run service, scale cloud run"
+  "googlecloud-plugin/required-scopes": "run.services.create, run.services.delete, run.services.get, run.services.list, run.services.update"
+  "googlecloud-plugin/mcp-servers": "google-cloud-run"
 ---
 ```
 
+The Agent Skills frontmatter field set is closed, so routing keywords live in
+`description` and everything plugin-specific is namespaced under `metadata`.
+See [ADR-007](architecture/decisions/ADR-007-agent-plugins-conformance.md).
+
 Followed by H1 title + comprehensive routing + references.
 
 **Consequences:**
@@ -505,23 +506,15 @@ Each persona skill follows the same SKILL.md contract but has an elevated role:
 # Example: gcp-architect frontmatter
 ---
 name: gcp-architect
-description: "Design-first GCP architect. Generates HLD/LLD, owns ADRs, enforces design gate. Aware of all GCP repos, patterns, MCPs, and Well-Architected Framework."
-version: 0.1
-persona: true
-triggers:
-  - "design a solution"
-  - "architect this"
-  - "how should we build"
-  - "what's the approach for"
-  - "HLD for"
-  - "ADR for"
-gate: design
-required_scopes: []
-mcp_servers: []
-references:
-  - url: https://cloud.google.com/architecture
-    title: Google Cloud Architecture Framework
-    retrieved: 2026-07-23
+description: "Design-first GCP architect. Generates HLD/LLD, owns ADRs, enforces the design gate. Aware of all GCP repos, patterns, MCPs, and the Well-Architected Framework. Use this once the design is GCP-only; use solution-designer instead for vendor selection and cross-cloud scope. Use when the user mentions: design a solution, architect this, how should we build, HLD for, ADR for."
+license: MIT
+metadata:
+  "googlecloud-plugin/version": "0.1"
+  "googlecloud-plugin/persona": "true"
+  "googlecloud-plugin/tier": "2"
+  "googlecloud-plugin/gate": "gcp-design"
+  "googlecloud-plugin/triggers": "design a solution, architect this, how should we build, HLD for, ADR for"
+  "googlecloud-plugin/required-scopes": ""
 ---
 ```
 

diff --git a/architecture/decisions/ADR-005-skill-contract.md b/architecture/decisions/ADR-005-skill-contract.md
@@ -1,7 +1,16 @@
 # ADR-005: SKILL.md Frontmatter Contract
 
-**Status:** Accepted  
+**Status:** Superseded by [ADR-007](ADR-007-agent-plugins-conformance.md)
 **Date:** 2026-07-23
+**Superseded:** 2026-08-07
+
+> **Superseded.** The contract below predates Agent Plugins 1.0.0. Agent Skills
+> defines a *closed* frontmatter field set, so the top-level `version`,
+> `triggers`, `required_scopes`, `mcp_servers`, `persona`, `tier` and `gate`
+> fields specified here made every skill non-conformant — and a conformant
+> client MUST skip a non-conforming skill. The same information is retained,
+> namespaced under `metadata`, per ADR-007. The reasoning below still explains
+> *why* the plugin carries this metadata at all; only its location changed.
 
 ## Context