Conform to Agent Plugins 1.0.0 and the Agent Skills specification

.claude-plugin/marketplace.json

@@ -3,7 +3,7 @@
   "description": "A full Google Cloud delivery team for coding agents — design-first, security-first, Well-Architected, with agentic (ADK / A2A / AP2 / MCP) coverage.",
   "owner": {
     "name": "Jaroslav Pantsjoha",
-    "url": "https://uk.linkedin.com/in/johas"
+    "url": "https://jpantsjoha.com"
   },
   "plugins": [
     {
@@ -13,7 +13,7 @@
       "source": "./",
       "author": {
         "name": "Jaroslav Pantsjoha",
-        "url": "https://uk.linkedin.com/in/johas"
+        "url": "https://jpantsjoha.com"
       }
     }
   ]

.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "version": "0.1.0",
   "author": {
     "name": "Jaroslav Pantsjoha",
-    "url": "https://uk.linkedin.com/in/johas"
+    "url": "https://jpantsjoha.com"
   },
   "homepage": "https://github.com/jpantsjoha/googlecloud-plugin",
   "repository": "https://github.com/jpantsjoha/googlecloud-plugin",

.claude/CLAUDE.md

@@ -32,14 +32,28 @@ 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)
-
-Run `make validate` after any SKILL.md edit.
+The frontmatter field set is **closed** by the Agent Skills specification. Only
+`name`, `description`, `license`, `compatibility`, `metadata` and `allowed-tools`
+are permitted — a skill carrying anything else is non-conformant, and Agent
+Plugins 1.0.0 requires clients to **skip** it. Never add a top-level field.
+
+Every `skills/<name>/SKILL.md` must have:
+- `name` — matches directory name exactly, lowercase, no `--`
+- `description` — meaningful, ≤1024 chars, **and carries every routing keyword**
+- `license`
+- `metadata` — string keys to **string** values, all namespaced
+  `googlecloud-plugin/…`. Required: `version`, `triggers`, `required-scopes`
+  (emit `""`, don't omit, when a skill needs no IAM scopes). Personas add
+  `persona`, `tier`, `gate`. Lists are comma-joined.
+
+**Routing lives in the description.** No client reads `metadata/triggers` — it is
+an index for this repo's own tooling, and `make validate` fails if any trigger is
+missing from the description. When two skills overlap, state in each description
+which one owns the case and name the other.
+
+Run `make validate` after any SKILL.md edit, and `make spec` after touching
+`plugin.json` or `mcp.json`. See
+`architecture/decisions/ADR-007-agent-plugins-conformance.md`.
 
 ## Safety Rules (Non-Negotiable)
 

.github/workflows/gate.yml

@@ -22,6 +22,9 @@ jobs:
       - name: Install deps
         run: pip install pyyaml pytest
 
+      - name: Validate Agent Plugins 1.0.0 conformance
+        run: python3 scripts/validate_agent_plugins.py
+
       - name: Validate skill contracts
         run: python3 scripts/validate_skills.py
 
@@ -36,3 +39,20 @@ jobs:
 
       - name: Smoke tests
         run: python3 -m pytest tests/skill-smoke-tests/ -q
+
+      # Advisory: validates against UPSTREAM rather than our transcription of it,
+      # so it catches spec drift early. Network-dependent, so it warns instead of
+      # blocking — validate_agent_plugins.py above is the deterministic gate.
+      - name: Independent conformance check (upstream reference validator)
+        continue-on-error: true
+        run: |
+          pipx install uv >/dev/null 2>&1 || pip install uv
+          for skill in skills/*/; do
+            uvx --quiet --from \
+              'git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref' \
+              skills-ref validate "$skill" || exit 1
+          done
+          uvx --quiet check-jsonschema \
+            --schemafile https://agent-plugins.org/schemas/1.0.0/plugin.schema.json plugin.json
+          uvx --quiet check-jsonschema \
+            --schemafile https://agent-plugins.org/schemas/1.0.0/mcp.schema.json mcp.json

.kimi-plugin/plugin.json

@@ -4,7 +4,7 @@
   "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",
-    "url": "https://uk.linkedin.com/in/johas"
+    "url": "https://jpantsjoha.com"
   },
   "homepage": "https://github.com/jpantsjoha/googlecloud-plugin",
   "repository": "https://github.com/jpantsjoha/googlecloud-plugin",

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)"

README.md

@@ -146,13 +146,37 @@ The rule underneath every gate: **infer intent, never infer permission.** An AI
 
 ---
 
+## Standards conformance
+
+This plugin conforms to **[Agent Plugins 1.0.0](https://agent-plugins.org/specification)** — the open, vendor-neutral packaging specification co-maintained by Amazon, Cursor, Google, Microsoft, OpenAI and Vercel — and to the **[Agent Skills specification](https://agentskills.io/specification)** it references.
+
+| Standard | Artefact | Verified by |
+|---|---|---|
+| Agent Plugins 1.0.0 manifest | `plugin.json` | [`plugin.schema.json`](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json) |
+| Agent Plugins 1.0.0 MCP config | `mcp.json` | [`mcp.schema.json`](https://agent-plugins.org/schemas/1.0.0/mcp.schema.json) |
+| Agent Skills | `skills/*/SKILL.md` | `skills-ref`, the official reference validator |
+
+That means any conformant client loads it — no per-harness fork. The Claude Code, Antigravity/Gemini, Codex and Kimi manifests remain in place alongside, so existing installs are unaffected.
+
+Reproduce the conformance evidence yourself:
+
+```bash
+make spec       # Agent Plugins 1.0.0 conformance (plugin.json + mcp.json)
+
+# independent, third-party checks — nothing in this repo is trusted
+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
+```
+
 ## 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 gate: spec + validate + manifest + mermaid + lint + test
+make spec       # Agent Plugins 1.0.0 conformance
+make validate   # SKILL.md frontmatter contract (Agent Skills + routing invariant)
 make lint       # every reference URL resolves (HTTP 200)
 make test       # skill smoke tests
 make check      # freshness: content-hash drift vs live GCP docs
@@ -169,6 +193,7 @@ Created and maintained by **Jaroslav Pantsjoha (JP)** — Technical Director and
 
 I built this to make my own Google Cloud work repeatable, then to share it. The model is the easy part; the durable engineering is the harness around it — the skills, rules, MCP servers, gates, and evals. GCP patterns outlast the week's model release, so they are worth encoding once and reusing. This plugin is that baseline aimed squarely at Google Cloud — the GCP companion to my [`join-the-team`](https://github.com/jpantsjoha/ai-native-developer-experience) harness. Part of the **#HarnessEngineering** body of work — the engineering discipline behind the Agentic Enterprise.
 
+- Website: [jpantsjoha.com](https://jpantsjoha.com)
 - LinkedIn: [uk.linkedin.com/in/johas](https://uk.linkedin.com/in/johas)
 - Google Developer Expert: [me.developers.google.com/u/jpantsjoha](https://me.developers.google.com/u/jpantsjoha)
 

SPEC.md

@@ -268,33 +268,43 @@ Every billable skill includes:
 **Context:**  
 Agents need to discover and route to skills at runtime. A standard contract ensures consistency.
 
-**Decision:**  
-Every skill has a `SKILL.md` with YAML frontmatter:
+**Decision:**
+Every skill has a `SKILL.md` conforming to the [Agent Skills
+specification](https://agentskills.io/specification). The frontmatter field set
+is closed, so the plugin's own contract lives under `metadata` as namespaced
+string values, and routing keywords fold into `description`:
+
 ```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. Covers
+  service creation, traffic splitting, IAM, VPC connectivity, secrets
+  integration, auto-scaling, and gcloud CLI patterns. Warns before billable
+  deployments. Use when the user mentions: deploy to cloud run, serverless
+  container, cloud run VPC, gcloud run."
+license: MIT
+metadata:
+  "googlecloud-plugin/version": "0.1"
+  "googlecloud-plugin/triggers": "deploy to cloud run, serverless container, …"
+  "googlecloud-plugin/required-scopes": "run.services.create, run.routes.invoke, …"
+  "googlecloud-plugin/mcp-servers": "google-cloud-run"
 ---
 ```
 
 Followed by H1 title + comprehensive routing + references.
 
 **Consequences:**
-- ✅ Machine-readable skill metadata for discovery
-- ✅ Agents know required IAM scopes before attempting task
+- ✅ A conformant Agent Plugins client loads every skill
+- ✅ Agents know required IAM scopes before attempting a task
 - ✅ Consistent structure across all skills
-- ⚠️ Must validate frontmatter format (tool: `validate_skills.py`)
+- ⚠️ Routing depends on `description` quality alone — `make validate` enforces
+  that every `metadata` trigger also appears there
 - ⚠️ Requires skill authors to understand IAM scope mapping
 
+> Superseded shape: the pre-ADR-007 contract put `version`, `triggers`,
+> `required_scopes` and `mcp_servers` at the top level. That is non-conformant —
+> see `architecture/decisions/ADR-007-agent-plugins-conformance.md`.
+
 ---
 
 ## 5. Constraints & Non-Negotiables
@@ -505,23 +515,19 @@ 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 — the skill for when GCP IS ALREADY THE
+  CHOSEN TARGET. Generates HLD/LLD, owns ADRs, enforces the design gate. Aware of
+  GCP repos, patterns, MCPs and the Well-Architected Framework. If the cloud is
+  still open, use solution-designer. Use when the user mentions: 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": "architect this, how should we build, HLD for, ADR for"
+  "googlecloud-plugin/required-scopes": ""
 ---
 ```
 

architecture/decisions/ADR-005-skill-contract.md

@@ -1,8 +1,21 @@
 # ADR-005: SKILL.md Frontmatter Contract
 
-**Status:** Accepted  
+**Status:** Superseded by [ADR-007](ADR-007-agent-plugins-conformance.md) (2026-08-07)
 **Date:** 2026-07-23
 
+> **Superseded.** The frontmatter shape below is non-conformant with the Agent
+> Skills specification, whose field set is closed. `version`, `triggers`,
+> `required_scopes`, `mcp_servers`, `persona`, `tier`, `gate` and `owns_eval`
+> are not permitted at the top level, and Agent Plugins 1.0.0 requires clients
+> to **skip** any skill that carries them — all 17 skills, in practice.
+>
+> The contract itself survives; only its location changed. Every field below now
+> lives under `metadata` as a namespaced string value, and routing keywords fold
+> into `description`. See ADR-007 for the current shape and the reasoning.
+>
+> Retained for the record: the *motivation* below still holds, and the gate
+> discipline it established is what made the drift detectable.
+
 ## Context
 
 Agents need machine-readable metadata to route prompts to the correct skill at runtime. Without a standard contract, each skill becomes its own format — discovery breaks, validation is impossible, and the plugin can't enumerate its own capabilities.